@optimystic/db-core 0.13.5 → 0.14.0

package/dist/src/cohort-topic/sig/threshold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.js","sourceRoot":"","sources":["../../../../src/cohort-topic/sig/threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAanC,MAAM,kBAAkB;IACM;IAAiD;IAA9E,YAA6B,MAA8B,EAAmB,OAAe;QAAhE,WAAM,GAAN,MAAM,CAAwB;QAAmB,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEjG,aAAa,CAAC,OAAmB;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,eAAe,CAAC,OAAmB,EAAE,GAAe,EAAE,OAA8B,EAAE,IAAsB,EAAE,OAAe;QAC5H,IAAI,OAAO,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACd,CAAC;QACD,kFAAkF;QAClF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;YAClC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,OAAO,KAAK,CAAC,CAAC,0DAA0D;YACzE,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,KAAK,CAAC,CAAC,gDAAgD;YAC/D,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;CACD;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAAC,MAA8B,EAAE,UAAkB,gBAAgB;IACpG,OAAO,IAAI,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/dist/src/cohort-topic/tiers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cohort-topic substrate — tier ladder (T0–T3) and node profiles (Edge / Core).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tier ladder. This module encodes only the **static**
+ * tier classes, the Edge/Core profiles, and the per-node override surface. The decline-policy
+ * *behavior* (T0 never declined while serving, T3 declined freely) and the Edge runtime overrides
+ * (`ttl = 60s`, `ping_interval = 20s`, sticky-cached backups) are willingness/TTL concerns owned by
+ * later tickets — only the profile *flags* (which tiers a node is willing to forward) live here.
+ */
+/**
+ * System-wide capacity tier, in priority order (T0 essential … T3 luxury).
+ *
+ * Modeled as a frozen const-object + value-union type rather than a TS `enum`: db-core's test
+ * runner uses Node's native type-stripping, which rejects `enum` (non-erasable syntax). The object
+ * carries the named members (`Tier.T0`), the type alias carries the value union (`0 | 1 | 2 | 3`).
+ *
+ * - **T0 — essential**: transaction commit, block production, threshold-sig contribution.
+ * - **T1 — correctness-supporting**: chain serving, replay-window storage, partition heal.
+ * - **T2 — functional**: matchmaking/voting directories, capability discovery, capacity gossip.
+ * - **T3 — luxury**: reactivity push forwarding, anticipatory warm-up, optional delta payloads.
+ */
+export declare const Tier: {
+    readonly T0: 0;
+    readonly T1: 1;
+    readonly T2: 2;
+    readonly T3: 3;
+};
+export type Tier = (typeof Tier)[keyof typeof Tier];
+/** All four tiers, ascending — useful for iteration and override validation. */
+export declare const ALL_TIERS: readonly Tier[];
+/**
+ * A node's static tier classification. `willingTiers` is the set of tiers this node will take on
+ * *forwarder* roles for; cohort assembly under FRET is tier-blind, so this is the per-node gate the
+ * willingness check consults. Edge: `{T0, T1}`; Core: `{T0, T1, T2, T3}` (operator-narrowable).
+ */
+export interface NodeProfile {
+    readonly kind: "edge" | "core";
+    readonly willingTiers: ReadonlySet<Tier>;
+}
+/** Per-node operator override surface. Currently the willing-tier set; widened by later tickets. */
+export interface NodeProfileOverrides {
+    /**
+     * Restrict the willing-tier set. Tiers outside the profile's base set are ignored (Edge can never
+     * be widened to T2/T3 via override — that is a hardware/policy class, not a knob).
+     */
+    willingTiers?: Iterable<Tier>;
+}
+/**
+ * Edge profile (mobile / browser / IoT): forwards T0 + T1 only. T2/T3 willingness is permanently
+ * off and an operator override cannot turn it on. An override may further narrow (e.g. to `{T0}`).
+ */
+export declare function edgeProfile(overrides?: NodeProfileOverrides): NodeProfile;
+/**
+ * Core profile (servers / fixed infrastructure): forwards T0–T3 by default. An operator override may
+ * restrict it to a subset (e.g. `{T0, T1, T2}` to shed reactivity-push duty).
+ */
+export declare function coreProfile(overrides?: NodeProfileOverrides): NodeProfile;
+//# sourceMappingURL=tiers.d.ts.map

package/dist/src/cohort-topic/tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/tiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI;;;;;CAA0C,CAAC;AAC5D,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;AAEpD,gFAAgF;AAChF,eAAO,MAAM,SAAS,EAAE,SAAS,IAAI,EAAyC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,oGAAoG;AACpG,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;CAC9B;AAcD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,WAAW,CAEzE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,WAAW,CAEzE"}

