@optimystic/db-core 0.13.4 → 0.14.0

package/dist/src/cohort-topic/load/barometer.js

@@ -0,0 +1,93 @@
+/**
+ * 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 } from "../tiers.js";
+/**
+ * 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) {
+    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;
+}
+class ArrayLoadBarometer {
+    buckets = [0, 0, 0, 0];
+    overloadBucket;
+    constructor(config) {
+        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, utilization) {
+        this.buckets[tier] = utilizationBucket(utilization);
+    }
+    bucket(tier) {
+        return this.buckets[tier];
+    }
+    reading(tier) {
+        return { tier, bucket: this.buckets[tier] };
+    }
+    loadBuckets() {
+        return [...this.buckets];
+    }
+    isOverloaded(tier) {
+        return this.buckets[tier] >= this.overloadBucket;
+    }
+    loadWilling(tier) {
+        return !this.isOverloaded(tier);
+    }
+}
+/** Construct an idle (all-bucket-0) {@link LoadBarometerState}. */
+export function createLoadBarometer(config) {
+    return new ArrayLoadBarometer(config);
+}
+/** Iterate the four tiers — convenience for callers folding the barometer into a gossip frame. */
+export function eachTier() {
+    return ALL_TIERS;
+}
+//# sourceMappingURL=barometer.js.map

package/dist/src/cohort-topic/load/barometer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barometer.js","sourceRoot":"","sources":["../../../../src/cohort-topic/load/barometer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,SAAS,EAAa,MAAM,aAAa,CAAC;AASnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACpD,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC,CAAC,gCAAgC;IAC3C,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,CAAC;AACV,CAAC;AA0BD,MAAM,kBAAkB;IACN,OAAO,GAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACjC,cAAc,CAAS;IAExC,YAAY,MAA4B;QACvC,MAAM,EAAE,GAAG,MAAM,EAAE,cAAc,IAAI,uBAAuB,CAAC;QAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,UAAU,CAAC,oDAAoD,EAAE,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED,OAAO,CAAC,IAAU,EAAE,WAAmB;QACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,CAAC,IAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAE,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,IAAU;QACjB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAE,EAAE,CAAC;IAC9C,CAAC;IAED,WAAW;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,YAAY,CAAC,IAAU;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAE,IAAI,IAAI,CAAC,cAAc,CAAC;IACnD,CAAC;IAED,WAAW,CAAC,IAAU;QACrB,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;CACD;AAED,mEAAmE;AACnE,MAAM,UAAU,mBAAmB,CAAC,MAA4B;IAC/D,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,QAAQ;IACvB,OAAO,SAAS,CAAC;AAClB,CAAC"}

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

@@ -0,0 +1,2 @@
+export * from "./barometer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cohort-topic/load/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/load/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/src/cohort-topic/load/index.js

@@ -0,0 +1,2 @@
+export * from "./barometer.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cohort-topic/load/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/load/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

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

