@optimystic/db-core 0.14.1 → 0.16.2

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

@@ -21,6 +21,14 @@ export interface MemberContribution {
 	readonly windowSeconds: number;
 	/** Exact per-topic summaries this member last reported. */
 	readonly topicSummaries: readonly CohortTopicSummary[];
+	/**
+	 * `topicId` (base64url) → summary, derived from {@link topicSummaries} at {@link MutableCohortView.merge}
+	 * so a per-topic reader (traffic `snapshot`) does an O(1) lookup instead of an O(summaries) `.find` per
+	 * member per reply. First occurrence wins on a duplicate `topicId` (matching `Array.prototype.find`).
+	 * Populated by `merge`; a contribution built without going through `merge` may omit it, in which case
+	 * consumers fall back to scanning {@link topicSummaries}.
+	 */
+	readonly topicIndex?: ReadonlyMap<string, CohortTopicSummary>;
 	/** Gossip timestamp (unix ms) — the last-writer-wins key. */
 	readonly timestamp: number;
 }
@@ -55,11 +63,28 @@ class MapCohortView implements MutableCohortView {
 		if (held !== undefined && c.timestamp < held.timestamp) {
 			return false; // stale; keep the newer contribution
 		}
-		this.byMember.set(member, c);
+		// Derive the per-topic index once, at write time, so per-topic readers never rescan the flat
+		// `topicSummaries` array per reply. A writer pays O(summaries) once per merge (gossip round).
+		this.byMember.set(member, { ...c, topicIndex: indexTopics(c.topicSummaries) });
 		return true;
 	}
 }
 
+/**
+ * Index a member's flat topic summaries by `topicId` (base64url). First occurrence wins on a duplicate
+ * `topicId`, exactly matching the `Array.prototype.find` scan this replaces — so a snapshot over the index
+ * returns identical numbers to one over the array.
+ */
+function indexTopics(summaries: readonly CohortTopicSummary[]): ReadonlyMap<string, CohortTopicSummary> {
+	const index = new Map<string, CohortTopicSummary>();
+	for (const s of summaries) {
+		if (!index.has(s.topicId)) {
+			index.set(s.topicId, s);
+		}
+	}
+	return index;
+}
+
 /** Construct an empty {@link MutableCohortView}. */
 export function createCohortView(): MutableCohortView {
 	return new MapCohortView();

package/src/cohort-topic/member-engine.ts

@@ -5,8 +5,9 @@
  * on it (the activity callback in `docs/cohort-topic.md` §FRET integration). It is the cohort-facing
  * half of the substrate, composed from the prereq tickets' pure modules — the participant-facing half
  * lives in {@link import("./service.js").CohortTopicService}. db-p2p's FRET host decodes an inbound
- * frame, supplies the routing context this module can't see (`followOn`, the quorum-willing tally),
- * and serializes whatever reply this returns back over the wire. db-core never imports FRET here.
+ * frame, supplies the routing context this module can't see (`followOn` — derived from the wire
+ * `RegisterV1.followOn` flag, evidence-gated in step 1 — plus the quorum-willing tally), and serializes
+ * whatever reply this returns back over the wire. db-core never imports FRET here.
  *
  * Inbound `RegisterV1` decision pipeline (§Registration mechanics, §Willingness, §Cold-start):
  *
@@ -26,7 +27,7 @@
 import type { IRingHash } from "./ports.js";
 import { bytesEqual, bytesKey } from "./registration/bytes.js";
 import type { RegistrationRecord, RegistrationStore } from "./registration/types.js";
-import { DEFAULT_TTL_MS } from "./registration/types.js";
+import { clampTtl } from "./registration/types.js";
 import type { SlotAssigner } from "./registration/sharding.js";
 import type { RenewalCohortSide } from "./registration/renewal.js";
 import type { WillingnessCheck } from "./willingness.js";
