@optimystic/db-core 0.13.5 → 0.14.1

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"dmax.js","sourceRoot":"","sources":["../../../src/cohort-topic/dmax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,uEAAuE;AACvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAapC;;;;GAIG;AACH,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACtC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG,CAAC;QAAE,CAAC,GAAG,CAAC,CAAC;IACjB,mEAAmE;IACnE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QAAE,CAAC,EAAE,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;QAAE,CAAC,EAAE,CAAC;IACxC,OAAO,CAAC,CAAC;AACV,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB;IAClD,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACrE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,iBAAiB,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,iDAAiD,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAEzC,OAAO;QACN,IAAI;YACH,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,CAAC;YAClD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;YACvE,gFAAgF;YAChF,0EAA0E;YAC1E,kDAAkD;YAClD,IAAI,UAAU,GAAG,aAAa,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,OAAO,CAAC;QAChB,CAAC;KACD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,85 @@
+/**
+ * Cohort-topic substrate — intra-cohort gossip bus.
+ *
+ * Per `docs/cohort-topic.md` §Cohort gossip. Each member periodically broadcasts a `CohortGossipV1`
+ * carrying its willingness vector, load buckets, exact per-topic summaries, and any registration
+ * record deltas (new/touched records + evictions). The bus:
+ *
+ * - **broadcasts** outbound gossip over the injected {@link ICohortGossipTransport} (FRET cohort
+ *   gossip underneath — db-core never imports FRET);
+ * - **routes by coord**: a delivered frame is fanned to every coord engine's bus on a node, so each
+ *   bus merges only the gossip whose `coord` names its own cohort (epoch alone never isolates two
+ *   coords — they can share a member set, hence an epoch);
+ * - **merges inbound** gossip — record deltas into the {@link RegistrationStore} (last-writer-wins
+ *   by `lastPing`; evictions remove), and willingness/load/summaries into the per-member
+ *   {@link CohortView};
+ * - **detects epoch drift**: an inbound `cohortEpoch` that differs from the local epoch fires the
+ *   drift handlers, and record deltas under a foreign epoch are *not* merged (their slot
+ *   assignments belong to a different membership snapshot);
+ * - **optionally authenticates** inbound transport frames via an injected {@link GossipInboundVerifier}
+ *   (db-p2p binds peer-sig + cohort membership), dropping forged or non-member gossip before any merge.
+ *
+ * Convergence target (doc): a single gossip round spreads a touched record / willingness flip to all
+ * members — one {@link CohortGossipBus.applyInbound} of that gossip makes it visible locally.
+ */
+import type { RegistrationStore } from "../registration/types.js";
+import type { ICohortGossipTransport, RingCoord } from "../ports.js";
+import type { CohortGossipV1 } from "../wire/types.js";
+import { type CohortView } from "./view.js";
+/** Handler for inbound gossip (after merge). */
+export type GossipHandler = (g: CohortGossipV1) => void;
+/** Handler for a detected cohort-epoch drift on an inbound gossip. */
+export type DriftHandler = (inboundEpoch: Uint8Array, localEpoch: Uint8Array, from: string) => void;
+/** Authenticity gate for an inbound gossip arriving over the transport — `false` drops the frame. */
+export type GossipInboundVerifier = (g: CohortGossipV1) => boolean;
+export interface CohortGossipBusDeps {
+    /** FRET-backed cohort gossip transport (broadcast / subscribe). */
+    transport: ICohortGossipTransport;
+    /** Local registration store record deltas merge into. */
+    store: RegistrationStore;
+    /** This cohort's coord — the broadcast key **and** the inbound routing key (see {@link CohortGossipV1.coord}). */
+    coord: RingCoord;
+    /** The local cohort epoch, read fresh each merge so rotation is observed. */
+    localEpoch: () => Uint8Array;
+    /** Wall clock for inbound merges via the transport path; injectable for tests. */
+    now?: () => number;
+    /** Frame ceiling for encode/decode (defaults to the codec default). */
+    maxMessageBytes?: number;
+    /**
+     * Optional authenticity gate run on every gossip arriving over the transport (db-p2p binds it to the
+     * peer-sig primitive: verify `fromMember`'s signature over the gossip image **and** that `fromMember`
+     * is a member of this coord's cohort). A `false` verdict drops the frame — no merge, no handler fire —
+     * so a forged or non-member gossip can neither spoof willingness/load nor replicate fake records.
+     * Absent → the gate is skipped (unit tests / key-less interim mode); the `coord` routing check below
+     * still runs regardless. Not applied to direct {@link CohortGossipBus.applyInbound} calls (the trusted
+     * test/internal merge entry point).
+     */
+    verifyInbound?: GossipInboundVerifier;
+    /**
+     * Optional hook fired after a merge that deleted one or more records via gossiped evictions, carrying
+     * the **distinct** topic ids touched. db-p2p wires it to re-`touch` the per-cohort topic budget down
+     * (`topicBudget.touch(t, store.directParticipants(t))`) so a topic whose participants drain on a
+     * *sibling* (the drain arrives here as a gossip eviction, never this member's own TTL sweep) still
+     * releases its budget slot — mirroring the engine's own `sweepStale` re-touch. Kept as a decoupled
+     * callback so this gossip/replication module carries no anti-DoS dependency. Absent → skipped.
+     */
+    onRecordsEvicted?: (topicIds: readonly Uint8Array[]) => void;
+}
+/** Intra-cohort gossip bus (merge logic over an injected transport). */
+export interface CohortGossipBus {
+    /** Broadcast `g` to the cohort. */
+    broadcast(g: CohortGossipV1): void;
+    /** Subscribe to inbound gossip (fired after merge); returns an unsubscribe handle. */
+    onGossip(handler: GossipHandler): () => void;
+    /** Subscribe to epoch-drift detections; returns an unsubscribe handle. */
+    onDrift(handler: DriftHandler): () => void;
+    /** Merge one inbound gossip: records/willingness/load, with epoch drift detection. */
+    applyInbound(g: CohortGossipV1, now: number): void;
+    /** The merged per-member view (willingness / load / summaries). */
+    view(): CohortView;
+    /** Detach the transport subscription. */
+    close(): void;
+}
+/** Build a {@link CohortGossipBus} over the injected transport + store. */
+export declare function createCohortGossipBus(deps: CohortGossipBusDeps): CohortGossipBus;
+//# sourceMappingURL=bus.d.ts.map

package/dist/src/cohort-topic/gossip/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAW,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAoB,KAAK,UAAU,EAA0B,MAAM,WAAW,CAAC;AAEtF,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;AACxD,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,CAAC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AACpG,qGAAqG;AACrG,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IACnC,mEAAmE;IACnE,SAAS,EAAE,sBAAsB,CAAC;IAClC,yDAAyD;IACzD,KAAK,EAAE,iBAAiB,CAAC;IACzB,kHAAkH;IAClH,KAAK,EAAE,SAAS,CAAC;IACjB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,UAAU,CAAC;IAC7B,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,KAAK,IAAI,CAAC;CAC7D;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC/B,mCAAmC;IACnC,SAAS,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAC7C,0EAA0E;IAC1E,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IAC3C,sFAAsF;IACtF,YAAY,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,mEAAmE;IACnE,IAAI,IAAI,UAAU,CAAC;IACnB,yCAAyC;IACzC,KAAK,IAAI,IAAI,CAAC;CACd;AA6HD,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAEhF"}

package/dist/src/cohort-topic/gossip/bus.js

@@ -0,0 +1,146 @@
+/**
+ * Cohort-topic substrate — intra-cohort gossip bus.
+ *
+ * Per `docs/cohort-topic.md` §Cohort gossip. Each member periodically broadcasts a `CohortGossipV1`
+ * carrying its willingness vector, load buckets, exact per-topic summaries, and any registration
+ * record deltas (new/touched records + evictions). The bus:
+ *
+ * - **broadcasts** outbound gossip over the injected {@link ICohortGossipTransport} (FRET cohort
+ *   gossip underneath — db-core never imports FRET);
+ * - **routes by coord**: a delivered frame is fanned to every coord engine's bus on a node, so each
+ *   bus merges only the gossip whose `coord` names its own cohort (epoch alone never isolates two
+ *   coords — they can share a member set, hence an epoch);
+ * - **merges inbound** gossip — record deltas into the {@link RegistrationStore} (last-writer-wins
+ *   by `lastPing`; evictions remove), and willingness/load/summaries into the per-member
+ *   {@link CohortView};
+ * - **detects epoch drift**: an inbound `cohortEpoch` that differs from the local epoch fires the
+ *   drift handlers, and record deltas under a foreign epoch are *not* merged (their slot
+ *   assignments belong to a different membership snapshot);
+ * - **optionally authenticates** inbound transport frames via an injected {@link GossipInboundVerifier}
+ *   (db-p2p binds peer-sig + cohort membership), dropping forged or non-member gossip before any merge.
+ *
+ * Convergence target (doc): a single gossip round spreads a touched record / willingness flip to all
+ * members — one {@link CohortGossipBus.applyInbound} of that gossip makes it visible locally.
+ */
+import { bytesEqual, bytesKey } from "../registration/bytes.js";
+import { b64urlToBytes, decodeCohortGossipV1, encodeCohortMessage } from "../wire/codec.js";
+import { fromGossipRecord } from "./records.js";
+import { createCohortView } from "./view.js";
+class TransportCohortGossipBus {
+    deps;
+    gossipHandlers = new Set();
+    driftHandlers = new Set();
+    memberView = createCohortView();
+    now;
+    detach;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => Date.now());
+        this.detach = deps.transport.onMessage((_from, msg) => this.onInbound(msg));
+    }
+    broadcast(g) {
+        this.deps.transport.broadcast(this.deps.coord, encodeCohortMessage(g, this.deps.maxMessageBytes));
+    }
+    onGossip(handler) {
+        this.gossipHandlers.add(handler);
+        return () => this.gossipHandlers.delete(handler);
+    }
+    onDrift(handler) {
+        this.driftHandlers.add(handler);
+        return () => this.driftHandlers.delete(handler);
+    }
+    applyInbound(g, now) {
+        // Coord routing: a frame is fanned to every coord engine's bus, but it belongs only to the bus
+        // whose coord it names. Drop any gossip for another cohort so it cannot merge into this store/view
+        // (two coords on one node can even share a member set — and thus an epoch — so epoch alone never
+        // isolates them).
+        if (!this.isOurCoord(g)) {
+            return;
+        }
+        const localEpoch = this.deps.localEpoch();
+        const inboundEpoch = b64urlToBytes(g.cohortEpoch);
+        const epochMatches = bytesEqual(inboundEpoch, localEpoch);
+        if (!epochMatches) {
+            for (const handler of this.driftHandlers) {
+                handler(inboundEpoch, localEpoch, g.fromMember);
+            }
+        }
+        this.mergeView(g, inboundEpoch);
+        if (epochMatches) {
+            this.mergeRecords(g, now);
+        }
+    }
+    view() {
+        return this.memberView;
+    }
+    close() {
+        this.detach();
+    }
+    onInbound(msg) {
+        const g = decodeCohortGossipV1(msg, this.deps.maxMessageBytes);
+        // Cheap routing check first so a non-matching coord skips the (expensive) signature verify.
+        if (!this.isOurCoord(g)) {
+            return;
+        }
+        // Authenticity gate (db-p2p binds peer-sig + cohort membership); a forged/non-member gossip is
+        // dropped before any merge or handler fire. Absent in key-less/unit composition.
+        if (this.deps.verifyInbound !== undefined && !this.deps.verifyInbound(g)) {
+            return;
+        }
+        this.applyInbound(g, this.now());
+        for (const handler of this.gossipHandlers) {
+            handler(g);
+        }
+    }
+    /** True iff `g` names this bus's cohort coord (the inbound routing key). */
+    isOurCoord(g) {
+        return bytesEqual(b64urlToBytes(g.coord), this.deps.coord);
+    }
+    mergeView(g, inboundEpoch) {
+        this.memberView.merge(g.fromMember, {
+            cohortEpoch: inboundEpoch,
+            willingness: parseInt(g.willingnessBits, 16),
+            loadBuckets: g.loadBuckets,
+            windowSeconds: g.windowSeconds,
+            topicSummaries: g.topicSummaries,
+            timestamp: g.timestamp,
+        });
+    }
+    mergeRecords(g, now) {
+        for (const gr of g.records ?? []) {
+            const incoming = fromGossipRecord(gr);
+            // A record already past its TTL is dead; merging it would resurrect a registration the
+            // owner has (or soon will have) evicted. Drop it, matching `store.evictStale`'s predicate
+            // so replication can never reintroduce what local eviction removes.
+            if (now - incoming.lastPing > incoming.ttl) {
+                continue;
+            }
+            const held = this.deps.store.getByParticipant(incoming.topicId, incoming.participantId);
+            // Last-writer-wins by lastPing: a touch (newer lastPing) replaces an older replica.
+            if (held === undefined || incoming.lastPing >= held.lastPing) {
+                this.deps.store.put(incoming);
+            }
+        }
+        // Collect the distinct topics a gossiped eviction drained so the budget can be re-touched *after*
+        // the deletes (the count must be post-drain). This is the sibling-drain half of the topic-budget
+        // leak fix: a topic whose participants are sharded onto a sibling primary drains into this store as
+        // a gossip eviction, never via this member's own TTL sweep, so the `onRecordsEvicted` callback must
+        // re-`touch` the budget down here too — otherwise the slot leaks for any multi-member topic.
+        let evictedTopics;
+        for (const ref of g.evicted ?? []) {
+            const topicId = b64urlToBytes(ref.topicId);
+            this.deps.store.delete(topicId, b64urlToBytes(ref.participantId));
+            if (this.deps.onRecordsEvicted !== undefined) {
+                (evictedTopics ??= new Map()).set(bytesKey(topicId), topicId);
+            }
+        }
+        if (evictedTopics !== undefined && evictedTopics.size > 0) {
+            this.deps.onRecordsEvicted([...evictedTopics.values()]);
+        }
+    }
+}
+/** Build a {@link CohortGossipBus} over the injected transport + store. */
+export function createCohortGossipBus(deps) {
+    return new TransportCohortGossipBus(deps);
+}
+//# sourceMappingURL=bus.js.map

