@optimystic/db-core 0.22.0 → 0.24.0

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

@@ -1,254 +1,254 @@
-/**
- * Cohort-topic substrate — intra-cohort gossip bus.
- *
- * Per `docs/cohort-topic.md` §Cohort gossip. Each member periodically broadcasts a `CohortGossipV1`
- * carrying its willingness vector, load buckets, exact per-topic summaries, and any registration
- * record deltas (new/touched records + evictions). The bus:
- *
- * - **broadcasts** outbound gossip over the injected {@link ICohortGossipTransport} (FRET cohort
- *   gossip underneath — db-core never imports FRET);
- * - **routes by coord**: a delivered frame is fanned to every coord engine's bus on a node, so each
- *   bus merges only the gossip whose `coord` names its own cohort (epoch alone never isolates two
- *   coords — they can share a member set, hence an epoch);
- * - **merges inbound** gossip — record deltas into the {@link RegistrationStore} (last-writer-wins
- *   by `lastPing`; evictions remove), and willingness/load/summaries into the per-member
- *   {@link CohortView};
- * - **detects epoch drift**: an inbound `cohortEpoch` that differs from the local epoch fires the
- *   drift handlers, and record deltas under a foreign epoch are *not* merged (their slot
- *   assignments belong to a different membership snapshot);
- * - **optionally authenticates** inbound transport frames via an injected {@link GossipInboundVerifier}
- *   (db-p2p binds peer-sig + cohort membership), dropping forged or non-member gossip before any merge.
- *
- * Convergence target (doc): a single gossip round spreads a touched record / willingness flip to all
- * members — one {@link CohortGossipBus.applyInbound} of that gossip makes it visible locally.
- */
-
-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 { ChildLinkRefV1, CohortGossipV1 } from "../wire/types.js";
-import { fromGossipRecord } from "./records.js";
-import { createCohortView, type CohortView, type MutableCohortView } from "./view.js";
-
-/** Handler for inbound gossip (after merge). */
-export type GossipHandler = (g: CohortGossipV1) => void;
-/** Handler for a detected cohort-epoch drift on an inbound gossip. */
-export type DriftHandler = (inboundEpoch: Uint8Array, localEpoch: Uint8Array, from: string) => void;
-/** Authenticity gate for an inbound gossip arriving over the transport — `false` drops the frame. */
-export type GossipInboundVerifier = (g: CohortGossipV1) => boolean;
-
-export interface CohortGossipBusDeps {
-	/** FRET-backed cohort gossip transport (broadcast / subscribe). */
-	transport: ICohortGossipTransport;
-	/** Local registration store record deltas merge into. */
-	store: RegistrationStore;
-	/** This cohort's coord — the broadcast key **and** the inbound routing key (see {@link CohortGossipV1.coord}). */
-	coord: RingCoord;
-	/** The local cohort epoch, read fresh each merge so rotation is observed. */
-	localEpoch: () => Uint8Array;
-	/** Wall clock for inbound merges via the transport path; injectable for tests. */
-	now?: () => number;
-	/** Frame ceiling for encode/decode (defaults to the codec default). */
-	maxMessageBytes?: number;
-	/**
-	 * Optional authenticity gate run on every gossip arriving over the transport (db-p2p binds it to the
-	 * peer-sig primitive: verify `fromMember`'s signature over the gossip image **and** that `fromMember`
-	 * is a member of this coord's cohort). A `false` verdict drops the frame — no merge, no handler fire —
-	 * so a forged or non-member gossip can neither spoof willingness/load nor replicate fake records.
-	 * Absent → the gate is skipped (unit tests / key-less interim mode); the `coord` routing check below
-	 * still runs regardless. Not applied to direct {@link CohortGossipBus.applyInbound} calls (the trusted
-	 * test/internal merge entry point).
-	 */
-	verifyInbound?: GossipInboundVerifier;
-	/**
-	 * Optional hook fired after a merge that deleted one or more records via gossiped evictions, carrying
-	 * the **distinct** topic ids touched. db-p2p wires it to re-`touch` the per-cohort topic budget down
-	 * (`topicBudget.touch(t, store.directParticipants(t))`) so a topic whose participants drain on a
-	 * *sibling* (the drain arrives here as a gossip eviction, never this member's own TTL sweep) still
-	 * releases its budget slot — mirroring the engine's own `sweepStale` re-touch. Kept as a decoupled
-	 * 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). */
-export interface CohortGossipBus {
-	/** Broadcast `g` to the cohort. */
-	broadcast(g: CohortGossipV1): void;
-	/** Subscribe to inbound gossip (fired after merge); returns an unsubscribe handle. */
-	onGossip(handler: GossipHandler): () => void;
-	/** Subscribe to epoch-drift detections; returns an unsubscribe handle. */
-	onDrift(handler: DriftHandler): () => void;
-	/** Merge one inbound gossip: records/willingness/load, with epoch drift detection. */
-	applyInbound(g: CohortGossipV1, now: number): void;
-	/** The merged per-member view (willingness / load / summaries). */
-	view(): CohortView;
-	/** Detach the transport subscription. */
-	close(): void;
-}
-
-class TransportCohortGossipBus implements CohortGossipBus {
-	private readonly gossipHandlers = new Set<GossipHandler>();
-	private readonly driftHandlers = new Set<DriftHandler>();
-	private readonly memberView: MutableCohortView = createCohortView();
-	private readonly now: () => number;
-	private readonly detach: () => void;
-
-	constructor(private readonly deps: CohortGossipBusDeps) {
-		this.now = deps.now ?? ((): number => Date.now());
-		this.detach = deps.transport.onMessage((_from: PeerRef, msg: Uint8Array) => this.onInbound(msg));
-	}
-
-	broadcast(g: CohortGossipV1): void {
-		this.deps.transport.broadcast(this.deps.coord, encodeCohortMessage(g, this.deps.maxMessageBytes));
-	}
-
-	onGossip(handler: GossipHandler): () => void {
-		this.gossipHandlers.add(handler);
-		return () => this.gossipHandlers.delete(handler);
-	}
-
-	onDrift(handler: DriftHandler): () => void {
-		this.driftHandlers.add(handler);
-		return () => this.driftHandlers.delete(handler);
-	}
-
-	applyInbound(g: CohortGossipV1, now: number): void {
-		// Coord routing: a frame is fanned to every coord engine's bus, but it belongs only to the bus
-		// whose coord it names. Drop any gossip for another cohort so it cannot merge into this store/view
-		// (two coords on one node can even share a member set — and thus an epoch — so epoch alone never
-		// isolates them).
-		if (!this.isOurCoord(g)) {
-			return;
-		}
-		const localEpoch = this.deps.localEpoch();
-		const inboundEpoch = b64urlToBytes(g.cohortEpoch);
-		const epochMatches = bytesEqual(inboundEpoch, localEpoch);
-		if (!epochMatches) {
-			for (const handler of this.driftHandlers) {
-				handler(inboundEpoch, localEpoch, g.fromMember);
-			}
-		}
-		this.mergeView(g, inboundEpoch);
-		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 {
-		return this.memberView;
-	}
-
-	close(): void {
-		this.detach();
-	}
-
-	private onInbound(msg: Uint8Array): void {
-		const g = decodeCohortGossipV1(msg, this.deps.maxMessageBytes);
-		// Cheap routing check first so a non-matching coord skips the (expensive) signature verify.
-		if (!this.isOurCoord(g)) {
-			return;
-		}
-		// Authenticity gate (db-p2p binds peer-sig + cohort membership); a forged/non-member gossip is
-		// dropped before any merge or handler fire. Absent in key-less/unit composition.
-		if (this.deps.verifyInbound !== undefined && !this.deps.verifyInbound(g)) {
-			return;
-		}
-		this.applyInbound(g, this.now());
-		for (const handler of this.gossipHandlers) {
-			handler(g);
-		}
-	}
-
-	/** True iff `g` names this bus's cohort coord (the inbound routing key). */
-	private isOurCoord(g: CohortGossipV1): boolean {
-		return bytesEqual(b64urlToBytes(g.coord), this.deps.coord);
-	}
-
-	private mergeView(g: CohortGossipV1, inboundEpoch: Uint8Array): void {
-		this.memberView.merge(g.fromMember, {
-			cohortEpoch: inboundEpoch,
-			willingness: parseInt(g.willingnessBits, 16),
-			loadBuckets: g.loadBuckets,
-			windowSeconds: g.windowSeconds,
-			topicSummaries: g.topicSummaries,
-			timestamp: g.timestamp,
-		});
-	}
-
-	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.
-			if (now - incoming.lastPing > incoming.ttl) {
-				continue;
-			}
-			const held = this.deps.store.getByParticipant(incoming.topicId, incoming.participantId);
-			// Last-writer-wins by lastPing: a touch (newer lastPing) replaces an older replica.
-			if (held === undefined || incoming.lastPing >= held.lastPing) {
-				this.deps.store.put(incoming);
-			}
-		}
-		// Collect the distinct topics a gossiped eviction drained so the budget can be re-touched *after*
-		// the deletes (the count must be post-drain). This is the sibling-drain half of the topic-budget
-		// leak fix: a topic whose participants are sharded onto a sibling primary drains into this store as
-		// a gossip eviction, never via this member's own TTL sweep, so the `onRecordsEvicted` callback must
-		// re-`touch` the budget down here too — otherwise the slot leaks for any multi-member topic.
-		let evictedTopics: Map<string, Uint8Array> | undefined;
-		for (const ref of g.evicted ?? []) {
-			const topicId = b64urlToBytes(ref.topicId);
-			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);
-			}
-		}
-		if (evictedTopics !== undefined && evictedTopics.size > 0) {
-			this.deps.onRecordsEvicted!([...evictedTopics.values()]);
-		}
-	}
-}
-
-/** Build a {@link CohortGossipBus} over the injected transport + store. */
-export function createCohortGossipBus(deps: CohortGossipBusDeps): CohortGossipBus {
-	return new TransportCohortGossipBus(deps);
-}
+/**
+ * Cohort-topic substrate — intra-cohort gossip bus.
+ *
+ * Per `docs/cohort-topic.md` §Cohort gossip. Each member periodically broadcasts a `CohortGossipV1`
+ * carrying its willingness vector, load buckets, exact per-topic summaries, and any registration
+ * record deltas (new/touched records + evictions). The bus:
+ *
+ * - **broadcasts** outbound gossip over the injected {@link ICohortGossipTransport} (FRET cohort
+ *   gossip underneath — db-core never imports FRET);
+ * - **routes by coord**: a delivered frame is fanned to every coord engine's bus on a node, so each
+ *   bus merges only the gossip whose `coord` names its own cohort (epoch alone never isolates two
+ *   coords — they can share a member set, hence an epoch);
+ * - **merges inbound** gossip — record deltas into the {@link RegistrationStore} (last-writer-wins
+ *   by `lastPing`; evictions remove), and willingness/load/summaries into the per-member
+ *   {@link CohortView};
+ * - **detects epoch drift**: an inbound `cohortEpoch` that differs from the local epoch fires the
+ *   drift handlers, and record deltas under a foreign epoch are *not* merged (their slot
+ *   assignments belong to a different membership snapshot);
+ * - **optionally authenticates** inbound transport frames via an injected {@link GossipInboundVerifier}
+ *   (db-p2p binds peer-sig + cohort membership), dropping forged or non-member gossip before any merge.
+ *
+ * Convergence target (doc): a single gossip round spreads a touched record / willingness flip to all
+ * members — one {@link CohortGossipBus.applyInbound} of that gossip makes it visible locally.
+ */
+
+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 { ChildLinkRefV1, CohortGossipV1 } from "../wire/types.js";
+import { fromGossipRecord } from "./records.js";
+import { createCohortView, type CohortView, type MutableCohortView } from "./view.js";
+
+/** Handler for inbound gossip (after merge). */
+export type GossipHandler = (g: CohortGossipV1) => void;
+/** Handler for a detected cohort-epoch drift on an inbound gossip. */
+export type DriftHandler = (inboundEpoch: Uint8Array, localEpoch: Uint8Array, from: string) => void;
+/** Authenticity gate for an inbound gossip arriving over the transport — `false` drops the frame. */
+export type GossipInboundVerifier = (g: CohortGossipV1) => boolean;
+
+export interface CohortGossipBusDeps {
+	/** FRET-backed cohort gossip transport (broadcast / subscribe). */
+	transport: ICohortGossipTransport;
+	/** Local registration store record deltas merge into. */
+	store: RegistrationStore;
+	/** This cohort's coord — the broadcast key **and** the inbound routing key (see {@link CohortGossipV1.coord}). */
+	coord: RingCoord;
+	/** The local cohort epoch, read fresh each merge so rotation is observed. */
+	localEpoch: () => Uint8Array;
+	/** Wall clock for inbound merges via the transport path; injectable for tests. */
+	now?: () => number;
+	/** Frame ceiling for encode/decode (defaults to the codec default). */
+	maxMessageBytes?: number;
+	/**
+	 * Optional authenticity gate run on every gossip arriving over the transport (db-p2p binds it to the
+	 * peer-sig primitive: verify `fromMember`'s signature over the gossip image **and** that `fromMember`
+	 * is a member of this coord's cohort). A `false` verdict drops the frame — no merge, no handler fire —
+	 * so a forged or non-member gossip can neither spoof willingness/load nor replicate fake records.
+	 * Absent → the gate is skipped (unit tests / key-less interim mode); the `coord` routing check below
+	 * still runs regardless. Not applied to direct {@link CohortGossipBus.applyInbound} calls (the trusted
+	 * test/internal merge entry point).
+	 */
+	verifyInbound?: GossipInboundVerifier;
+	/**
+	 * Optional hook fired after a merge that deleted one or more records via gossiped evictions, carrying
+	 * the **distinct** topic ids touched. db-p2p wires it to re-`touch` the per-cohort topic budget down
+	 * (`topicBudget.touch(t, store.directParticipants(t))`) so a topic whose participants drain on a
+	 * *sibling* (the drain arrives here as a gossip eviction, never this member's own TTL sweep) still
+	 * releases its budget slot — mirroring the engine's own `sweepStale` re-touch. Kept as a decoupled
+	 * 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). */
+export interface CohortGossipBus {
+	/** Broadcast `g` to the cohort. */
+	broadcast(g: CohortGossipV1): void;
+	/** Subscribe to inbound gossip (fired after merge); returns an unsubscribe handle. */
+	onGossip(handler: GossipHandler): () => void;
+	/** Subscribe to epoch-drift detections; returns an unsubscribe handle. */
+	onDrift(handler: DriftHandler): () => void;
+	/** Merge one inbound gossip: records/willingness/load, with epoch drift detection. */
+	applyInbound(g: CohortGossipV1, now: number): void;
+	/** The merged per-member view (willingness / load / summaries). */
+	view(): CohortView;
+	/** Detach the transport subscription. */
+	close(): void;
+}
+
+class TransportCohortGossipBus implements CohortGossipBus {
+	private readonly gossipHandlers = new Set<GossipHandler>();
+	private readonly driftHandlers = new Set<DriftHandler>();
+	private readonly memberView: MutableCohortView = createCohortView();
+	private readonly now: () => number;
+	private readonly detach: () => void;
+
+	constructor(private readonly deps: CohortGossipBusDeps) {
+		this.now = deps.now ?? ((): number => Date.now());
+		this.detach = deps.transport.onMessage((_from: PeerRef, msg: Uint8Array) => this.onInbound(msg));
+	}
+
+	broadcast(g: CohortGossipV1): void {
+		this.deps.transport.broadcast(this.deps.coord, encodeCohortMessage(g, this.deps.maxMessageBytes));
+	}
+
+	onGossip(handler: GossipHandler): () => void {
+		this.gossipHandlers.add(handler);
+		return () => this.gossipHandlers.delete(handler);
+	}
+
+	onDrift(handler: DriftHandler): () => void {
+		this.driftHandlers.add(handler);
+		return () => this.driftHandlers.delete(handler);
+	}
+
+	applyInbound(g: CohortGossipV1, now: number): void {
+		// Coord routing: a frame is fanned to every coord engine's bus, but it belongs only to the bus
+		// whose coord it names. Drop any gossip for another cohort so it cannot merge into this store/view
+		// (two coords on one node can even share a member set — and thus an epoch — so epoch alone never
+		// isolates them).
+		if (!this.isOurCoord(g)) {
+			return;
+		}
+		const localEpoch = this.deps.localEpoch();
+		const inboundEpoch = b64urlToBytes(g.cohortEpoch);
+		const epochMatches = bytesEqual(inboundEpoch, localEpoch);
+		if (!epochMatches) {
+			for (const handler of this.driftHandlers) {
+				handler(inboundEpoch, localEpoch, g.fromMember);
+			}
+		}
+		this.mergeView(g, inboundEpoch);
+		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 {
+		return this.memberView;
+	}
+
+	close(): void {
+		this.detach();
+	}
+
+	private onInbound(msg: Uint8Array): void {
+		const g = decodeCohortGossipV1(msg, this.deps.maxMessageBytes);
+		// Cheap routing check first so a non-matching coord skips the (expensive) signature verify.
+		if (!this.isOurCoord(g)) {
+			return;
+		}
+		// Authenticity gate (db-p2p binds peer-sig + cohort membership); a forged/non-member gossip is
+		// dropped before any merge or handler fire. Absent in key-less/unit composition.
+		if (this.deps.verifyInbound !== undefined && !this.deps.verifyInbound(g)) {
+			return;
+		}
+		this.applyInbound(g, this.now());
+		for (const handler of this.gossipHandlers) {
+			handler(g);
+		}
+	}
+
+	/** True iff `g` names this bus's cohort coord (the inbound routing key). */
+	private isOurCoord(g: CohortGossipV1): boolean {
+		return bytesEqual(b64urlToBytes(g.coord), this.deps.coord);
+	}
+
+	private mergeView(g: CohortGossipV1, inboundEpoch: Uint8Array): void {
+		this.memberView.merge(g.fromMember, {
+			cohortEpoch: inboundEpoch,
+			willingness: parseInt(g.willingnessBits, 16),
+			loadBuckets: g.loadBuckets,
+			windowSeconds: g.windowSeconds,
+			topicSummaries: g.topicSummaries,
+			timestamp: g.timestamp,
+		});
+	}
+
+	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.
+			if (now - incoming.lastPing > incoming.ttl) {
+				continue;
+			}
+			const held = this.deps.store.getByParticipant(incoming.topicId, incoming.participantId);
+			// Last-writer-wins by lastPing: a touch (newer lastPing) replaces an older replica.
+			if (held === undefined || incoming.lastPing >= held.lastPing) {
+				this.deps.store.put(incoming);
+			}
+		}
+		// Collect the distinct topics a gossiped eviction drained so the budget can be re-touched *after*
+		// the deletes (the count must be post-drain). This is the sibling-drain half of the topic-budget
+		// leak fix: a topic whose participants are sharded onto a sibling primary drains into this store as
+		// a gossip eviction, never via this member's own TTL sweep, so the `onRecordsEvicted` callback must
+		// re-`touch` the budget down here too — otherwise the slot leaks for any multi-member topic.
+		let evictedTopics: Map<string, Uint8Array> | undefined;
+		for (const ref of g.evicted ?? []) {
+			const topicId = b64urlToBytes(ref.topicId);
+			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);
+			}
+		}
+		if (evictedTopics !== undefined && evictedTopics.size > 0) {
+			this.deps.onRecordsEvicted!([...evictedTopics.values()]);
+		}
+	}
+}
+
+/** Build a {@link CohortGossipBus} over the injected transport + store. */
+export function createCohortGossipBus(deps: CohortGossipBusDeps): CohortGossipBus {
+	return new TransportCohortGossipBus(deps);
+}

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

