@optimystic/db-core 0.13.5 → 0.14.0

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

@@ -0,0 +1,409 @@
+/**
+ * Cohort-topic substrate — cohort-side member engine.
+ *
+ * This is the logic a cohort member runs when FRET's `RouteAndMaybeAct` lands a `RegisterV1`/`RenewV1`
+ * 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.
+ *
+ * Inbound `RegisterV1` decision pipeline (§Registration mechanics, §Willingness, §Cold-start):
+ *
+ * 1. **Anti-DoS** — freshness/replay guard, per-(peer,topic) rate limit, and cold-root bootstrap
+ *    evidence. A failure short-circuits to `unwilling_cohort` (temporal back-off) or, for a replay,
+ *    a silent `no_state` (no state is served and nothing is recorded).
+ * 2. **Hot vs cold** — if this cohort already serves the topic (forwarder state resident), run the
+ *    willingness check; a promoted topic answers `Promoted(d+1)`. If cold, the topic-budget +
+ *    cold-start gate decides whether to instantiate, else `no_state` (walk steps toward the root).
+ * 3. **Admission** — on `accepted`, assign the deterministic primary/backup slots, persist the
+ *    soft-state record, count the arrival, run the promotion trigger, and attach the topic-traffic
+ *    signal to the reply.
+ *
+ * Every collaborator is injected, so the engine unit-tests without FRET or libp2p.
+ */
+
+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 type { SlotAssigner } from "./registration/sharding.js";
+import type { RenewalCohortSide } from "./registration/renewal.js";
+import type { WillingnessCheck } from "./willingness.js";
+import { backoffRetryMs } from "./willingness.js";
+import type { PromotionLifecycle } from "./promotion.js";
+import { promotedRedirectReply } from "./coldstart.js";
+import type { ColdStartManager } from "./coldstart.js";
+import { shouldInstantiate } from "./coldstart.js";
+import type { TrafficCounters } from "./traffic.js";
+import { attachTopicTraffic } from "./traffic.js";
+import type { RegisterRateLimiter } from "./antidos/rate-limiter.js";
+import type { CorrelationReplayGuard } from "./antidos/replay-guard.js";
+import type { TopicBudget } from "./antidos/topic-budget.js";
+import type { BootstrapEvidence } from "./antidos/bootstrap-evidence.js";
+import type { NodeProfile, Tier } from "./tiers.js";
+import { b64urlToBytes } from "./wire/codec.js";
+import type { DemotionNoticeV1, PromotionNoticeV1, RegisterReplyV1, RegisterV1, RenewReplyV1, RenewV1 } from "./wire/types.js";
+
+/** 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? */
+	readonly followOn: boolean;
+	/** Tree tier `d` this cohort serves the topic at (the walk position the register landed on). */
+	readonly treeTier: number;
+	/** The tier-`(d − 1)` parent cohort coord, for a cold-start forwarder's parent registration. */
+	readonly parentCoord?: Uint8Array;
+}
+
+/** Current cohort snapshot — the FRET host fills this from the membership source. */
+export interface CohortSnapshotView {
+	readonly members: readonly Uint8Array[];
+	readonly cohortEpoch: Uint8Array;
+}
+
+export interface CohortMemberEngineDeps {
+	/** This member's own peer id. */
+	readonly self: Uint8Array;
+	/** This member's static tier profile (Edge/Core willing-tier set). */
+	readonly profile: NodeProfile;
+	/** Hash used for slot assignment + keys (db-core's own SHA-256). */
+	readonly hash: IRingHash;
+	/** Replicated soft-state registration store. */
+	readonly store: RegistrationStore;
+	/** Deterministic primary/backup slot assignment, shared with renewal + handoff. */
+	readonly slots: SlotAssigner;
+	/** Per-member willingness / admission control. */
+	readonly willingness: WillingnessCheck;
+	/** Promotion / demotion lifecycle. */
+	readonly promotion: PromotionLifecycle;
+	/** Cold-start forwarder instantiation + parent registration. */
+	readonly coldStart: ColdStartManager;
+	/** Per-topic traffic counters (gossip-derived snapshots feed the reply signal). */
+	readonly traffic: TrafficCounters;
+	/** Cohort-side TTL renewal handler (touch / primary_moved / sweep). */
+	readonly renewal: RenewalCohortSide;
+	/** Live cohort snapshot (members + epoch). */
+	readonly cohort: () => CohortSnapshotView;
+	/** Whether a quorum of members is willing to serve `tier` (the cold-start gate input). */
+	readonly quorumWilling: (tier: Tier) => boolean;
+	// --- anti-DoS guards (all optional; absent = that gate is skipped) ---
+	readonly rateLimiter?: RegisterRateLimiter;
+	/**
+	 * Dedicated per-(peer, topic) rate limiter for the read-only {@link CohortMemberEngine.handleRegister}
+	 * **probe** path — its own budget, separate from {@link rateLimiter}, so a probe flood cannot exhaust a
+	 * participant's register budget (or vice-versa). An over-rate probe answers `unwilling_cohort`
+	 * (walk → `retry_later` → `CohortBackoffError`). Absent → the probe rate gate is skipped (the read-only
+	 * classify still runs), keeping key-less / unit / mock flows composing.
+	 */
+	readonly probeRateLimiter?: RegisterRateLimiter;
+	readonly replayGuard?: CorrelationReplayGuard;
+	readonly topicBudget?: TopicBudget;
+	readonly bootstrapEvidence?: BootstrapEvidence;
+	/**
+	 * Optional participant peer-key signature verifier (db-p2p binds it to the peer-sig primitive over
+	 * {@link import("./wire/payloads.js").registerSigningPayload}). A `RegisterV1` whose signature does
+	 * not verify against the claimed `participantCoord` is answered `no_state` (serve nothing, record
+	 * nothing) — a cohort member cannot trust an unsigned/forged `participantCoord`. Verified first so a
+	 * forged frame never reaches (or pollutes) the replay/rate guards. Absent → the gate is skipped.
+	 */
+	readonly verifyRegisterSig?: (reg: RegisterV1) => boolean;
+	/**
+	 * Sink for a freshly threshold-signed promotion/demotion notice produced on an arrival (the `accept`
+	 * path's promotion trigger). db-p2p's host wires this to broadcast the notice over the `promote`
+	 * protocol to the cohort (and, for a demotion, the parent coord). Absent → notices are produced and
+	 * applied locally but not broadcast (unit/mock flows). Called fire-and-forget, off the reply path.
+	 */
+	readonly onNotice?: (notice: PromotionNoticeV1 | DemotionNoticeV1) => void;
+	/**
+	 * Optional logger. Used only to record a failed promotion sign/broadcast (the threshold-sign round
+	 * can reject when the cohort quorum is unreachable) rather than swallow it. Absent → silent.
+	 */
+	readonly log?: (formatter: string, ...args: unknown[]) => void;
+	/**
+	 * Sink for a freshly-admitted registration record (the `accept` path), symmetric to the renewal
+	 * `gossip.touch` hook. db-p2p wires this to the same per-coord gossip delta queue the renewal side
+	 * appends to, so an admitted record is replicated to the cohort at the next gossip round — closing the
+	 * durability window between admission and the participant's first renewal touch. A queue append, not a
+	 * synchronous broadcast: admission must not block on a round, and last-writer-wins by `lastPing` dedupes
+	 * an admit-then-touch landing in the same round. Absent → no admission-time replication (unit/mock flows
+	 * that don't exercise gossip).
+	 */
+	readonly onAdmit?: (rec: RegistrationRecord) => void;
+}
+
+/** Cohort-side register/renew handler — the body of the FRET activity callback. */
+export interface CohortMemberEngine {
+	/** Classify and admit (or decline) an inbound `RegisterV1`, returning the reply to serialize. */
+	handleRegister(reg: RegisterV1, ctx: RegisterContext, now: number): Promise<RegisterReplyV1>;
+	/** Handle an inbound `RenewV1` (ping / re-attach), delegating to the renewal cohort side. */
+	handleRenew(msg: RenewV1, now: number): RenewReplyV1;
+	/** Evict stale records and gossip each eviction; returns the evicted set. */
+	sweepStale(now: number): readonly RegistrationRecord[];
+}
+
+class StoreCohortMemberEngine implements CohortMemberEngine {
+	constructor(private readonly deps: CohortMemberEngineDeps) {}
+
+	async handleRegister(reg: RegisterV1, ctx: RegisterContext, now: number): Promise<RegisterReplyV1> {
+		const topicId = b64urlToBytes(reg.topicId);
+		const participantId = b64urlToBytes(reg.participantCoord);
+		const tier = reg.tier as Tier;
+
+		// 0. Read-only lookup probe: classify + return the cohort snapshot without admitting anything.
+		//    Branches before the admission pipeline (and the durable-state anti-DoS guards), so even a
+		//    hand-crafted `probe: true, bootstrap: true` frame can never instantiate — defense in depth.
+		if (reg.probe === true) {
+			return this.handleProbe(reg, topicId, participantId, ctx, now);
+		}
+
+		// 1. Anti-DoS gates. A replay/stale frame is answered with NoState (serve nothing, record
+		//    nothing); an over-rate source or missing bootstrap evidence backs off in time.
+		const guard = this.runGuards(reg, topicId, participantId, tier, now);
+		if (guard !== undefined) {
+			return guard;
+		}
+
+		// 2. Hot path: this cohort already serves the topic.
+		if (this.serves(topicId)) {
+			if (this.deps.promotion.isPromoted(topicId)) {
+				// Promoted: bounce same-tier registrations onward (the cheap single-RPC redirect).
+				return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
+			}
+			return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
+		}
+
+		// 3. Cold path: instantiate only at a legitimate growth point with a willing quorum.
+		const quorumWilling = this.deps.quorumWilling(tier);
+		if (!shouldInstantiate({ bootstrap: reg.bootstrap === true, followOn: ctx.followOn, quorumWilling })) {
+			return { v: 1, result: "no_state" };
+		}
+		if (this.deps.topicBudget?.admit(topicId) === false) {
+			// Forwarder-state budget is full of populated topics — decline in time.
+			return this.unwillingCohort(reg, now);
+		}
+		this.deps.coldStart.instantiate(topicId, ctx.treeTier, ctx.parentCoord, tier);
+		return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
+	}
+
+	/**
+	 * Read-only resolution of the cohort for a topic (the `lookup` probe). It walks the same path a
+	 * register does (the walk loop is byte-for-byte identical) but the **terminal** member action is a
+	 * classify, never an admission: it persists **no** record, counts **no** arrival, fires **no**
+	 * promotion trigger, touches **no** topic budget, and **never** instantiates a cold-start forwarder.
+	 *
+	 * DoS posture (`docs/cohort-topic.md` §Anti-DoS): a probe still runs the stateless participant-sig gate
+	 * (forged → `no_state`) and a dedicated probe rate limiter (over-rate → `unwilling_cohort`), but skips
+	 * the replay guard, the bootstrap-evidence gate, and the topic budget — an idempotent read records
+	 * nothing, so it is strictly cheaper than the register it replaces.
+	 *
+	 * Classification mirrors a register's terminal cases so the walk's existing branches drive a probe
+	 * unchanged: a served-and-promoted topic answers `promoted(treeTier + 1)` (the walk follows it), a
+	 * served topic answers `accepted` with the participant-specific slot assignment + read-only traffic
+	 * snapshot, and a topic this cohort does not serve answers `no_state` (the walk steps inward).
+	 */
+	private handleProbe(reg: RegisterV1, topicId: Uint8Array, participantId: Uint8Array, ctx: RegisterContext, now: number): RegisterReplyV1 {
+		if (this.deps.verifyRegisterSig?.(reg) === false) {
+			// Unsigned / forged participant signature: serve nothing, exactly like the register path — a
+			// cohort member never resolves a cohort snapshot for an untrusted `participantCoord`.
+			return { v: 1, result: "no_state" };
+		}
+		const rate = this.deps.probeRateLimiter?.check(participantId, topicId, now);
+		if (rate !== undefined && rate.ok === false) {
+			return { v: 1, result: "unwilling_cohort", retryAfterMs: rate.retryAfterMs };
+		}
+		if (this.serves(topicId)) {
+			if (this.deps.promotion.isPromoted(topicId)) {
+				return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
+			}
+			const { members, cohortEpoch } = this.deps.cohort();
+			const { primary, backups } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+			const reply: RegisterReplyV1 = {
+				v: 1,
+				result: "accepted",
+				primary: bytesKey(primary),
+				backups: backups.map(bytesKey),
+				cohortEpoch: bytesKey(cohortEpoch),
+				cohortMembers: members.map(bytesKey),
+			};
+			return attachTopicTraffic(reply, this.deps.traffic.snapshot(topicId));
+		}
+		return { v: 1, result: "no_state" };
+	}
+
+	handleRenew(msg: RenewV1, now: number): RenewReplyV1 {
+		const reply = this.deps.renewal.onRenew(msg, now);
+		if (reply.result === "ok") {
+			// A renewal is an arrival proxy for the traffic barometer (§Topic traffic signal).
+			this.deps.traffic.recordArrival(b64urlToBytes(msg.topicId), now);
+		} else if (reply.result === "withdrawn") {
+			// A withdraw evicted a direct participant: re-touch the topic budget DOWN (mirrors the
+			// sweepStale drain release below) so the freed slot does not leak. Never an arrival — it is a
+			// departure, so the traffic barometer is deliberately not touched.
+			const topicId = b64urlToBytes(msg.topicId);
+			this.deps.topicBudget?.touch(topicId, this.deps.store.directParticipants(topicId));
+		}
+		return reply;
+	}
+
+	sweepStale(now: number): readonly RegistrationRecord[] {
+		// Reclaim idle (peer, topic) rate-limiter keys on the existing gossip cadence. The limiters' own
+		// hard LRU cap already bounds worst-case footprint; this sweep adds proactive steady-state reclaim
+		// of long-quiet keys so a long-running coord does not hold register/probe state for departed peers.
+		this.deps.rateLimiter?.sweep(now);
+		this.deps.probeRateLimiter?.sweep(now);
+
+		const evicted = this.deps.renewal.sweepStale(now);
+		const budget = this.deps.topicBudget;
+		if (budget !== undefined && evicted.length > 0) {
+			// Mirror the `accept()` up-touch on the drain side: a TTL sweep that removes a topic's last
+			// direct participant must re-`touch` the budget down so the topic falls to participantCount 0
+			// and becomes the coldest-evictable resident again. Without this the budget slot leaks — a
+			// drained topic keeps its stale positive count forever and `coldestEvictable()` never picks it,
+			// so the cohort eventually refuses every new topic while serving nothing. Re-touch once per
+			// distinct affected topic from `store.directParticipants` (the source of truth, post-eviction).
+			const seen = new Set<string>();
+			for (const rec of evicted) {
+				const key = bytesKey(rec.topicId);
+				if (seen.has(key)) continue;
+				seen.add(key);
+				budget.touch(rec.topicId, this.deps.store.directParticipants(rec.topicId));
+			}
+		}
+		return evicted;
+	}
+
+	// --- admission ---
+
+	/** Run the willingness check; on `accepted` persist the record and attach the traffic signal. */
+	private async admitOrDecline(
+		reg: RegisterV1,
+		topicId: Uint8Array,
+		participantId: Uint8Array,
+		tier: Tier,
+		ctx: RegisterContext,
+		now: number,
+	): Promise<RegisterReplyV1> {
+		const outcome = this.deps.willingness.evaluate(reg, this.deps.profile, now);
+		switch (outcome.kind) {
+			case "unwilling_member": {
+				return { v: 1, result: "unwilling_member", candidateMembers: outcome.candidateMembers.map(bytesKey) };
+			}
+			case "unwilling_cohort": {
+				return { v: 1, result: "unwilling_cohort", retryAfterMs: outcome.retryAfterMs };
+			}
+			case "accepted": {
+				return this.accept(reg, topicId, participantId, tier, ctx, now);
+			}
+			default: {
+				return this.unwillingCohort(reg, now);
+			}
+		}
+	}
+
+	private async accept(
+		reg: RegisterV1,
+		topicId: Uint8Array,
+		participantId: Uint8Array,
+		tier: Tier,
+		ctx: RegisterContext,
+		now: number,
+	): 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 record: RegistrationRecord = {
+			topicId,
+			participantId,
+			tier,
+			primary,
+			backups,
+			attachedAt: now,
+			lastPing: now,
+			ttl,
+			appState: reg.appPayload === undefined ? undefined : b64urlToBytes(reg.appPayload),
+		};
+		this.deps.store.put(record);
+		this.deps.onAdmit?.(record);
+		this.deps.traffic.recordArrival(topicId, now);
+		this.deps.topicBudget?.touch(topicId, this.deps.store.directParticipants(topicId));
+		// Promotion may fire on this arrival; broadcast whatever notice comes back. Fire-and-forget so the
+		// register reply is not delayed by the threshold-sign collection round.
+		void this.firePromotion(topicId, now);
+
+		const reply: RegisterReplyV1 = {
+			v: 1,
+			result: "accepted",
+			primary: bytesKey(primary),
+			backups: backups.map(bytesKey),
+			cohortEpoch: bytesKey(cohortEpoch),
+			cohortMembers: members.map(bytesKey),
+		};
+		return attachTopicTraffic(reply, this.deps.traffic.snapshot(topicId));
+	}
+
+	/** Run the promotion trigger for an arrival and hand any signed notice to {@link CohortMemberEngineDeps.onNotice}. */
+	private async firePromotion(topicId: Uint8Array, now: number): Promise<void> {
+		try {
+			const notice = await this.deps.promotion.onParticipantCountChange(topicId, now);
+			if (notice !== undefined) {
+				this.deps.onNotice?.(notice);
+			}
+		} catch (err) {
+			// Threshold signing rejects when the cohort quorum is unreachable this round; the next arrival
+			// re-fires, so this is transient. Log rather than crash the register path — or leak the
+			// unhandled rejection the bare `void promotion...` did once signing became real (db-p2p ticket 1).
+			this.deps.log?.("cohort-topic: promotion sign/broadcast failed for an arrival: %o", err);
+		}
+	}
+
+	// --- guards ---
+
+	/** Returns a short-circuit reply if any anti-DoS gate rejects `reg`, else `undefined`. */
+	private runGuards(
+		reg: RegisterV1,
+		topicId: Uint8Array,
+		participantId: Uint8Array,
+		tier: Tier,
+		now: number,
+	): 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.
+			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" };
+		}
+		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 };
+		}
+		return undefined;
+	}
+
+	private serves(topicId: Uint8Array): boolean {
+		return this.deps.coldStart.get(topicId) !== undefined || this.deps.store.directParticipants(topicId) > 0;
+	}
+
+	private unwillingCohort(reg: RegisterV1, now: number): RegisterReplyV1 {
+		void reg;
+		void now;
+		return { v: 1, result: "unwilling_cohort", retryAfterMs: backoffRetryMs(0) };
+	}
+}
+
+/** Build a {@link CohortMemberEngine} over the injected cohort-side collaborators. */
+export function createCohortMemberEngine(deps: CohortMemberEngineDeps): CohortMemberEngine {
+	return new StoreCohortMemberEngine(deps);
+}
+
+/** True iff `a` and `b` name the same peer (re-exported convenience for host equality checks). */
+export function samePeer(a: Uint8Array, b: Uint8Array): boolean {
+	return bytesEqual(a, b);
+}

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