package/dist/src/cohort-topic/gossip/bus.js.map

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

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

@@ -0,0 +1,4 @@
+export * from "./records.js";
+export * from "./view.js";
+export * from "./bus.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

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

@@ -0,0 +1,4 @@
+export * from "./records.js";
+export * from "./view.js";
+export * from "./bus.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * Cohort-topic substrate — translation between the local {@link RegistrationRecord} (raw bytes)
+ * and the wire {@link GossipRecordV1} (base64url). The gossip bus carries record deltas so backups
+ * hold the record before the primary fails (per `docs/cohort-topic.md` §Registration record).
+ */
+import type { GossipRecordV1 } from "../wire/types.js";
+import type { RegistrationRecord } from "../registration/types.js";
+/** Encode a local registration record for cross-member gossip. */
+export declare function toGossipRecord(rec: RegistrationRecord): GossipRecordV1;
+/** Decode a gossiped record back into the local store shape. */
+export declare function fromGossipRecord(g: GossipRecordV1): RegistrationRecord;
+//# sourceMappingURL=records.d.ts.map

package/dist/src/cohort-topic/gossip/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/records.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,GAAG,EAAE,kBAAkB,GAAG,cAAc,CAetE;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,kBAAkB,CAetE"}

package/dist/src/cohort-topic/gossip/records.js

