@optimystic/db-p2p 0.22.0 → 0.24.1

package/src/cohort-topic/peer-codec.ts

@@ -1,31 +1,31 @@
-/**
- * Cohort-topic peer-id ↔ bytes bridge.
- *
- * db-core's substrate logic references peers as opaque `Uint8Array` ids ({@link PeerRef}`.id`); FRET +
- * libp2p reference them as `PeerId` / peer-id strings. The cohort-member ids the substrate carries on
- * the wire (a reply's `primary` / `backups` / `cohortMembers`) must round-trip back to a *dialable*
- * libp2p peer, so this module pins one unambiguous encoding for them: the UTF-8 bytes of the canonical
- * peer-id string. (The participant's own addressing coordinate `P` is a separate ring-coord value — see
- * the host — so this encoding never needs to feed the ring hash.)
- */
-
-import { peerIdFromString } from "@libp2p/peer-id";
-import type { PeerId } from "@libp2p/interface";
-
-const utf8Encoder = new TextEncoder();
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
-
-/** A cohort-member id as the substrate's opaque bytes: UTF-8 of the canonical peer-id string. */
-export function peerIdToBytes(peerId: PeerId | string): Uint8Array {
-	return utf8Encoder.encode(typeof peerId === "string" ? peerId : peerId.toString());
-}
-
-/** Reverse of {@link peerIdToBytes}: decode member bytes back to the canonical peer-id string. */
-export function bytesToPeerIdString(bytes: Uint8Array): string {
-	return utf8Decoder.decode(bytes);
-}
-
-/** Reverse of {@link peerIdToBytes}: decode member bytes back to a dialable {@link PeerId}. */
-export function bytesToPeerId(bytes: Uint8Array): PeerId {
-	return peerIdFromString(bytesToPeerIdString(bytes));
-}
+/**
+ * Cohort-topic peer-id ↔ bytes bridge.
+ *
+ * db-core's substrate logic references peers as opaque `Uint8Array` ids ({@link PeerRef}`.id`); FRET +
+ * libp2p reference them as `PeerId` / peer-id strings. The cohort-member ids the substrate carries on
+ * the wire (a reply's `primary` / `backups` / `cohortMembers`) must round-trip back to a *dialable*
+ * libp2p peer, so this module pins one unambiguous encoding for them: the UTF-8 bytes of the canonical
+ * peer-id string. (The participant's own addressing coordinate `P` is a separate ring-coord value — see
+ * the host — so this encoding never needs to feed the ring hash.)
+ */
+
+import { peerIdFromString } from "@libp2p/peer-id";
+import type { PeerId } from "@libp2p/interface";
+
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** A cohort-member id as the substrate's opaque bytes: UTF-8 of the canonical peer-id string. */
+export function peerIdToBytes(peerId: PeerId | string): Uint8Array {
+	return utf8Encoder.encode(typeof peerId === "string" ? peerId : peerId.toString());
+}
+
+/** Reverse of {@link peerIdToBytes}: decode member bytes back to the canonical peer-id string. */
+export function bytesToPeerIdString(bytes: Uint8Array): string {
+	return utf8Decoder.decode(bytes);
+}
+
+/** Reverse of {@link peerIdToBytes}: decode member bytes back to a dialable {@link PeerId}. */
+export function bytesToPeerId(bytes: Uint8Array): PeerId {
+	return peerIdFromString(bytesToPeerIdString(bytes));
+}

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