package/dist/src/cohort-topic/tiers.js

@@ -0,0 +1,49 @@
+/**
+ * Cohort-topic substrate — tier ladder (T0–T3) and node profiles (Edge / Core).
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tier ladder. This module encodes only the **static**
+ * tier classes, the Edge/Core profiles, and the per-node override surface. The decline-policy
+ * *behavior* (T0 never declined while serving, T3 declined freely) and the Edge runtime overrides
+ * (`ttl = 60s`, `ping_interval = 20s`, sticky-cached backups) are willingness/TTL concerns owned by
+ * later tickets — only the profile *flags* (which tiers a node is willing to forward) live here.
+ */
+/**
+ * System-wide capacity tier, in priority order (T0 essential … T3 luxury).
+ *
+ * Modeled as a frozen const-object + value-union type rather than a TS `enum`: db-core's test
+ * runner uses Node's native type-stripping, which rejects `enum` (non-erasable syntax). The object
+ * carries the named members (`Tier.T0`), the type alias carries the value union (`0 | 1 | 2 | 3`).
+ *
+ * - **T0 — essential**: transaction commit, block production, threshold-sig contribution.
+ * - **T1 — correctness-supporting**: chain serving, replay-window storage, partition heal.
+ * - **T2 — functional**: matchmaking/voting directories, capability discovery, capacity gossip.
+ * - **T3 — luxury**: reactivity push forwarding, anticipatory warm-up, optional delta payloads.
+ */
+export const Tier = { T0: 0, T1: 1, T2: 2, T3: 3 };
+/** All four tiers, ascending — useful for iteration and override validation. */
+export const ALL_TIERS = [Tier.T0, Tier.T1, Tier.T2, Tier.T3];
+const EDGE_BASE_TIERS = [Tier.T0, Tier.T1];
+const CORE_BASE_TIERS = ALL_TIERS;
+/** Intersect a requested override set with the profile's base tiers (override can only narrow). */
+function resolveWillingTiers(base, overrides) {
+    if (!overrides?.willingTiers) {
+        return new Set(base);
+    }
+    const requested = new Set(overrides.willingTiers);
+    return new Set(base.filter((t) => requested.has(t)));
+}
+/**
+ * Edge profile (mobile / browser / IoT): forwards T0 + T1 only. T2/T3 willingness is permanently
+ * off and an operator override cannot turn it on. An override may further narrow (e.g. to `{T0}`).
+ */
+export function edgeProfile(overrides) {
+    return { kind: "edge", willingTiers: resolveWillingTiers(EDGE_BASE_TIERS, overrides) };
+}
+/**
+ * Core profile (servers / fixed infrastructure): forwards T0–T3 by default. An operator override may
+ * restrict it to a subset (e.g. `{T0, T1, T2}` to shed reactivity-push duty).
+ */
+export function coreProfile(overrides) {
+    return { kind: "core", willingTiers: resolveWillingTiers(CORE_BASE_TIERS, overrides) };
+}
+//# sourceMappingURL=tiers.js.map

package/dist/src/cohort-topic/tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../../src/cohort-topic/tiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAW,CAAC;AAG5D,gFAAgF;AAChF,MAAM,CAAC,MAAM,SAAS,GAAoB,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AAqB/E,MAAM,eAAe,GAAoB,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5D,MAAM,eAAe,GAAoB,SAAS,CAAC;AAEnD,mGAAmG;AACnG,SAAS,mBAAmB,CAAC,IAAqB,EAAE,SAAgC;IACnF,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,CAAC;QAC9B,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAgC;IAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,mBAAmB,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,CAAC;AACxF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,SAAgC;IAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,mBAAmB,CAAC,eAAe,EAAE,SAAS,CAAC,EAAE,CAAC;AACxF,CAAC"}