@@ -1,3 +1,3 @@
-export * from "./records.js";
-export * from "./view.js";
-export * from "./bus.js";
+export * from "./records.js";
+export * from "./view.js";
+export * from "./bus.js";

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

@@ -1,45 +1,45 @@
-/**
- * Cohort-topic substrate — translation between the local {@link RegistrationRecord} (raw bytes)
- * and the wire {@link GossipRecordV1} (base64url). The gossip bus carries record deltas so backups
- * hold the record before the primary fails (per `docs/cohort-topic.md` §Registration record).
- */
-
-import { b64urlToBytes, bytesToB64url } from "../wire/codec.js";
-import type { GossipRecordV1 } from "../wire/types.js";
-import type { RegistrationRecord } from "../registration/types.js";
-
-/** Encode a local registration record for cross-member gossip. */
-export function toGossipRecord(rec: RegistrationRecord): GossipRecordV1 {
-	const out: GossipRecordV1 = {
-		topicId: bytesToB64url(rec.topicId),
-		participantId: bytesToB64url(rec.participantId),
-		tier: rec.tier,
-		primary: bytesToB64url(rec.primary),
-		backups: rec.backups.map(bytesToB64url),
-		attachedAt: rec.attachedAt,
-		lastPing: rec.lastPing,
-		ttl: rec.ttl,
-	};
-	if (rec.appState !== undefined) {
-		out.appState = bytesToB64url(rec.appState);
-	}
-	return out;
-}
-
-/** Decode a gossiped record back into the local store shape. */
-export function fromGossipRecord(g: GossipRecordV1): RegistrationRecord {
-	const out: RegistrationRecord = {
-		topicId: b64urlToBytes(g.topicId),
-		participantId: b64urlToBytes(g.participantId),
-		tier: g.tier,
-		primary: b64urlToBytes(g.primary),
-		backups: g.backups.map(b64urlToBytes),
-		attachedAt: g.attachedAt,
-		lastPing: g.lastPing,
-		ttl: g.ttl,
-	};
-	if (g.appState !== undefined) {
-		out.appState = b64urlToBytes(g.appState);
-	}
-	return out;
-}
+/**
+ * Cohort-topic substrate — translation between the local {@link RegistrationRecord} (raw bytes)
+ * and the wire {@link GossipRecordV1} (base64url). The gossip bus carries record deltas so backups
+ * hold the record before the primary fails (per `docs/cohort-topic.md` §Registration record).
+ */
+
+import { b64urlToBytes, bytesToB64url } from "../wire/codec.js";
+import type { GossipRecordV1 } from "../wire/types.js";
+import type { RegistrationRecord } from "../registration/types.js";
+
+/** Encode a local registration record for cross-member gossip. */
+export function toGossipRecord(rec: RegistrationRecord): GossipRecordV1 {
+	const out: GossipRecordV1 = {
+		topicId: bytesToB64url(rec.topicId),
+		participantId: bytesToB64url(rec.participantId),
+		tier: rec.tier,
+		primary: bytesToB64url(rec.primary),
+		backups: rec.backups.map(bytesToB64url),
+		attachedAt: rec.attachedAt,
+		lastPing: rec.lastPing,
+		ttl: rec.ttl,
+	};
+	if (rec.appState !== undefined) {
+		out.appState = bytesToB64url(rec.appState);
+	}
+	return out;
+}
+
+/** Decode a gossiped record back into the local store shape. */
+export function fromGossipRecord(g: GossipRecordV1): RegistrationRecord {
+	const out: RegistrationRecord = {
+		topicId: b64urlToBytes(g.topicId),
+		participantId: b64urlToBytes(g.participantId),
+		tier: g.tier,
+		primary: b64urlToBytes(g.primary),
+		backups: g.backups.map(b64urlToBytes),
+		attachedAt: g.attachedAt,
+		lastPing: g.lastPing,
+		ttl: g.ttl,
+	};
+	if (g.appState !== undefined) {
+		out.appState = b64urlToBytes(g.appState);
+	}
+	return out;
+}