@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/cohort-topic/bootstrap-evidence-builder.ts

@@ -0,0 +1,122 @@
+/**
+ * Cohort-topic substrate — participant-side bootstrap-evidence builder (db-p2p side of the `buildBootstrapEvidence` seam).
+ *
+ * Implements the db-core `CohortTopicServiceDeps.buildBootstrapEvidence` seam for the node's participant
+ * role: on a cold-start `bootstrap: true` re-issue the service calls this with the register's own
+ * canonical `(topicId, tier, participantCoord, timestamp)` tuple (base64url wire strings) and attaches the
+ * returned bytes — **before** signing — into `RegisterV1.bootstrapEvidence`.
+ *
+ * - **Tier ≤ maxNoPowTier (T0/T1):** proof-of-work is not the expected evidence. With an `endorse`
+ *   capability (a key-ful node) we mint a *self-vouch reputation endorsement* over the bound image so a
+ *   configured cohort's referee verifier admits it; without one we return `undefined` (parent-reference
+ *   origination is the follow-on `cohort-topic-bootstrap-parent-reference`). A T0/T1 bootstrap with no
+ *   evidence is denied by a configured cohort until that lands — but the single-tier-0 milestone's
+ *   cohort-side tests construct evidence directly, so this does not block them.
+ * - **Tier ≥ maxNoPowTier+1 (T2/T3):** mint a proof-of-work — loop nonces until
+ *   `meetsDifficulty(hash.H(powPreimage(reg, nonce)), bits)`. Bound work ≈ `2^bits` hashes (default 20 ≈
+ *   ~1 M, sub-second). The loop is capped ({@link DEFAULT_POW_MAX_ITERATIONS}); on cap-exceeded it returns
+ *   `undefined` so the register proceeds without evidence rather than ever hanging the register path.
+ *
+ * Returns the **raw** envelope JSON bytes (`utf8(JSON.stringify(env))`), NOT the already-base64url string
+ * from `serializeBootstrapEvidenceEnvelope` — the service base64url-encodes them itself (returning the
+ * serialized string's bytes would double-encode the field). We obtain the raw bytes by decoding the
+ * canonical serializer output once, so the byte layout matches exactly what a verifier reconstructs.
+ */
+
+import {
+	serializeBootstrapEvidenceEnvelope,
+	bootstrapBoundImage,
+	powPreimage,
+	meetsDifficulty,
+	DEFAULT_POW_DIFFICULTY_BITS,
+	DEFAULT_MAX_NO_POW_TIER,
+	bytesToB64url,
+	b64urlToBytes,
+	type IRingHash,
+	type BootstrapBoundFields,
+	type BootstrapEvidenceEnvelopeV1,
+	type ReputationEvidenceV1,
+} from "@optimystic/db-core";
+import { randomBytes } from "@libp2p/crypto";
+
+/**
+ * Defensive cap on the PoW nonce search (~16.7 M hashes). Comfortably above the ~`2^bits` expected for
+ * the default 20-bit difficulty (~1 M), so a real miner solves long before the cap; hitting it (a
+ * mis-set, very-high `bits`) returns `undefined` rather than hanging the register path.
+ */
+export const DEFAULT_POW_MAX_ITERATIONS = 1 << 24;
+
+/** The bound tuple the service hands the builder — the same shape a verifier binds via {@link bootstrapBoundImage}. */
+export type BootstrapEvidenceBuildParams = BootstrapBoundFields;
+
+/** Inputs to {@link createBootstrapEvidenceBuilder}. */
+export interface BootstrapEvidenceBuilderDeps {
+	/** The node's ring hash (SHA-256) — the same `H` the PoW verifier checks against. */
+	readonly hash: IRingHash;
+	/** Difficulty bits to mint at. Default {@link DEFAULT_POW_DIFFICULTY_BITS}. `0` solves on the first nonce (test). */
+	readonly bits?: number;
+	/** Highest tier exempt from PoW (T0/T1 → 1). Default {@link DEFAULT_MAX_NO_POW_TIER}. */
+	readonly maxNoPowTier?: number;
+	/** Nonce-search cap. Default {@link DEFAULT_POW_MAX_ITERATIONS}. */
+	readonly maxIterations?: number;
+	/**
+	 * Optional self-vouch endorsement capability for a key-ful node: signs the bound image with the node's
+	 * peer key and returns the referee (= self) + signature. Supplied → T0/T1 mints a reputation
+	 * endorsement (the interim T0/T1 path until parent-reference origination lands); absent → T0/T1 carries
+	 * no evidence.
+	 */
+	readonly endorse?: (boundImage: Uint8Array) => Promise<ReputationEvidenceV1>;
+}
+
+/**
+ * Build the {@link import("@optimystic/db-core").CohortTopicServiceDeps.buildBootstrapEvidence} seam:
+ * a `(params) => Promise<Uint8Array | undefined>` that mints the cold-start evidence for the node's own
+ * register. PoW for T2/T3; a self-vouch reputation endorsement (when `endorse` is supplied) or nothing
+ * for T0/T1. Never throws and never hangs (the nonce loop is capped).
+ */
+export function createBootstrapEvidenceBuilder(
+	deps: BootstrapEvidenceBuilderDeps,
+): (params: BootstrapEvidenceBuildParams) => Promise<Uint8Array | undefined> {
+	const bits = deps.bits ?? DEFAULT_POW_DIFFICULTY_BITS;
+	const maxNoPowTier = deps.maxNoPowTier ?? DEFAULT_MAX_NO_POW_TIER;
+	const maxIterations = deps.maxIterations ?? DEFAULT_POW_MAX_ITERATIONS;
+
+	return async (params: BootstrapEvidenceBuildParams): Promise<Uint8Array | undefined> => {
+		const bound: BootstrapBoundFields = {
+			topicId: params.topicId,
+			tier: params.tier,
+			participantCoord: params.participantCoord,
+			timestamp: params.timestamp,
+		};
+
+		if (params.tier <= maxNoPowTier) {
+			// T0/T1: PoW is not the expected evidence. A key-ful node self-vouches; otherwise no evidence
+			// (the parent-reference path is the follow-on ticket — documented deferral).
+			if (deps.endorse === undefined) {
+				return undefined;
+			}
+			const reputation = await deps.endorse(bootstrapBoundImage(bound));
+			return rawEnvelopeBytes({ v: 1, reputation });
+		}
+
+		// T2/T3: mint a proof-of-work — search nonces until the digest meets the difficulty target.
+		for (let i = 0; i < maxIterations; i++) {
+			const nonce = randomBytes(16); // CSPRNG nonce — bound to the register tuple via the preimage
+			if (meetsDifficulty(deps.hash.H(powPreimage(bound, nonce)), bits)) {
+				return rawEnvelopeBytes({ v: 1, pow: { nonce: bytesToB64url(nonce) } });
+			}
+		}
+		// Cap exceeded (mis-set difficulty): attach nothing rather than hang. A configured cohort denies it.
+		return undefined;
+	};
+}
+
+/**
+ * The raw envelope JSON bytes the service expects (`utf8(JSON.stringify(env))`). Reuses the db-core
+ * canonical serializer (fixed field order, deterministic JSON) and decodes its base64url output back to
+ * the underlying bytes — so the layout is byte-identical to what a verifier reconstructs, with zero
+ * duplicated canonicalization here.
+ */
+function rawEnvelopeBytes(env: BootstrapEvidenceEnvelopeV1): Uint8Array {
+	return b64urlToBytes(serializeBootstrapEvidenceEnvelope(env));
+}