@@ -1,86 +1,86 @@
-/**
- * Cohort-topic shared Ed25519 sign/verify primitive (libp2p peer keys).
- *
- * Mirrors the established peer-key signing pattern in `cluster-repo.ts` / `dispute-service.ts`
- * (`PrivateKey.sign` → base64url; verify against the peer's public key), specialized for the
- * cohort-topic substrate:
- *
- * - **Signing** uses the node's libp2p `PrivateKey.sign` (async — fine on the participant outbound
- *   path) and is the seam the threshold-assembly ticket reuses for per-member partial signatures.
- * - **Verification is SYNCHRONOUS**, because the db-core verify ports (e.g. the participant-signature
- *   predicates and `ICohortThresholdCrypto.verify`) are synchronous. libp2p's
- *   `publicKeyFromRaw(raw).verify` is async, so this verifies with `@noble/curves/ed25519` directly
- *   over the raw 32-byte key. noble's `ed25519.verify` (ZIP215) is a strict superset of the RFC8032
- *   signatures the libp2p signer (Node/WebCrypto Ed25519) produces, so it accepts them.
- *
- * The signer id on the cohort wire is the UTF-8 bytes of the peer-id string (see `peer-codec.ts`).
- * For an Ed25519 identity the public key is embedded in the identity multihash, so no network lookup
- * is needed — `peerIdFromString(str).publicKey.raw` yields the raw key. Verification is **total**: any
- * non-Ed25519 id, missing key, or malformed input returns `false` (it never throws). The cohort-topic
- * substrate therefore assumes Ed25519 identities (the libp2p default; `generateKeyPair('Ed25519')`).
- */
-
-import type { PrivateKey } from "@libp2p/interface";
-import { peerIdFromString } from "@libp2p/peer-id";
-import { ed25519 } from "@noble/curves/ed25519.js";
-import { bytesToPeerIdString } from "./peer-codec.js";
-
-/** Sign `payload` with the node's libp2p peer key. Async — libp2p `PrivateKey.sign` is async. */
-export async function signPeer(privateKey: PrivateKey, payload: Uint8Array): Promise<Uint8Array> {
-	return privateKey.sign(payload);
-}
-
-/**
- * Sign `payload` with a libp2p Ed25519 peer key **synchronously** — the mirror of the synchronous
- * {@link verifyPeerSig}. Use this where the signer seam is synchronous and the async {@link signPeer}
- * cannot be awaited: e.g. the reactivity recover `signBackfill` / `signResume` `(unsigned) => string`
- * ports, whose db-core driver builds the unsigned image internally (so a pre-signed value is impossible)
- * and whose seam shape is `=> string`, not `=> Promise<string>`.
- *
- * libp2p's own `PrivateKey.sign` is async (Node / WebCrypto Ed25519), so this signs directly with
- * `@noble/curves/ed25519` over the raw 32-byte seed. libp2p stores an Ed25519 private key as 64 bytes
- * (`raw` = 32-byte seed ‖ 32-byte public key); noble's `ed25519.sign(message, secretKey)` takes the
- * 32-byte seed. noble's signatures are RFC8032-compliant and deterministic, so both verify paths accept
- * them: the libp2p `publicKeyFromRaw(raw).verify` (Node / WebCrypto) and the synchronous
- * {@link verifyPeerSig} (noble, ZIP215) — symmetric with the verify direction's cross-acceptance, and
- * byte-identical to what the async {@link signPeer} would produce for the same key + payload.
- *
- * Assumes an Ed25519 identity (the cohort-topic substrate's standing assumption). Throws on a
- * non-Ed25519 key or an unexpected raw length — a programming error on the node's own key, never
- * attacker-reachable input (the verify side, by contrast, is total and returns `false`).
- */
-export function signPeerSig(privateKey: PrivateKey, payload: Uint8Array): Uint8Array {
-	if (privateKey.type !== "Ed25519") {
-		throw new Error(`signPeerSig: expected an Ed25519 private key, got "${privateKey.type}"`);
-	}
-	const raw = privateKey.raw;
-	// 64-byte libp2p form = seed ‖ public key; accept a bare 32-byte seed too.
-	const seed = raw.length === 64 ? raw.subarray(0, 32) : raw;
-	if (seed.length !== 32) {
-		throw new Error(`signPeerSig: expected a 32- or 64-byte Ed25519 raw key, got ${raw.length} bytes`);
-	}
-	return ed25519.sign(payload, seed);
-}
-
-/**
- * Verify an Ed25519 peer-key signature synchronously. `signer` is the cohort-wire member id — the
- * UTF-8 bytes of the peer-id string (see {@link bytesToPeerIdString}) — or that peer-id string
- * directly. Returns `false` (never throws) on a non-Ed25519 id, a missing/short key, a malformed
- * signature, or any decode failure.
- */
-export function verifyPeerSig(signer: string | Uint8Array, payload: Uint8Array, sig: Uint8Array): boolean {
-	try {
-		const peerIdStr = typeof signer === "string" ? signer : bytesToPeerIdString(signer);
-		const peerId = peerIdFromString(peerIdStr);
-		if (peerId.type !== "Ed25519" || peerId.publicKey === undefined) {
-			return false;
-		}
-		const rawPub = peerId.publicKey.raw;
-		if (rawPub.length !== 32) {
-			return false;
-		}
-		return ed25519.verify(sig, payload, rawPub);
-	} catch {
-		return false;
-	}
-}
+/**
+ * Cohort-topic shared Ed25519 sign/verify primitive (libp2p peer keys).
+ *
+ * Mirrors the established peer-key signing pattern in `cluster-repo.ts` / `dispute-service.ts`
+ * (`PrivateKey.sign` → base64url; verify against the peer's public key), specialized for the
+ * cohort-topic substrate:
+ *
+ * - **Signing** uses the node's libp2p `PrivateKey.sign` (async — fine on the participant outbound
+ *   path) and is the seam the threshold-assembly ticket reuses for per-member partial signatures.
+ * - **Verification is SYNCHRONOUS**, because the db-core verify ports (e.g. the participant-signature
+ *   predicates and `ICohortThresholdCrypto.verify`) are synchronous. libp2p's
+ *   `publicKeyFromRaw(raw).verify` is async, so this verifies with `@noble/curves/ed25519` directly
+ *   over the raw 32-byte key. noble's `ed25519.verify` (ZIP215) is a strict superset of the RFC8032
+ *   signatures the libp2p signer (Node/WebCrypto Ed25519) produces, so it accepts them.
+ *
+ * The signer id on the cohort wire is the UTF-8 bytes of the peer-id string (see `peer-codec.ts`).
+ * For an Ed25519 identity the public key is embedded in the identity multihash, so no network lookup
+ * is needed — `peerIdFromString(str).publicKey.raw` yields the raw key. Verification is **total**: any
+ * non-Ed25519 id, missing key, or malformed input returns `false` (it never throws). The cohort-topic
+ * substrate therefore assumes Ed25519 identities (the libp2p default; `generateKeyPair('Ed25519')`).
+ */
+
+import type { PrivateKey } from "@libp2p/interface";
+import { peerIdFromString } from "@libp2p/peer-id";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { bytesToPeerIdString } from "./peer-codec.js";
+
+/** Sign `payload` with the node's libp2p peer key. Async — libp2p `PrivateKey.sign` is async. */
+export async function signPeer(privateKey: PrivateKey, payload: Uint8Array): Promise<Uint8Array> {
+	return privateKey.sign(payload);
+}
+
+/**
+ * Sign `payload` with a libp2p Ed25519 peer key **synchronously** — the mirror of the synchronous
+ * {@link verifyPeerSig}. Use this where the signer seam is synchronous and the async {@link signPeer}
+ * cannot be awaited: e.g. the reactivity recover `signBackfill` / `signResume` `(unsigned) => string`
+ * ports, whose db-core driver builds the unsigned image internally (so a pre-signed value is impossible)
+ * and whose seam shape is `=> string`, not `=> Promise<string>`.
+ *
+ * libp2p's own `PrivateKey.sign` is async (Node / WebCrypto Ed25519), so this signs directly with
+ * `@noble/curves/ed25519` over the raw 32-byte seed. libp2p stores an Ed25519 private key as 64 bytes
+ * (`raw` = 32-byte seed ‖ 32-byte public key); noble's `ed25519.sign(message, secretKey)` takes the
+ * 32-byte seed. noble's signatures are RFC8032-compliant and deterministic, so both verify paths accept
+ * them: the libp2p `publicKeyFromRaw(raw).verify` (Node / WebCrypto) and the synchronous
+ * {@link verifyPeerSig} (noble, ZIP215) — symmetric with the verify direction's cross-acceptance, and
+ * byte-identical to what the async {@link signPeer} would produce for the same key + payload.
+ *
+ * Assumes an Ed25519 identity (the cohort-topic substrate's standing assumption). Throws on a
+ * non-Ed25519 key or an unexpected raw length — a programming error on the node's own key, never
+ * attacker-reachable input (the verify side, by contrast, is total and returns `false`).
+ */
+export function signPeerSig(privateKey: PrivateKey, payload: Uint8Array): Uint8Array {
+	if (privateKey.type !== "Ed25519") {
+		throw new Error(`signPeerSig: expected an Ed25519 private key, got "${privateKey.type}"`);
+	}
+	const raw = privateKey.raw;
+	// 64-byte libp2p form = seed ‖ public key; accept a bare 32-byte seed too.
+	const seed = raw.length === 64 ? raw.subarray(0, 32) : raw;
+	if (seed.length !== 32) {
+		throw new Error(`signPeerSig: expected a 32- or 64-byte Ed25519 raw key, got ${raw.length} bytes`);
+	}
+	return ed25519.sign(payload, seed);
+}
+
+/**
+ * Verify an Ed25519 peer-key signature synchronously. `signer` is the cohort-wire member id — the
+ * UTF-8 bytes of the peer-id string (see {@link bytesToPeerIdString}) — or that peer-id string
+ * directly. Returns `false` (never throws) on a non-Ed25519 id, a missing/short key, a malformed
+ * signature, or any decode failure.
+ */
+export function verifyPeerSig(signer: string | Uint8Array, payload: Uint8Array, sig: Uint8Array): boolean {
+	try {
+		const peerIdStr = typeof signer === "string" ? signer : bytesToPeerIdString(signer);
+		const peerId = peerIdFromString(peerIdStr);
+		if (peerId.type !== "Ed25519" || peerId.publicKey === undefined) {
+			return false;
+		}
+		const rawPub = peerId.publicKey.raw;
+		if (rawPub.length !== 32) {
+			return false;
+		}
+		return ed25519.verify(sig, payload, rawPub);
+	} catch {
+		return false;
+	}
+}

