@optimystic/db-core 0.13.4 → 0.14.0

package/dist/src/cohort-topic/ring-hash.js

@@ -0,0 +1,45 @@
+import { sha256 } from '@noble/hashes/sha2.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 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 class RingHash {
+    ringBits;
+    nBytes;
+    tailMask;
+    constructor(ringBits = RING_BITS) {
+        if (!Number.isInteger(ringBits) || ringBits <= 0 || ringBits > 256) {
+            throw new RangeError(`ringBits must be an integer in [1, 256], got ${ringBits}`);
+        }
+        this.ringBits = ringBits;
+        this.nBytes = Math.ceil(ringBits / 8);
+        const remBits = ringBits - (this.nBytes - 1) * 8;
+        this.tailMask = remBits === 8 ? 0xff : (0xff << (8 - remBits)) & 0xff;
+    }
+    H(bytes) {
+        const digest = sha256(bytes);
+        if (this.nBytes === digest.length && this.tailMask === 0xff) {
+            return digest;
+        }
+        const coord = digest.slice(0, this.nBytes);
+        coord[this.nBytes - 1] = coord[this.nBytes - 1] & this.tailMask;
+        return coord;
+    }
+}
+/** Convenience factory mirroring the db-p2p adapter construction style. */
+export function createRingHash(ringBits = RING_BITS) {
+    return new RingHash(ringBits);
+}
+//# sourceMappingURL=ring-hash.js.map