@@ -47,7 +48,13 @@ import type { DemotionNoticeV1, PromotionNoticeV1, RegisterReplyV1, RegisterV1,
 
 /** Routing context the FRET host supplies for an inbound register (db-core can't derive it). */
 export interface RegisterContext {
-	/** Did this register arrive as a follow-on to a parent cohort's `Promoted` redirect? */
+	/**
+	 * Did this register arrive as a follow-on to a parent cohort's `Promoted` redirect? The host derives
+	 * this from the wire `RegisterV1.followOn` flag (`followOn: reg.followOn === true`). It is participant-
+	 * asserted and therefore evidence-gated: `runGuards` (step 1) already ran `bootstrapEvidence.verify`,
+	 * which demands the same proof for `followOn: true` as for `bootstrap: true`, so an unbacked follow-on
+	 * never reaches this instantiation decision (it short-circuited to `unwilling_cohort`).
+	 */
 	readonly followOn: boolean;
 	/** Tree tier `d` this cohort serves the topic at (the walk position the register landed on). */
 	readonly treeTier: number;
@@ -172,7 +179,10 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
 			return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
 		}
 
-		// 3. Cold path: instantiate only at a legitimate growth point with a willing quorum.
+		// 3. Cold path: instantiate only at a legitimate growth point with a willing quorum. `ctx.followOn`
+		//    mirrors the wire `reg.followOn` flag (the host derives it), and by the time we reach here the
+		//    step-1 bootstrap-evidence gate has already verified a `followOn: true` carries the same proof a
+		//    `bootstrap: true` root cold-start carries — so this branch never instantiates an unbacked follow-on.
 		const quorumWilling = this.deps.quorumWilling(tier);
 		if (!shouldInstantiate({ bootstrap: reg.bootstrap === true, followOn: ctx.followOn, quorumWilling })) {
 			return { v: 1, result: "no_state" };
@@ -310,7 +320,7 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
 	): Promise<RegisterReplyV1> {
 		const { members, cohortEpoch } = this.deps.cohort();
 		const { primary, backups } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
-		const ttl = reg.ttl > 0 ? reg.ttl : DEFAULT_TTL_MS;
+		const ttl = clampTtl(reg.ttl);
 		const record: RegistrationRecord = {
 			topicId,
 			participantId,
@@ -368,21 +378,32 @@ class StoreCohortMemberEngine implements CohortMemberEngine {
 	): RegisterReplyV1 | undefined {
 		if (this.deps.verifyRegisterSig?.(reg) === false) {
 			// Unsigned / forged participant signature: serve nothing and record nothing (the cohort
-			// cannot trust this participantCoord). Checked before the replay/rate guards so a forged
-			// frame cannot consume their state.
+			// cannot trust this participantCoord). Cheap + stateless, so checked first — a forged frame
+			// cannot consume any downstream guard state.
 			return { v: 1, result: "no_state" };
 		}
-		const correlationId = b64urlToBytes(reg.correlationId);
-		if (this.deps.replayGuard?.accept(correlationId, participantId, reg.timestamp, now) === false) {
-			// Stale / future-skewed / replayed: serve nothing and record nothing.
-			return { v: 1, result: "no_state" };
+		// Rate-check BEFORE the replay guard records anything: a fresh-correlationId spam frame that the
+		// rate limiter would reject must not first insert a `seen` entry (which would let an attacker grow
+		// the replay guard's memory at full attack speed regardless of the rate limit). Running it before
+		// the potentially-expensive bootstrap verify (which may do PoW) also short-circuits floods sooner.
+		// NOTE: a replayed frame now consumes a rate-limiter accept before the replay guard (below) drops it,
+		// whereas the old order dropped replays pre-rate. Fine for spam (inbound traffic should be counted);
+		// only matters if a legitimate client reuses one correlationId across retransmits — it would then
+		// burn rate budget per retransmit. If clients adopt idempotent same-cid retry, revisit this order.
+		const rate = this.deps.rateLimiter?.check(participantId, topicId, now);
+		if (rate !== undefined && rate.ok === false) {
+			return { v: 1, result: "unwilling_cohort", retryAfterMs: rate.retryAfterMs };
 		}
 		if (this.deps.bootstrapEvidence?.verify(reg, tier) === false) {
 			return this.unwillingCohort(reg, now);
 		}
-		const rate = this.deps.rateLimiter?.check(participantId, topicId, now);
-		if (rate !== undefined && rate.ok === false) {
-			return { v: 1, result: "unwilling_cohort", retryAfterMs: rate.retryAfterMs };
+		// Replay guard records LAST, so only frames that passed signature + rate + bootstrap ever insert a
+		// `seen` entry. An *accepted* frame is still always recorded here, so a genuine replay of a served
+		// correlationId is still caught; only rate-rejected frames (never served, never recorded) skip it.
+		const correlationId = b64urlToBytes(reg.correlationId);
+		if (this.deps.replayGuard?.accept(correlationId, participantId, reg.timestamp, now) === false) {
+			// Stale / future-skewed / replayed: serve nothing and record nothing.
+			return { v: 1, result: "no_state" };
 		}
 		return undefined;
 	}

package/src/cohort-topic/membership/publisher.ts

@@ -4,20 +4,21 @@
  * Per `docs/cohort-topic.md` §Membership snapshots: the cohort publishes a threshold-signed
  * `MembershipCertV1`
  *
- * - at stabilization, and on any change to the first `k − x` members ({@link MembershipCertPublisher.onStabilized});
+ * - at stabilization, and on any change to the cohort identity — the epoch `H(sorted all members)`,
+ *   so *any* member change (head or tail) forces a fresh publish ({@link MembershipCertPublisher.onStabilized});
  * - refreshed every `T_membership_refresh` (default 5 min) ({@link MembershipCertPublisher.tick}).
  *
  * The publisher is db-core logic over the {@link CohortSigner} (threshold sign) and the
  * {@link IMembershipPublishSink} (serve/advertise). It never imports FRET. Members are sorted
- * ascending for the cert (matching the sharding order) and the first `minSigs` (= `k − x`) of that
- * order are the "first `k − x`" whose change forces a fresh publish.
+ * ascending for the cert (matching the sharding order); the snapshot's `cohortEpoch` is the full
+ * cohort identity, and a change to it across a publish forces a fresh publish.
  */
 
 import type { IMembershipPublishSink } from "../ports.js";
 import { bytesToB64url, encodeCohortMessage } from "../wire/codec.js";
 import type { MembershipCertV1 } from "../wire/types.js";
 import { compareBytes } from "../registration/bytes.js";
-import { DEFAULT_MIN_SIGS, type CohortSigner } from "../sig/threshold.js";
+import { type CohortSigner } from "../sig/threshold.js";
 import { membershipCertSigningPayload, type MembershipCertSignable } from "../sig/payloads.js";
 
 /** Default membership-cert refresh interval (`T_membership_refresh`). */
@@ -74,10 +75,11 @@ export interface RotationAttestation {
 /** Cohort-side membership-cert publisher. */
 export interface MembershipCertPublisher {
 	/**
-	 * Drive publication on a stabilization event. Publishes (and returns the cert) when the first
-	 * `k − x` members changed since the last publish, or on the first call; otherwise returns `undefined`.
-	 * Pass `rotation` to attach a predecessor-cohort rotation attestation (an epoch rotation); omit it for
-	 * the default non-rotation publish (no rotation fields are emitted).
+	 * Drive publication on a stabilization event. Publishes (and returns the cert) when the cohort identity
+	 * (`cohortEpoch = H(sorted members)`) changed since the last publish — i.e. on **any** member change,
+	 * head or tail — or on the first call; otherwise returns `undefined`. Pass `rotation` to attach a
+	 * predecessor-cohort rotation attestation (an epoch rotation); omit it for the default non-rotation
+	 * publish (no rotation fields are emitted).
 	 */
 	onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
 	/**
@@ -91,26 +93,33 @@ export interface MembershipCertPublisherDeps {
 	signer: CohortSigner;
 	sink: IMembershipPublishSink;
 	refreshMs?: number;
+	/**
+	 * Accepted for call-site compatibility but no longer read by the publisher: the republish gate now keys
+	 * on the full `cohortEpoch`, not the first `k − x` members, and the threshold-sign quorum lives in the
+	 * {@link CohortSigner}. Kept so existing callers (host + db-p2p tests) compile unchanged.
+	 */
 	minSigs?: number;
 	maxMessageBytes?: number;
 }
 
 class SigningMembershipCertPublisher implements MembershipCertPublisher {
 	private readonly refreshMs: number;
-	private readonly minSigs: number;
-	/** base64url of the first `minSigs` members of the last published snapshot. */
-	private lastFirstKx: string[] | undefined;
+	/** base64url of the last published snapshot's `cohortEpoch` — the full cohort-identity republish key. */
+	private lastEpoch: string | undefined;
 	private lastPublishedAt: number | undefined;
 
 	constructor(private readonly deps: MembershipCertPublisherDeps) {
 		this.refreshMs = deps.refreshMs ?? DEFAULT_T_MEMBERSHIP_REFRESH_MS;
-		this.minSigs = deps.minSigs ?? DEFAULT_MIN_SIGS;
 	}
 
 	async onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined> {
-		const firstKx = this.firstKx(snapshot.members);
-		if (this.lastFirstKx !== undefined && sameOrder(this.lastFirstKx, firstKx)) {
-			return undefined; // first k − x unchanged — no republish needed
+		// NOTE: republish (and the caller's rotation attestation) now fire on ANY epoch change — any member
+		// change, head or tail — not just first-(k − x) churn. Gated on an actual epoch change, never per
+		// tick, so cost is bounded by real churn. If a high-churn cohort ever shows excess `/sign` or publish
+		// load, reconsider a short debounce / batching here.
+		const epoch = bytesToB64url(snapshot.cohortEpoch);
+		if (this.lastEpoch !== undefined && this.lastEpoch === epoch) {
+			return undefined; // cohort identity unchanged — no republish needed
 		}
 		return this.publish(snapshot, now, rotation);
 	}
@@ -122,11 +131,6 @@ class SigningMembershipCertPublisher implements MembershipCertPublisher {
 		return this.publish(snapshot, now, rotation);
 	}
 
-	/** The first `minSigs` members of the cert's ascending order, base64url — the republish-change key. */
-	private firstKx(members: readonly Uint8Array[]): string[] {
-		return [...members].sort(compareBytes).slice(0, this.minSigs).map(bytesToB64url);
-	}
-
 	private async publish(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1> {
 		const signable = membershipCertSignable(snapshot);
 		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(membershipCertSigningPayload(signable));
@@ -147,24 +151,12 @@ class SigningMembershipCertPublisher implements MembershipCertPublisher {
 			cert.rotationSigners = rotation.rotationSigners.map(bytesToB64url);
 		}
 		this.deps.sink.publish(encodeCohortMessage(cert, this.deps.maxMessageBytes));
-		this.lastFirstKx = signable.members.slice(0, this.minSigs);
+		this.lastEpoch = bytesToB64url(snapshot.cohortEpoch);
 		this.lastPublishedAt = now;
 		return cert;
 	}
 }
 
-function sameOrder(a: readonly string[], b: readonly string[]): boolean {
-	if (a.length !== b.length) {
-		return false;
-	}
-	for (let i = 0; i < a.length; i++) {
-		if (a[i] !== b[i]) {
-			return false;
-		}
-	}
-	return true;
-}
-
 /** Build a cohort-side {@link MembershipCertPublisher}. */
 export function createMembershipCertPublisher(deps: MembershipCertPublisherDeps): MembershipCertPublisher {
 	return new SigningMembershipCertPublisher(deps);

package/src/cohort-topic/membership/verifier.ts

@@ -52,6 +52,15 @@ import type { MembershipCertV1 } from "../wire/types.js";
 import { DEFAULT_MIN_SIGS, type CohortSigner } from "../sig/threshold.js";
 import { membershipCertSigningPayload } from "../sig/payloads.js";
 import type { IMembershipSourceRouter } from "./source.js";
+import { LruMap } from "../../utility/lru-map.js";
+
+/**
+ * Default hard cap on distinct coords the verifier's per-coord maps retain (`byCoord`, `lastFetchAt`,
+ * `staleGapStrikes`). Beyond it the least-recently-used coord is evicted — bounding memory under a flood
+ * of verify-misses against attacker-chosen coords. Same 100k ballpark as the sibling anti-DoS caps
+ * ({@link import("../antidos/replay-guard.js").DEFAULT_REPLAY_GUARD_MAX_KEYS}).
+ */
+export const DEFAULT_MEMBERSHIP_VERIFIER_MAX_COORDS = 100_000;
 
 /** Outcome of verifying a threshold-signed message against cohort membership. */
 export type VerifyResult = "verified" | "untrusted";
@@ -99,6 +108,34 @@ export interface MembershipVerifierDeps {
 	anchor?: IMembershipTrustAnchor;
 	/** Out-of-band-seeded genesis trust roots (the base case of every attestation chain). Defaults to `[]`. */
 	trustRoots?: readonly TrustRoot[];
+	/**
+	 * Number of **consecutive** gap-signalled refetches after which a **trust-locked** coord whose direct
+	 * anchor has gone `"unknown"` re-enters the interim TOFU regime — the exit from a stale trust-lock a
+	 * former cohort member would otherwise be stranded in until the host process restarts.
+	 *
+	 * The lock (a coord holding a *trusted* cached cert refuses any un-anchored refetch — no TOFU downgrade)
+	 * has no other exit: a node that served coord `C`, self-published its cert (locking `C`), then left `C`'s
+	 * cohort keeps distrusting every later-epoch message from `C` if it missed an intermediate rotation, since
+	 * the refetched cert's `prevEpoch` no longer matches the stale cached epoch and the anchor no longer
+	 * vouches for `C`. Recovery counts **only** refetched certs presenting an *explicit chain gap* — a full
+	 * rotation attestation whose `prevEpoch ≠` the cached trusted epoch (the network provably rotated past the
+	 * cached epoch through an epoch this node never witnessed). A forged rotation off the *current* cached
+	 * predecessor (`prevEpoch == cachedEpoch`) never counts as a strike, so the lock's headline invariant
+	 * (un-anchored successor of a matching predecessor stays rejected) is preserved.
+	 *
+	 * Defaults to `3`. Setting it to `0` (or a negative) **disables** recovery — which re-opens the stale-lock
+	 * liveness bug, so leave it on unless a caller has an independent lock-drop mechanism (see the
+	 * drop-the-lock-on-demotion tripwire in the ticket).
+	 */
+	staleGapRecoveryStrikes?: number;
+	/**
+	 * Hard LRU cap on distinct coords retained across the verifier's per-coord maps (`byCoord`,
+	 * `lastFetchAt`, `staleGapStrikes`); the least-recently-used coord is evicted beyond it. Bounds memory
+	 * under a flood of verify-misses against attacker-chosen coords. Defaults to
+	 * {@link DEFAULT_MEMBERSHIP_VERIFIER_MAX_COORDS}; must be a positive integer (mirrors the sibling
+	 * anti-DoS `maxKeys` guard).
+	 */
+	maxCoords?: number;
 }
 
 /** Result of the trust gate: accept as a trusted anchor, accept as interim TOFU, or reject outright. */
@@ -119,17 +156,40 @@ interface NormalizedTrustRoot {
 }
 
 class CachingMembershipVerifier implements MembershipVerifier {
-	private readonly byCoord = new Map<string, CachedCert>();
+	// LRU-capped so a flood of verify-misses against attacker-chosen coords cannot grow these maps without
+	// bound (coordKey is base64url of an attacker-derivable RingCoord). Each is capped INDEPENDENTLY: the
+	// aux maps may briefly retain a coord `byCoord` already evicted — harmless (a stale `lastFetchAt` at
+	// worst permits one extra refetch; a stale strike count is itself bounded).
+	// NOTE: `byCoord` also holds this node's OWN `cache()`-published trusted cert (the trust lock). Under an
+	// attacker-coord flood the LRU can evict a trusted self-published entry, re-opening that coord to TOFU on
+	// next sight — the trust lock is best-effort under memory pressure. This mirrors the documented penalty
+	// tradeoff on the replay-guard cap and is acceptable; do not file it as a separate ticket.
+	private readonly byCoord: LruMap<string, CachedCert>;
 	/** Per-coord timestamp of the last `source.fetch()` attempt (the rate-limit clock for {@link RefetchBound}). */
-	private readonly lastFetchAt = new Map<string, number>();
+	private readonly lastFetchAt: LruMap<string, number>;
+	/**
+	 * Per-coord count of *consecutive* gap-signalled refetches against a trust-locked coord (base64url key).
+	 * Reset to zero whenever a message verifies for the coord (see {@link verifyMessage}); at
+	 * {@link staleGapRecoveryStrikes} the lock is released back to TOFU (see {@link staleGapRecovery}).
+	 */
+	private readonly staleGapStrikes: LruMap<string, number>;
 	private readonly minSigs: number;
 	private readonly anchor: IMembershipTrustAnchor;
 	private readonly trustRoots: readonly NormalizedTrustRoot[];
+	private readonly staleGapRecoveryStrikes: number;
 
 	constructor(private readonly deps: MembershipVerifierDeps) {
 		this.minSigs = deps.minSigs ?? DEFAULT_MIN_SIGS;
 		this.anchor = deps.anchor ?? noAuthorityTrustAnchor;
 		this.trustRoots = (deps.trustRoots ?? []).map(normalizeTrustRoot);
+		this.staleGapRecoveryStrikes = deps.staleGapRecoveryStrikes ?? 3;
+		const maxCoords = deps.maxCoords ?? DEFAULT_MEMBERSHIP_VERIFIER_MAX_COORDS;
+		if (!Number.isInteger(maxCoords) || maxCoords <= 0) {
+			throw new RangeError(`maxCoords must be a positive integer, got ${maxCoords}`);
+		}
+		this.byCoord = new LruMap(maxCoords);
+		this.lastFetchAt = new LruMap(maxCoords);
+		this.staleGapStrikes = new LruMap(maxCoords);
 	}
 
 	cache(cert: MembershipCertV1): void {
@@ -149,6 +209,7 @@ class CachingMembershipVerifier implements MembershipVerifier {
 			cert = await this.loadFrom(source.current(expectedCoord), tier);
 		}
 		if (cert !== undefined && this.messageVerifies(cert, signers, payload, sig)) {
+			this.staleGapStrikes.delete(coordKey); // a verify resets the consecutive stale-gap strike count
 			return "verified";
 		}
 
@@ -162,6 +223,7 @@ class CachingMembershipVerifier implements MembershipVerifier {
 		}
 		const refreshed = await this.loadFrom(source.fetch(expectedCoord), tier);
 		if (refreshed !== undefined && this.messageVerifies(refreshed, signers, payload, sig)) {
+			this.staleGapStrikes.delete(coordKey); // a verify resets the consecutive stale-gap strike count
 			return "verified";
 		}
 		return "untrusted";
@@ -242,7 +304,61 @@ class CachingMembershipVerifier implements MembershipVerifier {
 		if (this.hasRotationAttestation(cert) && this.chainGrantsTrust(cert)) {
 			return "trusted";
 		}
-		return this.fallbackTrust(cert);
+		const fallback = this.fallbackTrust(cert);
+		if (fallback !== "reject") {
+			return fallback; // first-use TOFU (coord not locked): no stale lock to recover from
+		}
+		// fallback === "reject" ⟺ the coord is trust-locked (holds a *trusted* cert) and this un-anchored cert
+		// did not chain-verify — the state that strands a former cohort member forever. Consult the stale-gap
+		// recovery counter, which releases the lock only on a demonstrated chain gap (never a forged rotation
+		// off the current predecessor). See {@link staleGapRecovery}.
+		return this.staleGapRecovery(cert);
+	}
+
+	/**
+	 * Bounded re-TOFU recovery for a coord that is **trust-locked at a stale epoch it can no longer anchor**.
+	 * Reached from {@link certIsTrusted} only when the coord already holds a *trusted* cached cert (locked),
+	 * the direct anchor said `"unknown"`, and `cert` did not chain-verify — i.e. {@link fallbackTrust} would
+	 * otherwise reject it forever. Runs on the *refetch* load only: a locked coord always holds a cached cert,
+	 * so `verifyMessage` never routes it through the `source.current()` seed path, and the strike logic keys on
+	 * "coord is locked", so `current()` never accrues a strike.
+	 *
+	 * NOTE: recovery fires **only** on a demonstrated chain gap — a full rotation attestation whose
+	 * `prevEpoch ≠` the cached trusted epoch (proof the network rotated past the cached epoch through at least
+	 * one epoch this node never witnessed). A forged rotation off the *current* cached predecessor
+	 * (`prevEpoch == cachedEpoch`) is NOT a gap, never counts as a strike, and stays rejected no matter how
+	 * often it is presented — that is the lock's headline invariant. After
+	 * {@link staleGapRecoveryStrikes} *consecutive* gap-signalled strikes the lock is released back to TOFU
+	 * (returns `"tofu"`, so {@link loadFrom} re-caches the cert as **untrusted** — a re-TOFU'd cert must never
+	 * launder trust into a rotation), which is no weaker than the documented TOFU baseline: a former member
+	 * returns to the same regime a never-member is already in. Strikes accrue only on refetches that actually
+	 * reach the source, so a {@link RefetchBound}-suppressed refetch observes no cert and recovery paces itself
+	 * with the (bounded) refetch rate — intended, do not "fix" that pacing.
+	 */
+	private staleGapRecovery(cert: MembershipCertV1): CertTrust {
+		const coordKey = cert.cohortCoord;
+		const locked = this.byCoord.get(coordKey);
+		// Recovery-eligible only on an explicit rotation gap: a full attestation whose prevEpoch is neither the
+		// cert's own epoch (a self-referential rotation) nor the cached trusted epoch (a forgery off the current
+		// predecessor — the case the lock exists to reject).
+		const isGap =
+			this.staleGapRecoveryStrikes > 0 &&
+			locked !== undefined &&
+			this.hasRotationAttestation(cert) &&
+			cert.prevEpoch !== cert.cohortEpoch &&
+			cert.prevEpoch !== locked.cert.cohortEpoch;
+		if (!isGap) {
+			return "reject"; // not a recovery-eligible gap → stay locked, exactly as before
+		}
+		const strikes = (this.staleGapStrikes.get(coordKey) ?? 0) + 1;
+		if (strikes < this.staleGapRecoveryStrikes) {
+			this.staleGapStrikes.set(coordKey, strikes);
+			return "reject"; // below threshold: keep rejecting; the inbound message stays untrusted
+		}
+		// Threshold reached: release the lock. `loadFrom` re-caches this cert as untrusted (`trusted: false`),
+		// and the message-verify retry runs against it, so the inbound later-epoch message finally verifies.
+		this.staleGapStrikes.delete(coordKey);
+		return "tofu";
 	}
 
 	/**

package/src/cohort-topic/promotion.ts

@@ -124,6 +124,13 @@ export interface PromotionDeps {
 	treeTier: (topicId: Uint8Array) => number;
 	/** The tier-`(d − 1)` parent cohort coord, target of a {@link DemotionNoticeV1}. */
 	parentCoord: (topicId: Uint8Array) => Uint8Array;
+	/**
+	 * The served coord `coord_d(participantCoord, topicId)` this cohort sits at (raw bytes) — stamped on
+	 * every notice as `cohortCoord` and covered by its threshold signature, so a receiver routes the notice
+	 * to exactly this cohort's engine and verifies it against exactly this cohort's cert. Constant for the
+	 * engine's lifetime (the engine is instantiated at one served coord).
+	 */
+	cohortCoord: () => Uint8Array;
 	/** Cohort epoch (raw bytes) the notices are signed under. */
 	cohortEpoch: () => Uint8Array;
 	/** Threshold signer (the gossip ticket's `k − x` cohort signer). */
@@ -281,9 +288,13 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 
 	private async promote(topicId: Uint8Array, state: PromotionState, now: number): Promise<PromotionNoticeV1> {
 		const fromTier = this.deps.treeTier(topicId);
+		// NOTE: no guard here against fromTier === DEFAULT_D_MAX_CAP (60). At that depth toTier = 61 exceeds the
+		// tree-tier ceiling, so validatePromotionNoticeV1 rejects the notice on every receiver. Unreachable today
+		// (tree tier 60 is pathological); if the tree can ever reach the cap, gate promotion below the cap here.
 		const topicB64 = bytesToB64url(topicId);
 		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
-		const signable = { topicId: topicB64, fromTier, toTier: fromTier + 1, effectiveAt: now, cohortEpoch: epochB64 };
+		const cohortB64 = bytesToB64url(this.deps.cohortCoord());
+		const signable = { topicId: topicB64, fromTier, toTier: fromTier + 1, effectiveAt: now, cohortEpoch: epochB64, cohortCoord: cohortB64 };
 		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(promotionNoticeSigningPayload(signable));
 		state.promoted = true;
 		state.promotedAt = now;
@@ -293,6 +304,7 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 			topicId: topicB64,
 			fromTier,
 			toTier: fromTier + 1,
+			cohortCoord: cohortB64,
 			effectiveAt: now,
 			thresholdSig: bytesToB64url(thresholdSig),
 			signers: signers.map(bytesToB64url),
@@ -329,10 +341,18 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 		const topicB64 = bytesToB64url(topicId);
 		const epochB64 = bytesToB64url(this.deps.cohortEpoch());
 		const parentB64 = bytesToB64url(this.deps.parentCoord(topicId));
-		const signable = { topicId: topicB64, tier, parentCohortCoord: parentB64, effectiveAt: now, cohortEpoch: epochB64 };
+		const cohortB64 = bytesToB64url(this.deps.cohortCoord());
+		const signable = { topicId: topicB64, tier, parentCohortCoord: parentB64, effectiveAt: now, cohortEpoch: epochB64, cohortCoord: cohortB64 };
 		const { thresholdSig, signers } = await this.deps.signer.thresholdSign(demotionNoticeSigningPayload(signable));
 		// Release forwarder state: a demoted cohort leaves promoted mode and resets its clocks so a
 		// later re-growth re-evaluates cleanly.
+		// NOTE: demotion currently resets only the promoted-bounce clocks; it does NOT stop the node serving
+		// the topic — the cold-start forwarder, the direct-participant records, and the budget slot all stay,
+		// and the cohort keeps serving at tier d. If demotion is ever made to actually collapse local tier
+		// state, it must reassign or drain the topic's records FIRST, then `coldStart.remove` + release the
+		// budget slot + `traffic.forget`, in that order — removing the forwarder while records remain re-creates
+		// the off-budget-serving drift fixed in `cohort-topic-coldstart-forwarder-reconcile` (the budget stops
+		// bounding the served-topic set). The eviction path already reconciles all three via `TopicBudget.onEvict`.
 		state.promoted = false;
 		state.promotedAt = undefined;
 		state.lowLoadSince = undefined;
@@ -342,6 +362,7 @@ class CohortPromotionLifecycle implements PromotionLifecycle {
 			topicId: topicB64,
 			tier,
 			parentCohortCoord: parentB64,
+			cohortCoord: cohortB64,
 			effectiveAt: now,
 			thresholdSig: bytesToB64url(thresholdSig),
 			signers: signers.map(bytesToB64url),

package/src/cohort-topic/registration/renewal.ts

@@ -20,6 +20,7 @@
  * in isolation; db-core never imports FRET or libp2p here.
  */
 
+import { DEFAULT_REPLAY_MAX_AGE_MS, DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS } from "../antidos/replay-guard.js";
 import { b64urlToBytes } from "../wire/codec.js";
 import type { RenewReplyV1, RenewV1 } from "../wire/types.js";
 import { bytesEqual, bytesKey, recordKey } from "./bytes.js";
@@ -280,6 +281,21 @@ export interface RenewalCohortSideDeps {
 	 * only touch `lastPing`).
 	 */
 	verifyParticipantSig?: (renew: RenewV1) => boolean;
+	/**
+	 * Optional freshness window for the two privileged, participant-attested paths (`withdraw` eviction and
+	 * `reattach` promotion). The renew signature already binds `timestamp` (see
+	 * {@link import("../wire/payloads.js").renewSigningPayload}), so an attacker cannot forge a fresher
+	 * timestamp onto a captured frame — replay is exact-frame only. A timestamp gate is therefore a
+	 * complete freshness regime for these frames: it rejects a stale/implausibly-future `timestamp`, and a
+	 * per-record monotonic check (`timestamp <= rec.lastPing`) closes the sub-`maxAge` fast-replay window
+	 * using state already on the record. Defaults to the register-path skew constants
+	 * ({@link DEFAULT_REPLAY_MAX_AGE_MS} / {@link DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS}); db-p2p wires the same
+	 * `{ maxAgeMs, maxFutureSkewMs }` config the register path's replay guard consumes so an operator tuning
+	 * the skew window moves both paths together. Absent → defaults (key-less unit tests and callers work
+	 * unchanged, matching how {@link verifyParticipantSig} is optional). Plain pings are NOT gated (a
+	 * replayed ping is low-harm — it only re-touches `lastPing`).
+	 */
+	freshness?: { maxAgeMs?: number; maxFutureSkewMs?: number };
 }
 
 /** Cohort-side TTL handling: touch on renew, redirect on rotation, sweep stale records. */
@@ -300,7 +316,45 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
 	 */
 	private readonly failoverServing = new Map<string, Uint8Array>();
 
-	constructor(private readonly deps: RenewalCohortSideDeps) {}
+	/** Resolved staleness window / forward-skew tolerance for the privileged freshness gate. */
+	private readonly maxAgeMs: number;
+	private readonly maxFutureSkewMs: number;
+
+	constructor(private readonly deps: RenewalCohortSideDeps) {
+		this.maxAgeMs = deps.freshness?.maxAgeMs ?? DEFAULT_REPLAY_MAX_AGE_MS;
+		this.maxFutureSkewMs = deps.freshness?.maxFutureSkewMs ?? DEFAULT_REPLAY_MAX_FUTURE_SKEW_MS;
+	}
+
+	/**
+	 * Freshness gate for the two privileged, participant-attested branches (`withdraw`, `reattach`). Returns
+	 * `false` — reject — when `msg.timestamp` is stale (older than `now − maxAgeMs`), implausibly future
+	 * (newer than `now + maxFutureSkewMs`), or not strictly newer than the record's `lastPing`. The signed
+	 * timestamp is immutable to a replayer, so this fully bounds a captured privileged frame: the skew
+	 * window catches an old capture, and the `<= rec.lastPing` monotonic check catches a fast replay that
+	 * still fits inside the window (e.g. a `withdraw` captured at `t0` replayed after the record was
+	 * re-registered at `t_reregister > t0`, or a `reattach` replayed after its own accepted re-stamp
+	 * already advanced `lastPing`).
+	 */
+	private isFreshPrivileged(msg: RenewV1, rec: RegistrationRecord, now: number): boolean {
+		if (msg.timestamp < now - this.maxAgeMs) {
+			return false; // stale
+		}
+		if (msg.timestamp > now + this.maxFutureSkewMs) {
+			return false; // implausibly future
+		}
+		// NOTE: condition (3) compares a participant-supplied `msg.timestamp` against a server-maintained
+		// `rec.lastPing` (set from whichever cohort member last touched the record, using its own clock) — two
+		// different machines' clocks. In normal operation a genuine leave/failover post-dates the last ping, so
+		// `timestamp > lastPing` holds. If a participant's clock lags the server that set `lastPing`, a
+		// legitimate reattach can be rejected; the failure is soft (returns `primary_moved`, so the failover
+		// loop tries the next backup / re-runs the d_max lookup — a delayed failover, not data loss). If
+		// cross-node skew is ever observed to stall failovers, relax (3) to strict `<` (accept `timestamp ==
+		// lastPing`); the `maxAge` window still backstops the replay-after-re-registration attack.
+		if (msg.timestamp <= rec.lastPing) {
+			return false; // replay / non-monotonic against the live record
+		}
+		return true;
+	}
 
 	onRenew(msg: RenewV1, now: number): RenewReplyV1 {
 		const topicId = b64(msg.topicId);
@@ -321,6 +375,13 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
 			if (this.deps.verifyParticipantSig?.(msg) === false) {
 				return { v: 1, result: "unknown_registration" };
 			}
+			// Freshness gate: a signed withdraw is valid forever without this, so a captured one could be
+			// replayed after the victim's record TTL-expires and re-registers, evicting the *fresh* record.
+			// Reject a stale/replayed frame with the same opaque `unknown_registration` the forged-sig branch
+			// returns above — indistinguishable from an untrusted frame — and never delete.
+			if (!this.isFreshPrivileged(msg, rec, now)) {
+				return { v: 1, result: "unknown_registration" };
+			}
 			this.deps.store.delete(topicId, participantId);
 			this.failoverServing.delete(key); // mirror sweepStale: drop any crash-failover override
 			this.deps.gossip.evicted(rec);
@@ -338,6 +399,12 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
 			if (this.deps.verifyParticipantSig?.(msg) === false) {
 				return this.primaryMoved(primary, backups, cohortEpoch);
 			}
+			// Freshness gate: a signed reattach is valid forever without this, so a captured one could be
+			// replayed to force bogus primary re-stamps. Reject a stale/replayed frame with the same redirect
+			// the forged-sig branch returns above — revealing nothing — and never promote.
+			if (!this.isFreshPrivileged(msg, rec, now)) {
+				return this.primaryMoved(primary, backups, cohortEpoch);
+			}
 			if (bytesEqual(primary, self)) {
 				// A rotation already made this member the computed primary; serve, no override needed.
 				return this.touchAndServe(rec, now);
@@ -365,6 +432,11 @@ class StoreRenewalCohortSide implements RenewalCohortSide {
 		}
 
 		// Plain ping.
+		// NOTE: plain pings are deliberately NOT run through the privileged freshness gate (isFreshPrivileged).
+		// A replayed ping is low-harm — it can only re-touch a record's `lastPing`, never delete or usurp — and
+		// the strict `timestamp <= lastPing` monotonic check would risk rejecting a legitimate ping that arrives
+		// slightly out of order or under minor participant-clock non-monotonicity. If plain-ping replay ever
+		// becomes a concern (e.g. touch-driven traffic accounting is abused), gate it here too.
 		const isComputedPrimary = bytesEqual(primary, self);
 		const override = this.failoverServing.get(key);
 		const overrideMatches = override !== undefined && bytesEqual(override, cohortEpoch);

package/src/cohort-topic/registration/types.ts

@@ -67,9 +67,24 @@ export interface RegistrationStore {
 export const DEFAULT_TTL_MS = 90_000;
 /** Edge-tier default registration TTL (ms). */
 export const EDGE_TTL_MS = 60_000;
+/** Minimum accepted registration TTL (ms). Requests below this are clamped up. */
+export const MIN_TTL_MS = 10_000;
+/** Maximum accepted registration TTL (ms). Requests above this are clamped down.
+ *  10 × DEFAULT_TTL_MS keeps the window predictable; prevents a wedged budget slot from a poison TTL. */
+export const MAX_TTL_MS = 10 * DEFAULT_TTL_MS;
 /** Consecutive ping failures before a participant promotes `backups[0]`. */
 export const MAX_PING_FAILURES = 3;
 
+/**
+ * Clamp a requested or replicated TTL into the accepted `[MIN_TTL_MS, MAX_TTL_MS]` window.
+ * Non-positive input falls to {@link DEFAULT_TTL_MS} first. This is the single TTL policy gate:
+ * both local admission (`accept()`) and gossip replication (`mergeRecords`) run every TTL through
+ * it, so no store — local or replica — can ever hold a record whose lifetime dodges the cap.
+ */
+export function clampTtl(ttl: number): number {
+	return Math.min(Math.max(ttl > 0 ? ttl : DEFAULT_TTL_MS, MIN_TTL_MS), MAX_TTL_MS);
+}
+
 /** `ping_interval = ttl / 3` (default 30s Core, 20s Edge), floored to whole ms. */
 export function pingIntervalMs(ttl: number): number {
 	return Math.floor(ttl / 3);