package/src/cohort-topic/protocols.ts

@@ -1,71 +1,71 @@
-/**
- * Cohort-topic libp2p protocol IDs (`docs/cohort-topic.md` §FRET integration L432-460).
- *
- * Five protocols ride the same FRET/libp2p node:
- *
- * - `register`      — Register, renew, re-attach (`RegisterV1` / `RenewV1`, routed via `RouteAndMaybeAct`).
- * - `cohort-gossip` — record replication, willingness, load barometers (`CohortGossipV1`).
- * - `promote`       — threshold-signed promotion / demotion notices.
- * - `membership`    — membership certificates (`MembershipCertV1`).
- * - `sign`          — intra-cohort per-member endorsement for `k − x` threshold-signature assembly
- *                     (`SignRequestV1` / `SignReplyV1`); a member collecting a threshold signature dials
- *                     each cohort member here and concatenates the returned per-member Ed25519 sigs.
- *
- * The default (network-agnostic) IDs match the doc verbatim; {@link makeCohortTopicProtocols}
- * mirrors FRET's `makeProtocols(networkName)` so a named network namespaces its cohort-topic
- * protocols the same way FRET namespaces its routing protocols.
- */
-
-/** Base path for the cohort-topic protocol family. */
-export const COHORT_TOPIC_BASE = "/optimystic/cohort-topic/1.0.0" as const;
-
-/** `RegisterV1` / `RenewV1` — register, renew, re-attach. */
-export const PROTOCOL_COHORT_REGISTER = `${COHORT_TOPIC_BASE}/register` as const;
-/** `CohortGossipV1` — record replication, willingness, load barometers. */
-export const PROTOCOL_COHORT_GOSSIP = `${COHORT_TOPIC_BASE}/cohort-gossip` as const;
-/** Threshold-signed promotion / demotion notices. */
-export const PROTOCOL_COHORT_PROMOTE = `${COHORT_TOPIC_BASE}/promote` as const;
-/** `MembershipCertV1` — membership certificates. */
-export const PROTOCOL_COHORT_MEMBERSHIP = `${COHORT_TOPIC_BASE}/membership` as const;
-/** `SignRequestV1` / `SignReplyV1` — intra-cohort per-member endorsement for threshold-signature assembly. */
-export const PROTOCOL_COHORT_SIGN = `${COHORT_TOPIC_BASE}/sign` as const;
-
-/** The five cohort-topic protocol IDs in registration order. */
-export interface CohortTopicProtocols {
-	readonly register: string;
-	readonly gossip: string;
-	readonly promote: string;
-	readonly membership: string;
-	readonly sign: string;
-}
-
-/** Default (network-agnostic) protocol IDs, matching `docs/cohort-topic.md` §FRET integration. */
-export const DEFAULT_COHORT_TOPIC_PROTOCOLS: CohortTopicProtocols = {
-	register: PROTOCOL_COHORT_REGISTER,
-	gossip: PROTOCOL_COHORT_GOSSIP,
-	promote: PROTOCOL_COHORT_PROMOTE,
-	membership: PROTOCOL_COHORT_MEMBERSHIP,
-	sign: PROTOCOL_COHORT_SIGN,
-};
-
-/**
- * Namespaced cohort-topic protocol IDs for `networkName` (mirrors FRET's `makeProtocols`, which
- * inserts the network segment even for `"default"` → `/optimystic/default/...`). Note this does NOT
- * equal {@link DEFAULT_COHORT_TOPIC_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment
- * entirely (`/optimystic/cohort-topic/1.0.0/...`); use those unless you need per-network namespacing.
- */
-export function makeCohortTopicProtocols(networkName = "default"): CohortTopicProtocols {
-	const base = `/optimystic/${networkName}/cohort-topic/1.0.0`;
-	return {
-		register: `${base}/register`,
-		gossip: `${base}/cohort-gossip`,
-		promote: `${base}/promote`,
-		membership: `${base}/membership`,
-		sign: `${base}/sign`,
-	};
-}
-
-/** All five protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
-export function cohortTopicProtocolList(p: CohortTopicProtocols): string[] {
-	return [p.register, p.gossip, p.promote, p.membership, p.sign];
-}
+/**
+ * Cohort-topic libp2p protocol IDs (`docs/cohort-topic.md` §FRET integration L432-460).
+ *
+ * Five protocols ride the same FRET/libp2p node:
+ *
+ * - `register`      — Register, renew, re-attach (`RegisterV1` / `RenewV1`, routed via `RouteAndMaybeAct`).
+ * - `cohort-gossip` — record replication, willingness, load barometers (`CohortGossipV1`).
+ * - `promote`       — threshold-signed promotion / demotion notices.
+ * - `membership`    — membership certificates (`MembershipCertV1`).
+ * - `sign`          — intra-cohort per-member endorsement for `k − x` threshold-signature assembly
+ *                     (`SignRequestV1` / `SignReplyV1`); a member collecting a threshold signature dials
+ *                     each cohort member here and concatenates the returned per-member Ed25519 sigs.
+ *
+ * The default (network-agnostic) IDs match the doc verbatim; {@link makeCohortTopicProtocols}
+ * mirrors FRET's `makeProtocols(networkName)` so a named network namespaces its cohort-topic
+ * protocols the same way FRET namespaces its routing protocols.
+ */
+
+/** Base path for the cohort-topic protocol family. */
+export const COHORT_TOPIC_BASE = "/optimystic/cohort-topic/1.0.0" as const;
+
+/** `RegisterV1` / `RenewV1` — register, renew, re-attach. */
+export const PROTOCOL_COHORT_REGISTER = `${COHORT_TOPIC_BASE}/register` as const;
+/** `CohortGossipV1` — record replication, willingness, load barometers. */
+export const PROTOCOL_COHORT_GOSSIP = `${COHORT_TOPIC_BASE}/cohort-gossip` as const;
+/** Threshold-signed promotion / demotion notices. */
+export const PROTOCOL_COHORT_PROMOTE = `${COHORT_TOPIC_BASE}/promote` as const;
+/** `MembershipCertV1` — membership certificates. */
+export const PROTOCOL_COHORT_MEMBERSHIP = `${COHORT_TOPIC_BASE}/membership` as const;
+/** `SignRequestV1` / `SignReplyV1` — intra-cohort per-member endorsement for threshold-signature assembly. */
+export const PROTOCOL_COHORT_SIGN = `${COHORT_TOPIC_BASE}/sign` as const;
+
+/** The five cohort-topic protocol IDs in registration order. */
+export interface CohortTopicProtocols {
+	readonly register: string;
+	readonly gossip: string;
+	readonly promote: string;
+	readonly membership: string;
+	readonly sign: string;
+}
+
+/** Default (network-agnostic) protocol IDs, matching `docs/cohort-topic.md` §FRET integration. */
+export const DEFAULT_COHORT_TOPIC_PROTOCOLS: CohortTopicProtocols = {
+	register: PROTOCOL_COHORT_REGISTER,
+	gossip: PROTOCOL_COHORT_GOSSIP,
+	promote: PROTOCOL_COHORT_PROMOTE,
+	membership: PROTOCOL_COHORT_MEMBERSHIP,
+	sign: PROTOCOL_COHORT_SIGN,
+};
+
+/**
+ * Namespaced cohort-topic protocol IDs for `networkName` (mirrors FRET's `makeProtocols`, which
+ * inserts the network segment even for `"default"` → `/optimystic/default/...`). Note this does NOT
+ * equal {@link DEFAULT_COHORT_TOPIC_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment
+ * entirely (`/optimystic/cohort-topic/1.0.0/...`); use those unless you need per-network namespacing.
+ */
+export function makeCohortTopicProtocols(networkName = "default"): CohortTopicProtocols {
+	const base = `/optimystic/${networkName}/cohort-topic/1.0.0`;
+	return {
+		register: `${base}/register`,
+		gossip: `${base}/cohort-gossip`,
+		promote: `${base}/promote`,
+		membership: `${base}/membership`,
+		sign: `${base}/sign`,
+	};
+}
+
+/** All five protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export function cohortTopicProtocolList(p: CohortTopicProtocols): string[] {
+	return [p.register, p.gossip, p.promote, p.membership, p.sign];
+}

package/src/cohort-topic/reactivity-membership-gate.ts

@@ -1,77 +1,77 @@
-/**
- * Reactivity origination membership gate (`docs/reactivity.md` §Anchor, `docs/internals.md`
- * §Cohort-Topic Origination Bridge).
- *
- * Builds the `selfIsCohortMember(event)` predicate the change-notifier bridge gates each member commit
- * on: this node is responsible for a collection's reactivity-topic fan-out iff it sits in the FRET
- * cohort around `coord_0(H(currentTailId ‖ "reactivity"))`. The tail comes from `event.tailId` (the seam
- * ticket put the committed `CommitRequest.tailId` on the change event), so the decision is synchronous —
- * no async storage read, no per-collection registry. A tail-less event (a read-driven promotion) is
- * never a member; those never originate and are cert-gated out downstream anyway.
- *
- * Extracted from the node assembly so the encoding + coord derivation are unit-testable in isolation and
- * reusable by the future reactivity origination wiring.
- */
-
-import {
-	createReactivityTopicAnchor,
-	createTierAddressing,
-	createRingHash,
-	type ReactivityTopicAnchor,
-	type TierAddressing,
-	type CollectionChangeEvent,
-} from "@optimystic/db-core";
-import type { FretService } from "p2p-fret";
-
-// The pinned `BlockId` → raw tail-bytes encoding now lives in the reactivity surface so the origination
-// gate (here) and the subscriber-side subscribe factory import the SAME function — see `reactivity/
-// topic-bytes.ts` for the load-bearing rationale. Re-exported so this module's existing callers (tests,
-// node wiring) keep importing `reactivityTailBytes` from the gate.
-export { reactivityTailBytes } from "../reactivity/topic-bytes.js";
-import { reactivityTailBytes } from "../reactivity/topic-bytes.js";
-
-/** Construction inputs for {@link createReactivitySelfMembershipGate}. */
-export interface ReactivitySelfMembershipGateDeps {
-	/** FRET membership read — the cohort assembler around a served coord (returns peer-id strings). */
-	readonly fret: Pick<FretService, "assembleCohort">;
-	/** This node's peer-id string, compared against the assembled cohort. */
-	readonly selfPeerId: string;
-	/**
-	 * Requested cohort size `wantK`. MUST equal the cohort-topic host's `wantK`, so the gate checks the
-	 * exact cohort the host serves; a mismatch silently breaks origination.
-	 */
-	readonly wantK: number;
-	/**
-	 * Reactivity topic anchor. Default db-core's {@link createReactivityTopicAnchor} (256-bit SHA-256),
-	 * byte-identical to the host's internal `new RingHash()` and the subscriber-side anchor.
-	 */
-	readonly anchor?: ReactivityTopicAnchor;
-	/**
-	 * Tier addressing. Default `createTierAddressing(createRingHash())`. `coord_0` is fan-out independent
-	 * (`H(0x00 ‖ topicId)`), so the default fan-out is irrelevant to the tier-0 reactivity coord.
-	 */
-	readonly addressing?: TierAddressing;
-}
-
-/**
- * Build the synchronous `selfIsCohortMember(event)` gate for {@link attachCohortChangeBridge}.
- *
- * Returns `false` for a tail-less event; otherwise resolves `coord_0(H(event.tailId ‖ "reactivity"))`
- * via the shared anchor + tier addressing and returns whether `fret.assembleCohort(coord, wantK)`
- * includes this node's peer id. Pure aside from the live FRET read; membership churn between commits is
- * fine because reactivity is hint-only.
- */
-export function createReactivitySelfMembershipGate(
-	deps: ReactivitySelfMembershipGateDeps,
-): (event: CollectionChangeEvent) => boolean {
-	const anchor = deps.anchor ?? createReactivityTopicAnchor();
-	const addressing = deps.addressing ?? createTierAddressing(createRingHash());
-	return (event: CollectionChangeEvent): boolean => {
-		if (event.tailId === undefined) {
-			return false; // promotion / tail-less event never originates
-		}
-		const topicId = anchor.topicId(reactivityTailBytes(event.tailId));
-		const coord = addressing.coord0(topicId);
-		return deps.fret.assembleCohort(coord, deps.wantK).includes(deps.selfPeerId);
-	};
-}
+/**
+ * Reactivity origination membership gate (`docs/reactivity.md` §Anchor, `docs/internals.md`
+ * §Cohort-Topic Origination Bridge).
+ *
+ * Builds the `selfIsCohortMember(event)` predicate the change-notifier bridge gates each member commit
+ * on: this node is responsible for a collection's reactivity-topic fan-out iff it sits in the FRET
+ * cohort around `coord_0(H(currentTailId ‖ "reactivity"))`. The tail comes from `event.tailId` (the seam
+ * ticket put the committed `CommitRequest.tailId` on the change event), so the decision is synchronous —
+ * no async storage read, no per-collection registry. A tail-less event (a read-driven promotion) is
+ * never a member; those never originate and are cert-gated out downstream anyway.
+ *
+ * Extracted from the node assembly so the encoding + coord derivation are unit-testable in isolation and
+ * reusable by the future reactivity origination wiring.
+ */
+
+import {
+	createReactivityTopicAnchor,
+	createTierAddressing,
+	createRingHash,
+	type ReactivityTopicAnchor,
+	type TierAddressing,
+	type CollectionChangeEvent,
+} from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+// The pinned `BlockId` → raw tail-bytes encoding now lives in the reactivity surface so the origination
+// gate (here) and the subscriber-side subscribe factory import the SAME function — see `reactivity/
+// topic-bytes.ts` for the load-bearing rationale. Re-exported so this module's existing callers (tests,
+// node wiring) keep importing `reactivityTailBytes` from the gate.
+export { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+import { reactivityTailBytes } from "../reactivity/topic-bytes.js";
+
+/** Construction inputs for {@link createReactivitySelfMembershipGate}. */
+export interface ReactivitySelfMembershipGateDeps {
+	/** FRET membership read — the cohort assembler around a served coord (returns peer-id strings). */
+	readonly fret: Pick<FretService, "assembleCohort">;
+	/** This node's peer-id string, compared against the assembled cohort. */
+	readonly selfPeerId: string;
+	/**
+	 * Requested cohort size `wantK`. MUST equal the cohort-topic host's `wantK`, so the gate checks the
+	 * exact cohort the host serves; a mismatch silently breaks origination.
+	 */
+	readonly wantK: number;
+	/**
+	 * Reactivity topic anchor. Default db-core's {@link createReactivityTopicAnchor} (256-bit SHA-256),
+	 * byte-identical to the host's internal `new RingHash()` and the subscriber-side anchor.
+	 */
+	readonly anchor?: ReactivityTopicAnchor;
+	/**
+	 * Tier addressing. Default `createTierAddressing(createRingHash())`. `coord_0` is fan-out independent
+	 * (`H(0x00 ‖ topicId)`), so the default fan-out is irrelevant to the tier-0 reactivity coord.
+	 */
+	readonly addressing?: TierAddressing;
+}
+
+/**
+ * Build the synchronous `selfIsCohortMember(event)` gate for {@link attachCohortChangeBridge}.
+ *
+ * Returns `false` for a tail-less event; otherwise resolves `coord_0(H(event.tailId ‖ "reactivity"))`
+ * via the shared anchor + tier addressing and returns whether `fret.assembleCohort(coord, wantK)`
+ * includes this node's peer id. Pure aside from the live FRET read; membership churn between commits is
+ * fine because reactivity is hint-only.
+ */
+export function createReactivitySelfMembershipGate(
+	deps: ReactivitySelfMembershipGateDeps,
+): (event: CollectionChangeEvent) => boolean {
+	const anchor = deps.anchor ?? createReactivityTopicAnchor();
+	const addressing = deps.addressing ?? createTierAddressing(createRingHash());
+	return (event: CollectionChangeEvent): boolean => {
+		if (event.tailId === undefined) {
+			return false; // promotion / tail-less event never originates
+		}
+		const topicId = anchor.topicId(reactivityTailBytes(event.tailId));
+		const coord = addressing.coord0(topicId);
+		return deps.fret.assembleCohort(coord, deps.wantK).includes(deps.selfPeerId);
+	};
+}

package/src/cohort-topic/size-estimator.ts

@@ -1,16 +1,16 @@
-import type { ISizeEstimator } from "@optimystic/db-core";
-import type { FretService } from "p2p-fret";
-
-/**
- * FRET-backed {@link ISizeEstimator}: feeds `d_max` from FRET's network-size estimate
- * (`FretService.getNetworkSizeEstimate`). A clean, total binding — db-core's `d_max` computer applies
- * the low-confidence clamp itself, so this adapter only forwards FRET's `(size_estimate, confidence)`.
- */
-export class FretSizeEstimator implements ISizeEstimator {
-	constructor(private readonly fret: FretService) {}
-
-	estimate(): { nEst: number; confidence: number } {
-		const { size_estimate, confidence } = this.fret.getNetworkSizeEstimate();
-		return { nEst: size_estimate, confidence };
-	}
-}
+import type { ISizeEstimator } from "@optimystic/db-core";
+import type { FretService } from "p2p-fret";
+
+/**
+ * FRET-backed {@link ISizeEstimator}: feeds `d_max` from FRET's network-size estimate
+ * (`FretService.getNetworkSizeEstimate`). A clean, total binding — db-core's `d_max` computer applies
+ * the low-confidence clamp itself, so this adapter only forwards FRET's `(size_estimate, confidence)`.
+ */
+export class FretSizeEstimator implements ISizeEstimator {
+	constructor(private readonly fret: FretService) {}
+
+	estimate(): { nEst: number; confidence: number } {
+		const { size_estimate, confidence } = this.fret.getNetworkSizeEstimate();
+		return { nEst: size_estimate, confidence };
+	}
+}