package/src/cohort-topic/bootstrap-evidence-verifiers.ts

@@ -0,0 +1,132 @@
+/**
+ * Cohort-topic substrate — real bootstrap-evidence verifiers (db-p2p side of the anti-DoS gate).
+ *
+ * db-core owns the *policy* (which evidence kinds satisfy which tier) and the crypto-free envelope /
+ * bound-image / PoW-preimage helpers (`antidos/bootstrap-evidence-envelope.ts`); it deliberately embeds
+ * no specific PoW or reputation scheme. This module supplies the **self-contained cryptographic checks**
+ * the host injects into `createBootstrapEvidence`, binding the node's `RingHash` (the same SHA-256 the
+ * addressing uses) and the cohort-topic peer-key `verifyPeerSig` — no new crypto dependency.
+ *
+ * Both verifiers are **synchronous** (one hash, or one signature verify + two reputation-map reads) and
+ * **total** — any parse / decode / verify failure on attacker-supplied input yields `false`, never a
+ * throw — because `BootstrapEvidence.verify` runs inside `member-engine.ts`'s `runGuards` on every
+ * register and must do no network I/O (that would itself be a DoS amplifier).
+ */
+
+import {
+	parseBootstrapEvidenceEnvelope,
+	powPreimage,
+	bootstrapBoundImage,
+	meetsDifficulty,
+	DEFAULT_POW_DIFFICULTY_BITS,
+	b64urlToBytes,
+	type IRingHash,
+	type RegisterV1,
+} from "@optimystic/db-core";
+import { DEFAULT_THRESHOLDS } from "../reputation/types.js";
+import { verifyPeerSig } from "./peer-sig.js";
+import { bytesToPeerIdString } from "./peer-codec.js";
+
+/**
+ * The slice of a peer-reputation service the bootstrap-evidence referee verifier consults — a subset of
+ * {@link import("../reputation/types.js").IPeerReputation} that `PeerReputationService` satisfies
+ * directly. "Sufficient reputation" is **stronger than mere non-ban**: the referee must be *both* not
+ * banned *and* below the deprioritize threshold.
+ */
+export interface BootstrapReputationView {
+	/** True when `peerId` (a peer-id string) is banned / excluded from operations. */
+	isBanned(peerId: string): boolean;
+	/** Effective reputation score for `peerId` (0 = a clean, unseen peer). Lower is better. */
+	getScore(peerId: string): number;
+}
+
+/**
+ * The default "sufficient reputation" cutoff: a referee with `score < deprioritize` is reputable enough
+ * to endorse a bootstrap. Mirrors the reputation service's default `deprioritize` threshold (20) so a
+ * default-configured node and the gate agree on "sufficient". Strict `<`, so a referee *at* the
+ * threshold is not sufficient.
+ */
+export const DEFAULT_DEPRIORITIZE_THRESHOLD = DEFAULT_THRESHOLDS.deprioritize;
+
+/** Inputs to {@link createPoWVerifier}. */
+export interface PoWVerifierDeps {
+	/** The node's ring hash (SHA-256) — the same `H` the addressing uses; hashes the PoW preimage. */
+	readonly hash: IRingHash;
+	/** Required leading-zero bits. Default {@link DEFAULT_POW_DIFFICULTY_BITS}. `0` admits any nonce (test). */
+	readonly bits?: number;
+}
+
+/**
+ * A real proof-of-work verifier for the T2/T3 evidence path. Self-contained — no subsystem, one hash.
+ *
+ * ```
+ * env = parseBootstrapEvidenceEnvelope(reg); if (!env?.pow) return false
+ * h = hash.H(powPreimage(reg, b64urlToBytes(env.pow.nonce)))
+ * return meetsDifficulty(h, bits)
+ * ```
+ *
+ * The preimage binds `(topicId, tier, participantCoord, timestamp)` (via {@link bootstrapBoundImage}),
+ * so a PoW minted for one topic / peer / time cannot bootstrap another. Any absent `pow`, malformed
+ * envelope, or non-base64url nonce → `false` (fails closed).
+ */
+export function createPoWVerifier(deps: PoWVerifierDeps): (reg: RegisterV1) => boolean {
+	const bits = deps.bits ?? DEFAULT_POW_DIFFICULTY_BITS;
+	return (reg: RegisterV1): boolean => {
+		try {
+			const env = parseBootstrapEvidenceEnvelope(reg);
+			if (env?.pow === undefined) {
+				return false; // not offered / not a PoW envelope
+			}
+			const nonce = b64urlToBytes(env.pow.nonce);
+			return meetsDifficulty(deps.hash.H(powPreimage(reg, nonce)), bits);
+		} catch {
+			return false; // any decode / hash failure on attacker input → fail closed
+		}
+	};
+}
+
+/** Inputs to {@link createReputationVerifier}. */
+export interface ReputationVerifierDeps {
+	/** Local reputation view the referee is scored against (not banned + below the threshold). */
+	readonly reputation: BootstrapReputationView;
+	/** Strict "sufficient reputation" cutoff. Default {@link DEFAULT_DEPRIORITIZE_THRESHOLD}. */
+	readonly deprioritizeThreshold?: number;
+}
+
+/**
+ * A real reputation-endorsement verifier: a *referee* peer endorses the bootstrap by peer-key-signing
+ * the {@link bootstrapBoundImage}, and the cohort checks the signature **and** that the referee is
+ * sufficiently reputable in the **local** reputation view.
+ *
+ * ```
+ * env = parseBootstrapEvidenceEnvelope(reg); if (!env?.reputation) return false
+ * refereeBytes = b64urlToBytes(env.reputation.referee)
+ * if (!verifyPeerSig(refereeBytes, bootstrapBoundImage(reg), b64urlToBytes(env.reputation.sig))) return false
+ * refereeId = bytesToPeerIdString(refereeBytes)
+ * return !reputation.isBanned(refereeId) && reputation.getScore(refereeId) < deprioritizeThreshold
+ * ```
+ *
+ * The `referee` MAY equal the participant (a reputable participant self-vouches with its own peer key).
+ * An unknown referee scores `0` (a clean, unseen peer) and so is sufficient; a referee exactly *at* the
+ * threshold is not (strict `<`). Bad sig / banned / over-threshold / malformed → `false` (fails closed).
+ */
+export function createReputationVerifier(deps: ReputationVerifierDeps): (reg: RegisterV1) => boolean {
+	const threshold = deps.deprioritizeThreshold ?? DEFAULT_DEPRIORITIZE_THRESHOLD;
+	return (reg: RegisterV1): boolean => {
+		try {
+			const env = parseBootstrapEvidenceEnvelope(reg);
+			if (env?.reputation === undefined) {
+				return false; // not offered / not a reputation envelope
+			}
+			const refereeBytes = b64urlToBytes(env.reputation.referee);
+			const sig = b64urlToBytes(env.reputation.sig);
+			if (!verifyPeerSig(refereeBytes, bootstrapBoundImage(reg), sig)) {
+				return false; // signature does not bind this register's tuple to the referee key
+			}
+			const refereeId = bytesToPeerIdString(refereeBytes);
+			return !deps.reputation.isBanned(refereeId) && deps.reputation.getScore(refereeId) < threshold;
+		} catch {
+			return false; // any decode / verify failure on attacker input → fail closed
+		}
+	};
+}