package/dist/src/cohort-topic/traffic.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Cohort-topic substrate — topic-traffic signal.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Topic traffic signal. A cohort tracks per-topic flow
+ * rates alongside the stock `directParticipants` count and returns them on registration replies so
+ * applications can decide whether the current tier is dense enough to settle on.
+ *
+ * Shape (`TopicTrafficV1` from the wire ticket):
+ * - `arrivalsPerMin` — **combines** fresh registrations and renewals into one scalar (the seeker
+ *   uses renewals as a proxy for active matchable supply); the caller invokes {@link recordArrival}
+ *   for both.
+ * - `queriesPerMin` — application-level query rate.
+ * - counts are **exact integers** over `windowSeconds` (default 60), *not* log-bucketed like the
+ *   load barometer — the consumer-side matchmaking formulas are numeric.
+ *
+ * Pipeline: each member counts arrivals/queries locally ({@link recordArrival} / {@link recordQuery})
+ * over a sliding window; {@link TrafficCounters.publish} freezes the windowed counts into the
+ * member's gossiped per-topic summary each gossip round; {@link TrafficCounters.snapshot} returns the
+ * **gossip-derived** view (own last-published summary + siblings' last-gossiped summaries from the
+ * {@link CohortView}), so the reply lags by at most one round and never recomputes from raw counters
+ * at reply time.
+ *
+ * Resolved open question (GROUNDING): the signal is returned **only** on `accepted` and `promoted`
+ * replies (see {@link attachTopicTraffic}); a participant getting `Promoted(d+1)` still receives the
+ * outgoing cohort's traffic so it can estimate whether the redirect target is hot.
+ *
+ * Counters reset to zero on `cohortEpoch` change ({@link TrafficCounters.reset}); the first round
+ * after a rotation may under-report, and consumers tolerate a single zero reading.
+ */
+import type { CohortView } from "./gossip/view.js";
+import type { RegistrationStore } from "./registration/types.js";
+import type { CohortTopicSummary, RegisterReplyV1, TopicTrafficV1 } from "./wire/types.js";
+/** Default observation window for the rate fields (seconds). */
+export declare const DEFAULT_TRAFFIC_WINDOW_SECONDS = 60;
+/** Frozen per-topic counts the member last published to gossip. */
+interface PublishedTopic {
+    readonly arrivals: number;
+    readonly queries: number;
+}
+/** Per-topic traffic counters with a gossip-derived snapshot. */
+export interface TrafficCounters {
+    /** Record a fresh registration **or** a renewal for `topicId` at `now` (combined arrivals). */
+    recordArrival(topicId: Uint8Array, now: number): void;
+    /** Record an application-level query against `topicId` at `now`. */
+    recordQuery(topicId: Uint8Array, now: number): void;
+    /**
+     * Freeze the current windowed counts into the member's gossiped summary (call once per gossip
+     * round, at `now`). The frozen values are what {@link snapshot} and the gossip frame read.
+     */
+    publish(topicId: Uint8Array, now: number): PublishedTopic;
+    /** Own most-recent published `(arrivals, queries)` for `topicId`, or zeros if never published. */
+    published(topicId: Uint8Array): PublishedTopic;
+    /**
+     * Gossip-derived traffic for `topicId`: own last-published counts plus siblings' last-gossiped
+     * summaries (exact-integer sums), with `directParticipants` from the replicated store. Lags ≤ one
+     * round; never recomputes from raw counters.
+     */
+    snapshot(topicId: Uint8Array): TopicTrafficV1;
+    /** Reset all counters to zero (call on `cohortEpoch` change). */
+    reset(): void;
+}
+export interface TrafficCountersDeps {
+    /** Merged per-member gossip view — siblings' last-gossiped per-topic summaries. */
+    view: CohortView;
+    /** Replicated registration store — supplies the cohort-wide `directParticipants` stock count. */
+    store: Pick<RegistrationStore, "directParticipants">;
+    /** This member's own id, base64url — excluded from the sibling summary scan (counted via own published). */
+    selfMember: string;
+    /** Observation window (seconds). Default {@link DEFAULT_TRAFFIC_WINDOW_SECONDS}. */
+    windowSeconds?: number;
+    /** Tier-(d+1) cohort count for a topic (0 if not promoted); the promotion ticket owns this. */
+    childCohortCount?: (topicId: Uint8Array) => number;
+}
+/** Construct empty {@link TrafficCounters}. */
+export declare function createTrafficCounters(deps: TrafficCountersDeps): TrafficCounters;
+/**
+ * Attach the topic-traffic signal to a reply **only** when the result is `accepted` or `promoted`
+ * (GROUNDING-resolved: absent on `no_state`, `unwilling_member`, `unwilling_cohort`). Mutates and
+ * returns `reply`. A no-op for non-traffic-bearing results, so callers can pipe every reply through.
+ */
+export declare function attachTopicTraffic(reply: RegisterReplyV1, traffic: TopicTrafficV1): RegisterReplyV1;
+/** The own published counts as a `CohortTopicSummary` for the gossip frame. Callers supply tier/promotion fields. */
+export declare function toCohortTopicSummary(topicId: Uint8Array, published: PublishedTopic, fields: {
+    tier: number;
+    directParticipants: number;
+    promoted: boolean;
+    childCohortCount: number;
+}): CohortTopicSummary;
+export {};
+//# sourceMappingURL=traffic.d.ts.map