package/dist/src/cohort-topic/ring-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-hash.js","sourceRoot":"","sources":["../../../src/cohort-topic/ring-hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAG/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAE7B;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAQ;IACJ,QAAQ,CAAS;IAChB,MAAM,CAAS;IACf,QAAQ,CAAS;IAElC,YAAY,WAAmB,SAAS;QACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,GAAG,GAAG,EAAE,CAAC;YACpE,MAAM,IAAI,UAAU,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;QACtC,MAAM,OAAO,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACvE,CAAC;IAED,CAAC,CAAC,KAAiB;QAClB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7D,OAAO,MAAM,CAAC;QACf,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QACjE,OAAO,KAAK,CAAC;IACd,CAAC;CACD;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,WAAmB,SAAS;IAC1D,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,157 @@
+/**
+ * Cohort-topic substrate — participant-facing service composition.
+ *
+ * This is the substrate's public contract to applications (`docs/cohort-topic.md` §Application
+ * policies): given a `topicId` and a `tier`, reliably find a willing primary (or fail with a clear
+ * back-off), keep a registration alive within its TTL, and verify cohort identity/membership. It is
+ * the participant half of the substrate; the cohort half is {@link import("./member-engine.js").CohortMemberEngine}.
+ *
+ * The service is FRET-free: it drives the {@link ITopicRouter} (walk / register / direct-dial) and the
+ * other db-core ports by injection. db-p2p binds those ports to FRET + libp2p and constructs the
+ * service on the same node it runs the member engine on, so a node is simultaneously a participant and
+ * a cohort member (`docs/cohort-topic.md` §FRET integration — all four protocols on one node).
+ *
+ * Composition wired here: {@link WalkEngine} (lookup / register), the `d_max` computer + tier
+ * addressing, the participant-side {@link RenewalParticipant} (the `ttl/3` ping with crash-failover),
+ * and the application integration hooks ({@link CohortGossipBus}, {@link MembershipVerifier}). The
+ * cohort-side modules (willingness, promotion, traffic, store, membership publisher, anti-DoS) are
+ * assembled by the member engine the FRET host wires into the `RouteAndMaybeAct` activity callback.
+ */
+import type { ISizeEstimator, ITopicRouter, IRingHash } from "./ports.js";
+import { type RenewalParticipant, type UnsignedRenew } from "./registration/renewal.js";
+import type { CohortGossipBus } from "./gossip/bus.js";
+import type { MembershipVerifier } from "./membership/verifier.js";
+import type { Tier } from "./tiers.js";
+import type { RegisterV1, TopicTrafficV1 } from "./wire/types.js";
+import type { CollectionChangeEvent, CommitCert } from "../transactor/change-notifier.js";
+/** A resolved cohort for a topic/tier — the return of {@link CohortTopicService.lookup}. */
+export interface CohortHint {
+    readonly topicId: Uint8Array;
+    readonly tier: Tier;
+    /** Serving cohort member. */
+    readonly primary: Uint8Array;
+    /** Warm-failover cohort members (1..2). */
+    readonly backups: Uint8Array[];
+    readonly cohortEpoch: Uint8Array;
+    /** Full cohort member set, for client-side caching. */
+    readonly cohortMembers: Uint8Array[];
+    /** Coarse traffic barometer, when the cohort attached one. */
+    readonly topicTraffic?: TopicTrafficV1;
+}
+/** A live registration: a {@link CohortHint} plus the participant-side renewal handle behind it. */
+export interface RegistrationHandle extends CohortHint {
+    /** Internal renewal driver (the `ttl/3` ping loop). Opaque to applications. */
+    readonly renewal: RenewalParticipant;
+}
+/**
+ * The substrate's **origination hook**: a commit that lands on a node which is a cohort member for the
+ * collection's reactivity topic is delivered here by the local change-notifier bridge
+ * (`local-change-notifier-bridge`), carrying the raw {@link CollectionChangeEvent} and the
+ * pass-through {@link CommitCert} (extracted from cluster consensus, forwarded UNCHANGED). Reactivity
+ * (and later matchmaking) set this hook to fan the event out — reusing `commitCert.thresholdSig`
+ * directly, never re-signing. The bridge swallows + logs any throw so origination can never break the
+ * commit.
+ */
+export type LocalChangeHook = (event: CollectionChangeEvent, commitCert: CommitCert) => void;
+/** Thrown when the substrate cannot place a registration right now; carries the back-off delay. */
+export declare class CohortBackoffError extends Error {
+    readonly afterMs: number;
+    constructor(afterMs: number);
+}
+/** A registration request (`docs/cohort-topic.md` §Application policies). */
+export interface RegisterRequest {
+    readonly topicId: Uint8Array;
+    readonly tier: Tier;
+    /** Opaque application slot (reactivity / matchmaking define the contents). */
+    readonly appPayload?: Uint8Array;
+    /** Registration TTL (ms); defaults to the tier default. */
+    readonly ttl?: number;
+    /** Mark this a cold-root bootstrap request. */
+    readonly bootstrap?: boolean;
+}
+/** The substrate's participant-facing contract. */
+export interface CohortTopicService {
+    /** Walk → register for `topicId` at `tier`; resolves a live {@link RegistrationHandle} or throws {@link CohortBackoffError}. */
+    register(req: RegisterRequest): Promise<RegistrationHandle>;
+    /** Run one `ttl/3` renewal cycle for `handle` (handles `primary_moved` + crash-failover). */
+    renew(handle: RegistrationHandle): Promise<void>;
+    /** Resolve the cohort for `topicId` at `tier` without keeping a live registration. */
+    lookup(topicId: Uint8Array, tier: Tier): Promise<CohortHint>;
+    /** Stop renewing `handle` and send a best-effort signed withdraw tombstone so the cohort frees the
+     * record immediately (TTL expiry remains the fallback if the primary is unreachable). */
+    withdraw(handle: RegistrationHandle): Promise<void>;
+    /** Origination hook the change-notifier bridge invokes per local member commit; see {@link LocalChangeHook}. */
+    onLocalCommit?: LocalChangeHook;
+    /** Cohort gossip bus — applications fold app state into the existing gossip. */
+    cohortGossip(): CohortGossipBus;
+    /** Membership verifier — applications verify threshold-signed app messages. */
+    verifier(): MembershipVerifier;
+}
+/**
+ * Signs the participant's outbound `RegisterV1` / `RenewV1` bodies (db-p2p supplies the peer key).
+ *
+ * Async because the underlying libp2p `PrivateKey.sign` is async; both call sites already `await`
+ * (`messageFactory.build` and the renewal `sign` hook). The signature is over the canonical body
+ * image ({@link import("./wire/payloads.js").registerSigningPayload} /
+ * {@link import("./wire/payloads.js").renewSigningPayload}) so a cohort member can recompute and
+ * verify it against the participant's peer key.
+ */
+export interface ParticipantSigner {
+    /** Sign a `RegisterV1` (minus its signature); resolves the base64url signature. */
+    signRegister(body: Omit<RegisterV1, "signature">): Promise<string>;
+    /** Sign a `RenewV1` (minus its signature); resolves the base64url signature. */
+    signRenew(body: UnsignedRenew): Promise<string>;
+}
+/** Per-service tunables (cohort size, threshold, fan-out, TTL); all optional. */
+export interface CohortServiceConfig {
+    /** Fan-out per tier `F`. Default {@link DEFAULT_FANOUT}. */
+    readonly fanout?: number;
+    /** Requested cohort size `wantK`. Default 16. */
+    readonly wantK?: number;
+    /** Threshold signers `minSigs = k − x`. Default 14. */
+    readonly minSigs?: number;
+    /** Default registration TTL (ms). Default {@link DEFAULT_TTL_MS}. */
+    readonly ttl?: number;
+    /** Frame ceiling for encode/decode. Defaults to the codec default. */
+    readonly maxMessageBytes?: number;
+}
+export interface CohortTopicServiceDeps {
+    /** This participant's peer id (the `P` in `coord_d(P, topicId)`). */
+    readonly self: Uint8Array;
+    /** Hash + ring math (db-core's own SHA-256). */
+    readonly hash: IRingHash;
+    /** FRET-backed router (walk / register / direct-dial). */
+    readonly router: ITopicRouter;
+    /** FRET-backed network-size estimator feeding `d_max`. */
+    readonly sizeEstimator: ISizeEstimator;
+    /** Participant body signer. */
+    readonly signer: ParticipantSigner;
+    /** Cohort gossip bus (the host constructs it for this node's cohort). */
+    readonly gossipBus: CohortGossipBus;
+    /** Participant-side membership verifier. */
+    readonly verifier: MembershipVerifier;
+    /** Monotonic-ish wall clock (unix ms); injectable for tests. Default `Date.now`. */
+    readonly clock?: () => number;
+    /**
+     * Optional cold-start bootstrap-evidence builder (db-p2p supplies it). Invoked **only** on the
+     * bootstrap re-issue (when the walk sets `bootstrap: true`), with the register's own canonical
+     * fields — the same `(topicId, tier, participantCoord, timestamp)` tuple a verifier binds via
+     * `bootstrapBoundImage`. It returns the **raw** envelope JSON bytes — `utf8(JSON.stringify(env))`,
+     * NOT the already-base64url string from `serializeBootstrapEvidenceEnvelope` — or `undefined` to
+     * attach none; the service base64url-encodes those bytes into `RegisterV1.bootstrapEvidence`
+     * **before** the body is signed, so the participant signature covers them and a MITM cannot strip or
+     * swap the proof. (Returning the `serialize()` string's bytes would double-encode the field.)
+     * Absent (default) → no evidence is attached, exactly today's behavior. The minting logic (PoW
+     * search, reputation/parent-ref signing) is the db-p2p follow-on.
+     */
+    readonly buildBootstrapEvidence?: (params: {
+        readonly topicId: string;
+        readonly tier: number;
+        readonly participantCoord: string;
+        readonly timestamp: number;
+    }) => Promise<Uint8Array | undefined>;
+    readonly config?: CohortServiceConfig;
+}
+/** Build the participant-facing {@link CohortTopicService} over the injected ports. */
+export declare function createCohortTopicService(deps: CohortTopicServiceDeps): CohortTopicService;
+//# sourceMappingURL=service.d.ts.map

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

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

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

