@optimystic/db-core 0.14.1 → 0.16.3

package/src/chain/chain.ts

@@ -121,7 +121,9 @@ export class Chain<TEntry> {
 				priorId: tail.header.id,
 				nextId: undefined,
 			} as ChainDataNode<TEntry>;
-			await this.options?.newBlock?.(newTail, oldTail);
+			// Predecessor is the running `tail` (immediately preceding block), NOT the original
+			// `oldTail`: across a multi-block append each new block links to the one before it.
+			await this.options?.newBlock?.(newTail, tail);
 			trx.insert(newTail);
 			apply(trx, tail, [nextId$, 0, 0, newTail.header.id]);
 			tail = newTail;
@@ -300,6 +302,14 @@ export class Chain<TEntry> {
 		};
 	}
 
+	// NOTE: chain walks (getTail/getHead/select/next/prev) read via `store.tryGet(id)` with the
+	// DEFAULT read purpose (`value`), so every chain node stays in the OCC conflict set. This is
+	// deliberate: the chain backs the log, whose tail is the commit-ordering race arbiter (OCC
+	// "tail binding"), and enumerations return a shape-dependent result set — both are load-bearing
+	// reads that MUST be retained. The B-tree point-lookup navigation exclusion (ticket 4.7) is NOT
+	// applied here. If chain navigation reads ever need excluding, tag ONLY intermediate hops of a
+	// walk that terminates in a consumed entry, and NEVER the tail/header — get the safety predicate
+	// right first (docs/correctness.md Theorem 5).
 	async getTail(header?: ChainHeaderNode): Promise<ChainPath<TEntry> | undefined> {
 		const headerBlock = header ?? await this.getHeader();
 		let tail = headerBlock ? await this.store.tryGet(headerBlock.tailId) as ChainDataNode<TEntry> : undefined;

package/src/cluster/index.ts

@@ -1,2 +1,3 @@
 export * from "./i-cluster.js";
 export * from "./structs.js";
+export * from "./membership.js";

package/src/cluster/membership.ts

@@ -0,0 +1,85 @@
+import type { RepoMessage } from "../network/repo-protocol.js";
+import type { ClusterPeers, ClusterRecord, Signature } from "./structs.js";
+import { sha256 } from "multiformats/hashes/sha2";
+import { base58btc } from "multiformats/bases/base58";
+import { toString as uint8ArrayToString } from "uint8arrays/to-string";
+
+/**
+ * Membership-binding version a new coordinator emits. A record at this version folds a
+ * {@link membershipDigest} of its peer set into `messageHash` / `promiseHash` / `commitHash`, so the
+ * responsible peer set is covered by every signature (see `docs/correctness.md` §2). Absent or `1` marks
+ * a legacy *unbound* record (pre-binding history) whose hashes must verify byte-identically to before
+ * this change.
+ */
+export const CURRENT_MEMBERSHIP_VERSION = 2 as const;
+
+/** Deterministic JSON: sorts object keys so the hash is independent of key insertion order. */
+function canonicalJson(value: unknown): string {
+	return JSON.stringify(value, (_, v) =>
+		v && typeof v === 'object' && !Array.isArray(v)
+			? Object.keys(v).sort().reduce((o: Record<string, unknown>, k) => { o[k] = v[k]; return o; }, {})
+			: v
+	);
+}
+
+/**
+ * Canonical membership digest for a peer set: `base64url(SHA256(canonicalJson(sorted peer-id list)))`.
+ *
+ * Derived from the sorted peer-id list ONLY — not multiaddrs or public keys. Multiaddrs churn and a
+ * peer's public key is already a function of its id, so folding either in would make identity unstable
+ * without adding agreement value. The set of ids IS the membership. The digest is therefore independent
+ * of peer-map key insertion order and of multiaddr / pubkey contents; adding or removing one id changes
+ * it. `membershipDigest({})` (the empty set) is a fixed constant.
+ */
+export async function membershipDigest(peers: ClusterPeers): Promise<string> {
+	const ids = Object.keys(peers ?? {}).sort();
+	const bytes = new TextEncoder().encode(canonicalJson(ids));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}
+
+/**
+ * The membership digest that participates in a record's hashes, or `undefined` for a legacy (v1 /
+ * unversioned) record. `undefined` selects the pre-binding hashing (empty-string concat is a no-op), so
+ * a v1 record hashes byte-identically to before this change. A v2 record folds in its declared
+ * `membershipDigest`.
+ */
+export function recordMembershipDigest(record: Pick<ClusterRecord, 'membershipVersion' | 'membershipDigest'>): string | undefined {
+	return record.membershipVersion === 2 ? record.membershipDigest : undefined;
+}
+
+/**
+ * `messageHash` = `base58btc(SHA256(canonicalJson(message) + digest))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage (`canonicalJson(message)` only); passing the membership
+ * digest folds the peer set in (v2). Empty-string concat means the v1 image is byte-identical to the
+ * pre-binding implementation.
+ */
+export async function computeClusterMessageHash(message: RepoMessage, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(canonicalJson(message) + (digest ?? ''));
+	const hash = await sha256.digest(bytes);
+	return base58btc.encode(hash.digest);
+}
+
+/**
+ * `promiseHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2).
+ */
+export async function computeClusterPromiseHash(messageHash: string, message: RepoMessage, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? ''));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}
+
+/**
+ * `commitHash` = `base64url(SHA256(messageHash + canonicalJson(message) + digest + canonicalJson(promises)))`.
+ *
+ * `digest` `undefined` → legacy v1 preimage; passing it folds the peer set in (v2). The digest sits
+ * between the message and the promises image, matching the v2 layout in `docs/correctness.md`.
+ */
+export async function computeClusterCommitHash(messageHash: string, message: RepoMessage, promises: Record<string, Signature>, digest?: string): Promise<string> {
+	const bytes = new TextEncoder().encode(messageHash + canonicalJson(message) + (digest ?? '') + canonicalJson(promises));
+	const hash = await sha256.digest(bytes);
+	return uint8ArrayToString(hash.digest, 'base64url');
+}