@@ -0,0 +1,41 @@
+/**
+ * Cohort-topic substrate — translation between the local {@link RegistrationRecord} (raw bytes)
+ * and the wire {@link GossipRecordV1} (base64url). The gossip bus carries record deltas so backups
+ * hold the record before the primary fails (per `docs/cohort-topic.md` §Registration record).
+ */
+import { b64urlToBytes, bytesToB64url } from "../wire/codec.js";
+/** Encode a local registration record for cross-member gossip. */
+export function toGossipRecord(rec) {
+    const out = {
+        topicId: bytesToB64url(rec.topicId),
+        participantId: bytesToB64url(rec.participantId),
+        tier: rec.tier,
+        primary: bytesToB64url(rec.primary),
+        backups: rec.backups.map(bytesToB64url),
+        attachedAt: rec.attachedAt,
+        lastPing: rec.lastPing,
+        ttl: rec.ttl,
+    };
+    if (rec.appState !== undefined) {
+        out.appState = bytesToB64url(rec.appState);
+    }
+    return out;
+}
+/** Decode a gossiped record back into the local store shape. */
+export function fromGossipRecord(g) {
+    const out = {
+        topicId: b64urlToBytes(g.topicId),
+        participantId: b64urlToBytes(g.participantId),
+        tier: g.tier,
+        primary: b64urlToBytes(g.primary),
+        backups: g.backups.map(b64urlToBytes),
+        attachedAt: g.attachedAt,
+        lastPing: g.lastPing,
+        ttl: g.ttl,
+    };
+    if (g.appState !== undefined) {
+        out.appState = b64urlToBytes(g.appState);
+    }
+    return out;
+}
+//# sourceMappingURL=records.js.map