@@ -0,0 +1,237 @@
+/**
+ * Cohort-topic substrate — participant-facing service composition.
+ *
+ * This is the substrate's public contract to applications (`docs/cohort-topic.md` §Application
+ * policies): given a `topicId` and a `tier`, reliably find a willing primary (or fail with a clear
+ * back-off), keep a registration alive within its TTL, and verify cohort identity/membership. It is
+ * the participant half of the substrate; the cohort half is {@link import("./member-engine.js").CohortMemberEngine}.
+ *
+ * The service is FRET-free: it drives the {@link ITopicRouter} (walk / register / direct-dial) and the
+ * other db-core ports by injection. db-p2p binds those ports to FRET + libp2p and constructs the
+ * service on the same node it runs the member engine on, so a node is simultaneously a participant and
+ * a cohort member (`docs/cohort-topic.md` §FRET integration — all four protocols on one node).
+ *
+ * Composition wired here: {@link WalkEngine} (lookup / register), the `d_max` computer + tier
+ * addressing, the participant-side {@link RenewalParticipant} (the `ttl/3` ping with crash-failover),
+ * and the application integration hooks ({@link CohortGossipBus}, {@link MembershipVerifier}). The
+ * cohort-side modules (willingness, promotion, traffic, store, membership publisher, anti-DoS) are
+ * assembled by the member engine the FRET host wires into the `RouteAndMaybeAct` activity callback.
+ */
+import { randomBytes } from "@noble/hashes/utils.js";
+import { createTierAddressing } from "./addressing.js";
+import { makeDMaxComputer } from "./dmax.js";
+import { DEFAULT_FANOUT } from "./addressing.js";
+import { createWalkEngine } from "./walk.js";
+import { createRenewalParticipant } from "./registration/renewal.js";
+import { DEFAULT_TTL_MS } from "./registration/types.js";
+import { recordKey } from "./registration/bytes.js";
+import { bytesToB64url, b64urlToBytes, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
+/** Thrown when the substrate cannot place a registration right now; carries the back-off delay. */
+export class CohortBackoffError extends Error {
+    afterMs;
+    constructor(afterMs) {
+        super(`cohort-topic: no willing primary right now; retry after ${afterMs}ms`);
+        this.afterMs = afterMs;
+        this.name = "CohortBackoffError";
+    }
+}
+class WalkRegisterService {
+    deps;
+    onLocalCommit;
+    addressing;
+    dmax;
+    walk;
+    clock;
+    ttl;
+    maxMessageBytes;
+    /** Live renewal drivers, keyed by `(topicId, participantId)` so renew/withdraw find their handle. */
+    renewals = new Map();
+    participantId;
+    constructor(deps) {
+        this.deps = deps;
+        const cfg = deps.config ?? {};
+        const fanout = cfg.fanout ?? DEFAULT_FANOUT;
+        this.clock = deps.clock ?? (() => Date.now());
+        this.ttl = cfg.ttl ?? DEFAULT_TTL_MS;
+        this.maxMessageBytes = cfg.maxMessageBytes;
+        // The participant identity carried on the wire (`participantCoord` on register, `participantId`
+        // on renew) IS `self` — the dialable peer id db-p2p supplies via its peer-codec. It is the
+        // record key the cohort stores AND the signer id its peer-key signature verifies against, so it
+        // must round-trip back to a peer id rather than being re-hashed here (§Tier addressing names the
+        // routing coord `P = self` directly; slot assignment hashes it internally for uniformity).
+        this.participantId = deps.self;
+        this.addressing = createTierAddressing(deps.hash, fanout);
+        this.dmax = makeDMaxComputer({ estimator: deps.sizeEstimator, F: fanout });
+        this.walk = createWalkEngine({
+            router: deps.router,
+            addressing: this.addressing,
+            dmax: this.dmax,
+            self: deps.self,
+            factory: this.messageFactory(),
+            config: { wantK: cfg.wantK, minSigs: cfg.minSigs, maxMessageBytes: cfg.maxMessageBytes },
+        });
+    }
+    async register(req) {
+        const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload);
+        return this.handleFromOutcome(req, outcome);
+    }
+    async lookup(topicId, tier) {
+        // A read-only probe: it walks to the responsible cohort exactly as a register would and returns the
+        // same cohort snapshot, but admits NOTHING — no soft-state record, no arrival, no promotion trigger,
+        // no topic-budget touch, and never a cold-start instantiation. A topic served nowhere resolves to a
+        // `CohortBackoffError` (the probe never bootstraps a cold root), so a lookup leaves no throwaway
+        // registration behind to TTL-expire (§Application policies; the lookup-as-register interim is gone).
+        const outcome = await this.walk.register(topicId, tier, undefined, { probe: true });
+        if (outcome.kind !== "accepted") {
+            throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
+        }
+        return this.hintFromReply(topicId, tier, outcome.reply);
+    }
+    async renew(handle) {
+        // Withdrawn handles drop out of the live set; renewing one is a no-op so withdraw() actually
+        // stops the local ping loop (rather than the app silently continuing to refresh it).
+        if (!this.renewals.has(recordKey(handle.topicId, this.participantId))) {
+            return;
+        }
+        await handle.renewal.pingLoop();
+        this.syncHandle(handle);
+    }
+    async withdraw(handle) {
+        // Two halves: (1) drop the handle from the live set so further renew() pings no-op (see renew()),
+        // stopping the local ping loop; (2) fire a best-effort signed withdraw tombstone to the current
+        // primary so the cohort frees the record immediately instead of holding it for up to a full TTL.
+        // The delete happens FIRST so a concurrent renew() already no-ops before the tombstone is sent. If
+        // the tombstone send fails (primary unreachable), the cohort soft-state TTL-expires as the
+        // fallback — withdraw never throws on a transport failure. Idempotent: a second withdraw finds
+        // `renewal === undefined` and no-ops.
+        const key = recordKey(handle.topicId, this.participantId);
+        const renewal = this.renewals.get(key);
+        this.renewals.delete(key);
+        await renewal?.withdraw();
+    }
+    cohortGossip() {
+        return this.deps.gossipBus;
+    }
+    verifier() {
+        return this.deps.verifier;
+    }
+    // --- internals ---
+    handleFromOutcome(req, outcome) {
+        if (outcome.kind !== "accepted") {
+            throw new CohortBackoffError(outcome.kind === "retry_later" ? outcome.afterMs : 0);
+        }
+        const hint = this.hintFromReply(req.topicId, req.tier, outcome.reply);
+        const renewal = this.startRenewal(req, hint, outcome.reply);
+        return { ...hint, renewal };
+    }
+    startRenewal(req, hint, reply) {
+        const ttl = req.ttl ?? this.ttl;
+        const initial = {
+            topicId: req.topicId,
+            participantId: this.participantId,
+            tier: req.tier,
+            primary: hint.primary,
+            backups: hint.backups,
+            attachedAt: this.clock(),
+            lastPing: this.clock(),
+            ttl,
+            appState: req.appPayload,
+        };
+        const transport = this.renewalTransport(req);
+        const renewal = createRenewalParticipant(initial, {
+            transport,
+            clock: this.clock,
+            sign: (body) => this.deps.signer.signRenew(body),
+            correlationId: reply.cohortEpoch ?? bytesToB64url(this.participantId),
+            initialCohortEpoch: hint.cohortEpoch,
+        });
+        this.renewals.set(recordKey(req.topicId, this.participantId), renewal);
+        return renewal;
+    }
+    /** Renewal transport: dial the cached primary directly; a full failure re-runs the register walk. */
+    renewalTransport(req) {
+        return {
+            send: async (target, msg) => {
+                const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
+                return decodeRenewReplyV1(raw, this.maxMessageBytes);
+            },
+            relookup: async () => {
+                await this.walk.register(req.topicId, req.tier, req.appPayload);
+            },
+        };
+    }
+    hintFromReply(topicId, tier, reply) {
+        if (reply.primary === undefined || reply.cohortEpoch === undefined) {
+            throw new CohortBackoffError(0);
+        }
+        return {
+            topicId,
+            tier,
+            primary: b64urlToBytes(reply.primary),
+            backups: (reply.backups ?? []).map(b64urlToBytes),
+            cohortEpoch: b64urlToBytes(reply.cohortEpoch),
+            cohortMembers: (reply.cohortMembers ?? []).map(b64urlToBytes),
+            topicTraffic: reply.topicTraffic,
+        };
+    }
+    syncHandle(handle) {
+        const rec = handle.renewal.record;
+        handle.primary = rec.primary;
+        handle.backups = [...rec.backups];
+        const epoch = handle.renewal.cohortEpochHint;
+        if (epoch !== undefined) {
+            handle.cohortEpoch = epoch;
+        }
+    }
+    /** The per-probe `RegisterV1` builder: stamps participant coord/ttl/correlation and signs. */
+    messageFactory() {
+        const participantCoord = bytesToB64url(this.participantId);
+        return {
+            build: async (params) => {
+                const body = {
+                    v: 1,
+                    topicId: bytesToB64url(params.topicId),
+                    tier: params.tier,
+                    treeTier: params.treeTier,
+                    participantCoord,
+                    ttl: this.ttl,
+                    timestamp: this.clock(),
+                    correlationId: this.freshCorrelationId(),
+                };
+                if (params.probe) {
+                    // A read-only lookup probe. Mutually exclusive with bootstrap (the walk never sets
+                    // `bootstrap` on a probe), so the cold-start-evidence branch below cannot run for a probe.
+                    body.probe = true;
+                }
+                if (params.bootstrap) {
+                    body.bootstrap = true;
+                    // Attach cold-start evidence BEFORE signing (so the signature covers it). Bind the
+                    // builder to the body's own canonical fields — the exact tuple a verifier reconstructs.
+                    const evidence = await this.deps.buildBootstrapEvidence?.({
+                        topicId: body.topicId,
+                        tier: body.tier,
+                        participantCoord: body.participantCoord,
+                        timestamp: body.timestamp,
+                    });
+                    if (evidence !== undefined && evidence.length > 0) {
+                        body.bootstrapEvidence = bytesToB64url(evidence);
+                    }
+                }
+                if (params.appPayload !== undefined) {
+                    body.appPayload = bytesToB64url(params.appPayload);
+                }
+                return { ...body, signature: await this.deps.signer.signRegister(body) };
+            },
+        };
+    }
+    /** 16 fresh CSPRNG bytes, base64url. A correlation id must be unique per probe — the replay guard
+     * keys on it — so it cannot be derived from the clock (two probes in the same ms would collide). */
+    freshCorrelationId() {
+        return bytesToB64url(randomBytes(16));
+    }
+}
+/** Build the participant-facing {@link CohortTopicService} over the injected ports. */
+export function createCohortTopicService(deps) {
+    return new WalkRegisterService(deps);
+}
+//# sourceMappingURL=service.js.map

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

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

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

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

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

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

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

