@optimystic/db-p2p 0.13.5 → 0.14.0

package/src/matchmaking/aggregate-counts.ts

@@ -0,0 +1,104 @@
+/**
+ * Matchmaking — root-cohort aggregate-count producer (db-p2p, wires the substrate to the sweep summary).
+ *
+ * `docs/matchmaking.md` §Multi-cohort sweep / §Aggregated provider counts. A *promoted* topic's root
+ * cohort answers a sweeping seeker with an {@link AggregateCountV1}: log-bucketed provider counts per
+ * tier-1 prefix shard, **threshold-signed** (an attested *registered*-provider count — unlike the
+ * advisory, single-member-signed `QueryReplyV1`). This module is the thin db-p2p binding that builds
+ * that message from the root's per-shard accounting and the cohort threshold signer.
+ *
+ * Two invariants the doc mandates, enforced here:
+ *
+ *  - **Depth gate.** The aggregate is produced **only** when the tree depth at this cohort is
+ *    `>= aggregate_count_minimum_tier` (default 1). A cold cohort that fell through to `NoState` has no
+ *    tier-1 children to summarize, so {@link buildAggregateCount} returns `undefined` and the seeker
+ *    falls back to the single-cohort sample.
+ *  - **Log-bucketing.** Raw per-shard counts are quantized through the db-core {@link logBucketCount}
+ *    (largest power of two `<= n`), never forwarded exactly.
+ *
+ * Like the cohort query handler, the inputs are injected (records/accounting, epoch, depth, the threshold
+ * signer), so this unit-tests without a live FRET/libp2p stack — the mock-tier e2e that drives it from a
+ * real promoted root is a documented follow-on. In the FRET host the root `CoordEngine` supplies
+ * `shardCounts` from its child-cohort accounting (the per-tier-1 `childCohortCount` / gossip-derived
+ * summaries), `treeDepth` from its tier state, `cohortEpoch` from the membership, and `thresholdSign`
+ * bound to the cohort signer's `/sign` assembly.
+ */
+
+import {
+	bytesToB64url,
+	logBucketCount,
+	aggregateCountSigningPayload,
+	AGGREGATE_COUNT_MINIMUM_TIER,
+	DEFAULT_FANOUT,
+	DEFAULT_SWEEP_TARGET_TIER,
+	type AggregateBucketV1,
+	type AggregateCountV1,
+} from "@optimystic/db-core";
+
+/** Everything {@link buildAggregateCount} needs from the root cohort, all injected. */
+export interface AggregateCountContext {
+	/** The topic id being summarized, 32 bytes. */
+	readonly topicId: Uint8Array;
+	/** The current cohort epoch, 32 bytes. */
+	readonly cohortEpoch: Uint8Array;
+	/**
+	 * Tree depth at this cohort. The aggregate is produced only when `treeDepth >= minimumTier`; a cold
+	 * cohort (depth 0) summarizes nothing.
+	 */
+	readonly treeDepth: number;
+	/**
+	 * Raw per-tier-1-shard provider counts, keyed by `prefixSlot` (`0..fanout-1`). Slots absent from the
+	 * map count as `0`. The root derives these from its child-cohort accounting; this binding log-buckets
+	 * them and never trusts the caller to pre-bucket.
+	 */
+	readonly shardCounts: ReadonlyMap<number, number>;
+	/**
+	 * Assemble a cohort threshold signature over the canonical aggregate image (db-p2p binds the cohort
+	 * signer). Returns the multisig blob plus the `>= minSigs` signer subset that produced it.
+	 */
+	readonly thresholdSign: (payload: Uint8Array) => Promise<{ thresholdSig: Uint8Array; signers: Uint8Array[] }>;
+	/** The tier whose shards are summarized. Default {@link DEFAULT_SWEEP_TARGET_TIER} (1). */
+	readonly targetTier?: number;
+	/** Number of prefix slots `F`. Default {@link DEFAULT_FANOUT} (16). */
+	readonly fanout?: number;
+	/** Depth gate. Default {@link AGGREGATE_COUNT_MINIMUM_TIER} (1). */
+	readonly minimumTier?: number;
+	/** Emit zero-count shards too (default `false` — empty shards are omitted to keep the summary compact). */
+	readonly includeEmptyShards?: boolean;
+}
+
+/**
+ * Build the threshold-signed {@link AggregateCountV1} for the root's per-shard accounting, or `undefined`
+ * when the depth gate is not met (`treeDepth < minimumTier`). Counts are log-bucketed; the canonical
+ * image is order-independent (the signing payload sorts buckets), so signer and verifier agree.
+ */
+export async function buildAggregateCount(ctx: AggregateCountContext): Promise<AggregateCountV1 | undefined> {
+	const minimumTier = ctx.minimumTier ?? AGGREGATE_COUNT_MINIMUM_TIER;
+	if (ctx.treeDepth < minimumTier) {
+		// Cold / unpromoted root: no tier-1 children to summarize (matches the seeker's NoState fallback).
+		return undefined;
+	}
+
+	const targetTier = ctx.targetTier ?? DEFAULT_SWEEP_TARGET_TIER;
+	const fanout = ctx.fanout ?? DEFAULT_FANOUT;
+	const bucketCounts: AggregateBucketV1[] = [];
+	for (let prefixSlot = 0; prefixSlot < fanout; prefixSlot++) {
+		const count = logBucketCount(ctx.shardCounts.get(prefixSlot) ?? 0);
+		if (count > 0 || ctx.includeEmptyShards === true) {
+			bucketCounts.push({ targetTier, prefixSlot, count });
+		}
+	}
+
+	const unsigned: Omit<AggregateCountV1, "signature" | "signers"> = {
+		v: 1,
+		topicId: bytesToB64url(ctx.topicId),
+		bucketCounts,
+		cohortEpoch: bytesToB64url(ctx.cohortEpoch),
+	};
+	const { thresholdSig, signers } = await ctx.thresholdSign(aggregateCountSigningPayload(unsigned));
+	return {
+		...unsigned,
+		signature: bytesToB64url(thresholdSig),
+		signers: signers.map(bytesToB64url),
+	};
+}