package/dist/src/cohort-topic/traffic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traffic.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/traffic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3F,gEAAgE;AAChE,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,mEAAmE;AACnE,UAAU,cAAc;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAQD,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC/B,+FAA+F;IAC/F,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,oEAAoE;IACpE,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;IAC1D,kGAAkG;IAClG,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,cAAc,CAAC;IAC9C,iEAAiE;IACjE,KAAK,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IACnC,mFAAmF;IACnF,IAAI,EAAE,UAAU,CAAC;IACjB,iGAAiG;IACjG,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IACrD,4GAA4G;IAC5G,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+FAA+F;IAC/F,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,CAAC;CACnD;AA6FD,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAKnG;AAED,qHAAqH;AACrH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC/F,kBAAkB,CAUpB"}

package/dist/src/cohort-topic/traffic.js

@@ -0,0 +1,146 @@
+/**
+ * Cohort-topic substrate — topic-traffic signal.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Topic traffic signal. A cohort tracks per-topic flow
+ * rates alongside the stock `directParticipants` count and returns them on registration replies so
+ * applications can decide whether the current tier is dense enough to settle on.
+ *
+ * Shape (`TopicTrafficV1` from the wire ticket):
+ * - `arrivalsPerMin` — **combines** fresh registrations and renewals into one scalar (the seeker
+ *   uses renewals as a proxy for active matchable supply); the caller invokes {@link recordArrival}
+ *   for both.
+ * - `queriesPerMin` — application-level query rate.
+ * - counts are **exact integers** over `windowSeconds` (default 60), *not* log-bucketed like the
+ *   load barometer — the consumer-side matchmaking formulas are numeric.
+ *
+ * Pipeline: each member counts arrivals/queries locally ({@link recordArrival} / {@link recordQuery})
+ * over a sliding window; {@link TrafficCounters.publish} freezes the windowed counts into the
+ * member's gossiped per-topic summary each gossip round; {@link TrafficCounters.snapshot} returns the
+ * **gossip-derived** view (own last-published summary + siblings' last-gossiped summaries from the
+ * {@link CohortView}), so the reply lags by at most one round and never recomputes from raw counters
+ * at reply time.
+ *
+ * Resolved open question (GROUNDING): the signal is returned **only** on `accepted` and `promoted`
+ * replies (see {@link attachTopicTraffic}); a participant getting `Promoted(d+1)` still receives the
+ * outgoing cohort's traffic so it can estimate whether the redirect target is hot.
+ *
+ * Counters reset to zero on `cohortEpoch` change ({@link TrafficCounters.reset}); the first round
+ * after a rotation may under-report, and consumers tolerate a single zero reading.
+ */
+import { bytesKey } from "./registration/bytes.js";
+import { bytesToB64url } from "./wire/codec.js";
+/** Default observation window for the rate fields (seconds). */
+export const DEFAULT_TRAFFIC_WINDOW_SECONDS = 60;
+class WindowedTrafficCounters {
+    deps;
+    windows = new Map();
+    lastPublished = new Map();
+    windowMs;
+    constructor(deps) {
+        this.deps = deps;
+        const ws = deps.windowSeconds ?? DEFAULT_TRAFFIC_WINDOW_SECONDS;
+        if (!(ws > 0)) {
+            throw new RangeError(`windowSeconds must be > 0, got ${ws}`);
+        }
+        this.windowMs = ws * 1000;
+    }
+    recordArrival(topicId, now) {
+        this.windowFor(topicId).arrivals.push(now);
+    }
+    recordQuery(topicId, now) {
+        this.windowFor(topicId).queries.push(now);
+    }
+    publish(topicId, now) {
+        const w = this.windows.get(bytesKey(topicId));
+        const frozen = {
+            arrivals: w === undefined ? 0 : countWithin(w.arrivals, now, this.windowMs),
+            queries: w === undefined ? 0 : countWithin(w.queries, now, this.windowMs),
+        };
+        this.lastPublished.set(bytesKey(topicId), frozen);
+        return frozen;
+    }
+    published(topicId) {
+        return this.lastPublished.get(bytesKey(topicId)) ?? { arrivals: 0, queries: 0 };
+    }
+    snapshot(topicId) {
+        const topicB64 = bytesToB64url(topicId);
+        const own = this.published(topicId);
+        let arrivals = own.arrivals;
+        let queries = own.queries;
+        let childCohortCount = 0;
+        for (const [member, contribution] of this.deps.view.all()) {
+            if (member === this.deps.selfMember)
+                continue; // own contribution comes from lastPublished
+            const summary = contribution.topicSummaries.find((s) => s.topicId === topicB64);
+            if (summary === undefined)
+                continue;
+            arrivals += summary.arrivalsPerMin;
+            queries += summary.queriesPerMin;
+            if (summary.childCohortCount > childCohortCount) {
+                childCohortCount = summary.childCohortCount;
+            }
+        }
+        const childOverride = this.deps.childCohortCount?.(topicId);
+        return {
+            windowSeconds: this.windowMs / 1000,
+            arrivalsPerMin: arrivals,
+            queriesPerMin: queries,
+            directParticipants: this.deps.store.directParticipants(topicId),
+            childCohortCount: childOverride ?? childCohortCount,
+        };
+    }
+    reset() {
+        this.windows.clear();
+        this.lastPublished.clear();
+    }
+    windowFor(topicId) {
+        const key = bytesKey(topicId);
+        let w = this.windows.get(key);
+        if (w === undefined) {
+            w = { arrivals: [], queries: [] };
+            this.windows.set(key, w);
+        }
+        return w;
+    }
+}
+/** Count timestamps within `[now - windowMs, now]`, pruning anything older from `events` in place. */
+function countWithin(events, now, windowMs) {
+    const cutoff = now - windowMs;
+    // Events accumulate in arrival order; drop the stale prefix so the array stays bounded.
+    let drop = 0;
+    while (drop < events.length && events[drop] < cutoff) {
+        drop++;
+    }
+    if (drop > 0) {
+        events.splice(0, drop);
+    }
+    return events.length;
+}
+/** Construct empty {@link TrafficCounters}. */
+export function createTrafficCounters(deps) {
+    return new WindowedTrafficCounters(deps);
+}
+/**
+ * Attach the topic-traffic signal to a reply **only** when the result is `accepted` or `promoted`
+ * (GROUNDING-resolved: absent on `no_state`, `unwilling_member`, `unwilling_cohort`). Mutates and
+ * returns `reply`. A no-op for non-traffic-bearing results, so callers can pipe every reply through.
+ */
+export function attachTopicTraffic(reply, traffic) {
+    if (reply.result === "accepted" || reply.result === "promoted") {
+        reply.topicTraffic = traffic;
+    }
+    return reply;
+}
+/** The own published counts as a `CohortTopicSummary` for the gossip frame. Callers supply tier/promotion fields. */
+export function toCohortTopicSummary(topicId, published, fields) {
+    return {
+        topicId: bytesToB64url(topicId),
+        tier: fields.tier,
+        directParticipants: fields.directParticipants,
+        arrivalsPerMin: published.arrivals,
+        queriesPerMin: published.queries,
+        promoted: fields.promoted,
+        childCohortCount: fields.childCohortCount,
+    };
+}
+//# sourceMappingURL=traffic.js.map