@@ -0,0 +1,3 @@
+export * from "./payloads.js";
+export * from "./threshold.js";
+//# sourceMappingURL=index.js.map

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

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

package/dist/src/cohort-topic/sig/payloads.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Cohort-topic substrate — canonical threshold-signature payloads.
+ *
+ * A threshold signature is only verifiable if signer and verifier agree on the exact bytes signed.
+ * These builders produce that deterministic byte image for each threshold-signed message
+ * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`), covering exactly the semantic
+ * fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
+ *
+ * Determinism comes from encoding an explicitly-ordered JSON array (array order is stable, unlike
+ * object key order) as UTF-8. The publisher signs this image; the verifier recomputes and checks it.
+ */
+import type { DemotionNoticeV1, MembershipCertV1, PromotionNoticeV1 } from "../wire/types.js";
+/** Fields of a `MembershipCertV1` covered by its threshold signature (doc: cohortCoord, cohortEpoch, members, stabilizedAt). */
+export type MembershipCertSignable = Pick<MembershipCertV1, "cohortCoord" | "cohortEpoch" | "members" | "stabilizedAt">;
+/** Canonical signed byte image of a membership certificate. */
+export declare function membershipCertSigningPayload(cert: MembershipCertSignable): Uint8Array;
+/** Fields of a `PromotionNoticeV1` covered by its threshold signature. */
+export type PromotionSignable = Pick<PromotionNoticeV1, "topicId" | "fromTier" | "toTier" | "effectiveAt" | "cohortEpoch">;
+/** Canonical signed byte image of a promotion notice. */
+export declare function promotionNoticeSigningPayload(n: PromotionSignable): Uint8Array;
+/** Fields of a `DemotionNoticeV1` covered by its threshold signature. */
+export type DemotionSignable = Pick<DemotionNoticeV1, "topicId" | "tier" | "parentCohortCoord" | "effectiveAt" | "cohortEpoch">;
+/** Canonical signed byte image of a demotion notice. */
+export declare function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array;
+//# sourceMappingURL=payloads.d.ts.map

package/dist/src/cohort-topic/sig/payloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloads.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/sig/payloads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAI9F,gIAAgI;AAChI,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC,CAAC;AAExH,+DAA+D;AAC/D,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,sBAAsB,GAAG,UAAU,CAErF;AAED,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC;AAE3H,yDAAyD;AACzD,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAE9E;AAED,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,MAAM,GAAG,mBAAmB,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC;AAEhI,wDAAwD;AACxD,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAE5E"}

package/dist/src/cohort-topic/sig/payloads.js

@@ -0,0 +1,25 @@
+/**
+ * Cohort-topic substrate — canonical threshold-signature payloads.
+ *
+ * A threshold signature is only verifiable if signer and verifier agree on the exact bytes signed.
+ * These builders produce that deterministic byte image for each threshold-signed message
+ * (`MembershipCertV1`, `PromotionNoticeV1`, `DemotionNoticeV1`), covering exactly the semantic
+ * fields per `docs/cohort-topic.md` §Wire formats — never the `thresholdSig`/`signers` envelope.
+ *
+ * Determinism comes from encoding an explicitly-ordered JSON array (array order is stable, unlike
+ * object key order) as UTF-8. The publisher signs this image; the verifier recomputes and checks it.
+ */
+const utf8 = new TextEncoder();
+/** Canonical signed byte image of a membership certificate. */
+export function membershipCertSigningPayload(cert) {
+    return utf8.encode(JSON.stringify(["MembershipCertV1", cert.cohortCoord, cert.cohortEpoch, cert.members, cert.stabilizedAt]));
+}
+/** Canonical signed byte image of a promotion notice. */
+export function promotionNoticeSigningPayload(n) {
+    return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortEpoch]));
+}
+/** Canonical signed byte image of a demotion notice. */
+export function demotionNoticeSigningPayload(n) {
+    return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortEpoch]));
+}
+//# sourceMappingURL=payloads.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"payloads.js","sourceRoot":"","sources":["../../../../src/cohort-topic/sig/payloads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAK/B,+DAA+D;AAC/D,MAAM,UAAU,4BAA4B,CAAC,IAA4B;IACxE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,kBAAkB,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAC/H,CAAC;AAKD,yDAAyD;AACzD,MAAM,UAAU,6BAA6B,CAAC,CAAoB;IACjE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAC1H,CAAC;AAKD,wDAAwD;AACxD,MAAM,UAAU,4BAA4B,CAAC,CAAmB;IAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAChI,CAAC"}

package/dist/src/cohort-topic/sig/threshold.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cohort-topic substrate — `k − x` threshold signing and verification.
+ *
+ * Per `docs/cohort-topic.md` §FRET integration (L659) and §Membership snapshots: the cohort
+ * threshold-signs `PromotionNoticeV1` / `DemotionNoticeV1` / `MembershipCertV1` with `minSigs`
+ * (= `k − x`, default 14) signers. This module is db-core logic over the {@link ICohortThresholdCrypto}
+ * port; db-p2p binds the port to FRET's `minSigs` cohort-signature assembly — db-core never imports
+ * FRET, and the underlying scheme is reused unchanged.
+ *
+ * {@link CohortSigner.verifyThreshold} layers the membership check db-core owns on top of the raw
+ * crypto: the `signers` must be a distinct `≥ minSigs` subset of the certificate's `members`, *and*
+ * the signature must verify against the payload. Either failure → not verified.
+ */
+import type { ICohortThresholdCrypto } from "../ports.js";
+import type { MembershipCertV1 } from "../wire/types.js";
+/** Default cohort-signature threshold, `k − x` (see §Configuration). */
+export declare const DEFAULT_MIN_SIGS = 14;
+/** Threshold signer/verifier over the injected cohort crypto. Peer ids are raw bytes. */
+export interface CohortSigner {
+    /** Assemble a cohort threshold signature over `payload` (collects `minSigs` signers). */
+    thresholdSign(payload: Uint8Array): Promise<{
+        thresholdSig: Uint8Array;
+        signers: Uint8Array[];
+    }>;
+    /**
+     * Verify a threshold-signed message: `signers` are a distinct `≥ minSigs` subset of
+     * `cert.members` and `sig` is a valid cohort signature over `payload`.
+     */
+    verifyThreshold(payload: Uint8Array, sig: Uint8Array, signers: readonly Uint8Array[], cert: MembershipCertV1, minSigs: number): boolean;
+}
+/** Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. */
+export declare function createCohortSigner(crypto: ICohortThresholdCrypto, minSigs?: number): CohortSigner;
+//# sourceMappingURL=threshold.d.ts.map

package/dist/src/cohort-topic/sig/threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/sig/threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC5B,yFAAyF;IACzF,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IACjG;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACxI;AA8BD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,sBAAsB,EAAE,OAAO,GAAE,MAAyB,GAAG,YAAY,CAEnH"}

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

@@ -0,0 +1,51 @@
+/**
+ * Cohort-topic substrate — `k − x` threshold signing and verification.
+ *
+ * Per `docs/cohort-topic.md` §FRET integration (L659) and §Membership snapshots: the cohort
+ * threshold-signs `PromotionNoticeV1` / `DemotionNoticeV1` / `MembershipCertV1` with `minSigs`
+ * (= `k − x`, default 14) signers. This module is db-core logic over the {@link ICohortThresholdCrypto}
+ * port; db-p2p binds the port to FRET's `minSigs` cohort-signature assembly — db-core never imports
+ * FRET, and the underlying scheme is reused unchanged.
+ *
+ * {@link CohortSigner.verifyThreshold} layers the membership check db-core owns on top of the raw
+ * crypto: the `signers` must be a distinct `≥ minSigs` subset of the certificate's `members`, *and*
+ * the signature must verify against the payload. Either failure → not verified.
+ */
+import { bytesToB64url } from "../wire/codec.js";
+/** Default cohort-signature threshold, `k − x` (see §Configuration). */
+export const DEFAULT_MIN_SIGS = 14;
+class CryptoCohortSigner {
+    crypto;
+    minSigs;
+    constructor(crypto, minSigs) {
+        this.crypto = crypto;
+        this.minSigs = minSigs;
+    }
+    thresholdSign(payload) {
+        return this.crypto.assemble(payload, this.minSigs);
+    }
+    verifyThreshold(payload, sig, signers, cert, minSigs) {
+        if (signers.length < minSigs) {
+            return false;
+        }
+        // Members are base64url on the wire; compare signers in that same canonical form.
+        const memberSet = new Set(cert.members);
+        const seen = new Set();
+        for (const signer of signers) {
+            const key = bytesToB64url(signer);
+            if (seen.has(key)) {
+                return false; // a duplicated signer cannot pad the count toward minSigs
+            }
+            seen.add(key);
+            if (!memberSet.has(key)) {
+                return false; // signer is not a member of the attested cohort
+            }
+        }
+        return this.crypto.verify(payload, sig, signers);
+    }
+}
+/** Build a {@link CohortSigner} over the FRET-backed (in db-p2p) threshold crypto. */
+export function createCohortSigner(crypto, minSigs = DEFAULT_MIN_SIGS) {
+    return new CryptoCohortSigner(crypto, minSigs);
+}
+//# sourceMappingURL=threshold.js.map