@optimystic/db-core 0.21.0 → 0.24.0

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

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

package/src/cohort-topic/index.ts

@@ -1,20 +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";
+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

@@ -1,134 +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;
-}
+/**
+ * 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

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