@optimystic/db-core 0.13.4 → 0.14.0

package/src/cohort-topic/coldstart.ts

@@ -0,0 +1,204 @@
+/**
+ * Cohort-topic substrate — cold-start instantiation.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Cold-start instantiation and folded back from the
+ * simulator-validated `packages/substrate-simulator/src/walk.ts` (the `followOn` / `bootstrap`
+ * instantiation paths). A **cold** cohort — one holding no forwarder state for a topic — instantiates
+ * as a forwarder for `T` when:
+ *
+ * - it receives a `RegisterV1` for `T` it does not yet serve, AND
+ * - the registration is a legitimate growth point: its `bootstrap: true` flag is set (the root
+ *   cold-start case) **or** it arrived as a follow-on to a parent cohort's `Promoted` redirect, AND
+ * - a quorum of cohort members is willing to serve `T` at the registration's tier.
+ *
+ * The `followOn` signal is **not** carried on the wire (`RegisterV1` has only `bootstrap`); a cold
+ * high-tier cohort returns `NoState` to a *speculative* `d_max` probe, but the single-direction walk
+ * means the only registrations that reach a cold tier-`(d+1)` cohort are those that followed the
+ * parent's `Promoted` redirect. Determining `followOn` for a given inbound register therefore belongs
+ * to the db-p2p cohort host (it has the routing context); db-core takes it as an explicit input to
+ * {@link shouldInstantiate}, keeping this module FRET-free. (See the implement handoff for the wiring
+ * gap this leaves for the db-p2p binding.)
+ *
+ * Once instantiated, the new forwarder **registers itself with its tier-`(d − 1)` parent at first
+ * opportunity**; until that registration is acked it {@link Forwarder.acceptsParticipants | accepts
+ * participants} but {@link Forwarder.servesParentOps | holds} notifications/queries that need parent
+ * involvement. The root (tree tier 0) has no parent and is serving immediately.
+ *
+ * **Just-promoted burst (GROUNDING-resolved: bounce, don't buffer).** A cohort that has just promoted
+ * but whose tier-`(d+1)` isn't fully instantiated yet, on a burst of new same-tier registrations,
+ * replies `Promoted(d+1)` ({@link promotedRedirectReply}) — a cheap single RPC. It does **not** buffer
+ * the registrations and does **not** decline with `UnwillingCohort`; the promotion sticky window
+ * (`T_promote_sticky`) keeps it in promoted mode through the burst.
+ */
+
+import { attachTopicTraffic } from "./traffic.js";
+import { bytesKey } from "./registration/bytes.js";
+import type { RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
+
+/** Inputs to the cold-start admission gate. */
+export interface ColdStartTrigger {
+	/** `RegisterV1.bootstrap` — the root cold-start request flag. */
+	readonly bootstrap: boolean;
+	/** This register arrived as a follow-on to a parent's `Promoted` redirect (db-p2p-determined). */
+	readonly followOn: boolean;
+	/** A quorum of cohort members is willing to serve the topic at this tier. */
+	readonly quorumWilling: boolean;
+}
+
+/**
+ * Whether a cold cohort should instantiate forwarder state for an inbound register: it must be a
+ * legitimate growth point (`bootstrap` root case **or** a `Promoted` follow-on) **and** have a willing
+ * quorum. A speculative `d_max` probe (neither flag set) yields `false`, so the walk gets `NoState`
+ * and steps toward the root instead of forking a parallel branch (§Cold-start; §Why the caller
+ * doesn't walk on UnwillingCohort).
+ */
+export function shouldInstantiate(trigger: ColdStartTrigger): boolean {
+	return (trigger.bootstrap || trigger.followOn) && trigger.quorumWilling;
+}
+
+/** Lifecycle phase of a freshly-instantiated forwarder. */
+export type ForwarderPhase =
+	/** Instantiated, registering with the parent; accepts participants, holds parent-involving ops. */
+	| "awaiting_parent"
+	/** Fully linked (parent acked, or root with no parent); serves everything. */
+	| "serving";
+
+/**
+ * A freshly cold-started forwarder for one topic at this cohort. Holds the "registered with parent
+ * yet?" state that gates parent-involving operations during the link-up window.
+ */
+export interface Forwarder {
+	/** Tree tier `d` this forwarder serves the topic at. */
+	readonly tier: number;
+	/** Current lifecycle phase. */
+	phase(): ForwarderPhase;
+	/** Accept new participants? True from instantiation onward (even before the parent ack). */
+	acceptsParticipants(): boolean;
+	/** Serve an operation needing parent involvement (notifications/queries)? Only once `serving`. */
+	servesParentOps(): boolean;
+	/** Mark the parent-registration RPC acked → transition to `serving`. Idempotent; no-op at the root. */
+	onParentAck(): void;
+}
+
+class ForwarderState implements Forwarder {
+	private serving: boolean;
+
+	constructor(readonly tier: number, hasParent: boolean) {
+		// The root (tree tier 0 / no parent) has nothing to hand off to — it serves immediately.
+		this.serving = !hasParent;
+	}
+
+	phase(): ForwarderPhase {
+		return this.serving ? "serving" : "awaiting_parent";
+	}
+
+	acceptsParticipants(): boolean {
+		return true;
+	}
+
+	servesParentOps(): boolean {
+		return this.serving;
+	}
+
+	onParentAck(): void {
+		this.serving = true;
+	}
+}
+
+/**
+ * Construct a forwarder. A tier-`0` forwarder (the root) has no parent and starts `serving`; a deeper
+ * forwarder starts `awaiting_parent` until {@link Forwarder.onParentAck} fires.
+ */
+export function createForwarder(tier: number): Forwarder {
+	if (!Number.isInteger(tier) || tier < 0) {
+		throw new RangeError(`forwarder tier must be a non-negative integer, got ${tier}`);
+	}
+	return new ForwarderState(tier, tier > 0);
+}
+
+/**
+ * Build a `Promoted(targetTier)` redirect reply — used both for the normal promotion redirect and for
+ * the just-promoted-burst bounce (the registrations arriving at a promoted cohort while its child tier
+ * is still instantiating). The outgoing cohort's `topicTraffic` is attached when supplied, so the
+ * redirected participant can estimate whether the target tier is hot (§Topic traffic signal).
+ */
+export function promotedRedirectReply(targetTier: number, traffic?: TopicTrafficV1): RegisterReplyV1 {
+	if (!Number.isInteger(targetTier) || targetTier < 1) {
+		throw new RangeError(`promoted targetTier must be an integer ≥ 1, got ${targetTier}`);
+	}
+	const reply: RegisterReplyV1 = { v: 1, result: "promoted", targetTier };
+	return traffic !== undefined ? attachTopicTraffic(reply, traffic) : reply;
+}
+
+/** Registers a newly-instantiated forwarder with its tier-`(d − 1)` parent; resolves on the parent ack. */
+export interface ParentRegistrar {
+	/**
+	 * Register the forwarder for `topicId` (served at tree tier `tier`, i.e. `d`) with the cohort at
+	 * `parentCoord`; resolves on ack. `opTier` is the topic's *capacity* tier (T0–T3), threaded so the
+	 * transport can stamp a well-formed forwarder-link frame; absent when the caller has no op-tier
+	 * context (the cohort host always supplies it from the instantiating `RegisterV1`).
+	 */
+	registerWithParent(topicId: Uint8Array, parentCoord: Uint8Array, tier: number, opTier?: number): Promise<void>;
+}
+
+export interface ColdStartManagerDeps {
+	/** Drives the parent-registration RPC (db-p2p binds it to the router). */
+	parentRegistrar: ParentRegistrar;
+}
+
+/**
+ * Tracks cold-started forwarders for a cohort and drives each one's parent registration. Keyed by
+ * `topicId`; idempotent per topic (a second instantiate for an already-tracked topic returns the
+ * existing forwarder).
+ */
+export interface ColdStartManager {
+	/**
+	 * Instantiate (or return the existing) forwarder for `topicId` at tree tier `tier` (`d`). For a
+	 * deeper-than-root forwarder this kicks off parent registration in the background and flips the
+	 * forwarder to `serving` on ack. The returned forwarder accepts participants immediately. `opTier`
+	 * (the topic's T0–T3 capacity tier) is forwarded to the parent registrar for the link frame.
+	 */
+	instantiate(topicId: Uint8Array, tier: number, parentCoord?: Uint8Array, opTier?: number): Forwarder;
+	/** The tracked forwarder for `topicId`, or `undefined`. */
+	get(topicId: Uint8Array): Forwarder | undefined;
+}
+
+class TrackingColdStartManager implements ColdStartManager {
+	private readonly forwarders = new Map<string, Forwarder>();
+
+	constructor(private readonly deps: ColdStartManagerDeps) {}
+
+	instantiate(topicId: Uint8Array, tier: number, parentCoord?: Uint8Array, opTier?: number): Forwarder {
+		const key = bytesKey(topicId);
+		const existing = this.forwarders.get(key);
+		if (existing !== undefined) {
+			return existing;
+		}
+		const forwarder = createForwarder(tier);
+		this.forwarders.set(key, forwarder);
+		if (tier > 0) {
+			if (parentCoord === undefined) {
+				throw new Error(`cold-start of a tier-${tier} forwarder requires a parentCoord`);
+			}
+			// Register with the parent at first opportunity; flip to serving on ack. A failed parent
+			// registration leaves the forwarder accepting participants but holding parent-involving ops,
+			// so a later retry (driven by the host) can complete the link-up — surfaced, not swallowed.
+			void this.deps.parentRegistrar
+				.registerWithParent(topicId, parentCoord, tier, opTier)
+				.then(() => forwarder.onParentAck())
+				.catch((err: unknown) => {
+					console.warn(`cohort-topic cold-start: parent registration for tier-${tier} forwarder failed`, err);
+				});
+		}
+		return forwarder;
+	}
+
+	get(topicId: Uint8Array): Forwarder | undefined {
+		return this.forwarders.get(bytesKey(topicId));
+	}
+}
+
+/** Build a {@link ColdStartManager} over the injected parent registrar. */
+export function createColdStartManager(deps: ColdStartManagerDeps): ColdStartManager {
+	return new TrackingColdStartManager(deps);
+}

package/src/cohort-topic/dmax.ts

@@ -0,0 +1,88 @@
+/**
+ * Cohort-topic substrate — network-size-driven `d_max`.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Maximum useful depth:
+ *
+ * ```
+ * d_max = max(0, ⌊log_F(n_est)⌋ − 1)
+ * ```
+ *
+ * If `n_est` confidence falls below `confidence_min` (default 0.3) the computation caps `d_max` at
+ * `⌊d_max_cap / 2⌋` (`d_max_cap` default 60) as an upper bound — i.e. `min(formula, ⌊d_max_cap / 2⌋)` —
+ * to avoid pathological deep probes from an over-estimated population. Small/sparse populations
+ * (where the formula already yields a small value) are unaffected.
+ *
+ * `d_max` is the start tier of the walk-toward-root and is recomputed **lazily** — participants
+ * don't need it precise. The size estimate is read through the injected {@link ISizeEstimator}
+ * (db-p2p wraps FRET's `estimateSizeAndConfidence`; db-core never imports FRET).
+ */
+
+import type { ISizeEstimator } from "./ports.js";
+
+/** Lazily computes the walk start tier `d_max` from the current network-size estimate. */
+export interface DMaxComputer {
+	/** Reads the size estimate, applies the low-confidence cap, returns `d_max`. */
+	dMax(): number;
+}
+
+/** Default below which `n_est` confidence triggers the `d_max` cap. */
+export const DEFAULT_CONFIDENCE_MIN = 0.3;
+/** Default hard cap on the walk-toward-root start tier. */
+export const DEFAULT_D_MAX_CAP = 60;
+
+export interface DMaxConfig {
+	/** Network-size estimate source (db-p2p wraps FRET `estimateSizeAndConfidence`). */
+	estimator: ISizeEstimator;
+	/** Fan-out per tier (the `F` in `log_F`). */
+	F: number;
+	/** Confidence floor; below it `d_max` is capped at `⌊d_max_cap / 2⌋` (upper bound). Default 0.3. */
+	confidenceMin?: number;
+	/** Hard cap on `d_max`; also drives the low-confidence cap value. Default 60. */
+	dMaxCap?: number;
+}
+
+/**
+ * `⌊log_F(n)⌋` computed without floating-point drift near exact powers of `F`. Multiplies back up to
+ * confirm the floor (`Math.log` can return e.g. `2.9999999` for `log_16(4096)`), so the result is
+ * exact for all `n` representable as a JS integer.
+ */
+function floorLogF(n: number, F: number): number {
+	if (n < 1) return 0;
+	let d = Math.floor(Math.log(n) / Math.log(F));
+	if (d < 0) d = 0;
+	// Correct floating-point error at the boundary in both directions.
+	while (Math.pow(F, d + 1) <= n) d++;
+	while (d > 0 && Math.pow(F, d) > n) d--;
+	return d;
+}
+
+/**
+ * Build a {@link DMaxComputer}. The estimate is read on every {@link DMaxComputer.dMax} call so the
+ * value tracks the latest FRET sample; callers cache it themselves if they want stability.
+ */
+export function makeDMaxComputer(config: DMaxConfig): DMaxComputer {
+	const { estimator, F } = config;
+	if (!Number.isInteger(F) || F < 2) {
+		throw new RangeError(`fan-out F must be an integer ≥ 2, got ${F}`);
+	}
+	const confidenceMin = config.confidenceMin ?? DEFAULT_CONFIDENCE_MIN;
+	const dMaxCap = config.dMaxCap ?? DEFAULT_D_MAX_CAP;
+	if (!Number.isInteger(dMaxCap) || dMaxCap < 0) {
+		throw new RangeError(`d_max_cap must be a non-negative integer, got ${dMaxCap}`);
+	}
+	const capValue = Math.floor(dMaxCap / 2);
+
+	return {
+		dMax(): number {
+			const { nEst, confidence } = estimator.estimate();
+			const formula = Math.min(Math.max(0, floorLogF(nEst, F) - 1), dMaxCap);
+			// Low confidence caps d_max as an upper bound (not a set-to): an over-estimated
+			// population can't push the walk deeper than ⌊d_max_cap / 2⌋, while small
+			// populations keep their (smaller) formula value.
+			if (confidence < confidenceMin) {
+				return Math.min(formula, capValue);
+			}
+			return formula;
+		},
+	};
+}

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

@@ -0,0 +1,217 @@
+/**
+ * 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 type { ICohortGossipTransport, PeerRef, RingCoord } from "../ports.js";
+import { b64urlToBytes, decodeCohortGossipV1, encodeCohortMessage } from "../wire/codec.js";
+import type { 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;
+}
+
+/** 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);
+		}
+	}
+
+	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);
+			// 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);
+			this.deps.store.delete(topicId, b64urlToBytes(ref.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

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

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

@@ -0,0 +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;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Cohort-topic substrate — the merged per-member gossip view.
+ *
+ * Each cohort member periodically gossips its willingness vector, load barometer buckets, and exact
+ * per-topic summaries (`CohortGossipV1`). The bus folds the latest such contribution per member into
+ * this view (last-writer-wins by gossip `timestamp`), which the willingness, barometer, and traffic
+ * tickets read. Records replicate into the registration store separately (see {@link createCohortGossipBus}).
+ */
+
+import type { CohortTopicSummary } from "../wire/types.js";
+
+/** Latest gossip contribution from a single cohort member. */
+export interface MemberContribution {
+	/** Cohort epoch this member gossiped under (drift signal). */
+	readonly cohortEpoch: Uint8Array;
+	/** Willingness vector, 4 bits T0..T3 (0..15) decoded from the hex nibble. */
+	readonly willingness: number;
+	/** Load barometer buckets, 4 entries 0..7 per tier. */
+	readonly loadBuckets: readonly number[];
+	/** Observation window for the rate fields in `topicSummaries`. */
+	readonly windowSeconds: number;
+	/** Exact per-topic summaries this member last reported. */
+	readonly topicSummaries: readonly CohortTopicSummary[];
+	/** Gossip timestamp (unix ms) — the last-writer-wins key. */
+	readonly timestamp: number;
+}
+
+/** Read view over the merged per-member contributions, keyed by `fromMember`. */
+export interface CohortView {
+	/** Latest contribution from `member` (the `fromMember` string), or `undefined`. */
+	get(member: string): MemberContribution | undefined;
+	/** All current contributions, keyed by `fromMember`. */
+	all(): ReadonlyMap<string, MemberContribution>;
+}
+
+/** Mutable view the bus writes into; exposes the read {@link CohortView} surface. */
+export interface MutableCohortView extends CohortView {
+	/** Merge `c` for `member` iff it is at least as recent as the held contribution. Returns true if applied. */
+	merge(member: string, c: MemberContribution): boolean;
+}
+
+class MapCohortView implements MutableCohortView {
+	private readonly byMember = new Map<string, MemberContribution>();
+
+	get(member: string): MemberContribution | undefined {
+		return this.byMember.get(member);
+	}
+
+	all(): ReadonlyMap<string, MemberContribution> {
+		return this.byMember;
+	}
+
+	merge(member: string, c: MemberContribution): boolean {
+		const held = this.byMember.get(member);
+		if (held !== undefined && c.timestamp < held.timestamp) {
+			return false; // stale; keep the newer contribution
+		}
+		this.byMember.set(member, c);
+		return true;
+	}
+}
+
+/** Construct an empty {@link MutableCohortView}. */
+export function createCohortView(): MutableCohortView {
+	return new MapCohortView();
+}

package/src/cohort-topic/index.ts

@@ -0,0 +1,20 @@
+export * from "./ports.js";
+export * from "./ring-hash.js";
+export * from "./addressing.js";
+export * from "./tiers.js";
+export * from "./dmax.js";
+export * from "./wire/index.js";
+export * from "./registration/index.js";
+export * from "./gossip/index.js";
+export * from "./sig/index.js";
+export * from "./membership/index.js";
+export * from "./load/index.js";
+export * from "./willingness.js";
+export * from "./traffic.js";
+export * from "./walk.js";
+export * from "./promotion.js";
+export * from "./coldstart.js";
+export * from "./antiflood/index.js";
+export * from "./antidos/index.js";
+export * from "./member-engine.js";
+export * from "./service.js";