package/dist/src/cohort-topic/traffic.js.map

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

package/dist/src/cohort-topic/walk.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Cohort-topic substrate — walk-toward-root lookup / registration.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tree growth and lookup (§Lookup loop) and folded back
+ * from the simulator-validated `packages/substrate-simulator/src/walk.ts`. A participant resolves a
+ * topic by walking **toward the root** from `d_max`, probing one tier coordinate per RPC. The walk's
+ * single-direction discipline is the anti-flood backbone: it only ever moves inward (toward the root)
+ * on `NoState`, and the *only* outward move is following an explicit `Promoted` redirect.
+ *
+ * Reply handling (§Lookup):
+ * - **`accepted`** → done; return the reply (carries `primary`/`backups`/`cohortEpoch` to cache).
+ * - **`no_state`** at tier `d` → step one tier toward the root (`d − 1`); no traffic signal. At the
+ *   root (`d − 1 < 0`) re-issue once at tier 0 with `bootstrap: true` (cold-start request).
+ * - **`promoted(targetTier)`** → recompute `coord_targetTier(self, topicId)` and register there — the
+ *   one outward move, taken only on this explicit redirect.
+ * - **`unwilling_member(candidates)`** → retry the **same** coord at a named alternative member
+ *   (spatial move within the cohort), via a direct dial.
+ * - **`unwilling_cohort(retryAfter)`** → back off in **time**; the walk terminates with
+ *   {@link RetryLaterOutcome} and the caller restarts a fresh {@link WalkEngine.register} after
+ *   `afterMs` — which begins again at `d_max`, decorrelating retries across the ring (§Anti-flood
+ *   claim 4: never re-hit the declined coord immediately).
+ *
+ * This module is FRET-free: it drives the {@link ITopicRouter} port (db-p2p binds it to FRET's
+ * `RouteAndMaybeAct` / direct dial) and the {@link TierAddressing} math, and delegates building +
+ * signing the {@link RegisterV1} to the injected {@link RegisterMessageFactory} (participant identity
+ * and crypto live there, not here).
+ */
+import type { ITopicRouter } from "./ports.js";
+import type { TierAddressing } from "./addressing.js";
+import type { DMaxComputer } from "./dmax.js";
+import type { RegisterReplyV1, RegisterV1 } from "./wire/types.js";
+/** The walk landed: the cohort accepted the registration. `reply` carries the cohort cache fields. */
+export interface AcceptedWalkOutcome {
+    readonly kind: "accepted";
+    readonly reply: RegisterReplyV1;
+}
+/**
+ * The walk hit a `Promoted` redirect and the engine was configured **not** to follow it
+ * ({@link WalkConfig.followPromoted} `= false`): the caller recomputes `coord_targetTier` and
+ * registers there itself. With the default (`followPromoted = true`) the engine follows the redirect
+ * internally and this outcome never surfaces.
+ */
+export interface PromotedWalkOutcome {
+    readonly kind: "promoted";
+    readonly targetTier: number;
+}
+/**
+ * The walk backed off in time (`unwilling_cohort`, exhausted sibling retries, a failed cold-start, or
+ * the safety step cap). The caller waits `afterMs` then calls {@link WalkEngine.register} again, which
+ * restarts at `d_max`.
+ */
+export interface RetryLaterOutcome {
+    readonly kind: "retry_later";
+    readonly afterMs: number;
+}
+export type WalkOutcome = AcceptedWalkOutcome | PromotedWalkOutcome | RetryLaterOutcome;
+/** Builds (and signs) the {@link RegisterV1} for one probe; owns participant identity + crypto. */
+export interface RegisterMessageFactory {
+    /**
+     * Produce a signed `RegisterV1` for this participant at walk position `treeTier`. `bootstrap` is
+     * set only on the root cold-start re-issue. `appPayload` is the opaque application slot. On the
+     * bootstrap re-issue the factory may additionally mint and attach the signed `bootstrapEvidence`
+     * envelope (§Anti-DoS) via the injected builder seam before signing — keyed off `bootstrap`, so no
+     * extra build parameter is needed (the walk decides `bootstrap` internally, not the application).
+     */
+    build(params: {
+        topicId: Uint8Array;
+        tier: number;
+        treeTier: number;
+        bootstrap: boolean;
+        /** Read-only lookup probe: the factory stamps `RegisterV1.probe` and never mints bootstrap evidence. */
+        probe: boolean;
+        appPayload?: Uint8Array;
+    }): Promise<RegisterV1>;
+}
+export interface WalkConfig {
+    /** Cohort size requested from the router (`wantK`). Default 16. */
+    wantK?: number;
+    /** Threshold signers requested from the router (`minSigs = k − x`). Default 14. */
+    minSigs?: number;
+    /** Max `unwilling_member` sibling retries at one coord before treating it as a cohort decline. Default `wantK`. */
+    maxMemberRetries?: number;
+    /**
+     * Whether to follow a `Promoted` redirect internally (recompute coord + continue) or surface it as
+     * a {@link PromotedWalkOutcome} for the caller to drive. Default `true` (self-contained walk).
+     */
+    followPromoted?: boolean;
+    /**
+     * Hard cap on probe RPCs in one walk — a safety valve against pathological oscillation between an
+     * inward `NoState` step and an outward `Promoted` redirect in a malformed tree. Default scales with
+     * `d_max`. Exceeding it yields a {@link RetryLaterOutcome}.
+     */
+    maxSteps?: number;
+    /** `max_message_bytes` ceiling for the encoded register frame. Defaults to the codec default. */
+    maxMessageBytes?: number;
+}
+export interface WalkEngineDeps {
+    router: ITopicRouter;
+    addressing: TierAddressing;
+    /** Computes the walk start tier `d_max` from the current network-size estimate. */
+    dmax: DMaxComputer;
+    /** This participant's peer id — the `P` in `coord_d(P, topicId)`. */
+    self: Uint8Array;
+    /** Builds + signs the per-probe `RegisterV1`. */
+    factory: RegisterMessageFactory;
+    config?: WalkConfig;
+}
+/** Drives a participant's walk-toward-root registration over the injected router + addressing. */
+export interface WalkEngine {
+    /**
+     * Walk from `d_max` toward the root registering for `topicId` at op `tier`, following `Promoted`
+     * redirects outward. Resolves with the terminal {@link WalkOutcome}. With `opts.probe` the walk is a
+     * **read-only lookup**: identical routing discipline, but the terminal cohort classifies rather than
+     * admits and the root `no_state` branch backs off instead of issuing a `bootstrap: true` cold-start
+     * (a probe never instantiates a cold root).
+     */
+    register(topicId: Uint8Array, tier: number, appPayload?: Uint8Array, opts?: {
+        probe?: boolean;
+    }): Promise<WalkOutcome>;
+}
+/** Build a {@link WalkEngine} over the injected router, addressing, `d_max`, and message factory. */
+export declare function createWalkEngine(deps: WalkEngineDeps): WalkEngine;
+//# sourceMappingURL=walk.d.ts.map