@@ -0,0 +1,134 @@
+/**
+ * Cohort-topic substrate — cohort-side member engine.
+ *
+ * This is the logic a cohort member runs when FRET's `RouteAndMaybeAct` lands a `RegisterV1`/`RenewV1`
+ * on it (the activity callback in `docs/cohort-topic.md` §FRET integration). It is the cohort-facing
+ * half of the substrate, composed from the prereq tickets' pure modules — the participant-facing half
+ * lives in {@link import("./service.js").CohortTopicService}. db-p2p's FRET host decodes an inbound
+ * frame, supplies the routing context this module can't see (`followOn`, the quorum-willing tally),
+ * and serializes whatever reply this returns back over the wire. db-core never imports FRET here.
+ *
+ * Inbound `RegisterV1` decision pipeline (§Registration mechanics, §Willingness, §Cold-start):
+ *
+ * 1. **Anti-DoS** — freshness/replay guard, per-(peer,topic) rate limit, and cold-root bootstrap
+ *    evidence. A failure short-circuits to `unwilling_cohort` (temporal back-off) or, for a replay,
+ *    a silent `no_state` (no state is served and nothing is recorded).
+ * 2. **Hot vs cold** — if this cohort already serves the topic (forwarder state resident), run the
+ *    willingness check; a promoted topic answers `Promoted(d+1)`. If cold, the topic-budget +
+ *    cold-start gate decides whether to instantiate, else `no_state` (walk steps toward the root).
+ * 3. **Admission** — on `accepted`, assign the deterministic primary/backup slots, persist the
+ *    soft-state record, count the arrival, run the promotion trigger, and attach the topic-traffic
+ *    signal to the reply.
+ *
+ * Every collaborator is injected, so the engine unit-tests without FRET or libp2p.
+ */
+import type { IRingHash } from "./ports.js";
+import type { RegistrationRecord, RegistrationStore } from "./registration/types.js";
+import type { SlotAssigner } from "./registration/sharding.js";
+import type { RenewalCohortSide } from "./registration/renewal.js";
+import type { WillingnessCheck } from "./willingness.js";
+import type { PromotionLifecycle } from "./promotion.js";
+import type { ColdStartManager } from "./coldstart.js";
+import type { TrafficCounters } from "./traffic.js";
+import type { RegisterRateLimiter } from "./antidos/rate-limiter.js";
+import type { CorrelationReplayGuard } from "./antidos/replay-guard.js";
+import type { TopicBudget } from "./antidos/topic-budget.js";
+import type { BootstrapEvidence } from "./antidos/bootstrap-evidence.js";
+import type { NodeProfile, Tier } from "./tiers.js";
+import type { DemotionNoticeV1, PromotionNoticeV1, RegisterReplyV1, RegisterV1, RenewReplyV1, RenewV1 } from "./wire/types.js";
+/** Routing context the FRET host supplies for an inbound register (db-core can't derive it). */
+export interface RegisterContext {
+    /** Did this register arrive as a follow-on to a parent cohort's `Promoted` redirect? */
+    readonly followOn: boolean;
+    /** Tree tier `d` this cohort serves the topic at (the walk position the register landed on). */
+    readonly treeTier: number;
+    /** The tier-`(d − 1)` parent cohort coord, for a cold-start forwarder's parent registration. */
+    readonly parentCoord?: Uint8Array;
+}
+/** Current cohort snapshot — the FRET host fills this from the membership source. */
+export interface CohortSnapshotView {
+    readonly members: readonly Uint8Array[];
+    readonly cohortEpoch: Uint8Array;
+}
+export interface CohortMemberEngineDeps {
+    /** This member's own peer id. */
+    readonly self: Uint8Array;
+    /** This member's static tier profile (Edge/Core willing-tier set). */
+    readonly profile: NodeProfile;
+    /** Hash used for slot assignment + keys (db-core's own SHA-256). */
+    readonly hash: IRingHash;
+    /** Replicated soft-state registration store. */
+    readonly store: RegistrationStore;
+    /** Deterministic primary/backup slot assignment, shared with renewal + handoff. */
+    readonly slots: SlotAssigner;
+    /** Per-member willingness / admission control. */
+    readonly willingness: WillingnessCheck;
+    /** Promotion / demotion lifecycle. */
+    readonly promotion: PromotionLifecycle;
+    /** Cold-start forwarder instantiation + parent registration. */
+    readonly coldStart: ColdStartManager;
+    /** Per-topic traffic counters (gossip-derived snapshots feed the reply signal). */
+    readonly traffic: TrafficCounters;
+    /** Cohort-side TTL renewal handler (touch / primary_moved / sweep). */
+    readonly renewal: RenewalCohortSide;
+    /** Live cohort snapshot (members + epoch). */
+    readonly cohort: () => CohortSnapshotView;
+    /** Whether a quorum of members is willing to serve `tier` (the cold-start gate input). */
+    readonly quorumWilling: (tier: Tier) => boolean;
+    readonly rateLimiter?: RegisterRateLimiter;
+    /**
+     * Dedicated per-(peer, topic) rate limiter for the read-only {@link CohortMemberEngine.handleRegister}
+     * **probe** path — its own budget, separate from {@link rateLimiter}, so a probe flood cannot exhaust a
+     * participant's register budget (or vice-versa). An over-rate probe answers `unwilling_cohort`
+     * (walk → `retry_later` → `CohortBackoffError`). Absent → the probe rate gate is skipped (the read-only
+     * classify still runs), keeping key-less / unit / mock flows composing.
+     */
+    readonly probeRateLimiter?: RegisterRateLimiter;
+    readonly replayGuard?: CorrelationReplayGuard;
+    readonly topicBudget?: TopicBudget;
+    readonly bootstrapEvidence?: BootstrapEvidence;
+    /**
+     * Optional participant peer-key signature verifier (db-p2p binds it to the peer-sig primitive over
+     * {@link import("./wire/payloads.js").registerSigningPayload}). A `RegisterV1` whose signature does
+     * not verify against the claimed `participantCoord` is answered `no_state` (serve nothing, record
+     * nothing) — a cohort member cannot trust an unsigned/forged `participantCoord`. Verified first so a
+     * forged frame never reaches (or pollutes) the replay/rate guards. Absent → the gate is skipped.
+     */
+    readonly verifyRegisterSig?: (reg: RegisterV1) => boolean;
+    /**
+     * Sink for a freshly threshold-signed promotion/demotion notice produced on an arrival (the `accept`
+     * path's promotion trigger). db-p2p's host wires this to broadcast the notice over the `promote`
+     * protocol to the cohort (and, for a demotion, the parent coord). Absent → notices are produced and
+     * applied locally but not broadcast (unit/mock flows). Called fire-and-forget, off the reply path.
+     */
+    readonly onNotice?: (notice: PromotionNoticeV1 | DemotionNoticeV1) => void;
+    /**
+     * Optional logger. Used only to record a failed promotion sign/broadcast (the threshold-sign round
+     * can reject when the cohort quorum is unreachable) rather than swallow it. Absent → silent.
+     */
+    readonly log?: (formatter: string, ...args: unknown[]) => void;
+    /**
+     * Sink for a freshly-admitted registration record (the `accept` path), symmetric to the renewal
+     * `gossip.touch` hook. db-p2p wires this to the same per-coord gossip delta queue the renewal side
+     * appends to, so an admitted record is replicated to the cohort at the next gossip round — closing the
+     * durability window between admission and the participant's first renewal touch. A queue append, not a
+     * synchronous broadcast: admission must not block on a round, and last-writer-wins by `lastPing` dedupes
+     * an admit-then-touch landing in the same round. Absent → no admission-time replication (unit/mock flows
+     * that don't exercise gossip).
+     */
+    readonly onAdmit?: (rec: RegistrationRecord) => void;
+}
+/** Cohort-side register/renew handler — the body of the FRET activity callback. */
+export interface CohortMemberEngine {
+    /** Classify and admit (or decline) an inbound `RegisterV1`, returning the reply to serialize. */
+    handleRegister(reg: RegisterV1, ctx: RegisterContext, now: number): Promise<RegisterReplyV1>;
+    /** Handle an inbound `RenewV1` (ping / re-attach), delegating to the renewal cohort side. */
+    handleRenew(msg: RenewV1, now: number): RenewReplyV1;
+    /** Evict stale records and gossip each eviction; returns the evicted set. */
+    sweepStale(now: number): readonly RegistrationRecord[];
+}
+/** Build a {@link CohortMemberEngine} over the injected cohort-side collaborators. */
+export declare function createCohortMemberEngine(deps: CohortMemberEngineDeps): CohortMemberEngine;
+/** True iff `a` and `b` name the same peer (re-exported convenience for host equality checks). */
+export declare function samePeer(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=member-engine.d.ts.map

package/dist/src/cohort-topic/member-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-engine.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/member-engine.ts"],"names":[],"mappings":"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"}

package/dist/src/cohort-topic/member-engine.js

@@ -0,0 +1,264 @@
+/**
+ * Cohort-topic substrate — cohort-side member engine.
+ *
+ * This is the logic a cohort member runs when FRET's `RouteAndMaybeAct` lands a `RegisterV1`/`RenewV1`
+ * on it (the activity callback in `docs/cohort-topic.md` §FRET integration). It is the cohort-facing
+ * half of the substrate, composed from the prereq tickets' pure modules — the participant-facing half
+ * lives in {@link import("./service.js").CohortTopicService}. db-p2p's FRET host decodes an inbound
+ * frame, supplies the routing context this module can't see (`followOn`, the quorum-willing tally),
+ * and serializes whatever reply this returns back over the wire. db-core never imports FRET here.
+ *
+ * Inbound `RegisterV1` decision pipeline (§Registration mechanics, §Willingness, §Cold-start):
+ *
+ * 1. **Anti-DoS** — freshness/replay guard, per-(peer,topic) rate limit, and cold-root bootstrap
+ *    evidence. A failure short-circuits to `unwilling_cohort` (temporal back-off) or, for a replay,
+ *    a silent `no_state` (no state is served and nothing is recorded).
+ * 2. **Hot vs cold** — if this cohort already serves the topic (forwarder state resident), run the
+ *    willingness check; a promoted topic answers `Promoted(d+1)`. If cold, the topic-budget +
+ *    cold-start gate decides whether to instantiate, else `no_state` (walk steps toward the root).
+ * 3. **Admission** — on `accepted`, assign the deterministic primary/backup slots, persist the
+ *    soft-state record, count the arrival, run the promotion trigger, and attach the topic-traffic
+ *    signal to the reply.
+ *
+ * Every collaborator is injected, so the engine unit-tests without FRET or libp2p.
+ */
+import { bytesEqual, bytesKey } from "./registration/bytes.js";
+import { DEFAULT_TTL_MS } from "./registration/types.js";
+import { backoffRetryMs } from "./willingness.js";
+import { promotedRedirectReply } from "./coldstart.js";
+import { shouldInstantiate } from "./coldstart.js";
+import { attachTopicTraffic } from "./traffic.js";
+import { b64urlToBytes } from "./wire/codec.js";
+class StoreCohortMemberEngine {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async handleRegister(reg, ctx, now) {
+        const topicId = b64urlToBytes(reg.topicId);
+        const participantId = b64urlToBytes(reg.participantCoord);
+        const tier = reg.tier;
+        // 0. Read-only lookup probe: classify + return the cohort snapshot without admitting anything.
+        //    Branches before the admission pipeline (and the durable-state anti-DoS guards), so even a
+        //    hand-crafted `probe: true, bootstrap: true` frame can never instantiate — defense in depth.
+        if (reg.probe === true) {
+            return this.handleProbe(reg, topicId, participantId, ctx, now);
+        }
+        // 1. Anti-DoS gates. A replay/stale frame is answered with NoState (serve nothing, record
+        //    nothing); an over-rate source or missing bootstrap evidence backs off in time.
+        const guard = this.runGuards(reg, topicId, participantId, tier, now);
+        if (guard !== undefined) {
+            return guard;
+        }
+        // 2. Hot path: this cohort already serves the topic.
+        if (this.serves(topicId)) {
+            if (this.deps.promotion.isPromoted(topicId)) {
+                // Promoted: bounce same-tier registrations onward (the cheap single-RPC redirect).
+                return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
+            }
+            return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
+        }
+        // 3. Cold path: instantiate only at a legitimate growth point with a willing quorum.
+        const quorumWilling = this.deps.quorumWilling(tier);
+        if (!shouldInstantiate({ bootstrap: reg.bootstrap === true, followOn: ctx.followOn, quorumWilling })) {
+            return { v: 1, result: "no_state" };
+        }
+        if (this.deps.topicBudget?.admit(topicId) === false) {
+            // Forwarder-state budget is full of populated topics — decline in time.
+            return this.unwillingCohort(reg, now);
+        }
+        this.deps.coldStart.instantiate(topicId, ctx.treeTier, ctx.parentCoord, tier);
+        return this.admitOrDecline(reg, topicId, participantId, tier, ctx, now);
+    }
+    /**
+     * Read-only resolution of the cohort for a topic (the `lookup` probe). It walks the same path a
+     * register does (the walk loop is byte-for-byte identical) but the **terminal** member action is a
+     * classify, never an admission: it persists **no** record, counts **no** arrival, fires **no**
+     * promotion trigger, touches **no** topic budget, and **never** instantiates a cold-start forwarder.
+     *
+     * DoS posture (`docs/cohort-topic.md` §Anti-DoS): a probe still runs the stateless participant-sig gate
+     * (forged → `no_state`) and a dedicated probe rate limiter (over-rate → `unwilling_cohort`), but skips
+     * the replay guard, the bootstrap-evidence gate, and the topic budget — an idempotent read records
+     * nothing, so it is strictly cheaper than the register it replaces.
+     *
+     * Classification mirrors a register's terminal cases so the walk's existing branches drive a probe
+     * unchanged: a served-and-promoted topic answers `promoted(treeTier + 1)` (the walk follows it), a
+     * served topic answers `accepted` with the participant-specific slot assignment + read-only traffic
+     * snapshot, and a topic this cohort does not serve answers `no_state` (the walk steps inward).
+     */
+    handleProbe(reg, topicId, participantId, ctx, now) {
+        if (this.deps.verifyRegisterSig?.(reg) === false) {
+            // Unsigned / forged participant signature: serve nothing, exactly like the register path — a
+            // cohort member never resolves a cohort snapshot for an untrusted `participantCoord`.
+            return { v: 1, result: "no_state" };
+        }
+        const rate = this.deps.probeRateLimiter?.check(participantId, topicId, now);
+        if (rate !== undefined && rate.ok === false) {
+            return { v: 1, result: "unwilling_cohort", retryAfterMs: rate.retryAfterMs };
+        }
+        if (this.serves(topicId)) {
+            if (this.deps.promotion.isPromoted(topicId)) {
+                return promotedRedirectReply(ctx.treeTier + 1, this.deps.traffic.snapshot(topicId));
+            }
+            const { members, cohortEpoch } = this.deps.cohort();
+            const { primary, backups } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+            const reply = {
+                v: 1,
+                result: "accepted",
+                primary: bytesKey(primary),
+                backups: backups.map(bytesKey),
+                cohortEpoch: bytesKey(cohortEpoch),
+                cohortMembers: members.map(bytesKey),
+            };
+            return attachTopicTraffic(reply, this.deps.traffic.snapshot(topicId));
+        }
+        return { v: 1, result: "no_state" };
+    }
+    handleRenew(msg, now) {
+        const reply = this.deps.renewal.onRenew(msg, now);
+        if (reply.result === "ok") {
+            // A renewal is an arrival proxy for the traffic barometer (§Topic traffic signal).
+            this.deps.traffic.recordArrival(b64urlToBytes(msg.topicId), now);
+        }
+        else if (reply.result === "withdrawn") {
+            // A withdraw evicted a direct participant: re-touch the topic budget DOWN (mirrors the
+            // sweepStale drain release below) so the freed slot does not leak. Never an arrival — it is a
+            // departure, so the traffic barometer is deliberately not touched.
+            const topicId = b64urlToBytes(msg.topicId);
+            this.deps.topicBudget?.touch(topicId, this.deps.store.directParticipants(topicId));
+        }
+        return reply;
+    }
+    sweepStale(now) {
+        // Reclaim idle (peer, topic) rate-limiter keys on the existing gossip cadence. The limiters' own
+        // hard LRU cap already bounds worst-case footprint; this sweep adds proactive steady-state reclaim
+        // of long-quiet keys so a long-running coord does not hold register/probe state for departed peers.
+        this.deps.rateLimiter?.sweep(now);
+        this.deps.probeRateLimiter?.sweep(now);
+        const evicted = this.deps.renewal.sweepStale(now);
+        const budget = this.deps.topicBudget;
+        if (budget !== undefined && evicted.length > 0) {
+            // Mirror the `accept()` up-touch on the drain side: a TTL sweep that removes a topic's last
+            // direct participant must re-`touch` the budget down so the topic falls to participantCount 0
+            // and becomes the coldest-evictable resident again. Without this the budget slot leaks — a
+            // drained topic keeps its stale positive count forever and `coldestEvictable()` never picks it,
+            // so the cohort eventually refuses every new topic while serving nothing. Re-touch once per
+            // distinct affected topic from `store.directParticipants` (the source of truth, post-eviction).
+            const seen = new Set();
+            for (const rec of evicted) {
+                const key = bytesKey(rec.topicId);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                budget.touch(rec.topicId, this.deps.store.directParticipants(rec.topicId));
+            }
+        }
+        return evicted;
+    }
+    // --- admission ---
+    /** Run the willingness check; on `accepted` persist the record and attach the traffic signal. */
+    async admitOrDecline(reg, topicId, participantId, tier, ctx, now) {
+        const outcome = this.deps.willingness.evaluate(reg, this.deps.profile, now);
+        switch (outcome.kind) {
+            case "unwilling_member": {
+                return { v: 1, result: "unwilling_member", candidateMembers: outcome.candidateMembers.map(bytesKey) };
+            }
+            case "unwilling_cohort": {
+                return { v: 1, result: "unwilling_cohort", retryAfterMs: outcome.retryAfterMs };
+            }
+            case "accepted": {
+                return this.accept(reg, topicId, participantId, tier, ctx, now);
+            }
+            default: {
+                return this.unwillingCohort(reg, now);
+            }
+        }
+    }
+    async accept(reg, topicId, participantId, tier, ctx, now) {
+        const { members, cohortEpoch } = this.deps.cohort();
+        const { primary, backups } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+        const ttl = reg.ttl > 0 ? reg.ttl : DEFAULT_TTL_MS;
+        const record = {
+            topicId,
+            participantId,
+            tier,
+            primary,
+            backups,
+            attachedAt: now,
+            lastPing: now,
+            ttl,
+            appState: reg.appPayload === undefined ? undefined : b64urlToBytes(reg.appPayload),
+        };
+        this.deps.store.put(record);
+        this.deps.onAdmit?.(record);
+        this.deps.traffic.recordArrival(topicId, now);
+        this.deps.topicBudget?.touch(topicId, this.deps.store.directParticipants(topicId));
+        // Promotion may fire on this arrival; broadcast whatever notice comes back. Fire-and-forget so the
+        // register reply is not delayed by the threshold-sign collection round.
+        void this.firePromotion(topicId, now);
+        const reply = {
+            v: 1,
+            result: "accepted",
+            primary: bytesKey(primary),
+            backups: backups.map(bytesKey),
+            cohortEpoch: bytesKey(cohortEpoch),
+            cohortMembers: members.map(bytesKey),
+        };
+        return attachTopicTraffic(reply, this.deps.traffic.snapshot(topicId));
+    }
+    /** Run the promotion trigger for an arrival and hand any signed notice to {@link CohortMemberEngineDeps.onNotice}. */
+    async firePromotion(topicId, now) {
+        try {
+            const notice = await this.deps.promotion.onParticipantCountChange(topicId, now);
+            if (notice !== undefined) {
+                this.deps.onNotice?.(notice);
+            }
+        }
+        catch (err) {
+            // Threshold signing rejects when the cohort quorum is unreachable this round; the next arrival
+            // re-fires, so this is transient. Log rather than crash the register path — or leak the
+            // unhandled rejection the bare `void promotion...` did once signing became real (db-p2p ticket 1).
+            this.deps.log?.("cohort-topic: promotion sign/broadcast failed for an arrival: %o", err);
+        }
+    }
+    // --- guards ---
+    /** Returns a short-circuit reply if any anti-DoS gate rejects `reg`, else `undefined`. */
+    runGuards(reg, topicId, participantId, tier, now) {
+        if (this.deps.verifyRegisterSig?.(reg) === false) {
+            // Unsigned / forged participant signature: serve nothing and record nothing (the cohort
+            // cannot trust this participantCoord). Checked before the replay/rate guards so a forged
+            // frame cannot consume their state.
+            return { v: 1, result: "no_state" };
+        }
+        const correlationId = b64urlToBytes(reg.correlationId);
+        if (this.deps.replayGuard?.accept(correlationId, participantId, reg.timestamp, now) === false) {
+            // Stale / future-skewed / replayed: serve nothing and record nothing.
+            return { v: 1, result: "no_state" };
+        }
+        if (this.deps.bootstrapEvidence?.verify(reg, tier) === false) {
+            return this.unwillingCohort(reg, now);
+        }
+        const rate = this.deps.rateLimiter?.check(participantId, topicId, now);
+        if (rate !== undefined && rate.ok === false) {
+            return { v: 1, result: "unwilling_cohort", retryAfterMs: rate.retryAfterMs };
+        }
+        return undefined;
+    }
+    serves(topicId) {
+        return this.deps.coldStart.get(topicId) !== undefined || this.deps.store.directParticipants(topicId) > 0;
+    }
+    unwillingCohort(reg, now) {
+        void reg;
+        void now;
+        return { v: 1, result: "unwilling_cohort", retryAfterMs: backoffRetryMs(0) };
+    }
+}
+/** Build a {@link CohortMemberEngine} over the injected cohort-side collaborators. */
+export function createCohortMemberEngine(deps) {
+    return new StoreCohortMemberEngine(deps);
+}
+/** True iff `a` and `b` name the same peer (re-exported convenience for host equality checks). */
+export function samePeer(a, b) {
+    return bytesEqual(a, b);
+}
+//# sourceMappingURL=member-engine.js.map

package/dist/src/cohort-topic/member-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"member-engine.js","sourceRoot":"","sources":["../../../src/cohort-topic/member-engine.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+export * from "./source.js";
+export * from "./verifier.js";
+export * from "./publisher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cohort-topic/membership/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/membership/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/dist/src/cohort-topic/membership/index.js

@@ -0,0 +1,4 @@
+export * from "./source.js";
+export * from "./verifier.js";
+export * from "./publisher.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cohort-topic/membership/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/membership/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

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

@@ -0,0 +1,82 @@
+/**
+ * Cohort-topic substrate — cohort-side `MembershipCertV1` publication.
+ *
+ * Per `docs/cohort-topic.md` §Membership snapshots: the cohort publishes a threshold-signed
+ * `MembershipCertV1`
+ *
+ * - at stabilization, and on any change to the first `k − x` members ({@link MembershipCertPublisher.onStabilized});
+ * - refreshed every `T_membership_refresh` (default 5 min) ({@link MembershipCertPublisher.tick}).
+ *
+ * The publisher is db-core logic over the {@link CohortSigner} (threshold sign) and the
+ * {@link IMembershipPublishSink} (serve/advertise). It never imports FRET. Members are sorted
+ * ascending for the cert (matching the sharding order) and the first `minSigs` (= `k − x`) of that
+ * order are the "first `k − x`" whose change forces a fresh publish.
+ */
+import type { IMembershipPublishSink } from "../ports.js";
+import type { MembershipCertV1 } from "../wire/types.js";
+import { type CohortSigner } from "../sig/threshold.js";
+import { type MembershipCertSignable } from "../sig/payloads.js";
+/** Default membership-cert refresh interval (`T_membership_refresh`). */
+export declare const DEFAULT_T_MEMBERSHIP_REFRESH_MS: number;
+/**
+ * The canonical {@link MembershipCertSignable} for a stabilized snapshot: members sorted ascending (the
+ * cert / sharding order), byte fields base64url-encoded, over exactly the threshold-signed fields. The
+ * publisher signs `membershipCertSigningPayload` of this; a rotation-attestation **producer** (db-p2p,
+ * `cohort-topic-trust-anchor-rotation-production`) signs the *successor* cert's image through the SAME
+ * helper, so signer and verifier never canonicalize the cert independently (signature-image agreement —
+ * a mismatch makes the db-core chain check fail).
+ */
+export declare function membershipCertSignable(snapshot: CohortSnapshot): MembershipCertSignable;
+/** A stabilized cohort snapshot the publisher attests. */
+export interface CohortSnapshot {
+    /** Cohort coord (32 bytes). */
+    coord: Uint8Array;
+    /** Cohort epoch for this snapshot. */
+    cohortEpoch: Uint8Array;
+    /** Cohort members (any order; the cert sorts them ascending). */
+    members: readonly Uint8Array[];
+    /** Unix ms this membership stabilized. */
+    stabilizedAt: number;
+    /** Optional FRET stabilization proof. */
+    fretAttestation?: Uint8Array;
+}
+/**
+ * A predecessor-cohort rotation attestation to attach to a fresh cert (an epoch rotation). The
+ * predecessor cohort threshold-signs the **successor** cert's `membershipCertSigningPayload`; that
+ * `(prevEpoch, rotationSig, rotationSigners)` triple lets a participant holding a trusted predecessor
+ * verify the rotation is legitimate. Producing this triple is the db-p2p ticket
+ * `cohort-topic-trust-anchor-rotation-production`; the publisher only attaches a provided one.
+ */
+export interface RotationAttestation {
+    /** Predecessor cohort epoch this cert rotates from (32 bytes). */
+    prevEpoch: Uint8Array;
+    /** Predecessor cohort's threshold signature over the successor cert's signing payload. */
+    rotationSig: Uint8Array;
+    /** Predecessor cohort signers that produced {@link rotationSig}; `>= minSigs`. */
+    rotationSigners: readonly Uint8Array[];
+}
+/** Cohort-side membership-cert publisher. */
+export interface MembershipCertPublisher {
+    /**
+     * Drive publication on a stabilization event. Publishes (and returns the cert) when the first
+     * `k − x` members changed since the last publish, or on the first call; otherwise returns `undefined`.
+     * Pass `rotation` to attach a predecessor-cohort rotation attestation (an epoch rotation); omit it for
+     * the default non-rotation publish (no rotation fields are emitted).
+     */
+    onStabilized(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+    /**
+     * Periodic tick. Re-publishes (and returns the cert) when `T_membership_refresh` has elapsed since
+     * the last publish; otherwise returns `undefined`. Pass `rotation` to attach a rotation attestation.
+     */
+    tick(snapshot: CohortSnapshot, now: number, rotation?: RotationAttestation): Promise<MembershipCertV1 | undefined>;
+}
+export interface MembershipCertPublisherDeps {
+    signer: CohortSigner;
+    sink: IMembershipPublishSink;
+    refreshMs?: number;
+    minSigs?: number;
+    maxMessageBytes?: number;
+}
+/** Build a cohort-side {@link MembershipCertPublisher}. */
+export declare function createMembershipCertPublisher(deps: MembershipCertPublisherDeps): MembershipCertPublisher;
+//# sourceMappingURL=publisher.d.ts.map