@optimystic/db-core 0.13.4 → 0.14.0

package/dist/src/cohort-topic/registration/renewal.js

@@ -0,0 +1,306 @@
+/**
+ * Cohort-topic substrate — TTL renewal and failover.
+ *
+ * Per `docs/cohort-topic.md` §TTL and renewal and §Failure modes:
+ *
+ * - Participant pings `primary` every `ttl/3`. Success → primary touches `lastPing` and gossips it.
+ * - Three consecutive ping failures → participant promotes `backups[0]` via a re-attach RPC: a renew
+ *   carrying a **signed `reattach` flag** (no full re-registration). The backup accepts when it holds
+ *   the record locally *and* is a computed backup under the current epoch — re-stamping `primary` to
+ *   itself and serving subsequent plain pings via an epoch-scoped failover override (the unchanged
+ *   `cohortEpoch` still names the dead node as the computed primary). A re-attach answered
+ *   `primary_moved` means a real rotation moved primary to a live member: the participant adopts that
+ *   payload instead of promoting the contacted backup (ignoring a reply that points back at the dead
+ *   primary). **Resolved (GROUNDING):** the participant's `cohortEpoch` hint refreshes lazily — on the
+ *   *next* ping/renewal after failover, not eagerly at failover time.
+ * - All of primary + backups fail → participant re-runs lookup from `d_max` (walk ticket, injected).
+ * - Cohort-side: evict where `now − lastPing > ttl`; eviction is gossiped so members converge.
+ *
+ * Both sides take their transport/gossip by injection so storage + sharding + TTL stay unit-testable
+ * in isolation; db-core never imports FRET or libp2p here.
+ */
+import { b64urlToBytes } from "../wire/codec.js";
+import { bytesEqual, bytesKey, recordKey } from "./bytes.js";
+import { MAX_PING_FAILURES, pingIntervalMs } from "./types.js";
+class TtlRenewalParticipant {
+    deps;
+    consecutiveFailures = 0;
+    current;
+    epochHint;
+    constructor(initial, deps) {
+        this.deps = deps;
+        this.current = initial;
+        this.epochHint = deps.initialCohortEpoch;
+    }
+    get record() {
+        return this.current;
+    }
+    get cohortEpochHint() {
+        return this.epochHint;
+    }
+    get pingIntervalMs() {
+        return pingIntervalMs(this.current.ttl);
+    }
+    async pingLoop() {
+        const reply = await this.trySend(this.current.primary);
+        if (reply !== undefined) {
+            this.onPingSuccess(reply);
+            return;
+        }
+        this.consecutiveFailures++;
+        if (this.consecutiveFailures < MAX_PING_FAILURES) {
+            return;
+        }
+        await this.failover();
+    }
+    async reattach(target) {
+        return this.deps.transport.send(target, await this.buildRenew({ reattach: true }));
+    }
+    async withdraw() {
+        // Fire-and-forget signed tombstone to the current primary. A send failure is swallowed — the
+        // record TTL-expires as it does today (the local-half fallback) — and crucially we never bump
+        // `consecutiveFailures` or fail over: the participant is leaving, not recovering.
+        try {
+            await this.deps.transport.send(this.current.primary, await this.buildRenew({ withdraw: true }));
+        }
+        catch {
+            /* best-effort; the cohort TTL bounds the leak */
+        }
+    }
+    /** Send a renew, mapping an RPC rejection to `undefined` (a counted failure). */
+    async trySend(target) {
+        try {
+            return await this.deps.transport.send(target, await this.buildRenew({}));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    onPingSuccess(reply) {
+        this.consecutiveFailures = 0;
+        if (reply.result === "primary_moved") {
+            // Lazy cohortEpoch refresh lands here: a move discovered on a normal ping updates the hint.
+            this.applyPrimaryMoved(reply);
+        }
+    }
+    /**
+     * 3-fail path: re-attach to each backup in turn (a signed `reattach=true` renew). An `ok` means the
+     * backup accepted the crash-failover promotion → promote it locally. A `primary_moved` means a real
+     * rotation moved primary to a different live member → adopt that payload (not the contacted backup),
+     * **unless** it points back at the just-failed primary (the bounce guard) — then keep trying. All
+     * backups exhausted → re-run lookup from `d_max`.
+     */
+    async failover() {
+        const failedPrimary = this.current.primary;
+        for (const backup of this.current.backups) {
+            const reply = await this.tryReattach(backup);
+            if (reply === undefined) {
+                continue;
+            }
+            if (reply.result === "ok") {
+                this.promote(backup);
+                return;
+            }
+            if (reply.result === "primary_moved") {
+                // A genuine rotation: adopt the rotated assignment — but never re-adopt the dead primary
+                // (the defensive guard against the exact bounce crash-failover is meant to fix).
+                if (reply.newPrimary !== undefined && bytesEqual(b64(reply.newPrimary), failedPrimary)) {
+                    continue;
+                }
+                this.applyPrimaryMoved(reply);
+                // We now have a fresh, live primary to ping — clear the strike count so the next single
+                // transient failure doesn't immediately re-failover (matching `promote` and the
+                // normal-ping `primary_moved` path, which both reset here).
+                this.consecutiveFailures = 0;
+                return;
+            }
+            // unknown_registration (replication lag) or anything else: try the next backup.
+        }
+        await this.deps.transport.relookup();
+        // relookup is a terminal recovery action (it owns re-establishing the registration out of
+        // band); reset the counter so a still-dead primary backs off to one relookup per
+        // MAX_PING_FAILURES cycles rather than re-running the d_max walk on every subsequent ping.
+        this.consecutiveFailures = 0;
+    }
+    async tryReattach(target) {
+        try {
+            return await this.reattach(target);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Promote `target` (a backup) to primary. The `cohortEpoch` hint is deliberately *not* refreshed
+     * here — per the resolved open question it refreshes lazily on the next ping/renewal.
+     */
+    promote(target) {
+        const backups = this.current.backups.filter((b) => !bytesEqual(b, target));
+        this.current = { ...this.current, primary: target, backups, lastPing: this.deps.clock() };
+        this.consecutiveFailures = 0;
+    }
+    applyPrimaryMoved(reply) {
+        const patch = { lastPing: this.deps.clock() };
+        if (reply.newPrimary !== undefined) {
+            patch.primary = b64(reply.newPrimary);
+        }
+        if (reply.newBackups !== undefined) {
+            patch.backups = reply.newBackups.map(b64);
+        }
+        if (reply.cohortEpoch !== undefined) {
+            // Lazy refresh: the epoch hint catches up here, on the ping that discovers the move.
+            this.epochHint = b64(reply.cohortEpoch);
+        }
+        this.current = { ...this.current, ...patch };
+    }
+    /**
+     * Build a signed renew. The `reattach=true` (crash-failover) / `withdraw=true` (leave tombstone)
+     * flags are carried inside the signed body so the accepting member can trust the attestation; a plain
+     * ping omits both fields entirely (a stray renew can never silently usurp a live primary or evict a
+     * registration). Each flag is set only when true, matching the current plain-ping wire shape.
+     */
+    async buildRenew(opts) {
+        const body = {
+            v: 1,
+            topicId: bytesKey(this.current.topicId),
+            participantId: bytesKey(this.current.participantId),
+            correlationId: this.deps.correlationId,
+            timestamp: this.deps.clock(),
+        };
+        if (opts.reattach === true) {
+            body.reattach = true;
+        }
+        if (opts.withdraw === true) {
+            body.withdraw = true;
+        }
+        return { ...body, signature: await this.deps.sign(body) };
+    }
+}
+/** Build a {@link RenewalParticipant} around an initial record. */
+export function createRenewalParticipant(initial, deps) {
+    return new TtlRenewalParticipant(initial, deps);
+}
+class StoreRenewalCohortSide {
+    deps;
+    /**
+     * Epoch-scoped crash-failover overrides: `recordKey → cohortEpoch under which this member accepted a
+     * promotion`. A matching entry makes a *subsequent plain ping* serve here even though the computed
+     * primary is still the dead node, so the migrated participant stops bouncing. Cleared on epoch change
+     * (the next rotation handoff reasserts the deterministic assignment). Sibling to the rotation
+     * `isServing` dual-serve exception — distinct state, OR-ed into the serve decision.
+     */
+    failoverServing = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    onRenew(msg, now) {
+        const topicId = b64(msg.topicId);
+        const participantId = b64(msg.participantId);
+        const rec = this.deps.store.getByParticipant(topicId, participantId);
+        if (rec === undefined) {
+            return { v: 1, result: "unknown_registration" };
+        }
+        const key = recordKey(topicId, participantId);
+        if (msg.withdraw === true) {
+            // Signed leave attestation. A forged/missing signature must never evict someone else's
+            // registration → ignore, revealing nothing (`unknown_registration`, the same opaque answer a
+            // non-existent record gets). The gate is absent in key-less unit mode, matching reattach.
+            // `withdraw` is checked before the slot/primary computation: a withdraw needs no slot or
+            // primary check (any holder evicts its replica), and it takes precedence over a (malformed)
+            // co-set `reattach` — a record being withdrawn is gone regardless of a promotion request.
+            if (this.deps.verifyParticipantSig?.(msg) === false) {
+                return { v: 1, result: "unknown_registration" };
+            }
+            this.deps.store.delete(topicId, participantId);
+            this.failoverServing.delete(key); // mirror sweepStale: drop any crash-failover override
+            this.deps.gossip.evicted(rec);
+            return { v: 1, result: "withdrawn" };
+        }
+        const { members, cohortEpoch } = this.deps.cohort();
+        const { primary, backups } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+        const self = this.deps.self;
+        if (msg.reattach === true) {
+            // Crash-failover promotion request (participant attests primary unreachable). The signed
+            // `reattach` flag is what a backup trusts to promote itself, so a missing/forged signature
+            // must never escalate: fall through to a plain redirect (never promote).
+            if (this.deps.verifyParticipantSig?.(msg) === false) {
+                return this.primaryMoved(primary, backups, cohortEpoch);
+            }
+            if (bytesEqual(primary, self)) {
+                // A rotation already made this member the computed primary; serve, no override needed.
+                return this.touchAndServe(rec, now);
+            }
+            if (backups.some((b) => bytesEqual(b, self))) {
+                // Legitimate backup takeover: re-stamp primary, gossip the new assignment, and record an
+                // epoch-scoped override so subsequent plain pings keep being served here.
+                const restamped = {
+                    ...rec,
+                    primary: self,
+                    backups: rec.backups.filter((b) => !bytesEqual(b, self)),
+                    lastPing: now,
+                };
+                this.deps.store.put(restamped);
+                this.failoverServing.set(key, cohortEpoch);
+                this.deps.gossip.touch(restamped);
+                return { v: 1, result: "ok" };
+            }
+            if (this.deps.isServing?.(topicId, participantId) === true) {
+                // Rotation dual-serve already covers this record here.
+                return this.touchAndServe(rec, now);
+            }
+            // Not a valid takeover target (stale participant view): redirect, do not promote.
+            return this.primaryMoved(primary, backups, cohortEpoch);
+        }
+        // Plain ping.
+        const isComputedPrimary = bytesEqual(primary, self);
+        const override = this.failoverServing.get(key);
+        const overrideMatches = override !== undefined && bytesEqual(override, cohortEpoch);
+        // Housekeeping: drop a now-redundant override (this member is the computed primary again) or a
+        // stale one tagged under a prior epoch (the rotation handoff governs across the epoch change).
+        if (override !== undefined && (isComputedPrimary || !overrideMatches)) {
+            this.failoverServing.delete(key);
+        }
+        const serving = isComputedPrimary || this.deps.isServing?.(topicId, participantId) === true || overrideMatches;
+        if (serving) {
+            return this.touchAndServe(rec, now);
+        }
+        return this.primaryMoved(primary, backups, cohortEpoch);
+    }
+    /** Existing touch path: stamp `lastPing`, gossip the touch, reply `ok`. */
+    touchAndServe(rec, now) {
+        const touched = { ...rec, lastPing: now };
+        this.deps.store.put(touched);
+        this.deps.gossip.touch(touched);
+        return { v: 1, result: "ok" };
+    }
+    primaryMoved(primary, backups, cohortEpoch) {
+        return {
+            v: 1,
+            result: "primary_moved",
+            newPrimary: bytesKey(primary),
+            newBackups: backups.map(bytesKey),
+            cohortEpoch: bytesKey(cohortEpoch),
+        };
+    }
+    sweepStale(now) {
+        const evicted = this.deps.store.evictStale(now);
+        for (const rec of evicted) {
+            // Drop any crash-failover override for an evicted record. Otherwise it leaks (the record gets
+            // no more pings, so the plain-ping housekeeping that would clear it never runs) and — if the
+            // same `(topic, participant)` re-registers under the unchanged epoch — could wrongly make a
+            // non-primary member keep serving via the stale override.
+            this.failoverServing.delete(recordKey(rec.topicId, rec.participantId));
+            this.deps.gossip.evicted(rec);
+        }
+        return evicted;
+    }
+}
+/** Build a {@link RenewalCohortSide}. */
+export function createRenewalCohortSide(deps) {
+    return new StoreRenewalCohortSide(deps);
+}
+/** Decode a base64url wire field to bytes (the canonical byte form on the wire). */
+function b64(s) {
+    return b64urlToBytes(s);
+}
+//# sourceMappingURL=renewal.js.map

package/dist/src/cohort-topic/registration/renewal.js.map

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

package/dist/src/cohort-topic/registration/sharding.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cohort-topic substrate — deterministic primary/backup sharding.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Primary and backup sharding:
+ *
+ * ```
+ * order(cohortMembers) = sort(cohortMembers, by PeerId ascending)
+ * slot(participantId, cohortEpoch) = H(participantId ‖ cohortEpoch) mod k
+ * primary  = order[slot]
+ * backups  = order[slot+1 .. slot+2  (mod k)]
+ * ```
+ *
+ * Deterministic given `(participantId, cohortEpoch, members)`; shards delivery load roughly evenly
+ * across the `~k` members. `H` is the injected {@link IRingHash} (db-core's own SHA-256 — **not** a
+ * FRET import), reused so coords stay byte-compatible with the rest of the substrate.
+ */
+import type { IRingHash } from "../ports.js";
+/** Deterministic slot assignment over a fixed cohort snapshot. */
+export interface SlotAssigner {
+    /**
+     * `(primary, backups)` for `participantId` under `cohortEpoch` and `cohortMembers`.
+     * Backups are the 1..2 members following the primary in ascending order, wrapping mod `k`.
+     */
+    assignSlots(participantId: Uint8Array, cohortEpoch: Uint8Array, cohortMembers: readonly Uint8Array[]): {
+        primary: Uint8Array;
+        backups: Uint8Array[];
+    };
+}
+/** Build a {@link SlotAssigner} bound to a hash. */
+export declare function createSlotAssigner(hash: IRingHash): SlotAssigner;
+//# sourceMappingURL=sharding.d.ts.map

package/dist/src/cohort-topic/registration/sharding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/sharding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC5B;;;OAGG;IACH,WAAW,CAAC,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,UAAU,EAAE,GAAG;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;CACtJ;AAcD,oDAAoD;AACpD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAkBhE"}

package/dist/src/cohort-topic/registration/sharding.js

@@ -0,0 +1,48 @@
+/**
+ * Cohort-topic substrate — deterministic primary/backup sharding.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Primary and backup sharding:
+ *
+ * ```
+ * order(cohortMembers) = sort(cohortMembers, by PeerId ascending)
+ * slot(participantId, cohortEpoch) = H(participantId ‖ cohortEpoch) mod k
+ * primary  = order[slot]
+ * backups  = order[slot+1 .. slot+2  (mod k)]
+ * ```
+ *
+ * Deterministic given `(participantId, cohortEpoch, members)`; shards delivery load roughly evenly
+ * across the `~k` members. `H` is the injected {@link IRingHash} (db-core's own SHA-256 — **not** a
+ * FRET import), reused so coords stay byte-compatible with the rest of the substrate.
+ */
+import { compareBytes, concatBytes } from "./bytes.js";
+/** Number of warm-failover backups (capped by available members). */
+const MAX_BACKUPS = 2;
+/** `coord mod k` over the full digest, MSB-first, without bigint allocation. */
+function modK(coord, k) {
+    let acc = 0;
+    for (let i = 0; i < coord.length; i++) {
+        acc = (acc * 256 + coord[i]) % k;
+    }
+    return acc;
+}
+/** Build a {@link SlotAssigner} bound to a hash. */
+export function createSlotAssigner(hash) {
+    return {
+        assignSlots(participantId, cohortEpoch, cohortMembers) {
+            const k = cohortMembers.length;
+            if (k === 0) {
+                throw new RangeError("assignSlots requires a non-empty cohort");
+            }
+            const order = [...cohortMembers].sort(compareBytes);
+            const slot = modK(hash.H(concatBytes(participantId, cohortEpoch)), k);
+            const primary = order[slot];
+            const backups = [];
+            const nBackups = Math.min(MAX_BACKUPS, k - 1);
+            for (let i = 1; i <= nBackups; i++) {
+                backups.push(order[(slot + i) % k]);
+            }
+            return { primary, backups };
+        },
+    };
+}
+//# sourceMappingURL=sharding.js.map

package/dist/src/cohort-topic/registration/sharding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.js","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/sharding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAWvD,qEAAqE;AACrE,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,gFAAgF;AAChF,SAAS,IAAI,CAAC,KAAiB,EAAE,CAAS;IACzC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,IAAe;IACjD,OAAO;QACN,WAAW,CAAC,aAAyB,EAAE,WAAuB,EAAE,aAAoC;YACnG,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACb,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;YACjE,CAAC;YACD,MAAM,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACtE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAE,CAAC;YAC7B,MAAM,OAAO,GAAiB,EAAE,CAAC;YACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAC7B,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/src/cohort-topic/registration/store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cohort-topic substrate — in-memory registration store.
+ *
+ * Per `docs/cohort-topic.md` §Registration mechanics. Records are doubly indexed: an outer map
+ * keyed by topic, each holding an inner map keyed by participant. This gives O(1)
+ * {@link RegistrationStore.getByParticipant} / {@link RegistrationStore.delete} and O(participants)
+ * {@link RegistrationStore.listByTopic} without a secondary index to keep in sync. The store is
+ * local soft state; cross-member replication runs over cohort gossip in a later ticket.
+ */
+import type { RegistrationStore } from "./types.js";
+/** Construct an empty {@link RegistrationStore}. */
+export declare function createRegistrationStore(): RegistrationStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/src/cohort-topic/registration/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAkExE,oDAAoD;AACpD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}

package/dist/src/cohort-topic/registration/store.js

@@ -0,0 +1,72 @@
+/**
+ * Cohort-topic substrate — in-memory registration store.
+ *
+ * Per `docs/cohort-topic.md` §Registration mechanics. Records are doubly indexed: an outer map
+ * keyed by topic, each holding an inner map keyed by participant. This gives O(1)
+ * {@link RegistrationStore.getByParticipant} / {@link RegistrationStore.delete} and O(participants)
+ * {@link RegistrationStore.listByTopic} without a secondary index to keep in sync. The store is
+ * local soft state; cross-member replication runs over cohort gossip in a later ticket.
+ */
+import { bytesKey } from "./bytes.js";
+class InMemoryRegistrationStore {
+    /** topicKey → (participantKey → record). Inner maps are pruned when they empty. */
+    byTopic = new Map();
+    put(rec) {
+        const tk = bytesKey(rec.topicId);
+        let inner = this.byTopic.get(tk);
+        if (inner === undefined) {
+            inner = new Map();
+            this.byTopic.set(tk, inner);
+        }
+        inner.set(bytesKey(rec.participantId), rec);
+    }
+    getByParticipant(topicId, participantId) {
+        return this.byTopic.get(bytesKey(topicId))?.get(bytesKey(participantId));
+    }
+    listByTopic(topicId) {
+        const inner = this.byTopic.get(bytesKey(topicId));
+        return inner === undefined ? [] : [...inner.values()];
+    }
+    listAll() {
+        const out = [];
+        for (const inner of this.byTopic.values()) {
+            for (const rec of inner.values()) {
+                out.push(rec);
+            }
+        }
+        return out;
+    }
+    delete(topicId, participantId) {
+        const tk = bytesKey(topicId);
+        const inner = this.byTopic.get(tk);
+        if (inner === undefined)
+            return;
+        inner.delete(bytesKey(participantId));
+        if (inner.size === 0) {
+            this.byTopic.delete(tk);
+        }
+    }
+    directParticipants(topicId) {
+        return this.byTopic.get(bytesKey(topicId))?.size ?? 0;
+    }
+    evictStale(now) {
+        const evicted = [];
+        for (const [tk, inner] of this.byTopic) {
+            for (const [pk, rec] of inner) {
+                if (now - rec.lastPing > rec.ttl) {
+                    evicted.push(rec);
+                    inner.delete(pk);
+                }
+            }
+            if (inner.size === 0) {
+                this.byTopic.delete(tk);
+            }
+        }
+        return evicted;
+    }
+}
+/** Construct an empty {@link RegistrationStore}. */
+export function createRegistrationStore() {
+    return new InMemoryRegistrationStore();
+}
+//# sourceMappingURL=store.js.map

package/dist/src/cohort-topic/registration/store.js.map

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

package/dist/src/cohort-topic/registration/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Cohort-topic substrate — registration record store, types and constants.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Registration mechanics and §Primary and backup
+ * sharding. This module owns the **local**, transport-agnostic shapes: the soft-state record a
+ * cohort member holds per participant, the in-memory store interface over those records, and the
+ * TTL constants. Cross-member replication (cohort gossip) is layered on top by db-p2p and the
+ * bridge ticket; db-core never imports FRET or libp2p here.
+ *
+ * Peer ids are the opaque byte-array references the cohort-topic substrate uses throughout — the
+ * same representation as {@link import("../ports.js").PeerRef}`.id` and
+ * {@link import("../ports.js").RingCoord} (raw `Uint8Array`, not the structural
+ * {@link import("../../network/types.js").PeerId}). The wire layer carries them as base64url
+ * strings; this store works in raw bytes and the renewal/handoff bridges translate at the wire
+ * boundary.
+ */
+/**
+ * Soft-state registration a cohort member holds per participant. Replicated across the `~k`
+ * members by cohort gossip; only {@link RegistrationRecord.primary} serves, with
+ * {@link RegistrationRecord.backups} watching for warm failover.
+ */
+export interface RegistrationRecord {
+    /** Topic id, 32 bytes. */
+    topicId: Uint8Array;
+    /** Registering participant. */
+    participantId: Uint8Array;
+    /** Tier this registration sits at (0..3). */
+    tier: number;
+    /** Cohort member assigned to serve this participant. */
+    primary: Uint8Array;
+    /** 1..2 warm-failover cohort members. */
+    backups: Uint8Array[];
+    /** Unix ms the registration first attached. */
+    attachedAt: number;
+    /** Unix ms of the most recent successful ping/touch. */
+    lastPing: number;
+    /** Lifetime in ms; record is stale once `now − lastPing > ttl`. */
+    ttl: number;
+    /** Opaque application-defined per-registration state; the layer never interprets it. */
+    appState?: Uint8Array;
+}
+/**
+ * In-memory registration store, indexed for both per-participant lookup and per-topic listing.
+ * This ticket owns the **local** store and its indexes; the gossip layer and TTL loop call the
+ * deterministic functions over it.
+ */
+export interface RegistrationStore {
+    /** Insert or replace the record for `(topicId, participantId)`. */
+    put(rec: RegistrationRecord): void;
+    /** Record for `(topicId, participantId)`, or `undefined`. */
+    getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined;
+    /** All records held for `topicId` (empty if none). */
+    listByTopic(topicId: Uint8Array): readonly RegistrationRecord[];
+    /** Every record across all topics — used by the rotation handoff inventory pass. */
+    listAll(): readonly RegistrationRecord[];
+    /** Remove the record for `(topicId, participantId)`. */
+    delete(topicId: Uint8Array, participantId: Uint8Array): void;
+    /** Stock count of direct participants for `topicId` (drives promotion). */
+    directParticipants(topicId: Uint8Array): number;
+    /** Remove and return every record where `now − lastPing > ttl`. */
+    evictStale(now: number): readonly RegistrationRecord[];
+}
+/** Core-tier default registration TTL (ms). */
+export declare const DEFAULT_TTL_MS = 90000;
+/** Edge-tier default registration TTL (ms). */
+export declare const EDGE_TTL_MS = 60000;
+/** Consecutive ping failures before a participant promotes `backups[0]`. */
+export declare const MAX_PING_FAILURES = 3;
+/** `ping_interval = ttl / 3` (default 30s Core, 20s Edge), floored to whole ms. */
+export declare function pingIntervalMs(ttl: number): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/cohort-topic/registration/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,0BAA0B;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,+BAA+B;IAC/B,aAAa,EAAE,UAAU,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,OAAO,EAAE,UAAU,CAAC;IACpB,yCAAyC;IACzC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,wFAAwF;IACxF,QAAQ,CAAC,EAAE,UAAU,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC,6DAA6D;IAC7D,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACjG,sDAAsD;IACtD,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,kBAAkB,EAAE,CAAC;IAChE,oFAAoF;IACpF,OAAO,IAAI,SAAS,kBAAkB,EAAE,CAAC;IACzC,wDAAwD;IACxD,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7D,2EAA2E;IAC3E,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IAChD,mEAAmE;IACnE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CAAC;CACvD;AAED,+CAA+C;AAC/C,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,+CAA+C;AAC/C,eAAO,MAAM,WAAW,QAAS,CAAC;AAClC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/dist/src/cohort-topic/registration/types.js

@@ -0,0 +1,27 @@
+/**
+ * Cohort-topic substrate — registration record store, types and constants.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Registration mechanics and §Primary and backup
+ * sharding. This module owns the **local**, transport-agnostic shapes: the soft-state record a
+ * cohort member holds per participant, the in-memory store interface over those records, and the
+ * TTL constants. Cross-member replication (cohort gossip) is layered on top by db-p2p and the
+ * bridge ticket; db-core never imports FRET or libp2p here.
+ *
+ * Peer ids are the opaque byte-array references the cohort-topic substrate uses throughout — the
+ * same representation as {@link import("../ports.js").PeerRef}`.id` and
+ * {@link import("../ports.js").RingCoord} (raw `Uint8Array`, not the structural
+ * {@link import("../../network/types.js").PeerId}). The wire layer carries them as base64url
+ * strings; this store works in raw bytes and the renewal/handoff bridges translate at the wire
+ * boundary.
+ */
+/** Core-tier default registration TTL (ms). */
+export const DEFAULT_TTL_MS = 90_000;
+/** Edge-tier default registration TTL (ms). */
+export const EDGE_TTL_MS = 60_000;
+/** Consecutive ping failures before a participant promotes `backups[0]`. */
+export const MAX_PING_FAILURES = 3;
+/** `ping_interval = ttl / 3` (default 30s Core, 20s Edge), floored to whole ms. */
+export function pingIntervalMs(ttl) {
+    return Math.floor(ttl / 3);
+}
+//# sourceMappingURL=types.js.map

package/dist/src/cohort-topic/registration/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAkDH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAClC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;AAC5B,CAAC"}

package/dist/src/cohort-topic/ring-hash.d.ts

@@ -0,0 +1,27 @@
+import type { IRingHash, RingCoord } from './ports.js';
+/**
+ * Default ring width in bits. 256 = the full SHA-256 digest, which lines up byte-for-byte with
+ * FRET's coordinate type (FRET hashes ring keys with SHA-256). Override only when targeting a
+ * DHT with a narrower ring.
+ */
+export declare const RING_BITS = 256;
+/**
+ * db-core's {@link IRingHash}, backed by its own SHA-256 (the same digest db-core already uses
+ * for logs and block ids) — **not** an import of any FRET hash module. This keeps db-core
+ * FRET-free while guaranteeing on-the-wire coord compatibility: at the default `ringBits = 256`,
+ * `H(bytes)` is the full SHA-256 digest, identical to what FRET produces for the same input.
+ *
+ * For ring widths that are not a whole number of bytes, the digest is truncated to
+ * `ceil(ringBits / 8)` bytes and the trailing partial byte's unused low bits are zeroed, so two
+ * inputs whose digests share the first `ringBits` bits yield byte-identical coords.
+ */
+export declare class RingHash implements IRingHash {
+    readonly ringBits: number;
+    private readonly nBytes;
+    private readonly tailMask;
+    constructor(ringBits?: number);
+    H(bytes: Uint8Array): RingCoord;
+}
+/** Convenience factory mirroring the db-p2p adapter construction style. */
+export declare function createRingHash(ringBits?: number): IRingHash;
+//# sourceMappingURL=ring-hash.d.ts.map

package/dist/src/cohort-topic/ring-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-hash.d.ts","sourceRoot":"","sources":["../../../src/cohort-topic/ring-hash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;;;;;;;GASG;AACH,qBAAa,QAAS,YAAW,SAAS;IACzC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,MAAkB;IAUxC,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS;CAS/B;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAAkB,GAAG,SAAS,CAEtE"}