package/dist/src/cohort-topic/gossip/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/records.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIhE,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,MAAM,GAAG,GAAmB;QAC3B,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC;QACnC,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC,aAAa,CAAC;QAC/C,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC;QACnC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QACvC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,GAAG,EAAE,GAAG,CAAC,GAAG;KACZ,CAAC;IACF,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,GAAG,CAAC,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,gBAAgB,CAAC,CAAiB;IACjD,MAAM,GAAG,GAAuB;QAC/B,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QACjC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QACjC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QACrC,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,GAAG,EAAE,CAAC,CAAC,GAAG;KACV,CAAC;IACF,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC9B,GAAG,CAAC,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

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

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

package/dist/src/cohort-topic/gossip/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IAC1B,mFAAmF;IACnF,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACpD,wDAAwD;IACxD,GAAG,IAAI,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC/C;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACpD,6GAA6G;IAC7G,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC;CACtD;AAuBD,oDAAoD;AACpD,wBAAgB,gBAAgB,IAAI,iBAAiB,CAEpD"}

package/dist/src/cohort-topic/gossip/view.js

@@ -0,0 +1,30 @@
+/**
+ * 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}).
+ */
+class MapCohortView {
+    byMember = new Map();
+    get(member) {
+        return this.byMember.get(member);
+    }
+    all() {
+        return this.byMember;
+    }
+    merge(member, c) {
+        const held = this.byMember.get(member);
+        if (held !== undefined && c.timestamp < held.timestamp) {
+            return false; // stale; keep the newer contribution
+        }
+        this.byMember.set(member, c);
+        return true;
+    }
+}
+/** Construct an empty {@link MutableCohortView}. */
+export function createCohortView() {
+    return new MapCohortView();
+}
+//# sourceMappingURL=view.js.map