package/src/matchmaking/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Matchmaking — db-p2p wiring to the cohort-topic substrate.
+ *
+ * The db-core `matchmaking` module owns the wire codecs, anchor, config, provider/seeker
+ * decision/state, the capability filter, the pure query evaluation, and the hang-out decision engine;
+ * these db-p2p bindings wire that logic to the cohort-topic substrate: the register/renew/withdraw
+ * managers (tier T2), the cohort-side `QueryV1` handler, and the seeker walk client that drives the
+ * hang-out-vs-continue walk. See `docs/matchmaking.md` §Provider registration / §Seeker query /
+ * §Hang-out vs. continue.
+ */
+
+export * from "./protocols.js";
+export * from "./provider-manager.js";
+export * from "./seeker-manager.js";
+export * from "./query-handler.js";
+export * from "./query-transport.js";
+export * from "./seeker-walk-client.js";
+export * from "./aggregate-counts.js";
+export * from "./traffic-validation.js";
+export * from "./module.js";

package/src/matchmaking/module.ts

@@ -0,0 +1,363 @@
+/**
+ * Matchmaking — cohesive public module (db-p2p, the cohort-topic-integrated entry points).
+ *
+ * `docs/matchmaking.md` §Overview / §Configuration names two public roles. This module composes the
+ * lower db-core state + db-p2p substrate wiring (managers, seeker walk client, multi-cohort sweep) into
+ * those roles, plus the `QuorumDiscovery` binding the voting plan consumes:
+ *
+ *  - {@link MatchmakingProviderSession} — `register(topic, payload)` / `renew()` / `withdraw()` (plus
+ *    `setCapacity` / `signalFull` self-throttling), driving a {@link MatchmakingProvider} through the
+ *    {@link MatchmakingProviderManager} at cohort-topic tier **T2**.
+ *  - {@link MatchmakingSeekerSession} — `register(topic, payload)` (brief T2 registration), `query(q)`
+ *    (one-shot cohort query), and `walk(topic, want)` (the hang-out engine, escalating to the
+ *    multi-cohort sweep on a hot topic).
+ *  - {@link createMatchmakingQuorumDiscovery} — binds the db-core voting `QuorumDiscovery` port to the
+ *    seeker walk (single-cohort) + {@link runMultiCohortSweep} (sweep), so `VotingQuorumAssembler` runs
+ *    over real substrate I/O.
+ *
+ * **Naming note (honest):** the db-core `MatchmakingProvider` / `MatchmakingSeeker` are the
+ * transport-free *state + signed-payload builders*; these `*Session` classes are the substrate-wired
+ * *public entry points* the doc's `MatchmakingProvider` / `MatchmakingSeeker` sketch refers to. They are
+ * named `*Session` to avoid colliding with the re-exported db-core state classes.
+ *
+ * The substrate I/O is **injected** — the seeker walk transport, the one-shot query, the `d_max`
+ * estimate, and the sweep ports are all ports the FRET host binds. The module therefore unit-tests
+ * without a live libp2p stack; the mock-tier e2e that drives these against a real promoted tree is a
+ * documented follow-on (the same posture as the rest of the subsystem).
+ */
+
+import {
+	MatchmakingProvider,
+	MatchmakingSeeker,
+	createMatchTopicAnchor,
+	runMultiCohortSweep,
+	type MatchTopicAnchor,
+	type MatchTopicKind,
+	type CohortTopicService,
+	type NodeProfile,
+	type CapabilityFilter,
+	type EntrySigVerifier,
+	type HangOutConfig,
+	type ProviderEntryV1,
+	type QueryReplyV1,
+	type QueryV1,
+	type MultiCohortSweepPorts,
+	type QuorumDiscovery,
+	type QuorumDiscoveryRequest,
+	type QuorumDiscoverySlice,
+} from "@optimystic/db-core";
+import { MatchmakingProviderManager } from "./provider-manager.js";
+import { MatchmakingSeekerManager } from "./seeker-manager.js";
+import { SeekerWalkClient, type SeekerWalkTransport } from "./seeker-walk-client.js";
+
+/** A matchmaking topic reference: `(kind, label)` resolved to `topicId = H(kind ‖ label ‖ "match")`. */
+export interface MatchTopicRef {
+	readonly kind: MatchTopicKind;
+	readonly label: string;
+}
+
+// --- provider session ----------------------------------------------------------------------------
+
+/** The provider registration inputs a {@link MatchmakingProviderSession.register} call carries. */
+export interface ProviderRegistrationInput {
+	readonly capabilities: readonly string[];
+	readonly capacityBudget: number;
+	readonly contactHint: string;
+	readonly serviceUntil?: number;
+}
+
+/** Construction inputs for a {@link MatchmakingProviderSession}. */
+export interface MatchmakingProviderSessionDeps {
+	/** Participant-facing cohort-topic substrate API. */
+	readonly service: CohortTopicService;
+	/** Sign the provider registration image (db-p2p supplies the libp2p peer key). */
+	readonly sign: (payload: Uint8Array) => Promise<string>;
+	/** Topic anchor; defaults to db-core's ring-hash anchor. */
+	readonly anchor?: MatchTopicAnchor;
+	/** Node profile used to derive the provider TTL (Core 90 s / Edge 60 s). */
+	readonly profile?: NodeProfile;
+	/** Explicit provider TTL (ms); overrides the profile-derived TTL. */
+	readonly ttlMs?: number;
+	/** CSPRNG source for the provider correlation id (injectable for deterministic tests). */
+	readonly randomBytes?: (n: number) => Uint8Array;
+}
+
+/**
+ * Public provider entry point: registers a {@link MatchmakingProvider} at a topic (cohort-topic T2) and
+ * drives its lifecycle. One session owns one live registration; calling {@link register} again
+ * re-registers (e.g. at a different topic).
+ */
+export class MatchmakingProviderSession {
+	private readonly deps: MatchmakingProviderSessionDeps;
+	private readonly anchor: MatchTopicAnchor;
+	private manager?: MatchmakingProviderManager;
+
+	constructor(deps: MatchmakingProviderSessionDeps) {
+		this.deps = deps;
+		this.anchor = deps.anchor ?? createMatchTopicAnchor();
+	}
+
+	/** The live registration handle, or `undefined` before the first {@link register}. */
+	get registration(): MatchmakingProviderManager["registration"] {
+		return this.manager?.registration;
+	}
+
+	/** Register the provider at `topic` with the signed payload, at cohort-topic tier T2. */
+	async register(topic: MatchTopicRef, reg: ProviderRegistrationInput): Promise<void> {
+		const topicId = this.anchor.topicId(topic.kind, topic.label);
+		const provider = new MatchmakingProvider({
+			topicId,
+			capabilities: reg.capabilities,
+			capacityBudget: reg.capacityBudget,
+			contactHint: reg.contactHint,
+			sign: this.deps.sign,
+			...(reg.serviceUntil !== undefined ? { serviceUntil: reg.serviceUntil } : {}),
+			...(this.deps.randomBytes !== undefined ? { randomBytes: this.deps.randomBytes } : {}),
+		});
+		this.manager = new MatchmakingProviderManager({
+			service: this.deps.service,
+			provider,
+			...(this.deps.ttlMs !== undefined ? { ttlMs: this.deps.ttlMs } : {}),
+			...(this.deps.profile !== undefined ? { profile: this.deps.profile } : {}),
+		});
+		await this.manager.register();
+	}
+
+	/** Run one renewal cycle (keep-alive). No-op before {@link register}. */
+	async renew(): Promise<void> {
+		await this.manager?.renew();
+	}
+
+	/** Update the live capacity budget and push it by re-registering (`RenewV1` cannot carry a payload). */
+	async setCapacity(budget: number): Promise<void> {
+		await this.requireManager().setCapacity(budget);
+	}
+
+	/** Signal "available but at capacity" (`capacityBudget = 0`) by re-registering. */
+	async signalFull(): Promise<void> {
+		await this.requireManager().signalFull();
+	}
+
+	/** Withdraw: sends a best-effort signed `RenewV1.withdraw` tombstone so the cohort frees the record
+	 * immediately (an optimization; the record otherwise TTL-expires). No-op before register. */
+	async withdraw(): Promise<void> {
+		await this.manager?.withdraw();
+	}
+
+	private requireManager(): MatchmakingProviderManager {
+		if (this.manager === undefined) {
+			throw new Error("MatchmakingProviderSession: register() must precede setCapacity()/signalFull()");
+		}
+		return this.manager;
+	}
+}
+
+// --- seeker session ------------------------------------------------------------------------------
+
+/** The seeker registration inputs a {@link MatchmakingSeekerSession.register} call carries. */
+export interface SeekerRegistrationInput {
+	readonly wantCount: number;
+	readonly contactHint: string;
+	readonly filter?: CapabilityFilter;
+	readonly pushOnArrival?: boolean;
+}
+
+/** A {@link MatchmakingSeekerSession.walk} request — the hang-out engine's per-task knobs. */
+export interface SeekerWalkRequest {
+	readonly wantCount: number;
+	readonly patienceMs: number;
+	readonly filter?: CapabilityFilter;
+	/** Force the multi-cohort sweep even when the single-cohort walk would suffice (representativeness). */
+	readonly preferSweep?: boolean;
+}
+
+/** The injected substrate-I/O seam a seeker session drives. The FRET host binds these to libp2p RPCs. */
+export interface MatchmakingSeekerSessionDeps {
+	/** Participant-facing cohort-topic substrate API (seeker registration). */
+	readonly service: CohortTopicService;
+	/** Sign the seeker registration image. */
+	readonly sign: (payload: Uint8Array) => Promise<string>;
+	/** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+	readonly verifyEntry: EntrySigVerifier;
+	/** Topic anchor; defaults to db-core's ring-hash anchor. */
+	readonly anchor?: MatchTopicAnchor;
+	/** Build the seeker walk transport (register/query/renew/withdraw at a tier) for a topic. */
+	readonly walkTransport: (topicId: Uint8Array) => SeekerWalkTransport;
+	/** Issue a one-shot `QueryV1` (resolves the cohort from `q.topicId`). */
+	readonly queryCohort: (q: QueryV1) => Promise<QueryReplyV1>;
+	/** Estimate `d_max` for a topic (the size-estimator seam). */
+	readonly estimateDMax: (topicId: Uint8Array) => Promise<number>;
+	/** Build the multi-cohort sweep ports for a topic; absent ⇒ the sweep is unavailable (walk only). */
+	readonly sweepPorts?: (topicId: Uint8Array) => MultiCohortSweepPorts;
+	/** Seeker registration TTL (ms); default {@link MatchmakingSeekerManager}'s seeker TTL. */
+	readonly ttlMs?: number;
+	/** Hang-out decision config (default {@link import("@optimystic/db-core").DEFAULT_HANG_OUT_CONFIG}). */
+	readonly config?: HangOutConfig;
+	/** Assumed competing-seeker mean `wantCount`. */
+	readonly meanWantCount?: number;
+	/** Wall clock (unix ms); injectable for tests. */
+	readonly clock?: () => number;
+	/** Sleep for the requery cadence; injectable for tests. */
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Public seeker entry point: brief registration, one-shot query, and the hang-out `walk` (which escalates
+ * to the multi-cohort sweep on a hot topic). One session may register and walk independently.
+ */
+export class MatchmakingSeekerSession {
+	private readonly deps: MatchmakingSeekerSessionDeps;
+	private readonly anchor: MatchTopicAnchor;
+	private manager?: MatchmakingSeekerManager;
+
+	constructor(deps: MatchmakingSeekerSessionDeps) {
+		this.deps = deps;
+		this.anchor = deps.anchor ?? createMatchTopicAnchor();
+	}
+
+	/** Resolve the `topicId` for a topic ref. */
+	topicIdFor(topic: MatchTopicRef): Uint8Array {
+		return this.anchor.topicId(topic.kind, topic.label);
+	}
+
+	/** Register the seeker briefly at `topic` (cohort-topic T2, short TTL). */
+	async register(topic: MatchTopicRef, reg: SeekerRegistrationInput): Promise<void> {
+		const topicId = this.topicIdFor(topic);
+		const seeker = new MatchmakingSeeker({
+			topicId,
+			wantCount: reg.wantCount,
+			contactHint: reg.contactHint,
+			sign: this.deps.sign,
+			...(reg.filter !== undefined ? { filter: reg.filter } : {}),
+			...(reg.pushOnArrival !== undefined ? { pushOnArrival: reg.pushOnArrival } : {}),
+		});
+		this.manager = new MatchmakingSeekerManager({
+			service: this.deps.service,
+			seeker,
+			...(this.deps.ttlMs !== undefined ? { ttlMs: this.deps.ttlMs } : {}),
+		});
+		await this.manager.register();
+	}
+
+	/** Drop the seeker registration: sends a best-effort tombstone so the cohort frees the record
+	 * immediately (the record otherwise TTL-expires). No-op before register. */
+	async withdraw(): Promise<void> {
+		await this.manager?.withdraw();
+	}
+
+	/** Issue a one-shot `QueryV1` against the topic's cohort (resolved from `q.topicId`). */
+	async query(q: QueryV1): Promise<QueryReplyV1> {
+		return this.deps.queryCohort(q);
+	}
+
+	/**
+	 * Run the hang-out walk for `topic`, then — on a hot topic (`childCohortCount > 0`) or when
+	 * `preferSweep` is set, and when the sweep ports are bound — escalate to the multi-cohort sweep and
+	 * union the deduped providers. Returns the assembled (possibly `< wantCount`) provider set.
+	 */
+	async walk(topic: MatchTopicRef, want: SeekerWalkRequest): Promise<ProviderEntryV1[]> {
+		const topicId = this.topicIdFor(topic);
+		const dMax = await this.deps.estimateDMax(topicId);
+		const client = new SeekerWalkClient({
+			transport: this.deps.walkTransport(topicId),
+			topicId,
+			wantCount: want.wantCount,
+			dMax,
+			patienceMs: want.patienceMs,
+			verifyEntry: this.deps.verifyEntry,
+			...(want.filter !== undefined ? { filter: want.filter } : {}),
+			...(this.deps.config !== undefined ? { config: this.deps.config } : {}),
+			...(this.deps.meanWantCount !== undefined ? { meanWantCount: this.deps.meanWantCount } : {}),
+			...(this.deps.clock !== undefined ? { clock: this.deps.clock } : {}),
+			...(this.deps.sleep !== undefined ? { sleep: this.deps.sleep } : {}),
+		});
+		const result = await client.run();
+		const providers = new Map<string, ProviderEntryV1>(result.providers.map((p) => [p.participantId, p]));
+
+		const hot = result.maxChildCohortCount > 0;
+		const wantSweep = want.preferSweep === true || (hot && providers.size < want.wantCount);
+		if (wantSweep && this.deps.sweepPorts !== undefined) {
+			// Pass want.patienceMs as a fresh (coarser) bound — this path does not track a draining
+			// remainder (SeekerWalkClient ran on its own deadline). Still strictly better than unbounded.
+			const sweep = await runMultiCohortSweep(this.deps.sweepPorts(topicId), {
+				topicId,
+				wantCount: want.wantCount,
+				verifyEntry: this.deps.verifyEntry,
+				patienceMs: want.patienceMs,
+				...(want.filter !== undefined ? { filter: want.filter } : {}),
+				...(this.deps.clock !== undefined ? { clock: this.deps.clock } : {}),
+			});
+			for (const entry of sweep.providers) {
+				providers.set(entry.participantId, entry);
+			}
+		}
+		return [...providers.values()];
+	}
+}
+
+// --- voting quorum-discovery binding -------------------------------------------------------------
+
+/** Construction inputs for {@link createMatchmakingQuorumDiscovery}. */
+export interface MatchmakingQuorumDiscoveryDeps {
+	/** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+	readonly verifyEntry: EntrySigVerifier;
+	/** Build the seeker walk transport for a topic. */
+	readonly walkTransport: (topicId: Uint8Array) => SeekerWalkTransport;
+	/** Estimate `d_max` for a topic. */
+	readonly estimateDMax: (topicId: Uint8Array) => Promise<number>;
+	/** Build the multi-cohort sweep ports for a topic. */
+	readonly sweepPorts: (topicId: Uint8Array) => MultiCohortSweepPorts;
+	/** Optional capability filter applied to both the walk and the sweep. */
+	readonly filter?: CapabilityFilter;
+	/** Hang-out decision config (passed to the walk). */
+	readonly config?: HangOutConfig;
+	/** Assumed competing-seeker mean `wantCount` (passed to the walk). */
+	readonly meanWantCount?: number;
+	/** Wall clock (unix ms); injectable for tests. */
+	readonly clock?: () => number;
+	/** Sleep for the requery cadence; injectable for tests. */
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Bind the db-core voting {@link QuorumDiscovery} port (`docs/matchmaking.md` §Voting-quorum assembly)
+ * to the matchmaking substrate: `walk` runs the single-cohort hang-out walk and surfaces its hotness
+ * signal (`childCohortCount`); `sweep` runs {@link runMultiCohortSweep} across the high-population tier
+ * shards. `VotingQuorumAssembler` composes the two — walk, then sweep on a hot topic — re-validating
+ * every entry itself, so this binding stays a thin transport adapter.
+ */
+export function createMatchmakingQuorumDiscovery(deps: MatchmakingQuorumDiscoveryDeps): QuorumDiscovery {
+	return {
+		async walk(req: QuorumDiscoveryRequest): Promise<QuorumDiscoverySlice> {
+			const dMax = await deps.estimateDMax(req.topicId);
+			const client = new SeekerWalkClient({
+				transport: deps.walkTransport(req.topicId),
+				topicId: req.topicId,
+				wantCount: req.wantCount,
+				dMax,
+				patienceMs: req.patienceMs,
+				verifyEntry: deps.verifyEntry,
+				...(deps.filter !== undefined ? { filter: deps.filter } : {}),
+				...(deps.config !== undefined ? { config: deps.config } : {}),
+				...(deps.meanWantCount !== undefined ? { meanWantCount: deps.meanWantCount } : {}),
+				...(deps.clock !== undefined ? { clock: deps.clock } : {}),
+				...(deps.sleep !== undefined ? { sleep: deps.sleep } : {}),
+			});
+			const result = await client.run();
+			return { entries: result.providers, childCohortCount: result.maxChildCohortCount };
+		},
+		async sweep(req: QuorumDiscoveryRequest): Promise<QuorumDiscoverySlice> {
+			const result = await runMultiCohortSweep(deps.sweepPorts(req.topicId), {
+				topicId: req.topicId,
+				wantCount: req.wantCount,
+				verifyEntry: deps.verifyEntry,
+				patienceMs: req.patienceMs,
+				...(deps.filter !== undefined ? { filter: deps.filter } : {}),
+				...(deps.clock !== undefined ? { clock: deps.clock } : {}),
+			});
+			// The sweep hop has already crossed the ring — its childCohortCount is moot (the escalation
+			// decision is made). Report 0 so the assembler never double-escalates.
+			return { entries: result.providers, childCohortCount: 0 };
+		},
+	};
+}

package/src/matchmaking/protocols.ts

@@ -0,0 +1,51 @@
+/**
+ * Matchmaking libp2p protocol IDs (`docs/matchmaking.md` §Seeker query).
+ *
+ * Matchmaking is an application layered **above** the cohort-topic substrate, so it owns its own protocol
+ * family rather than riding the cohort-topic protocols (which carry only substrate concerns — register,
+ * gossip, promote, membership, sign). Exactly one protocol lives here today:
+ *
+ * - `query` — `QueryV1` → `QueryReplyV1`, the seeker's request-reply RPC against a cohort for the
+ *             providers/seekers it locally holds (the serve side is `query-transport.ts`; the seeker
+ *             walk client is the follow-on `matchmaking-query-rpc-seeker-walk`).
+ *
+ * The default (network-agnostic) ID omits the network segment; {@link makeMatchmakingProtocols} mirrors
+ * FRET's `makeProtocols(networkName)` so a named network namespaces its matchmaking protocols the same way
+ * FRET namespaces its routing protocols (and the cohort-topic / reactivity families namespace via their own
+ * `make*Protocols`). Production wires the network-agnostic default, matching the cohort-topic + reactivity
+ * families' production default.
+ */
+
+/** Base path for the matchmaking protocol family. */
+export const MATCHMAKING_BASE = "/optimystic/matchmaking/1.0.0" as const;
+
+/** `QueryV1` / `QueryReplyV1` — a seeker's query for a cohort's locally-held provider/seeker registrations. */
+export const PROTOCOL_MATCHMAKING_QUERY = `${MATCHMAKING_BASE}/query` as const;
+
+/** The matchmaking protocol IDs in registration order. */
+export interface MatchmakingProtocols {
+	readonly query: string;
+}
+
+/** Default (network-agnostic) protocol IDs, matching `docs/matchmaking.md`. */
+export const DEFAULT_MATCHMAKING_PROTOCOLS: MatchmakingProtocols = {
+	query: PROTOCOL_MATCHMAKING_QUERY,
+};
+
+/**
+ * Namespaced matchmaking 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_MATCHMAKING_PROTOCOLS}: the canonical, network-agnostic IDs omit the segment entirely
+ * (`/optimystic/matchmaking/1.0.0/...`); use those unless you need per-network namespacing.
+ */
+export function makeMatchmakingProtocols(networkName = "default"): MatchmakingProtocols {
+	const base = `/optimystic/${networkName}/matchmaking/1.0.0`;
+	return {
+		query: `${base}/query`,
+	};
+}
+
+/** All matchmaking protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export function matchmakingProtocolList(p: MatchmakingProtocols): string[] {
+	return [p.query];
+}

package/src/matchmaking/provider-manager.ts

@@ -0,0 +1,95 @@
+/**
+ * Matchmaking — provider manager (db-p2p, wires to the cohort-topic substrate).
+ *
+ * Drives a db-core {@link MatchmakingProvider}'s lifecycle against the participant-facing
+ * {@link CohortTopicService}: register at cohort-topic tier **T2 (functional)** with a profile-based
+ * TTL, renew to keep the record alive, and withdraw by ceasing renewal (`docs/matchmaking.md`
+ * §Provider registration).
+ *
+ * Self-throttling maps onto the substrate as follows (an honest gap surfaced for the reviewer): the
+ * cohort-topic `RenewV1` carries **no** `appPayload` and **no** `ttl` field — a renewal is a pure
+ * keep-alive touch. So a capacity change ("signal full", `capacityBudget = 0`) is realized by
+ * **re-registering** with the new signed payload (which updates the cohort record's `appState`), not
+ * by a renewal. Likewise immediate withdrawal (`RenewV1` TTL = 0 in the matchmaking doc) has no wire
+ * realization yet — {@link withdraw} stops renewing and lets the record age out by TTL. Per the
+ * §Provider self-throttling GROUNDING resolution, withdrawal is an **optimization, not correctness**,
+ * so passive TTL expiry is acceptable; an immediate-tombstone renew is a documented cohort-topic
+ * follow-on.
+ */
+
+import { Tier, providerTtlForProfile, type CohortTopicService, type MatchmakingProvider, type NodeProfile, type RegistrationHandle } from "@optimystic/db-core";
+
+/** Construction inputs for a {@link MatchmakingProviderManager}. */
+export interface MatchmakingProviderManagerOptions {
+	/** Participant-facing cohort-topic substrate API. */
+	readonly service: CohortTopicService;
+	/** The provider state/decision object this manager drives. */
+	readonly provider: MatchmakingProvider;
+	/** Provider TTL (ms). Default: derived from {@link profile} via `providerTtlForProfile`. */
+	readonly ttlMs?: number;
+	/** Node profile used to derive the TTL when {@link ttlMs} is absent (Core 90 s / Edge 60 s). */
+	readonly profile?: NodeProfile;
+}
+
+/** Wires one matchmaking provider to the cohort-topic substrate at tier T2. */
+export class MatchmakingProviderManager {
+	private readonly service: CohortTopicService;
+	private readonly provider: MatchmakingProvider;
+	private readonly ttlMs: number;
+	private handle?: RegistrationHandle;
+
+	constructor(options: MatchmakingProviderManagerOptions) {
+		this.service = options.service;
+		this.provider = options.provider;
+		this.ttlMs = options.ttlMs ?? (options.profile !== undefined ? providerTtlForProfile(options.profile) : undefined) ?? DEFAULT_PROVIDER_TTL_MS;
+	}
+
+	/** The live registration handle, or `undefined` before the first {@link register}. */
+	get registration(): RegistrationHandle | undefined {
+		return this.handle;
+	}
+
+	/** Register (or re-register) the provider at tier T2 with the current signed payload. */
+	async register(): Promise<RegistrationHandle> {
+		const appPayload = await this.provider.appPayloadBytes();
+		this.handle = await this.service.register({
+			topicId: this.provider.topicId,
+			tier: Tier.T2,
+			appPayload,
+			ttl: this.ttlMs,
+		});
+		return this.handle;
+	}
+
+	/** Run one renewal cycle (keep-alive touch). No-op before the first {@link register}. */
+	async renew(): Promise<void> {
+		if (this.handle === undefined) {
+			return;
+		}
+		await this.service.renew(this.handle);
+	}
+
+	/** Set the live capacity budget and push it by re-registering (`RenewV1` cannot carry payload). */
+	async setCapacity(budget: number): Promise<RegistrationHandle> {
+		this.provider.setCapacity(budget);
+		return this.register();
+	}
+
+	/** Signal "available but at capacity" (`capacityBudget = 0`) and push it by re-registering. */
+	async signalFull(): Promise<RegistrationHandle> {
+		this.provider.signalFull();
+		return this.register();
+	}
+
+	/** Withdraw: stop renewing and send a best-effort signed tombstone so the cohort frees the record
+	 * immediately; TTL expiry is the fallback (the immediate tombstone is an optimization, not correctness). */
+	async withdraw(): Promise<void> {
+		this.provider.markWithdrawn();
+		if (this.handle !== undefined) {
+			await this.service.withdraw(this.handle);
+		}
+	}
+}
+
+/** Fallback provider TTL when neither an explicit `ttlMs` nor a `profile` is supplied (Core default). */
+const DEFAULT_PROVIDER_TTL_MS = 90_000;