package/src/cluster/structs.ts

@@ -17,6 +17,16 @@ export type ClusterPeers = {
 export type ClusterRecord = {
 	messageHash: string;	// Serves as a unique identifier for the clustered transaction record
 	peers: ClusterPeers;
+	/**
+	 * Membership-binding version. Absent or `1` = legacy *unbound* record: the peer set is NOT covered by
+	 * any hash (pre-binding history and its stored commit certs verify byte-identically to before). `2` =
+	 * the sorted peer-id set (as {@link ClusterRecord.membershipDigest}) is folded into `messageHash`,
+	 * `promiseHash`, and `commitHash`, so two different peer sets yield two different `messageHash`es.
+	 * New coordinators always emit `2`. See `packages/db-core/src/cluster/membership.ts`.
+	 */
+	membershipVersion?: 1 | 2;
+	/** Membership digest of {@link ClusterRecord.peers}; present iff `membershipVersion === 2`. base64url. */
+	membershipDigest?: string;
 	message: RepoMessage;
 	coordinatingBlockIds?: string[];
 	promises: { [peerId: string]: Signature };
@@ -37,8 +47,18 @@ export type ClusterRecord = {
 	};
 }
 
+/**
+ * Single source of truth for the default super-majority threshold — the fraction of a cluster's peers
+ * that must promise before a transaction may proceed. Every component that falls back to a default when
+ * config is absent (cluster member, coordinator policy, node composition root) references THIS constant,
+ * so a member cannot silently default to a different threshold than the coordinator that commits. Explicit
+ * caller-supplied thresholds are unaffected; this only unifies the *absent-config* default.
+ * 0.75 = 3/4: chosen because the coordinator (which actually commits) already used it and the type documents it.
+ */
+export const DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75;
+
 export interface ClusterConsensusConfig {
-	/** Super-majority threshold for promises (default 0.75 = 3/4) */
+	/** Super-majority threshold for promises (default {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} = 0.75 = 3/4) */
 	superMajorityThreshold: number;
 	/** Simple majority threshold for commits (default 0.51 = >50%) */
 	simpleMajorityThreshold: number;
@@ -48,6 +68,20 @@ export interface ClusterConsensusConfig {
 	allowClusterDownsize: boolean;
 	/** Tolerance for cluster size variance as fraction (default 0.5 = 50%) */
 	clusterSizeTolerance: number;
+	/**
+	 * Configured full cluster size (the responsibility-K). Present so a cluster **member** has its own
+	 * reference for "full size" when running the membership admission gate — a below-full-size declared
+	 * peer set under low derivation confidence is refused (see {@link ClusterMember} admission gate).
+	 * The coordinator supplies this as a required `clusterSize` via `ClusterConsensusConfig & { clusterSize: number }`.
+	 */
+	clusterSize?: number;
+	/**
+	 * Fraction of the member's OWN confident cluster-size estimate a declared peer set must meet to be
+	 * admitted for voting (default 0.75). Below `⌈membershipAdmissionFraction · K_est⌉` a declared set is
+	 * treated as an unjustified self-shrink and the member declines to approve. Distinct from
+	 * {@link superMajorityThreshold} (the vote-counting threshold) — this gates *which set* may be voted on.
+	 */
+	membershipAdmissionFraction?: number;
 	/** Window for detecting partition in milliseconds (default 60000 = 1 min) */
 	partitionDetectionWindow: number;
 	/** Enable dispute escalation protocol (default false) */
@@ -77,10 +111,26 @@ export interface ClusterConsensusConfig {
 	commitBroadcastRetryMaxAttempts?: number;
 	/** Immediate in-line retries per failed peer inside the broadcast (default 1) */
 	commitBroadcastImmediateRetries?: number;
+	/**
+	 * Immediate in-line retries per peer while collecting promises (default 1).
+	 * The promise phase rides the same libp2p stream the commit broadcast does;
+	 * a circuit-relay ("limited") connection can reset that stream once a
+	 * per-circuit cap is hit, surfacing to the coordinator as a StreamResetError.
+	 * Unlike the commit broadcast there is no follow-up scheduled retry, so a
+	 * single reset here would otherwise drop the peer and sink super-majority.
+	 */
+	promiseImmediateRetries?: number;
 	/** Read-repair behavior: 'off' (only fetch on missing — legacy), 'lazy' (fetch when local age > window), 'paranoid' (always verify against cluster on read). Default 'lazy'. */
 	readRepairMode?: 'off' | 'lazy' | 'paranoid';
 	/** For 'lazy' mode: read-repair triggers when (now - localEntry.lastSeenCommitMs) > this. Default 10000. */
 	readRepairWindowMs?: number;
 	/** Per-read probability of triggering read-repair in 'lazy' mode even within the window (0..1). Default 0 (no random check). */
 	readRepairSampleRate?: number;
+	/**
+	 * When FRET has no confident network-size estimate, allow an undersized cluster
+	 * (peerCount < minAbsoluteClusterSize) to proceed anyway. Default false: with no
+	 * confident estimate an undersized cluster is REJECTED. Turn on only for
+	 * single-node / local dev where you knowingly run below the safe floor.
+	 */
+	allowUnvalidatedSmallCluster?: boolean;
 }

package/src/cohort-topic/addressing.ts

@@ -5,9 +5,15 @@
  *
  * ```
  * coord_0(_, topicId) = H(0x00 ‖ topicId)
- * coord_d(P, topicId) = H(d ‖ prefix(P, d·log₂F) ‖ topicId)   for d ≥ 1
+ * coord_d(P, topicId) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)   for d ≥ 1
  * ```
  *
+ * `P` is ring-hashed before the prefix so the shard input is uniformly distributed across
+ * participants (the raw peer-id string bytes share a near-constant `12D3Koo…` prefix that would
+ * collapse all tier-`d` shards to one coordinate). The wire field `participantCoord` keeps the
+ * unmodified peer id so the Ed25519 key remains recoverable; the ring-hash is applied only inside
+ * the addressing math.
+ *
  * `H` is the injected {@link IRingHash} (db-core's own SHA-256 truncated to the ring width — **not**
  * a FRET import). `prefix(P, n)` is the `n` most-significant bits of peer id `P`, left-padded if
  * shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
@@ -24,7 +30,7 @@ export interface TierAddressing {
 	readonly F: number;
 	/** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
 	coord0(topicId: Uint8Array): RingCoord;
-	/** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(peerId, d·log₂F) ‖ topicId)`. */
+	/** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)` where `H(P)` is the ring-hash of `peerId`. */
 	coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
 	/** Dispatches `d === 0` to {@link coord0}, otherwise to {@link coordD}. */
 	coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
@@ -92,8 +98,10 @@ export class HashTierAddressing implements TierAddressing {
 		if (d > 255) {
 			throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
 		}
-		// H(d ‖ prefix(peerId, d·log₂F) ‖ topicId)
-		const prefix = prefixBits(peerId, d * this.log2F);
+		// H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)  — ring-hash P first so the shard input is uniform
+		// NOTE: re-hashes peerId on every coordD call; a walk over a tier ladder recomputes H(self) per
+		// tier. Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
+		const prefix = prefixBits(this.hash.H(peerId), d * this.log2F);
 		const input = new Uint8Array(1 + prefix.length + topicId.length);
 		input[0] = d;
 		input.set(prefix, 1);

package/src/cohort-topic/antidos/bootstrap-evidence.ts

@@ -1,9 +1,14 @@
 /**
  * Cohort-topic substrate — bootstrap evidence policy (anti-DoS).
  *
- * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 4. A cold root that accepts a
- * `bootstrap: true` registration must demand evidence, so a cold topic cannot be instantiated for
- * free by an attacker. The accepted evidence is **tier-dependent**:
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 4. A cold cohort that accepts a cold-start
+ * registration must demand evidence, so a cold topic cannot be instantiated for free by an attacker.
+ * **A follow-on cold-start (`followOn: true`) is gated identically to a root bootstrap
+ * (`bootstrap: true`)**: the cold tier-`(d+1)` child a `Promoted` redirect points at is participant-
+ * asserted (the child cannot infer the redirect — the routing key decorrelates tiers and it holds no
+ * breadcrumb of where the participant came from), so its safety cannot rest on provenance; it rests on
+ * this gate paying the same anti-abuse cost the root already pays. The accepted evidence is
+ * **tier-dependent**:
  *
  * - **T0 / T1** — generally no proof-of-work, because these tiers correspond to committed work; a
  *   *signed reference to a committed parent topic that does exist* is sufficient.
@@ -18,7 +23,7 @@
  * `bootstrapEvidence` field — a versioned `BootstrapEvidenceEnvelopeV1`
  * (`./bootstrap-evidence-envelope.js`), parsed crypto-free here and checked by the injected verifiers;
  * NOT the opaque `appPayload` slot (which the cohort copies verbatim into the registration's appState).
- * A registration that is not a bootstrap needs no evidence and is admitted.
+ * A registration that is neither a bootstrap nor a follow-on cold-start needs no evidence and is admitted.
  */
 
 import type { RegisterV1 } from "../wire/types.js";
@@ -47,9 +52,10 @@ export interface BootstrapEvidenceConfig {
 /** Tier-dependent bootstrap-evidence gate for cold-root registrations. */
 export interface BootstrapEvidence {
 	/**
-	 * Whether `reg` carries acceptable bootstrap evidence for `tier`. A non-bootstrap registration is
-	 * always acceptable (nothing to prove). For a bootstrap: T0/T1 require a signed parent reference;
-	 * T2/T3 accept proof-of-work OR a reputation signature OR a signed parent reference.
+	 * Whether `reg` carries acceptable cold-start evidence for `tier`. A registration that is neither a
+	 * `bootstrap` nor a `followOn` is always acceptable (nothing to prove). For a cold-start (either flag):
+	 * T0/T1 require a signed parent reference; T2/T3 accept proof-of-work OR a reputation signature OR a
+	 * signed parent reference.
 	 */
 	verify(reg: RegisterV1, tier: number): boolean;
 }
@@ -68,8 +74,14 @@ class TieredBootstrapEvidence implements BootstrapEvidence {
 	}
 
 	verify(reg: RegisterV1, tier: number): boolean {
-		if (reg.bootstrap !== true) {
-			return true; // only a cold-root bootstrap must carry evidence
+		// A follow-on cold-start is gated identically to a root bootstrap — both must carry evidence.
+		// NOTE: follow-on cold-start is PoW-gated exactly like a root bootstrap; if a spoofed, PoW-paid
+		// follow-on instantiation ever shows up as real abuse, upgrade to a parent-vouched redirect —
+		// echo the parent cohort's threshold-signed PromotionNoticeV1 on the follow-on and verify it
+		// against the parent's MembershipCertV1 (needs a RegisterReplyV1 field + admission-path membership
+		// verify). See docs/cohort-topic.md §Anti-DoS "follow-on hardening".
+		if (reg.bootstrap !== true && reg.followOn !== true) {
+			return true; // only a cold-start (bootstrap or follow-on) must carry evidence
 		}
 		if (tier <= this.maxNoPowTier) {
 			// T0/T1: a signed reference to a committed parent topic is sufficient (no PoW expected).

package/src/cohort-topic/antidos/replay-guard.ts

@@ -11,6 +11,17 @@
  * Because a stale registration is rejected outright, the guard only needs to remember correlation ids
  * for one `maxAgeMs` window: an id older than that would be rejected on timestamp alone, so its record
  * can be pruned. Pruning runs on access, bounding memory to the live window's worth of registrations.
+ *
+ * On top of the age-based prune, the map carries a **hard LRU `maxKeys` cap** (mirroring the sibling
+ * {@link import("./rate-limiter.js").RegisterRateLimiter}) so a flood of genuinely-fresh, admitted
+ * correlationIds cannot grow `seen` without bound before the age prune fires. When a new id would
+ * exceed the cap, the **oldest-inserted** entries are evicted until within cap. That victim is the
+ * least-bad one: replay entries are inserted once and never refreshed, so `Map` insertion order tracks
+ * timestamp order — the oldest entry is the one nearest to aging out of the window and being pruned as
+ * stale anyway. Evicting it forgives at most that entry's remaining replay-protection window: a bounded,
+ * documented tradeoff (unlike the rate limiter's fully penalty-free eviction), and one that only
+ * triggers under a flood of admitted ids — which, in the register pipeline, must also have passed the
+ * signature, rate, and bootstrap gates before ever reaching this guard.
  */
 
 import { bytesKey } from "../registration/bytes.js";
@@ -22,12 +33,16 @@ const log = createLogger("cohort-topic:antidos");
 export const DEFAULT_REPLAY_MAX_AGE_MS = 60_000;
 /** Default tolerated forward clock skew: a timestamp this far past `now` is rejected as implausible. */
 export const DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS = 5_000;
+/** Default hard cap on remembered correlationIds; the oldest-inserted are evicted beyond this. */
+export const DEFAULT_REPLAY_GUARD_MAX_KEYS = 100_000;
 
 export interface CorrelationReplayGuardConfig {
 	/** A timestamp older than `now − maxAgeMs` is stale. Default {@link DEFAULT_REPLAY_MAX_AGE_MS}. */
 	maxAgeMs?: number;
 	/** A timestamp newer than `now + maxFutureSkewMs` is rejected. Default {@link DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS}. */
 	maxFutureSkewMs?: number;
+	/** Hard LRU cap on remembered correlationIds; oldest-inserted (≈ oldest-timestamp) evicted beyond this. Default {@link DEFAULT_REPLAY_GUARD_MAX_KEYS}. */
+	maxKeys?: number;
 }
 
 /** Freshness + anti-replay gate over registration `correlationId`s and timestamps. */
@@ -39,6 +54,8 @@ export interface CorrelationReplayGuard {
 	 * id on first sight of a fresh registration.
 	 */
 	accept(correlationId: Uint8Array, peerId: Uint8Array, timestamp: number, now: number): boolean;
+	/** Remembered correlationId count (test/diagnostic introspection). */
+	readonly size: number;
 }
 
 /** A remembered acceptance, kept until its timestamp ages out of the window. */
@@ -51,6 +68,7 @@ class WindowedReplayGuard implements CorrelationReplayGuard {
 	private readonly seen = new Map<string, SeenEntry>();
 	private readonly maxAgeMs: number;
 	private readonly maxFutureSkewMs: number;
+	private readonly maxKeys: number;
 	/** `now` of the last prune, so pruning amortizes rather than scanning on every call. */
 	private lastPruneAt = -Infinity;
 
@@ -63,6 +81,10 @@ class WindowedReplayGuard implements CorrelationReplayGuard {
 		if (!(this.maxFutureSkewMs >= 0)) {
 			throw new RangeError(`maxFutureSkewMs must be >= 0, got ${this.maxFutureSkewMs}`);
 		}
+		this.maxKeys = config.maxKeys ?? DEFAULT_REPLAY_GUARD_MAX_KEYS;
+		if (!Number.isInteger(this.maxKeys) || this.maxKeys <= 0) {
+			throw new RangeError(`maxKeys must be a positive integer, got ${this.maxKeys}`);
+		}
 	}
 
 	accept(correlationId: Uint8Array, peerId: Uint8Array, timestamp: number, now: number): boolean {
@@ -83,6 +105,17 @@ class WindowedReplayGuard implements CorrelationReplayGuard {
 			log("replay-guard reject: replayed correlationId (first seen from peer=%s)", prior.peer);
 			return false; // replay
 		}
+		// New id: enforce the hard cap by evicting the oldest-inserted entries (oldest by `Map` insertion
+		// order) until this insertion stays within `maxKeys`. Since entries are inserted once and never
+		// refreshed, insertion order closely tracks timestamp order, so the victim is ≈ the oldest-timestamp
+		// — nearest to aging out as stale. (It is only ≈: ids from distinct peers can arrive out of
+		// timestamp order within the skew window, so a victim may retain slightly more window than a
+		// strictly-oldest pick. The forgiveness bound — at most one entry's remaining window — holds either way.)
+		while (this.seen.size >= this.maxKeys) {
+			const oldest = this.seen.keys().next().value;
+			if (oldest === undefined) break;
+			this.seen.delete(oldest);
+		}
 		this.seen.set(key, { timestamp, peer: bytesKey(peerId) });
 		return true;
 	}
@@ -101,6 +134,10 @@ class WindowedReplayGuard implements CorrelationReplayGuard {
 			}
 		}
 	}
+
+	get size(): number {
+		return this.seen.size;
+	}
 }
 
 /** Build a {@link CorrelationReplayGuard} over the configured staleness window and forward skew. */

package/src/cohort-topic/antidos/topic-budget.ts

@@ -26,6 +26,13 @@ export const DEFAULT_TOPICS_MAX = 2048;
 export interface TopicBudgetConfig {
 	/** Max topics with forwarder state. Default {@link DEFAULT_TOPICS_MAX}. */
 	topicsMax?: number;
+	/**
+	 * Called with the evicted topic's id just before its slot is freed in {@link TopicBudget.admit}, so
+	 * the caller can tear down the now-unbacked forwarder + traffic window that outlives the slot. Fires
+	 * only for a genuine eviction (a zero-participant victim), never for a plain admit, an already-resident
+	 * re-admit, or a refusal. Absent → no teardown hook.
+	 */
+	onEvict?: (topicId: Uint8Array) => void;
 }
 
 /** Per-cohort cap on the number of topics with forwarder state, with LRU eviction of cold topics. */
@@ -60,11 +67,14 @@ interface ResidentState {
 	participantCount: number;
 	/** Monotonic access sequence (LRU tiebreaker; lower = least-recently used). */
 	seq: number;
+	/** The original topic-id bytes, captured on admit so `onEvict` can be handed real bytes (residents key by string). */
+	topicId: Uint8Array;
 }
 
 class LruTopicBudget implements TopicBudget {
 	private readonly residents = new Map<string, ResidentState>();
 	private readonly topicsMax: number;
+	private readonly onEvict?: (topicId: Uint8Array) => void;
 	private seqCounter = 0;
 
 	constructor(config: TopicBudgetConfig = {}) {
@@ -72,6 +82,7 @@ class LruTopicBudget implements TopicBudget {
 		if (!Number.isInteger(this.topicsMax) || this.topicsMax <= 0) {
 			throw new RangeError(`topicsMax must be a positive integer, got ${this.topicsMax}`);
 		}
+		this.onEvict = config.onEvict;
 	}
 
 	get size(): number {
@@ -94,7 +105,7 @@ class LruTopicBudget implements TopicBudget {
 			return true;
 		}
 		if (this.residents.size < this.topicsMax) {
-			this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+			this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter, topicId });
 			return true;
 		}
 		// Full: only a zero-participant resident may be evicted to make room for a new topic.
@@ -103,8 +114,12 @@ class LruTopicBudget implements TopicBudget {
 			log("topic-budget full size=%d max=%d — refuse new topic", this.residents.size, this.topicsMax);
 			return false;
 		}
+		// Fire the teardown hook with the victim's real bytes BEFORE freeing the slot, so the callback
+		// (drop the now-unbacked forwarder + traffic window) sees a coherent state. Only a genuine
+		// eviction reaches here — `coldestEvictable()` already refused a full-of-populated budget above.
+		this.onEvict?.(this.residents.get(victim)!.topicId);
 		this.residents.delete(victim);
-		this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter });
+		this.residents.set(key, { participantCount: 0, seq: ++this.seqCounter, topicId });
 		log("topic-budget evicted cold topic to admit new (size=%d max=%d)", this.residents.size, this.topicsMax);
 		return true;
 	}

package/src/cohort-topic/coldstart.ts

@@ -11,18 +11,22 @@
  *   cold-start case) **or** it arrived as a follow-on to a parent cohort's `Promoted` redirect, AND
  * - a quorum of cohort members is willing to serve `T` at the registration's tier.
  *
- * The `followOn` signal is **not** carried on the wire (`RegisterV1` has only `bootstrap`); a cold
- * high-tier cohort returns `NoState` to a *speculative* `d_max` probe, but the single-direction walk
- * means the only registrations that reach a cold tier-`(d+1)` cohort are those that followed the
- * parent's `Promoted` redirect. Determining `followOn` for a given inbound register therefore belongs
- * to the db-p2p cohort host (it has the routing context); db-core takes it as an explicit input to
- * {@link shouldInstantiate}, keeping this module FRET-free. (See the implement handoff for the wiring
- * gap this leaves for the db-p2p binding.)
+ * The `followOn` signal **is** carried on the wire (`RegisterV1.followOn`), set only on the dedicated
+ * re-issue a participant sends after a parent cohort's `Promoted` redirect target answered `NoState`
+ * (the deeper child is cold). A cold high-tier cohort still returns `NoState` to a *speculative* `d_max`
+ * probe (neither flag set), but the single-direction walk means the only registrations that reach a cold
+ * tier-`(d+1)` cohort carrying `followOn: true` are those that followed the parent's `Promoted` redirect.
+ * The db-p2p cohort host derives `ctx.followOn` from the wire flag (`followOn: reg.followOn === true`) and
+ * db-core takes it as an explicit input to {@link shouldInstantiate}, keeping this module FRET-free. Because
+ * the flag is participant-forgeable, a `followOn: true` register is gated by the **same** tier-dependent
+ * bootstrap-evidence policy a `bootstrap: true` cold-root register passes (§Anti-DoS), so an unbacked
+ * follow-on never reaches this instantiation decision.
  *
  * Once instantiated, the new forwarder **registers itself with its tier-`(d − 1)` parent at first
- * opportunity**; until that registration is acked it {@link Forwarder.acceptsParticipants | accepts
- * participants} but {@link Forwarder.servesParentOps | holds} notifications/queries that need parent
- * involvement. The root (tree tier 0) has no parent and is serving immediately.
+ * opportunity** by sending a child-link the parent authenticates + records; until that link is acked
+ * (`linked`) it {@link Forwarder.acceptsParticipants | accepts participants} but
+ * {@link Forwarder.servesParentOps | holds} notifications/queries that need parent involvement. The root
+ * (tree tier 0) has no parent and is serving immediately.
  *
  * **Just-promoted burst (GROUNDING-resolved: bounce, don't buffer).** A cohort that has just promoted
  * but whose tier-`(d+1)` isn't fully instantiated yet, on a burst of new same-tier registrations,
@@ -34,6 +38,9 @@
 import { attachTopicTraffic } from "./traffic.js";
 import { bytesKey } from "./registration/bytes.js";
 import type { RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('cohort-topic:coldstart');
 
 /** Inputs to the cold-start admission gate. */
 export interface ColdStartTrigger {
@@ -130,13 +137,18 @@ export function promotedRedirectReply(targetTier: number, traffic?: TopicTraffic
 	return traffic !== undefined ? attachTopicTraffic(reply, traffic) : reply;
 }
 
-/** Registers a newly-instantiated forwarder with its tier-`(d − 1)` parent; resolves on the parent ack. */
+/**
+ * Registers a newly-instantiated forwarder with its tier-`(d − 1)` parent; resolves only when the parent
+ * authenticates + records the child and returns a `linked` ack. A `rejected` reply (bad coord binding /
+ * failed threshold verify) or an unreachable parent rejects the promise, so the forwarder stays
+ * `awaiting_parent` for a later retry.
+ */
 export interface ParentRegistrar {
 	/**
 	 * Register the forwarder for `topicId` (served at tree tier `tier`, i.e. `d`) with the cohort at
-	 * `parentCoord`; resolves on ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so the
-	 * transport can stamp a well-formed forwarder-link frame; absent when the caller has no op-tier
-	 * context (the cohort host always supplies it from the instantiating `RegisterV1`).
+	 * `parentCoord`; resolves on a `linked` ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so
+	 * the transport can stamp a well-formed child-link frame; absent when the caller has no op-tier context
+	 * (the cohort host always supplies it from the instantiating `RegisterV1`).
 	 */
 	registerWithParent(topicId: Uint8Array, parentCoord: Uint8Array, tier: number, opTier?: number): Promise<void>;
 }
@@ -161,6 +173,17 @@ export interface ColdStartManager {
 	instantiate(topicId: Uint8Array, tier: number, parentCoord?: Uint8Array, opTier?: number): Forwarder;
 	/** The tracked forwarder for `topicId`, or `undefined`. */
 	get(topicId: Uint8Array): Forwarder | undefined;
+	/**
+	 * Drop the forwarder for `topicId` (budget eviction / teardown). Idempotent; a no-op if the topic is
+	 * not tracked. After this, {@link get} returns `undefined` for `topicId`, so the cohort no longer
+	 * reports serving it via cold-start state.
+	 */
+	remove(topicId: Uint8Array): void;
+	/**
+	 * Whether this manager currently tracks any forwarder. The host's idle-engine eviction reads this to
+	 * avoid reclaiming a cohort that holds a live (possibly `awaiting_parent`) cold-start forwarder.
+	 */
+	hasForwarders(): boolean;
 }
 
 class TrackingColdStartManager implements ColdStartManager {
@@ -187,7 +210,7 @@ class TrackingColdStartManager implements ColdStartManager {
 				.registerWithParent(topicId, parentCoord, tier, opTier)
 				.then(() => forwarder.onParentAck())
 				.catch((err: unknown) => {
-					console.warn(`cohort-topic cold-start: parent registration for tier-${tier} forwarder failed`, err);
+					log('WARN: parent registration for tier-%s forwarder failed %o', tier, err);
 				});
 		}
 		return forwarder;
@@ -196,6 +219,16 @@ class TrackingColdStartManager implements ColdStartManager {
 	get(topicId: Uint8Array): Forwarder | undefined {
 		return this.forwarders.get(bytesKey(topicId));
 	}
+
+	remove(topicId: Uint8Array): void {
+		// Idempotent: `Map.delete` on an absent key is a safe no-op, so a double-remove (or a remove of a
+		// never-instantiated topic) does nothing.
+		this.forwarders.delete(bytesKey(topicId));
+	}
+
+	hasForwarders(): boolean {
+		return this.forwarders.size > 0;
+	}
 }
 
 /** Build a {@link ColdStartManager} over the injected parent registrar. */

package/src/cohort-topic/gossip/bus.ts

@@ -25,9 +25,10 @@
 
 import { bytesEqual, bytesKey } from "../registration/bytes.js";
 import type { RegistrationStore } from "../registration/types.js";
+import { clampTtl } from "../registration/types.js";
 import type { ICohortGossipTransport, PeerRef, RingCoord } from "../ports.js";
 import { b64urlToBytes, decodeCohortGossipV1, encodeCohortMessage } from "../wire/codec.js";
-import type { CohortGossipV1 } from "../wire/types.js";
+import type { ChildLinkRefV1, CohortGossipV1 } from "../wire/types.js";
 import { fromGossipRecord } from "./records.js";
 import { createCohortView, type CohortView, type MutableCohortView } from "./view.js";
 
@@ -70,6 +71,17 @@ export interface CohortGossipBusDeps {
 	 * callback so this gossip/replication module carries no anti-DoS dependency. Absent → skipped.
 	 */
 	onRecordsEvicted?: (topicIds: readonly Uint8Array[]) => void;
+	/**
+	 * Optional hook fired for the child-cohort link/unlink deltas on an inbound frame (db-p2p merges them into
+	 * this coord's child registry, last-writer-wins by `effectiveAt`), so every parent member converges on the
+	 * same child set — not only the FRET-routed member that recorded the child. Fired for **our-coord** frames
+	 * regardless of epoch match: the child set is keyed by child coord, not the parent's epoch, so a parent
+	 * membership rotation (an epoch drift) must not skip the merge (unlike record deltas, whose slot
+	 * assignments are epoch-scoped). The merge is a direct registry write — it does **not** re-enqueue the
+	 * delta, so a received link/unlink is not re-gossiped (one broadcast reaches the whole cohort). Kept as a
+	 * decoupled callback so this module carries no child-registry dependency. Absent → skipped.
+	 */
+	onChildDeltas?: (childLinks: readonly ChildLinkRefV1[], childUnlinks: readonly ChildLinkRefV1[]) => void;
 }
 
 /** Intra-cohort gossip bus (merge logic over an injected transport). */
@@ -134,6 +146,14 @@ class TransportCohortGossipBus implements CohortGossipBus {
 		if (epochMatches) {
 			this.mergeRecords(g, now);
 		}
+		// Child link/unlink deltas merge regardless of epoch match: the child set is keyed by child coord, not
+		// the parent's epoch, so a rotation (epoch drift) must not drop it. Freshness (last-writer-wins by
+		// effectiveAt) lives in the registry the callback writes.
+		const childLinks = g.childLinks ?? [];
+		const childUnlinks = g.childUnlinks ?? [];
+		if (this.deps.onChildDeltas !== undefined && (childLinks.length > 0 || childUnlinks.length > 0)) {
+			this.deps.onChildDeltas(childLinks, childUnlinks);
+		}
 	}
 
 	view(): CohortView {
@@ -180,6 +200,11 @@ class TransportCohortGossipBus implements CohortGossipBus {
 	private mergeRecords(g: CohortGossipV1, now: number): void {
 		for (const gr of g.records ?? []) {
 			const incoming = fromGossipRecord(gr);
+			// Gossip is a second admission path into the store — a peer (buggy, unpatched, or hostile)
+			// can replicate a record whose TTL never passed local `accept()`'s clamp. Re-clamp here so
+			// no replica can hold an unbounded lifetime that wedges the topic budget. Clamp BEFORE the
+			// dead-check below so a poison TTL cannot dodge staleness eviction.
+			incoming.ttl = clampTtl(incoming.ttl);
 			// A record already past its TTL is dead; merging it would resurrect a registration the
 			// owner has (or soon will have) evicted. Drop it, matching `store.evictStale`'s predicate
 			// so replication can never reintroduce what local eviction removes.
@@ -200,7 +225,19 @@ class TransportCohortGossipBus implements CohortGossipBus {
 		let evictedTopics: Map<string, Uint8Array> | undefined;
 		for (const ref of g.evicted ?? []) {
 			const topicId = b64urlToBytes(ref.topicId);
-			this.deps.store.delete(topicId, b64urlToBytes(ref.participantId));
+			const participantId = b64urlToBytes(ref.participantId);
+			// NOTE: freshness guard adds one getByParticipant per eviction ref (on top of the delete's own
+			// lookup); evictions are low-volume, but if this path ever shows as hot, fold the guard into a
+			// single conditional-delete store op.
+			const held = this.deps.store.getByParticipant(topicId, participantId);
+			// A stale eviction (older than the held record) must not delete a fresher re-registration.
+			// Evictions are otherwise NOT last-writer-wins like merges are, so a reordered/slow delta would
+			// win against a record the participant already renewed. Skip it — and, since nothing drained,
+			// do NOT add the topic to `evictedTopics` (no delete → no budget re-touch).
+			if (held !== undefined && held.lastPing > ref.lastPing) {
+				continue;
+			}
+			this.deps.store.delete(topicId, participantId);
 			if (this.deps.onRecordsEvicted !== undefined) {
 				(evictedTopics ??= new Map()).set(bytesKey(topicId), topicId);
 			}