@@ -0,0 +1,3 @@
+export * from "./source.js";
+export * from "./verifier.js";
+export * from "./publisher.js";

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

@@ -0,0 +1,171 @@
+/**
+ * Cohort-topic substrate — cohort-side `MembershipCertV1` publication.
+ *
+ * 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});
+ * - 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.
+ */
+
+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 { membershipCertSigningPayload, type MembershipCertSignable } from "../sig/payloads.js";
+
+/** Default membership-cert refresh interval (`T_membership_refresh`). */
+export const DEFAULT_T_MEMBERSHIP_REFRESH_MS = 5 * 60_000;
+
+/**
+ * The canonical {@link MembershipCertSignable} for a stabilized snapshot: members sorted ascending (the
+ * cert / sharding order), byte fields base64url-encoded, over exactly the threshold-signed fields. The
+ * publisher signs `membershipCertSigningPayload` of this; a rotation-attestation **producer** (db-p2p,
+ * `cohort-topic-trust-anchor-rotation-production`) signs the *successor* cert's image through the SAME
+ * helper, so signer and verifier never canonicalize the cert independently (signature-image agreement —
+ * a mismatch makes the db-core chain check fail).
+ */
+export function membershipCertSignable(snapshot: CohortSnapshot): MembershipCertSignable {
+	const sorted = [...snapshot.members].sort(compareBytes);
+	return {
+		cohortCoord: bytesToB64url(snapshot.coord),
+		cohortEpoch: bytesToB64url(snapshot.cohortEpoch),
+		members: sorted.map(bytesToB64url),
+		stabilizedAt: snapshot.stabilizedAt,
+	};
+}
+
+/** A stabilized cohort snapshot the publisher attests. */
+export interface CohortSnapshot {
+	/** Cohort coord (32 bytes). */
+	coord: Uint8Array;
+	/** Cohort epoch for this snapshot. */
+	cohortEpoch: Uint8Array;
+	/** Cohort members (any order; the cert sorts them ascending). */
+	members: readonly Uint8Array[];
+	/** Unix ms this membership stabilized. */
+	stabilizedAt: number;
+	/** Optional FRET stabilization proof. */
+	fretAttestation?: Uint8Array;
+}
+
+/**
+ * A predecessor-cohort rotation attestation to attach to a fresh cert (an epoch rotation). The
+ * predecessor cohort threshold-signs the **successor** cert's `membershipCertSigningPayload`; that
+ * `(prevEpoch, rotationSig, rotationSigners)` triple lets a participant holding a trusted predecessor
+ * verify the rotation is legitimate. Producing this triple is the db-p2p ticket
+ * `cohort-topic-trust-anchor-rotation-production`; the publisher only attaches a provided one.
+ */
+export interface RotationAttestation {
+	/** Predecessor cohort epoch this cert rotates from (32 bytes). */
+	prevEpoch: Uint8Array;
+	/** Predecessor cohort's threshold signature over the successor cert's signing payload. */
+	rotationSig: Uint8Array;
+	/** Predecessor cohort signers that produced {@link rotationSig}; `>= minSigs`. */
+	rotationSigners: readonly Uint8Array[];
+}
+
+/** 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).
+	 */
+	onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+	/**
+	 * Periodic tick. Re-publishes (and returns the cert) when `T_membership_refresh` has elapsed since
+	 * the last publish; otherwise returns `undefined`. Pass `rotation` to attach a rotation attestation.
+	 */
+	tick(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+}
+
+export interface MembershipCertPublisherDeps {
+	signer: CohortSigner;
+	sink: IMembershipPublishSink;
+	refreshMs?: number;
+	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;
+	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
+		}
+		return this.publish(snapshot, now, rotation);
+	}
+
+	async tick(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined> {
+		if (this.lastPublishedAt !== undefined && now - this.lastPublishedAt < this.refreshMs) {
+			return undefined;
+		}
+		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));
+		const cert: MembershipCertV1 = {
+			v: 1,
+			...signable,
+			thresholdSig: bytesToB64url(thresholdSig),
+			signers: signers.map(bytesToB64url),
+		};
+		if (snapshot.fretAttestation !== undefined) {
+			cert.fretAttestation = bytesToB64url(snapshot.fretAttestation);
+		}
+		// A rotation attestation (when given) signs *over* the cert's signing payload, so it is attached to the
+		// envelope after signing and is not part of `membershipCertSigningPayload`. Omitted → no rotation fields.
+		if (rotation !== undefined) {
+			cert.prevEpoch = bytesToB64url(rotation.prevEpoch);
+			cert.rotationSig = bytesToB64url(rotation.rotationSig);
+			cert.rotationSigners = rotation.rotationSigners.map(bytesToB64url);
+		}
+		this.deps.sink.publish(encodeCohortMessage(cert, this.deps.maxMessageBytes));
+		this.lastFirstKx = signable.members.slice(0, this.minSigs);
+		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/source.ts