package/dist/src/cohort-topic/gossip/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../../src/cohort-topic/gossip/view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkCH,MAAM,aAAa;IACD,QAAQ,GAAG,IAAI,GAAG,EAA8B,CAAC;IAElE,GAAG,CAAC,MAAc;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,GAAG;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,MAAc,EAAE,CAAqB;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACxD,OAAO,KAAK,CAAC,CAAC,qCAAqC;QACpD,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACb,CAAC;CACD;AAED,oDAAoD;AACpD,MAAM,UAAU,gBAAgB;IAC/B,OAAO,IAAI,aAAa,EAAE,CAAC;AAC5B,CAAC"}

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

@@ -0,0 +1,21 @@
+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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}

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

@@ -0,0 +1,21 @@
+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";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cohort-topic/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}

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

@@ -0,0 +1,78 @@
+/**
+ * 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 { 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 declare 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 declare function utilizationBucket(utilization: number): number;
+/** 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;
+}
+/** Construct an idle (all-bucket-0) {@link LoadBarometerState}. */
+export declare function createLoadBarometer(config?: LoadBarometerConfig): LoadBarometerState;
+/** Iterate the four tiers — convenience for callers folding the barometer into a gossip frame. */
+export declare function eachTier(): readonly Tier[];
+//# sourceMappingURL=barometer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"barometer.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/load/barometer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnD,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IAClC,+EAA+E;IAC/E,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,sCAAsC;IACtC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,CAAC;IACnC,qFAAqF;IACrF,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAClC,2HAA2H;IAC3H,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IACnC,qGAAqG;IACrG,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAuCD,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAEpF;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,IAAI,SAAS,IAAI,EAAE,CAE1C"}