package/src/cohort-topic/bootstrap-parent-reference.ts

@@ -0,0 +1,159 @@
+/**
+ * Cohort-topic substrate — real signed-parent-reference bootstrap-evidence verifier (db-p2p side).
+ *
+ * The committed-work proxy for the no-proof-of-work path: a `bootstrap: true` register carries a **signed
+ * reference to a parent topic that actually exists**, and the cohort admits it only after confirming the
+ * parent topic exists in locally-available committed / membership state. This is the *only* accepted
+ * evidence for the committed tiers (T0/T1) and the third option for T2/T3 (`PoW || reputation || parent-ref`).
+ *
+ * It replaces the interim reputation stand-in for `verifyParentReference` that
+ * `cohort-topic-bootstrap-evidence-verifiers` left in `host.ts`.
+ *
+ * The verifier is **synchronous** (it runs in `member-engine.ts`'s `runGuards` on every register) and
+ * **total** (any parse / decode / verify failure on attacker input yields `false`, never a throw). The
+ * existence check therefore consults a **synchronous local view** — never a network fetch, which inside an
+ * admission gate would itself be a DoS amplifier.
+ *
+ * Two independent checks, both must pass (`docs/cohort-topic.md` §Anti-DoS bullet 4):
+ *
+ * 1. **Signed reference (anti-replay).** The participant peer-key-signs the {@link parentRefSigningImage}
+ *    — the bound tuple extended with `parentTopicId` — so a reference minted for one
+ *    `(topic, tier, peer, time, parent)` cannot be lifted onto another register. Verified against the
+ *    participant's own peer key, so it stands alone even in key-less mode (where the outer register
+ *    signature is absent).
+ * 2. **Existence.** The referenced parent topic must exist in locally-available committed / membership
+ *    state, via the injectable synchronous {@link BootstrapParentTopicView}.
+ *
+ * A node only admits a parent-ref bootstrap for a parent topic it has *locally cached* a cert/commit for
+ * (fail-closed when unknown). That is acceptable for an admission gate: a participant whose parent the node
+ * does not know retries / uses PoW (T2/T3); a genuinely-new committed (T0/T1) topic is bootstrapped by
+ * nodes that already serve the parent's committed work, which hold its cert. A *richer* check — that the
+ * parent's commit certificate names *this* child topic — is the follow-on
+ * `cohort-topic-parent-ref-tx-log-content`, not this module.
+ */
+
+import {
+	parseBootstrapEvidenceEnvelope,
+	parentRefSigningImage,
+	DEFAULT_MAX_NO_POW_TIER,
+	b64urlToBytes,
+	type RegisterV1,
+	type RingCoord,
+} from "@optimystic/db-core";
+import { verifyPeerSig } from "./peer-sig.js";
+
+/**
+ * A synchronous local view answering "does this node locally know parent topic `parentTopicId` exists?".
+ * Backed (in the host default) by the committed / FRET membership state the node already holds — never a
+ * network lookup (a round-trip inside an admission gate is a DoS amplifier).
+ */
+export interface BootstrapParentTopicView {
+	/**
+	 * True iff the node locally knows parent topic `parentTopicId` exists (a committed cohort serves it /
+	 * its membership cert is cached) for a cohort at `tier`. `tier` is the registering child's tier and
+	 * routes the lookup to the committed (T0/T1) or FRET (T2/T3) backing, mirroring the membership source.
+	 */
+	exists(parentTopicId: Uint8Array, tier: number): boolean;
+}
+
+/** Inputs to {@link createParentReferenceVerifier}. */
+export interface ParentReferenceVerifierDeps {
+	/** The synchronous local existence view the verifier consults (no network I/O). */
+	readonly parentTopicView: BootstrapParentTopicView;
+}
+
+/**
+ * The real, all-tiers `verifyParentReference(reg) => boolean`. Total and synchronous:
+ *
+ * ```
+ * env = parseBootstrapEvidenceEnvelope(reg); if (!env?.parentRef) return false
+ * if (parentRef.parentTopicId === reg.topicId) return false            // a topic cannot vouch for itself
+ * if (!verifyPeerSig(participantCoord, parentRefSigningImage(reg, parentTopicId), parentRef.sig)) return false
+ * return parentTopicView.exists(parentTopicId, reg.tier)
+ * ```
+ *
+ * - Absent `parentRef`, a malformed envelope, a bad/non-base64url signature, or an unknown parent → `false`
+ *   (fails closed → `unwilling_cohort`).
+ * - The self-referential guard rejects `parentTopicId === reg.topicId`: a topic cannot reference itself to
+ *   prove its own existence (a circular bootstrap).
+ */
+export function createParentReferenceVerifier(deps: ParentReferenceVerifierDeps): (reg: RegisterV1) => boolean {
+	const { parentTopicView } = deps;
+	return (reg: RegisterV1): boolean => {
+		try {
+			const env = parseBootstrapEvidenceEnvelope(reg);
+			if (env?.parentRef === undefined) {
+				return false; // not offered / not a parent-reference envelope
+			}
+			const { parentTopicId, sig } = env.parentRef;
+			// A topic cannot vouch for its own existence (self-referential / circular bootstrap).
+			if (parentTopicId === reg.topicId) {
+				return false;
+			}
+			// 1. Signed reference (anti-replay): the participant binds THIS parent to THIS register.
+			const image = parentRefSigningImage(reg, parentTopicId);
+			if (!verifyPeerSig(b64urlToBytes(reg.participantCoord), image, b64urlToBytes(sig))) {
+				return false;
+			}
+			// 2. Existence: the parent topic must exist in locally-available committed / membership state.
+			return parentTopicView.exists(b64urlToBytes(parentTopicId), reg.tier);
+		} catch {
+			return false; // any decode / verify failure on attacker input → fail closed
+		}
+	};
+}
+
+/** A synchronous local "is a cohort cached for this coord?" read — the {@link FretMembershipSource} cache shape. */
+export interface LocalCohortExistence {
+	/** True iff a `MembershipCertV1` is locally cached for `coord`. */
+	has(coord: RingCoord): boolean;
+}
+
+/** Inputs to {@link createDefaultParentTopicView}. */
+export interface DefaultParentTopicViewDeps {
+	/** The FRET membership cache (T2/T3 backing): a cached cert means a cohort genuinely serves the parent. */
+	readonly membershipSource: LocalCohortExistence;
+	/** Tier addressing — supplies `coord0(parentTopicId)`, the parent topic's root cohort coordinate. */
+	readonly addressing: { coord0(topicId: Uint8Array): RingCoord };
+	/**
+	 * Optional committed-state backing for the committed tiers (T0/T1). Reads `coord_0(parentTopicId)`. When
+	 * **omitted the committed tiers fail closed** (return `false`) — a FRET-cached cert (T2/T3 membership)
+	 * must NOT vouch for committed-tier parent existence (committed-tier integrity). A node supplies a real
+	 * committed-by-coord reader (e.g. a future tx-log / commit-cert index) here when one is available.
+	 */
+	readonly committedReader?: (coord: RingCoord) => boolean;
+	/** Highest tier exempt from PoW / served by committed work (T0/T1 → 1). Default {@link DEFAULT_MAX_NO_POW_TIER}. */
+	readonly maxNoPowTier?: number;
+}
+
+/**
+ * The host-default {@link BootstrapParentTopicView}, tier-routed exactly like the membership source
+ * (`docs/cohort-topic.md` §Membership source):
+ *
+ * - **T0/T1 (committed tiers):** consult `committedReader` — the committed-state backing. Absent → `false`
+ *   (fail closed). A FRET-cached cert never satisfies a committed-tier existence check, so committed-tier
+ *   integrity holds: a parent known only as a FRET (T2/T3) cohort cannot back a committed parent reference.
+ * - **T2/T3:** `membershipSource.has(coord_0(parentTopicId))` — a cached `MembershipCertV1` means a cohort
+ *   is genuinely serving the parent topic.
+ *
+ * **Known limitation (interim).** No coord-keyed committed-membership index exists yet (the transaction-log
+ * commit certificate is keyed by action, not by `coord_0`), so a node typically wires no `committedReader`
+ * and T0/T1 parent-ref existence fails closed. T2/T3 parent-ref is fully real today. The dedicated committed
+ * backing is the follow-on `cohort-topic-parent-ref-tx-log-content`.
+ */
+export function createDefaultParentTopicView(deps: DefaultParentTopicViewDeps): BootstrapParentTopicView {
+	const { membershipSource, addressing, committedReader } = deps;
+	const maxNoPowTier = deps.maxNoPowTier ?? DEFAULT_MAX_NO_POW_TIER;
+	return {
+		exists(parentTopicId: Uint8Array, tier: number): boolean {
+			const coord = addressing.coord0(parentTopicId);
+			if (tier <= maxNoPowTier) {
+				// Committed tiers (T0/T1): require a committed backing; fail closed without one. The FRET cache
+				// must not vouch for committed-tier existence (committed-tier integrity).
+				return committedReader !== undefined && committedReader(coord);
+			}
+			// T2/T3: the FRET membership cache reflects a cohort serving the parent topic.
+			return membershipSource.has(coord);
+		},
+	};
+}