package/dist/src/cohort-topic/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEnE,sGAAsG;AACtG,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAExF,mGAAmG;AACnG,MAAM,WAAW,sBAAsB;IACtC;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE;QACb,OAAO,EAAE,UAAU,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC;QACnB,wGAAwG;QACxG,KAAK,EAAE,OAAO,CAAC;QACf,UAAU,CAAC,EAAE,UAAU,CAAC;KACxB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IAC1B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mHAAmH;IACnH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,cAAc,CAAC;IAC3B,mFAAmF;IACnF,IAAI,EAAE,YAAY,CAAC;IACnB,qEAAqE;IACrE,IAAI,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,OAAO,EAAE,sBAAsB,CAAC;IAChC,MAAM,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,kGAAkG;AAClG,MAAM,WAAW,UAAU;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACvH;AA2HD,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAEjE"}

package/dist/src/cohort-topic/walk.js

@@ -0,0 +1,150 @@
+/**
+ * Cohort-topic substrate — walk-toward-root lookup / registration.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Tree growth and lookup (§Lookup loop) and folded back
+ * from the simulator-validated `packages/substrate-simulator/src/walk.ts`. A participant resolves a
+ * topic by walking **toward the root** from `d_max`, probing one tier coordinate per RPC. The walk's
+ * single-direction discipline is the anti-flood backbone: it only ever moves inward (toward the root)
+ * on `NoState`, and the *only* outward move is following an explicit `Promoted` redirect.
+ *
+ * Reply handling (§Lookup):
+ * - **`accepted`** → done; return the reply (carries `primary`/`backups`/`cohortEpoch` to cache).
+ * - **`no_state`** at tier `d` → step one tier toward the root (`d − 1`); no traffic signal. At the
+ *   root (`d − 1 < 0`) re-issue once at tier 0 with `bootstrap: true` (cold-start request).
+ * - **`promoted(targetTier)`** → recompute `coord_targetTier(self, topicId)` and register there — the
+ *   one outward move, taken only on this explicit redirect.
+ * - **`unwilling_member(candidates)`** → retry the **same** coord at a named alternative member
+ *   (spatial move within the cohort), via a direct dial.
+ * - **`unwilling_cohort(retryAfter)`** → back off in **time**; the walk terminates with
+ *   {@link RetryLaterOutcome} and the caller restarts a fresh {@link WalkEngine.register} after
+ *   `afterMs` — which begins again at `d_max`, decorrelating retries across the ring (§Anti-flood
+ *   claim 4: never re-hit the declined coord immediately).
+ *
+ * This module is FRET-free: it drives the {@link ITopicRouter} port (db-p2p binds it to FRET's
+ * `RouteAndMaybeAct` / direct dial) and the {@link TierAddressing} math, and delegates building +
+ * signing the {@link RegisterV1} to the injected {@link RegisterMessageFactory} (participant identity
+ * and crypto live there, not here).
+ */
+import { backoffRetryMs } from "./willingness.js";
+import { b64urlToBytes, decodeRegisterReplyV1, encodeCohortMessage } from "./wire/codec.js";
+class RouterWalkEngine {
+    deps;
+    wantK;
+    minSigs;
+    maxMemberRetries;
+    followPromoted;
+    configuredMaxSteps;
+    maxMessageBytes;
+    constructor(deps) {
+        this.deps = deps;
+        const cfg = deps.config ?? {};
+        this.wantK = cfg.wantK ?? 16;
+        this.minSigs = cfg.minSigs ?? 14;
+        this.maxMemberRetries = cfg.maxMemberRetries ?? this.wantK;
+        this.followPromoted = cfg.followPromoted ?? true;
+        this.configuredMaxSteps = cfg.maxSteps;
+        this.maxMessageBytes = cfg.maxMessageBytes;
+    }
+    async register(topicId, tier, appPayload, opts) {
+        const dMax = this.deps.dmax.dMax();
+        const maxSteps = this.configuredMaxSteps ?? 2 * (dMax + 2) + this.maxMemberRetries + 8;
+        const probe = opts?.probe ?? false;
+        let d = dMax;
+        let bootstrap = false;
+        let memberAttempts = 0;
+        let dialTarget;
+        let steps = 0;
+        let probeFollowedPromoted = false;
+        for (;;) {
+            if (++steps > maxSteps) {
+                // Safety valve: a well-formed tree converges well within this bound. Surface a temporal
+                // back-off rather than spin.
+                return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+            }
+            const reg = await this.deps.factory.build({ topicId, tier, treeTier: d, bootstrap, probe, appPayload });
+            const activity = encodeCohortMessage(reg, this.maxMessageBytes);
+            const raw = dialTarget !== undefined
+                ? await this.deps.router.dialMember(dialTarget, activity)
+                : await this.deps.router.routeAndAct(this.deps.addressing.coord(d, this.deps.self, topicId), activity, {
+                    wantK: this.wantK,
+                    minSigs: this.minSigs,
+                });
+            const reply = decodeRegisterReplyV1(raw, this.maxMessageBytes);
+            switch (reply.result) {
+                case "accepted": {
+                    return { kind: "accepted", reply };
+                }
+                case "no_state": {
+                    // Step toward the root. The cohort served nothing here; no spatial sibling state.
+                    dialTarget = undefined;
+                    memberAttempts = 0;
+                    if (probe && probeFollowedPromoted) {
+                        // The promoted child is cold (not yet instantiated). A probe never instantiates it,
+                        // so back off immediately — walking inward to the promoting ancestor would just
+                        // re-trigger the Promoted redirect and loop.
+                        return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+                    }
+                    const next = d - 1;
+                    if (next < 0) {
+                        if (bootstrap) {
+                            // Already re-issued at the root as a bootstrap and still nothing — no cohort
+                            // anywhere will instantiate right now. Back off in time.
+                            return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+                        }
+                        if (probe) {
+                            // A read-only probe never instantiates a cold root: the topic exists nowhere, so
+                            // resolve "not found / back off" rather than re-issuing with bootstrap:true.
+                            return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+                        }
+                        // Root returned NoState → cold-start: re-issue once at tier 0 with bootstrap:true.
+                        d = 0;
+                        bootstrap = true;
+                        break;
+                    }
+                    d = next;
+                    bootstrap = false;
+                    break;
+                }
+                case "promoted": {
+                    dialTarget = undefined;
+                    memberAttempts = 0;
+                    bootstrap = false;
+                    const targetTier = reply.targetTier ?? d + 1;
+                    if (probe) {
+                        probeFollowedPromoted = true;
+                    }
+                    if (!this.followPromoted) {
+                        return { kind: "promoted", targetTier };
+                    }
+                    d = targetTier; // the one outward move — recompute coord at the redirect target
+                    break;
+                }
+                case "unwilling_member": {
+                    const candidates = reply.candidateMembers ?? [];
+                    if (candidates.length === 0 || memberAttempts >= this.maxMemberRetries) {
+                        // Exhausted the named siblings (or none offered) → fall through to a cohort-level
+                        // temporal back-off, restarting at d_max on the caller's retry.
+                        return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+                    }
+                    // Retry the SAME coord at a named alternative member (spatial move within the cohort).
+                    dialTarget = { id: b64urlToBytes(candidates[memberAttempts % candidates.length]) };
+                    memberAttempts++;
+                    break;
+                }
+                case "unwilling_cohort": {
+                    // Back off in TIME, no spatial move; the caller restarts at d_max after the delay.
+                    return { kind: "retry_later", afterMs: reply.retryAfterMs ?? backoffRetryMs(0) };
+                }
+                default: {
+                    // Exhaustive over RegisterResult; an unknown result is treated as a temporal decline.
+                    return { kind: "retry_later", afterMs: backoffRetryMs(0) };
+                }
+            }
+        }
+    }
+}
+/** Build a {@link WalkEngine} over the injected router, addressing, `d_max`, and message factory. */
+export function createWalkEngine(deps) {
+    return new RouterWalkEngine(deps);
+}
+//# sourceMappingURL=walk.js.map