@@ -0,0 +1,41 @@
+/**
+ * Cohort-topic substrate — membership-source dispatch.
+ *
+ * Resolved open question (per `docs/cohort-topic.md` §Membership source): how *committed*
+ * membership is obtained differs by tier.
+ *
+ * - **T0/T1** cohorts serve committed work (transaction commits, chain serving); their membership is
+ *   anchored in the transaction log's commit certificate. The verifier reads it from there (it never
+ *   writes the log).
+ * - **T2/T3** cohorts (matchmaking, push forwarding) derive membership from current FRET state and
+ *   verify against FRET's signed `MembershipCertV1` advertisements.
+ *
+ * Both back-ends present the same {@link IMembershipSource} surface; this router picks between them by
+ * tier. db-p2p supplies the two concrete sources (tx-log reader and FRET cert source).
+ */
+
+import type { IMembershipSource } from "../ports.js";
+
+/** Picks the authoritative membership source for a cohort by its tier. */
+export interface IMembershipSourceRouter {
+	/** Source for a cohort at `tier`: T0/T1 → committed tx-log, T2/T3 → FRET certs. */
+	for(tier: number): IMembershipSource;
+}
+
+/** Tiers whose committed membership is anchored in the transaction log. */
+function isCommittedTier(tier: number): boolean {
+	return tier === 0 || tier === 1;
+}
+
+/**
+ * Build a router over the two membership back-ends.
+ * @param deps.committed source backed by the transaction-log commit certificate (T0/T1).
+ * @param deps.fret source backed by FRET's signed `MembershipCertV1` advertisements (T2/T3).
+ */
+export function createMembershipSourceRouter(deps: { committed: IMembershipSource; fret: IMembershipSource }): IMembershipSourceRouter {
+	return {
+		for(tier: number): IMembershipSource {
+			return isCommittedTier(tier) ? deps.committed : deps.fret;
+		},
+	};
+}