package/src/cohort-topic/change-bridge.ts

@@ -0,0 +1,109 @@
+import type { CohortTopicService, CollectionChangeEvent, CollectionChangeListener, CommitCert, IBlockChangeNotifier } from "@optimystic/db-core";
+import { createLogger } from "../logger.js";
+
+const log = createLogger('cohort-change-bridge');
+
+/**
+ * The local commit feed the bridge observes: a {@link IBlockChangeNotifier} (the node's
+ * `StorageRepo`) extended with the catch-all {@link onAnyCollectionChange} the bridge needs to see
+ * EVERY commit — it cannot enumerate collection ids ahead of time to subscribe per-collection, and
+ * origination must fire whether or not anyone subscribed to that collection.
+ */
+export interface ChangeBridgeSource extends IBlockChangeNotifier {
+	onAnyCollectionChange(listener: CollectionChangeListener): () => void;
+}
+
+export interface CohortTopicChangeNotifierDeps {
+	/** The local node's commit feed (its `StorageRepo`). */
+	readonly source: ChangeBridgeSource;
+	/** The cohort-topic substrate whose `onLocalCommit` origination hook receives member commits. */
+	readonly service: CohortTopicService;
+	/**
+	 * True iff this node is a cohort member responsible for this change event's reactivity-topic fan-out.
+	 * Receives the whole {@link CollectionChangeEvent} (not just the collection id) because the reactivity
+	 * topic is tail-anchored — `H(event.tailId ‖ "reactivity")` — so the gate needs `event.tailId` to
+	 * derive the topic's `coord_0` cohort. A tail-less event (a read-driven promotion) is never a member.
+	 */
+	readonly selfIsCohortMember: (event: CollectionChangeEvent) => boolean;
+	/** Resolve the pass-through commit cert for a change event (e.g. the cluster commit-cert store). */
+	readonly extractCommitCert: (event: CollectionChangeEvent) => CommitCert | undefined;
+}
+
+/**
+ * The reactivity/matchmaking **origination point**: bridge the local single-node change-notifier
+ * primitive into the networked cohort-topic substrate.
+ *
+ * On EVERY commit landing on this node (via the catch-all {@link ChangeBridgeSource.onAnyCollectionChange}
+ * feed), if this node is a cohort member for the collection's reactivity topic, the bridge hands the
+ * `CollectionChangeEvent` plus the pass-through {@link CommitCert} to `service.onLocalCommit` —
+ * reactivity reuses the commit cert's threshold signature directly and never re-signs. A commit on a
+ * non-member node (no fan-out responsibility) or one for which no cert is retained (nothing
+ * authoritative to forward) is a no-op. A throwing downstream hook is isolated + logged so
+ * origination can never break the commit (matching the {@link IBlockChangeNotifier} listener contract).
+ *
+ * The returned value IS an {@link IBlockChangeNotifier}: it is what `network-transactor` takes as its
+ * `localChangeNotifier`, so per-collection {@link IBlockChangeNotifier.onCollectionChange} subscribers
+ * (e.g. the Quereus reactive-watch vtab) keep working — those subscriptions delegate straight to
+ * `source`. Origination runs independently on the catch-all feed.
+ *
+ * `makeCohortTopicChangeNotifier` discards the catch-all unsubscribe (node-lifetime by intent) for the
+ * unit tests; the node assembly uses {@link attachCohortChangeBridge}, which returns the teardown.
+ */
+export function makeCohortTopicChangeNotifier(deps: CohortTopicChangeNotifierDeps): IBlockChangeNotifier {
+	return buildCohortTopicChangeBridge(deps).notifier;
+}
+
+/**
+ * Shared wiring behind both entry points: subscribe the origination handler to the source's catch-all
+ * commit feed and build the decorating {@link IBlockChangeNotifier}. Returns the notifier plus the
+ * idempotent teardown for that catch-all subscription (the underlying `onAnyCollectionChange` unsub is
+ * itself idempotent), so the node assembly can release it on node stop alongside `host.stop()`.
+ */
+function buildCohortTopicChangeBridge(deps: CohortTopicChangeNotifierDeps): { notifier: IBlockChangeNotifier; unsubscribe: () => void } {
+	const unsubscribe = deps.source.onAnyCollectionChange((event) => originate(deps, event));
+	const notifier: IBlockChangeNotifier = {
+		onCollectionChange: (collectionId, listener): (() => void) => deps.source.onCollectionChange(collectionId, listener),
+	};
+	return { notifier, unsubscribe };
+}
+
+/** Run the membership gate, cert extraction, and origination hook for one change event, isolating throws. */
+function originate(deps: CohortTopicChangeNotifierDeps, event: CollectionChangeEvent): void {
+	try {
+		if (!deps.selfIsCohortMember(event)) {
+			return; // not responsible for this topic's fan-out
+		}
+		const hook = deps.service.onLocalCommit;
+		if (!hook) {
+			return; // no reactivity/matchmaking consumer has attached an origination handler yet
+		}
+		const commitCert = deps.extractCommitCert(event);
+		if (!commitCert) {
+			return; // nothing authoritative to forward; never fabricate an unsigned cert (extractor logs why)
+		}
+		hook(event, commitCert);
+	} catch (err) {
+		log('origination hook threw for collection=%s rev=%d: %o', event.collectionId, event.rev, err);
+	}
+}
+
+/**
+ * Wire the cohort-topic origination bridge as `node`'s `blockChangeNotifier` (the value the
+ * `NetworkTransactor` consumes as its `localChangeNotifier`). Call this from the node assembly once a
+ * {@link CohortTopicService} is running on the node, passing the node's `StorageRepo` as `source` and
+ * the membership + cert-extraction seams.
+ *
+ * Returns the installed `notifier` plus an idempotent `unsubscribe` that tears down the catch-all
+ * origination subscription — the node assembly calls it on node stop (alongside `host.stop()`) so the
+ * origination feed is released before the node's transports close. Tearing it down stops further
+ * origination but leaves the per-collection `onCollectionChange` delegation intact (those subscriptions
+ * live on the `source` `StorageRepo`, not on the bridge).
+ */
+export function attachCohortChangeBridge(
+	node: { blockChangeNotifier?: IBlockChangeNotifier },
+	deps: CohortTopicChangeNotifierDeps,
+): { notifier: IBlockChangeNotifier; unsubscribe: () => void } {
+	const bridge = buildCohortTopicChangeBridge(deps);
+	node.blockChangeNotifier = bridge.notifier;
+	return bridge;
+}

