@optimystic/db-core 0.13.4 → 0.14.0

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

@@ -0,0 +1,81 @@
+/**
+ * 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";
+import type { RegistrationRecord, RegistrationStore } from "./types.js";
+
+class InMemoryRegistrationStore implements RegistrationStore {
+	/** topicKey → (participantKey → record). Inner maps are pruned when they empty. */
+	private readonly byTopic = new Map<string, Map<string, RegistrationRecord>>();
+
+	put(rec: RegistrationRecord): void {
+		const tk = bytesKey(rec.topicId);
+		let inner = this.byTopic.get(tk);
+		if (inner === undefined) {
+			inner = new Map<string, RegistrationRecord>();
+			this.byTopic.set(tk, inner);
+		}
+		inner.set(bytesKey(rec.participantId), rec);
+	}
+
+	getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined {
+		return this.byTopic.get(bytesKey(topicId))?.get(bytesKey(participantId));
+	}
+
+	listByTopic(topicId: Uint8Array): readonly RegistrationRecord[] {
+		const inner = this.byTopic.get(bytesKey(topicId));
+		return inner === undefined ? [] : [...inner.values()];
+	}
+
+	listAll(): readonly RegistrationRecord[] {
+		const out: RegistrationRecord[] = [];
+		for (const inner of this.byTopic.values()) {
+			for (const rec of inner.values()) {
+				out.push(rec);
+			}
+		}
+		return out;
+	}
+
+	delete(topicId: Uint8Array, participantId: Uint8Array): void {
+		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: Uint8Array): number {
+		return this.byTopic.get(bytesKey(topicId))?.size ?? 0;
+	}
+
+	evictStale(now: number): readonly RegistrationRecord[] {
+		const evicted: RegistrationRecord[] = [];
+		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(): RegistrationStore {
+	return new InMemoryRegistrationStore();
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 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 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: number): number {
+	return Math.floor(ttl / 3);
+}

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

@@ -0,0 +1,50 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+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 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 implements IRingHash {
+	public readonly ringBits: number;
+	private readonly nBytes: number;
+	private readonly tailMask: number;
+
+	constructor(ringBits: number = 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: Uint8Array): RingCoord {
+		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: number = RING_BITS): IRingHash {
+	return new RingHash(ringBits);
+}

package/src/cohort-topic/service.ts

@@ -0,0 +1,390 @@
+/**
+ * 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, type TierAddressing } from "./addressing.js";
+import { makeDMaxComputer, type DMaxComputer } from "./dmax.js";
+import { DEFAULT_FANOUT } from "./addressing.js";
+import type { ISizeEstimator, ITopicRouter, IRingHash, RingCoord } from "./ports.js";
+import { createWalkEngine, type RegisterMessageFactory, type WalkEngine, type WalkOutcome } from "./walk.js";
+import { createRenewalParticipant, type RenewalParticipant, type RenewalParticipantTransport, type UnsignedRenew } from "./registration/renewal.js";
+import type { RegistrationRecord } from "./registration/types.js";
+import { DEFAULT_TTL_MS } from "./registration/types.js";
+import { recordKey } from "./registration/bytes.js";
+import type { CohortGossipBus } from "./gossip/bus.js";
+import type { MembershipVerifier } from "./membership/verifier.js";
+import type { Tier } from "./tiers.js";
+import { bytesToB64url, b64urlToBytes, decodeRenewReplyV1, encodeCohortMessage } from "./wire/codec.js";
+import type { RegisterReplyV1, RegisterV1, RenewReplyV1, 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 class CohortBackoffError extends Error {
+	constructor(readonly afterMs: number) {
+		super(`cohort-topic: no willing primary right now; retry after ${afterMs}ms`);
+		this.name = "CohortBackoffError";
+	}
+}
+
+/** 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;
+}
+
+class WalkRegisterService implements CohortTopicService {
+	public onLocalCommit?: LocalChangeHook;
+
+	private readonly addressing: TierAddressing;
+	private readonly dmax: DMaxComputer;
+	private readonly walk: WalkEngine;
+	private readonly clock: () => number;
+	private readonly ttl: number;
+	private readonly maxMessageBytes?: number;
+	/** Live renewal drivers, keyed by `(topicId, participantId)` so renew/withdraw find their handle. */
+	private readonly renewals = new Map<string, RenewalParticipant>();
+	private readonly participantId: Uint8Array;
+
+	constructor(private readonly deps: CohortTopicServiceDeps) {
+		const cfg = deps.config ?? {};
+		const fanout = cfg.fanout ?? DEFAULT_FANOUT;
+		this.clock = deps.clock ?? ((): number => 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: RegisterRequest): Promise<RegistrationHandle> {
+		const outcome = await this.walk.register(req.topicId, req.tier, req.appPayload);
+		return this.handleFromOutcome(req, outcome);
+	}
+
+	async lookup(topicId: Uint8Array, tier: Tier): Promise<CohortHint> {
+		// 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: RegistrationHandle): Promise<void> {
+		// 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: RegistrationHandle): Promise<void> {
+		// 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(): CohortGossipBus {
+		return this.deps.gossipBus;
+	}
+
+	verifier(): MembershipVerifier {
+		return this.deps.verifier;
+	}
+
+	// --- internals ---
+
+	private handleFromOutcome(req: RegisterRequest, outcome: WalkOutcome): RegistrationHandle {
+		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 };
+	}
+
+	private startRenewal(req: RegisterRequest, hint: CohortHint, reply: RegisterReplyV1): RenewalParticipant {
+		const ttl = req.ttl ?? this.ttl;
+		const initial: RegistrationRecord = {
+			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: UnsignedRenew): Promise<string> => 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. */
+	private renewalTransport(req: RegisterRequest): RenewalParticipantTransport {
+		return {
+			send: async (target: Uint8Array, msg): Promise<RenewReplyV1> => {
+				const raw = await this.deps.router.dialMember({ id: target }, encodeCohortMessage(msg, this.maxMessageBytes));
+				return decodeRenewReplyV1(raw, this.maxMessageBytes);
+			},
+			relookup: async (): Promise<void> => {
+				await this.walk.register(req.topicId, req.tier, req.appPayload);
+			},
+		};
+	}
+
+	private hintFromReply(topicId: Uint8Array, tier: Tier, reply: RegisterReplyV1): CohortHint {
+		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,
+		};
+	}
+
+	private syncHandle(handle: RegistrationHandle): void {
+		const rec = handle.renewal.record;
+		(handle as { primary: Uint8Array }).primary = rec.primary;
+		(handle as { backups: Uint8Array[] }).backups = [...rec.backups];
+		const epoch = handle.renewal.cohortEpochHint;
+		if (epoch !== undefined) {
+			(handle as { cohortEpoch: Uint8Array }).cohortEpoch = epoch;
+		}
+	}
+
+	/** The per-probe `RegisterV1` builder: stamps participant coord/ttl/correlation and signs. */
+	private messageFactory(): RegisterMessageFactory {
+		const participantCoord = bytesToB64url(this.participantId);
+		return {
+			build: async (params): Promise<RegisterV1> => {
+				const body: Omit<RegisterV1, "signature"> = {
+					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). */
+	private freshCorrelationId(): string {
+		return bytesToB64url(randomBytes(16));
+	}
+}
+
+/** Build the participant-facing {@link CohortTopicService} over the injected ports. */
+export function createCohortTopicService(deps: CohortTopicServiceDeps): CohortTopicService {
+	return new WalkRegisterService(deps);
+}

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

@@ -0,0 +1,2 @@
+export * from "./payloads.js";
+export * from "./threshold.js";

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

@@ -0,0 +1,39 @@
+/**
+ * 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";
+
+const utf8 = new TextEncoder();
+
+/** 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 function membershipCertSigningPayload(cert: MembershipCertSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["MembershipCertV1", cert.cohortCoord, cert.cohortEpoch, cert.members, cert.stabilizedAt]));
+}
+
+/** 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 function promotionNoticeSigningPayload(n: PromotionSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["PromotionNoticeV1", n.topicId, n.fromTier, n.toTier, n.effectiveAt, n.cohortEpoch]));
+}
+
+/** 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 function demotionNoticeSigningPayload(n: DemotionSignable): Uint8Array {
+	return utf8.encode(JSON.stringify(["DemotionNoticeV1", n.topicId, n.tier, n.parentCohortCoord, n.effectiveAt, n.cohortEpoch]));
+}