@optimystic/db-core 0.13.5 → 0.14.0

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";

package/src/cohort-topic/load/barometer.ts

@@ -0,0 +1,134 @@
+/**
+ * Cohort-topic substrate — capacity barometer.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Capacity barometer (and folded back from the
+ * simulator-validated `packages/substrate-simulator/src/willingness.ts`). A cohort member tracks a
+ * coarse **3-bit (0..7) log-bucketed utilization** per tier (T0..T3). The barometer feeds two
+ * decisions:
+ *
+ * 1. **Willingness-bit refresh.** When a tier's bucket reaches `overloadBucket` the member sheds
+ *    that tier — its load-driven willingness bit flips off until utilization recedes. Siblings see
+ *    the flip within one gossip round (the bit rides `CohortGossipV1.willingnessBits`).
+ * 2. **Early-promote signal.** `bucket ≥ overloadBucket` (default 6, the `bucket_overload` of
+ *    §Configuration) is the "cohort is hot at this tier" signal the promotion ticket consumes to
+ *    fire promotion earlier than the strict `cap_promote`. This module only *exposes* the signal;
+ *    it does not itself promote.
+ *
+ * The barometer is **not** aggregated across the tree — children promote independently, so a member
+ * only ever observes its own per-tier utilization here. The 3-bit buckets (× 4 tiers) plus the
+ * willingness bit fit in 16 bits of cohort gossip; the cost is negligible.
+ */
+
+import { ALL_TIERS, type Tier } from "../tiers.js";
+
+/** A single tier's coarse load reading, as carried in cohort gossip. */
+export interface LoadBarometer {
+	readonly tier: Tier;
+	/** 0..7, log-bucketed utilization (see {@link utilizationBucket}). */
+	readonly bucket: number;
+}
+
+/**
+ * Load-barometer bucket at/above which a member sheds a tier (willingness flips off) and the cohort
+ * is considered hot enough to promote early. `bucket_overload` in `docs/cohort-topic.md`
+ * §Configuration; simulator-confirmed at 6.
+ */
+export const DEFAULT_OVERLOAD_BUCKET = 6;
+
+/**
+ * Map a utilization ratio (`load / capacity`, where `1.0` = at capacity) to a 0..7 log bucket.
+ *
+ * Each bucket spans a doubling of utilization, anchored so the top of the range is at-capacity:
+ *
+ * | bucket | utilization range |
+ * |--------|-------------------|
+ * | 7      | `u ≥ 1.0`         |
+ * | 6      | `[0.5, 1.0)`      |
+ * | 5      | `[0.25, 0.5)`     |
+ * | …      | …                 |
+ * | 1      | `[1/64, 1/32)`    |
+ * | 0      | `u < 1/64` (incl. 0, negative clamped) |
+ *
+ * Monotonic non-decreasing in `u`; `bucket = clamp(7 + ⌊log₂ u⌋, 0, 7)`. With the default
+ * `overloadBucket = 6`, a member sheds a tier once utilization reaches half capacity.
+ */
+export function utilizationBucket(utilization: number): number {
+	if (!(utilization > 0)) {
+		return 0; // zero, negative, or NaN → idle
+	}
+	const b = 7 + Math.floor(Math.log2(utilization));
+	if (b < 0) return 0;
+	if (b > 7) return 7;
+	return b;
+}
+
+/** Mutable per-tier capacity barometer for one cohort member. */
+export interface LoadBarometerState {
+	/** Record this member's current utilization (`load / capacity`) for `tier`. */
+	observe(tier: Tier, utilization: number): void;
+	/** Current 0..7 bucket for `tier`. */
+	bucket(tier: Tier): number;
+	/** `{ tier, bucket }` reading for `tier`. */
+	reading(tier: Tier): LoadBarometer;
+	/** All four buckets (T0..T3), the array gossiped in `CohortGossipV1.loadBuckets`. */
+	loadBuckets(): number[];
+	/**
+	 * Early-promote / shed signal: `bucket(tier) ≥ overloadBucket`. True means the member is hot at
+	 * `tier` — its load-driven willingness bit is off and the promotion layer may promote early.
+	 */
+	isOverloaded(tier: Tier): boolean;
+	/** Load-driven willingness bit for `tier`: `!isOverloaded(tier)`. (Profile/budget gates live in the willingness check.) */
+	loadWilling(tier: Tier): boolean;
+}
+
+export interface LoadBarometerConfig {
+	/** Bucket at/above which a tier is shed and flagged hot. Default {@link DEFAULT_OVERLOAD_BUCKET}. */
+	overloadBucket?: number;
+}
+
+class ArrayLoadBarometer implements LoadBarometerState {
+	private readonly buckets: number[] = [0, 0, 0, 0];
+	private readonly overloadBucket: number;
+
+	constructor(config?: LoadBarometerConfig) {
+		const ob = config?.overloadBucket ?? DEFAULT_OVERLOAD_BUCKET;
+		if (!Number.isInteger(ob) || ob < 1 || ob > 7) {
+			throw new RangeError(`overloadBucket must be an integer in [1, 7], got ${ob}`);
+		}
+		this.overloadBucket = ob;
+	}
+
+	observe(tier: Tier, utilization: number): void {
+		this.buckets[tier] = utilizationBucket(utilization);
+	}
+
+	bucket(tier: Tier): number {
+		return this.buckets[tier]!;
+	}
+
+	reading(tier: Tier): LoadBarometer {
+		return { tier, bucket: this.buckets[tier]! };
+	}
+
+	loadBuckets(): number[] {
+		return [...this.buckets];
+	}
+
+	isOverloaded(tier: Tier): boolean {
+		return this.buckets[tier]! >= this.overloadBucket;
+	}
+
+	loadWilling(tier: Tier): boolean {
+		return !this.isOverloaded(tier);
+	}
+}
+
+/** Construct an idle (all-bucket-0) {@link LoadBarometerState}. */
+export function createLoadBarometer(config?: LoadBarometerConfig): LoadBarometerState {
+	return new ArrayLoadBarometer(config);
+}
+
+/** Iterate the four tiers — convenience for callers folding the barometer into a gossip frame. */
+export function eachTier(): readonly Tier[] {
+	return ALL_TIERS;
+}

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

@@ -0,0 +1 @@
+export * from "./barometer.js";