package/src/cohort-topic/cohort-gossip-driver.ts

@@ -0,0 +1,144 @@
+/**
+ * Cohort-topic gossip-cadence driver helpers (host-side, gap 5).
+ *
+ * The {@link import("./host.js").CohortTopicHost} owns a single repeating timer; on each tick it drives
+ * every live `CoordEngine`'s gossip round. The per-round work this module factors out — assembling a
+ * `CohortGossipV1` and accumulating/draining the registration-record deltas the renewal `touch`/`evicted`
+ * hooks emit — is split here so it is unit-testable without the timer or libp2p.
+ *
+ * db-p2p (not db-core) owns the cadence because the round interval, the peer-key signature on the gossip
+ * envelope, and the per-coord inbound routing all live at the FRET/libp2p boundary; db-core supplies the
+ * pure substrate (`selfWillingnessBits`, `toCohortTopicSummary`, `toGossipRecord`, the bus merge).
+ */
+
+import {
+	bytesToB64url,
+	toGossipRecord,
+	willingnessBitsHex,
+	selfWillingnessBits,
+	type CohortGossipV1,
+	type CohortTopicSummary,
+	type GossipRecordRefV1,
+	type GossipRecordV1,
+	type LoadBarometerState,
+	type NodeProfile,
+	type RegistrationRecord,
+} from "@optimystic/db-core";
+
+/**
+ * Default gossip-round cadence in ms. There is no dedicated `gossip_round` constant in
+ * `docs/cohort-topic.md` §Configuration, so this is a derived, injectable default on the order of one
+ * round — a few seconds, aligned with the traffic window / ping cadence (`ping_interval = ttl/3` is
+ * 30 s Core, so a sub-round of that). The membership refresh (`T_membership_refresh`, 5 min) and the
+ * demotion hysteresis (`T_demote`, 5 min) are gated by elapsed-time **inside** their modules, so the
+ * driver can tick fast and let those modules decide when to act.
+ */
+export const DEFAULT_GOSSIP_INTERVAL_MS = 5_000;
+
+/**
+ * Per-`CoordEngine` queue of registration-record deltas accumulated between gossip rounds. The renewal
+ * cohort side calls {@link PendingDeltas.touch} on every served ping/re-attach and
+ * {@link PendingDeltas.evicted} on every TTL sweep; the next round {@link PendingDeltas.drain}s the
+ * batch into the gossip frame and clears it — one broadcast per round rather than one per ping.
+ */
+export interface PendingDeltas {
+	/** Upsert a fresh/touched record (keyed by `(topicId, participantId)`; last write wins on `lastPing`). */
+	touch(rec: RegistrationRecord): void;
+	/** Queue an eviction ref and drop any pending record for the same key (a stale record can't also re-advertise). */
+	evicted(rec: RegistrationRecord): void;
+	/** True iff nothing is queued. */
+	isEmpty(): boolean;
+	/** Drain the queue into wire-shaped deltas, clearing it. */
+	drain(): { records: GossipRecordV1[]; evicted: GossipRecordRefV1[] };
+}
+
+/** Build an empty {@link PendingDeltas} queue. */
+export function createPendingDeltas(): PendingDeltas {
+	const records = new Map<string, RegistrationRecord>();
+	const evicted = new Map<string, GossipRecordRefV1>();
+	const keyOf = (topicId: Uint8Array, participantId: Uint8Array): string =>
+		`${bytesToB64url(topicId)}|${bytesToB64url(participantId)}`;
+	return {
+		touch(rec: RegistrationRecord): void {
+			const key = keyOf(rec.topicId, rec.participantId);
+			const held = records.get(key);
+			// Last-writer-wins on lastPing: never let an older touch shadow a newer one queued the same round.
+			if (held === undefined || rec.lastPing >= held.lastPing) {
+				records.set(key, rec);
+			}
+			evicted.delete(key); // a live touch supersedes a pending eviction (eviction-vs-late-touch)
+		},
+		evicted(rec: RegistrationRecord): void {
+			const key = keyOf(rec.topicId, rec.participantId);
+			evicted.set(key, { topicId: bytesToB64url(rec.topicId), participantId: bytesToB64url(rec.participantId) });
+			records.delete(key);
+		},
+		isEmpty(): boolean {
+			return records.size === 0 && evicted.size === 0;
+		},
+		drain(): { records: GossipRecordV1[]; evicted: GossipRecordRefV1[] } {
+			const out = {
+				records: [...records.values()].map(toGossipRecord),
+				evicted: [...evicted.values()],
+			};
+			records.clear();
+			evicted.clear();
+			return out;
+		},
+	};
+}
+
+/** Inputs to {@link buildCohortGossip} — the per-round signals already gathered by the engine. */
+export interface GossipFrameInputs {
+	/** This member's dialable id, base64url (the `fromMember` / view key). */
+	readonly fromMember: string;
+	/** This cohort's served coord, base64url (the inbound routing key). */
+	readonly coord: string;
+	/** This cohort's epoch, base64url. */
+	readonly cohortEpoch: string;
+	/** This node's tier profile (the `∧` half of the willingness vector). */
+	readonly profile: NodeProfile;
+	/** This member's load barometer (load buckets + the load-shed half of willingness). */
+	readonly barometer: LoadBarometerState;
+	/** Cohort-wide observation window (seconds) for the rate fields in `topicSummaries`. */
+	readonly windowSeconds: number;
+	/** Per-resident-topic summaries (own published counts), already frozen for this round. */
+	readonly topicSummaries: CohortTopicSummary[];
+	/** Drained fresh/touched record deltas for this round. */
+	readonly records: GossipRecordV1[];
+	/** Drained eviction refs for this round. */
+	readonly evicted: GossipRecordRefV1[];
+	/** Round timestamp, unix ms. */
+	readonly timestamp: number;
+}
+
+/**
+ * Assemble one round's {@link CohortGossipV1}, or `undefined` when this engine is **idle** — no resident
+ * topics and no pending deltas, so it has nothing for siblings and the host skips the broadcast (idle
+ * empty engines cost no gossip). `willingnessBits` is `profile ∧ load` ({@link selfWillingnessBits}); the
+ * `signature` slot is left empty for the host's peer-key signer to fill before broadcast.
+ */
+export function buildCohortGossip(i: GossipFrameInputs): CohortGossipV1 | undefined {
+	if (i.topicSummaries.length === 0 && i.records.length === 0 && i.evicted.length === 0) {
+		return undefined;
+	}
+	const g: CohortGossipV1 = {
+		v: 1,
+		fromMember: i.fromMember,
+		coord: i.coord,
+		cohortEpoch: i.cohortEpoch,
+		willingnessBits: willingnessBitsHex(selfWillingnessBits(i.profile, i.barometer)),
+		loadBuckets: i.barometer.loadBuckets(),
+		windowSeconds: i.windowSeconds,
+		topicSummaries: i.topicSummaries,
+		timestamp: i.timestamp,
+		signature: "",
+	};
+	if (i.records.length > 0) {
+		g.records = i.records;
+	}
+	if (i.evicted.length > 0) {
+		g.evicted = i.evicted;
+	}
+	return g;
+}