@optimystic/db-core 0.13.5 → 0.14.0

package/src/matchmaking/multi-cohort-seeker.ts

@@ -0,0 +1,234 @@
+/**
+ * Matchmaking — multi-cohort sweep (db-core, pure orchestration of the hot-topic representative sample).
+ *
+ * Per `docs/matchmaking.md` §Multi-cohort sweep. When a topic is hot enough that its providers live
+ * across many tier-`d >= 1` cohorts, a seeker that wants a *representative* cross-ring sample (rather
+ * than the prefix-biased single-cohort slice) does:
+ *
+ *  1. Registers at its natural tier as usual (the single-cohort {@link import("./seeker-walk.js").decide}
+ *     walk — not this module).
+ *  2. Queries the **root** cohort, which returns an {@link AggregateCountV1}: log-bucketed provider counts
+ *     per tier-1 prefix shard, **threshold-signed**. A cold root that fell through to `NoState` produces
+ *     no aggregate (the producer gates on tree depth — see `db-p2p/matchmaking/aggregate-counts.ts`).
+ *  3. Selects the high-population tier-1 shards ({@link selectShards}) and queries them directly, unioning
+ *     the returned providers into a deduped, re-validated set.
+ *
+ * This module is **pure**: the root-aggregate fetch, the per-shard query, and the optional threshold-sig
+ * verification are injected as a {@link MultiCohortSweepPorts} port (db-p2p binds them to the matchmaking
+ * query RPCs), exactly like the single-cohort walk splits pure `decide` (here) from the db-p2p walk
+ * client. The advisory trust model is preserved end-to-end: every shard entry is re-validated with
+ * {@link verifyProviderEntry} before it counts, so a lying shard primary buys nothing.
+ *
+ * The sweep costs more RPCs than the single-cohort sample and is reserved for representativeness-over-
+ * latency use cases (voting quorums, capability fairness audits); db-p2p binds it to the voting
+ * `QuorumDiscovery.sweep` port.
+ */
+
+import { matchesFilter } from "./capability-filter.js";
+import { verifyProviderEntry, type AggregateCountV1, type CapabilityFilter, type EntrySigVerifier, type ProviderEntryV1 } from "./wire.js";
+
+/** The tier whose prefix shards the sweep ranges over (`docs/matchmaking.md` §Wire formats — typically 1). */
+export const DEFAULT_SWEEP_TARGET_TIER = 1;
+/** Fan-out ceiling: never query more than this many shards in one sweep (bounds RPC cost). */
+export const DEFAULT_SWEEP_MAX_SHARDS = 16;
+/**
+ * Multiplier on `wantCount` when accumulating bucketed shard populations. `1` because {@link logBucketCount}
+ * already rounds counts *down* — the true population is `>=` the reported sum, so the selection already
+ * over-provisions without an extra factor.
+ */
+export const DEFAULT_SWEEP_OVERPROVISION = 1;
+
+/** One tier-1 prefix shard the sweep elected to query, with its (bucketed) reported population. */
+export interface ShardSelection {
+	/** Prefix slot `0..F-1` identifying the tier-1 cohort. */
+	readonly prefixSlot: number;
+	/** The tier whose shard this is (typically 1). */
+	readonly targetTier: number;
+	/** The shard's log-bucketed reported provider count (rounds down — see {@link logBucketCount}). */
+	readonly bucketedCount: number;
+}
+
+/** Inputs to {@link selectShards}. */
+export interface SelectShardsOptions {
+	/** Providers the seeker needs (drives how many shards are unioned). */
+	readonly wantCount: number;
+	/** Which `targetTier` buckets to consider. Default {@link DEFAULT_SWEEP_TARGET_TIER}. */
+	readonly targetTier?: number;
+	/** Fan-out ceiling. Default {@link DEFAULT_SWEEP_MAX_SHARDS}. */
+	readonly maxShards?: number;
+	/** Multiplier on `wantCount`. Default {@link DEFAULT_SWEEP_OVERPROVISION}. */
+	readonly overprovision?: number;
+}
+
+/**
+ * Choose which tier-1 shards to query from an {@link AggregateCountV1}: the highest-population shards
+ * first (ties broken by ascending `prefixSlot` for determinism), accumulating bucketed counts until they
+ * cover `wantCount * overprovision`, capped at `maxShards`. Empty shards (`count === 0`) are skipped.
+ * Pure and deterministic.
+ */
+export function selectShards(aggregate: AggregateCountV1, opts: SelectShardsOptions): ShardSelection[] {
+	const targetTier = opts.targetTier ?? DEFAULT_SWEEP_TARGET_TIER;
+	const maxShards = opts.maxShards ?? DEFAULT_SWEEP_MAX_SHARDS;
+	const overprovision = opts.overprovision ?? DEFAULT_SWEEP_OVERPROVISION;
+	const need = Math.max(1, Math.ceil(opts.wantCount * overprovision));
+
+	const ranked = aggregate.bucketCounts
+		.filter((b) => b.targetTier === targetTier && b.count > 0)
+		.sort((a, b) => b.count - a.count || a.prefixSlot - b.prefixSlot);
+
+	const selected: ShardSelection[] = [];
+	let cumulative = 0;
+	for (const bucket of ranked) {
+		if (selected.length >= maxShards) {
+			break;
+		}
+		selected.push({ prefixSlot: bucket.prefixSlot, targetTier: bucket.targetTier, bucketedCount: bucket.count });
+		cumulative += bucket.count;
+		if (cumulative >= need) {
+			break;
+		}
+	}
+	return selected;
+}
+
+/** Identifies one tier shard to query directly (db-p2p resolves it to `coord_d` and dials the cohort). */
+export interface SweepShardQuery {
+	readonly prefixSlot: number;
+	readonly targetTier: number;
+}
+
+/**
+ * The transport seam the sweep drives, injected by db-p2p. `fetchAggregate` queries the root cohort
+ * (resolving `undefined` when the root is cold / unpromoted and returns no {@link AggregateCountV1});
+ * `queryShard` queries one elected tier-1 cohort; `verifyAggregate` (optional) threshold-verifies the
+ * aggregate before its counts are trusted.
+ */
+export interface MultiCohortSweepPorts {
+	/** Query the root cohort for the aggregate; `undefined` when the root produced none (cold / unpromoted). */
+	fetchAggregate(): Promise<AggregateCountV1 | undefined>;
+	/** Threshold-verify the aggregate (db-p2p binds the cohort crypto). Omitted → trusted unconditionally. */
+	verifyAggregate?(aggregate: AggregateCountV1): boolean;
+	/** Query one elected shard; returns its advisory provider entries (the sweep re-validates each). */
+	queryShard(shard: SweepShardQuery): Promise<readonly ProviderEntryV1[]>;
+}
+
+/** Inputs to {@link runMultiCohortSweep}. */
+export interface MultiCohortSweepOptions {
+	/** The matchmaking topic id (used to re-validate each forwarded entry's `registrationSig`). */
+	readonly topicId: Uint8Array;
+	/** Providers the seeker needs (drives shard selection). */
+	readonly wantCount: number;
+	/** Per-entry signature verifier (db-p2p binds `verifyPeerSig`). */
+	readonly verifyEntry: EntrySigVerifier;
+	/** Optional capability filter, re-applied over every shard's returned set. */
+	readonly filter?: CapabilityFilter;
+	/** Which `targetTier` shards to range over. Default {@link DEFAULT_SWEEP_TARGET_TIER}. */
+	readonly targetTier?: number;
+	/** Fan-out ceiling. Default {@link DEFAULT_SWEEP_MAX_SHARDS}. */
+	readonly maxShards?: number;
+	/** Multiplier on `wantCount`. Default {@link DEFAULT_SWEEP_OVERPROVISION}. */
+	readonly overprovision?: number;
+	/**
+	 * Patience budget (ms) for the whole sweep; drains across the shard fan-out. Omitted ⇒ unbounded
+	 * (query every selected shard, today's behaviour). Mirrors the walk leg's budget.
+	 */
+	readonly patienceMs?: number;
+	/** Wall clock (unix ms); injectable for tests. Default `Date.now`. Only consulted when `patienceMs` set. */
+	readonly clock?: () => number;
+}
+
+/** The assembled result of a multi-cohort sweep. */
+export interface MultiCohortSweepResult {
+	/** The unioned, filtered, `registrationSig`-re-validated providers, deduped by `participantId`. */
+	readonly providers: ProviderEntryV1[];
+	/** The shards selected from the aggregate (empty when no aggregate / untrusted). */
+	readonly selectedShards: ShardSelection[];
+	/** How many shards were actually queried (== `selectedShards.length` on success). */
+	readonly shardsQueried: number;
+	/** Whether the root produced an aggregate at all (`false` for a cold / unpromoted root). */
+	readonly aggregateAvailable: boolean;
+	/** Whether the aggregate's threshold signature verified (`false` when absent or invalid). */
+	readonly aggregateTrusted: boolean;
+}
+
+/** An empty result (no aggregate, or an aggregate that failed verification). */
+function emptyResult(aggregateAvailable: boolean, aggregateTrusted: boolean): MultiCohortSweepResult {
+	return { providers: [], selectedShards: [], shardsQueried: 0, aggregateAvailable, aggregateTrusted };
+}
+
+/**
+ * Run the multi-cohort sweep (`docs/matchmaking.md` §Multi-cohort sweep): fetch the root aggregate,
+ * threshold-verify it, select high-population shards, query each, and union the deduped + re-validated
+ * providers. A cold root (no aggregate) or an aggregate that fails verification yields an empty set so
+ * the caller falls back to the single-cohort sample. Each shard entry is filtered and
+ * `registrationSig`-re-validated before it counts — the cohort vouches only for "the set I held".
+ *
+ * When `opts.patienceMs` is supplied, a wall-clock deadline is fixed at entry and the shard fan-out
+ * stops as soon as the budget drains — mirroring the walk leg's patience model. This is
+ * "stop starting new shard queries": an in-flight `queryShard` call is not cancelled mid-flight.
+ * When `opts.patienceMs` is absent, every elected shard is queried (today's behaviour).
+ */
+export async function runMultiCohortSweep(ports: MultiCohortSweepPorts, opts: MultiCohortSweepOptions): Promise<MultiCohortSweepResult> {
+	// Budget: optional wall-clock deadline mirroring the walk leg. Only consulted when patienceMs is set.
+	const clock = opts.clock ?? ((): number => Date.now());
+	const deadline = opts.patienceMs !== undefined ? clock() + opts.patienceMs : undefined;
+	const remaining = (): number => (deadline !== undefined ? Math.max(0, deadline - clock()) : Infinity);
+	// If the budget is already drained on entry, skip even the aggregate RPC — the walk already consumed
+	// all patience and there is no point spending an RPC on an aggregate we have no time to act on.
+	if (deadline !== undefined && remaining() <= 0) {
+		return emptyResult(false, false);
+	}
+
+	const aggregate = await ports.fetchAggregate();
+	if (aggregate === undefined) {
+		return emptyResult(false, false);
+	}
+	// `aggregateTrusted` is asserted only when a verifier actually ran and passed. With no verifier injected
+	// the sweep still proceeds — every shard entry is `registrationSig`-re-validated below, so a forged
+	// aggregate can at worst mis-steer shard selection (wasted RPCs / a thinner sample), never inject
+	// providers — but the flag stays honest rather than claiming a trust that was never established.
+	const aggregateTrusted = ports.verifyAggregate !== undefined;
+	if (ports.verifyAggregate !== undefined && !ports.verifyAggregate(aggregate)) {
+		return emptyResult(true, false);
+	}
+
+	const selectShardOpts: SelectShardsOptions = { wantCount: opts.wantCount };
+	if (opts.targetTier !== undefined) {
+		(selectShardOpts as { targetTier: number }).targetTier = opts.targetTier;
+	}
+	if (opts.maxShards !== undefined) {
+		(selectShardOpts as { maxShards: number }).maxShards = opts.maxShards;
+	}
+	if (opts.overprovision !== undefined) {
+		(selectShardOpts as { overprovision: number }).overprovision = opts.overprovision;
+	}
+	const selected = selectShards(aggregate, selectShardOpts);
+
+	const matched = new Map<string, ProviderEntryV1>();
+	let shardsQueried = 0;
+	for (const shard of selected) {
+		// Stop starting new shard queries once the budget has drained.
+		if (remaining() <= 0) {
+			break;
+		}
+		const entries = await ports.queryShard({ prefixSlot: shard.prefixSlot, targetTier: shard.targetTier });
+		shardsQueried++;
+		for (const entry of entries) {
+			if (!matchesFilter(entry, opts.filter)) {
+				continue;
+			}
+			if (!verifyProviderEntry(opts.topicId, entry, opts.verifyEntry)) {
+				continue;
+			}
+			matched.set(entry.participantId, entry);
+		}
+	}
+
+	return {
+		providers: [...matched.values()],
+		selectedShards: selected,
+		shardsQueried,
+		aggregateAvailable: true,
+		aggregateTrusted,
+	};
+}

package/src/matchmaking/provider.ts

@@ -0,0 +1,123 @@
+/**
+ * Matchmaking — provider decision/state (db-core, transport-agnostic).
+ *
+ * A {@link MatchmakingProvider} owns the live provider state for one topic: its capability tags, its
+ * current `capacityBudget`, and a correlation id (registration identity; not bound into the
+ * matchmaking signature — see {@link providerSigningPayload} option (b)). It builds the
+ * signed {@link ProviderAppPayloadV1} (and the opaque bytes for the cohort-topic
+ * `RegisterV1.appPayload` slot) that the db-p2p `provider-manager` registers at cohort-topic tier
+ * **T2** (`docs/matchmaking.md` §Provider registration).
+ *
+ * It is crypto-free: signing is an injected callback (db-p2p supplies the libp2p peer key), matching
+ * the cohort-topic {@link import("../cohort-topic/service.js").ParticipantSigner} pattern.
+ *
+ * Self-throttling (`docs/matchmaking.md` §Provider self-throttling) is expressed here as state:
+ * - **Signal full** — {@link MatchmakingProvider.signalFull} sets `capacityBudget = 0`; the provider
+ *   stays listed as "available but at capacity". The manager re-registers to push the new payload
+ *   (the cohort-topic `RenewV1` carries no `appPayload`, so a capacity change is a re-register, not a
+ *   ping — see the implement handoff).
+ * - **Withdraw** — {@link MatchmakingProvider.markWithdrawn} records intent; the manager stops
+ *   renewing so the record ages out by TTL. Withdrawal is an **optimization, not a correctness
+ *   requirement** (§Provider self-throttling, GROUNDING resolution): a non-withdrawn registration is
+ *   bounded by TTL eviction.
+ */
+
+import { randomBytes } from "@noble/hashes/utils.js";
+import { providerSigningPayload, type ProviderAppPayloadV1, encodeProviderAppPayload } from "./wire.js";
+
+/** Construction inputs for a {@link MatchmakingProvider}. */
+export interface MatchmakingProviderOptions {
+	/** The matchmaking topic this provider serves (from {@link import("./topic-anchor.js").MatchTopicAnchor}). */
+	readonly topicId: Uint8Array;
+	/** Application-defined capability tags. */
+	readonly capabilities: readonly string[];
+	/** Initial concurrent-task budget (integer `>= 0`). */
+	readonly capacityBudget: number;
+	/** Multiaddr or PeerId-based callback. */
+	readonly contactHint: string;
+	/** Optional soft expiry hint (unix ms). */
+	readonly serviceUntil?: number;
+	/** Sign the canonical registration image; resolves the base64url signature. */
+	readonly sign: (payload: Uint8Array) => Promise<string>;
+	/** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
+	readonly correlationId?: Uint8Array;
+	/** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
+	readonly randomBytes?: (n: number) => Uint8Array;
+}
+
+/** Live provider state + signed-payload builder for one matchmaking topic. */
+export class MatchmakingProvider {
+	readonly topicId: Uint8Array;
+	readonly correlationId: Uint8Array;
+	private readonly capabilities: readonly string[];
+	private readonly contactHint: string;
+	private readonly serviceUntil?: number;
+	private readonly sign: (payload: Uint8Array) => Promise<string>;
+	private capacity: number;
+	private withdrawnFlag = false;
+
+	constructor(options: MatchmakingProviderOptions) {
+		this.topicId = options.topicId;
+		this.capabilities = [...options.capabilities];
+		this.contactHint = options.contactHint;
+		this.serviceUntil = options.serviceUntil;
+		this.sign = options.sign;
+		this.capacity = requireBudget(options.capacityBudget);
+		const rand = options.randomBytes ?? randomBytes;
+		this.correlationId = options.correlationId ?? rand(16);
+	}
+
+	/** Current concurrent-task budget; `0` means "listed but full". */
+	get capacityBudget(): number {
+		return this.capacity;
+	}
+
+	/** True once {@link markWithdrawn} has been called (the manager should stop renewing). */
+	get withdrawn(): boolean {
+		return this.withdrawnFlag;
+	}
+
+	/** Set the live budget (integer `>= 0`). The next built payload reflects it. */
+	setCapacity(budget: number): void {
+		this.capacity = requireBudget(budget);
+	}
+
+	/** Signal "available but at capacity" by setting `capacityBudget = 0` (§Provider self-throttling). */
+	signalFull(): void {
+		this.capacity = 0;
+	}
+
+	/** Record withdrawal intent; the manager stops renewing so the record TTL-expires (optimization). */
+	markWithdrawn(): void {
+		this.withdrawnFlag = true;
+	}
+
+	/** Build the signed {@link ProviderAppPayloadV1} reflecting the current capacity. */
+	async buildAppPayload(): Promise<ProviderAppPayloadV1> {
+		const signature = await this.sign(providerSigningPayload(this.topicId, this.capabilities, this.capacity));
+		const payload: ProviderAppPayloadV1 = {
+			kind: "match-provider",
+			capabilities: [...this.capabilities],
+			capacityBudget: this.capacity,
+			contactHint: this.contactHint,
+			signature,
+		};
+		if (this.serviceUntil !== undefined) {
+			payload.serviceUntil = this.serviceUntil;
+		}
+		return payload;
+	}
+
+	/** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
+	async appPayloadBytes(): Promise<Uint8Array> {
+		return encodeProviderAppPayload(await this.buildAppPayload());
+	}
+}
+
+/** Validate a capacity budget is an integer `>= 0`. */
+function requireBudget(budget: number): number {
+	if (!Number.isInteger(budget) || budget < 0) {
+		throw new RangeError(`matchmaking provider: capacityBudget must be an integer >= 0, got ${budget}`);
+	}
+	return budget;
+}

package/src/matchmaking/query-eval.ts

@@ -0,0 +1,105 @@
+/**
+ * Matchmaking — pure `QueryV1` evaluation (db-core, transport-agnostic).
+ *
+ * The cohort-side query handler (`db-p2p/src/matchmaking/query-handler.ts`) decodes its local
+ * registration records into the {@link LocalProviderRegistration} / {@link LocalSeekerRegistration}
+ * shapes below and hands them here; this module performs the *advisory* selection that
+ * `docs/matchmaking.md` §Seeker query / §Capability filter specify:
+ *
+ * - Providers are filtered through {@link matchesFilter} (when `includeProviders`).
+ * - Each included set is truncated to `query.limit` (`<= query_limit_max`, enforced on decode in
+ *   `wire.ts`); {@link QueryEvalResult.truncated} is set when *any* included set had more matches than
+ *   `limit` allowed, so the seeker knows to re-query a sibling cohort.
+ * - The forwarded entries carry the provider/seeker's own `registrationSig` verbatim, so the seeker
+ *   re-validates each one (`verifyProviderEntry`) — the cohort vouches only for the *set it held*.
+ *
+ * Pure: no I/O, no clock, no crypto. The db-p2p handler attaches `topicTraffic` / `cohortEpoch` and
+ * the primary's reply signature.
+ */
+
+import { matchesFilter } from "./capability-filter.js";
+import type { ProviderAppPayloadV1, SeekerAppPayloadV1, ProviderEntryV1, SeekerEntryV1, QueryV1 } from "./wire.js";
+
+/** A decoded local provider registration held by the cohort, ready for {@link evaluateQuery}. */
+export interface LocalProviderRegistration {
+	/** The provider's peer-id string — the entry's `participantId` AND the `registrationSig` signer. */
+	readonly participantId: string;
+	/** Unix ms the registration first attached (forwarded verbatim for seeker FCFS ordering). */
+	readonly attachedAt: number;
+	/** The decoded, validated provider app payload (capabilities, budget, contact, signature). */
+	readonly payload: ProviderAppPayloadV1;
+}
+
+/** A decoded local seeker registration held by the cohort (collective-assembly discovery). */
+export interface LocalSeekerRegistration {
+	readonly participantId: string;
+	readonly attachedAt: number;
+	readonly payload: SeekerAppPayloadV1;
+}
+
+/** The selected entries for a {@link QueryReplyV1} body (the db-p2p handler signs + frames it). */
+export interface QueryEvalResult {
+	readonly providers?: ProviderEntryV1[];
+	readonly seekers?: SeekerEntryV1[];
+	/** `true` when an included set had more matches than `query.limit` allowed (re-query hint). */
+	readonly truncated: boolean;
+}
+
+/** Build a forwarded {@link ProviderEntryV1} from a local registration (signature forwarded verbatim). */
+export function providerEntryOf(reg: LocalProviderRegistration): ProviderEntryV1 {
+	return {
+		participantId: reg.participantId,
+		capabilities: [...reg.payload.capabilities],
+		capacityBudget: reg.payload.capacityBudget,
+		contactHint: reg.payload.contactHint,
+		attachedAt: reg.attachedAt,
+		registrationSig: reg.payload.signature,
+	};
+}
+
+/** Build a forwarded {@link SeekerEntryV1} from a local registration (signature forwarded verbatim). */
+export function seekerEntryOf(reg: LocalSeekerRegistration): SeekerEntryV1 {
+	return {
+		participantId: reg.participantId,
+		wantCount: reg.payload.wantCount,
+		contactHint: reg.payload.contactHint,
+		attachedAt: reg.attachedAt,
+		registrationSig: reg.payload.signature,
+	};
+}
+
+/**
+ * Evaluate `query` against the cohort's locally-held registrations: filter providers, optionally include
+ * seekers, truncate each included set to `query.limit`. Inputs are returned in `attachedAt` order
+ * (oldest first) so truncation keeps the longest-waiting registrations — the FCFS bias the arrival-push
+ * fairness rule also uses (`docs/matchmaking.md` §Fairness).
+ */
+export function evaluateQuery(
+	query: QueryV1,
+	providers: readonly LocalProviderRegistration[],
+	seekers: readonly LocalSeekerRegistration[],
+): QueryEvalResult {
+	let truncated = false;
+	const result: { providers?: ProviderEntryV1[]; seekers?: SeekerEntryV1[]; truncated: boolean } = { truncated: false };
+
+	if (query.includeProviders) {
+		const matched = providers
+			.filter((reg) => matchesFilter(reg.payload, query.filter))
+			.sort((a, b) => a.attachedAt - b.attachedAt);
+		if (matched.length > query.limit) {
+			truncated = true;
+		}
+		result.providers = matched.slice(0, query.limit).map(providerEntryOf);
+	}
+
+	if (query.includeSeekers) {
+		const ordered = [...seekers].sort((a, b) => a.attachedAt - b.attachedAt);
+		if (ordered.length > query.limit) {
+			truncated = true;
+		}
+		result.seekers = ordered.slice(0, query.limit).map(seekerEntryOf);
+	}
+
+	result.truncated = truncated;
+	return result;
+}

package/src/matchmaking/seeker-walk.ts

@@ -0,0 +1,127 @@
+/**
+ * Matchmaking — seeker hang-out-vs-continue decision engine (db-core, pure).
+ *
+ * Per `docs/matchmaking.md` §Hang-out vs. continue. After a seeker registers at a cohort and receives
+ * `Accepted` with `topicTraffic` at tree tier `d`, it must decide: is *this* tier the right place to
+ * wait, or should it walk one tier toward the root? This module is the pure arithmetic of that choice
+ * — no I/O, no clock — so it is unit-testable directly against the doc's worked examples. The db-p2p
+ * `seeker-walk-client` drives the walk (register / query / renew / withdraw) and calls {@link decide}.
+ *
+ * Decision rule (`docs/matchmaking.md` §Decision rule):
+ *
+ * 1. **Immediate-match.** If `currentMatches >= wantCount` → `done`. (The caller has already issued the
+ *    `QueryV1`; `currentMatches` is its filter-matched, re-validated yield. This also covers edge case 2
+ *    — a stale `arrivalsPerMin = 0` after an epoch rotation still gets a real query first, so a quiet
+ *    cohort that actually holds enough providers resolves to `done` rather than a spurious escalate.)
+ * 2. **Hang-out feasibility.**
+ *    ```
+ *    expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)
+ *    contentionFactor   ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)
+ *    hang out  iff  currentMatches + expectedNewMatches ≥ wantCount × contentionFactor
+ *    ```
+ * 3. **Otherwise escalate** (walk one tier toward the root).
+ *
+ * Edge cases the engine encodes (the rest live in the walk client, which owns the walk topology):
+ * - **Filter matches almost nothing (case 4):** a `filterAcceptRatio` decayed toward 0 collapses
+ *   `expectedNewMatches`, so the feasibility test fails at every tier and the seeker walks to the root.
+ * - **Many seekers competing (case 5):** a high `queriesPerMin` inflates `contentionFactor` up to
+ *   `cap`, raising the threshold so more seekers escalate toward aggregation — self-balancing, bounded.
+ */
+
+import type { HangOutConfig } from "./config.js";
+import { FILTER_ACCEPT_RATIO_INITIAL, MEAN_WANT_COUNT_DEFAULT } from "./config.js";
+
+/** Inputs to {@link decide}: the cohort's `topicTraffic` plus the seeker's running state. */
+export interface SeekerDecisionInputs {
+	/** Filter-matched, re-validated providers from the immediate `QueryV1` at this tier. */
+	readonly currentMatches: number;
+	/** `topicTraffic.directParticipants` — informational (providers known here right now). */
+	readonly directParticipants: number;
+	/** `topicTraffic.arrivalsPerMin` — provider registration + renewal rate. */
+	readonly arrivalsPerMin: number;
+	/** `topicTraffic.queriesPerMin` — competing seeker activity over the same pool. */
+	readonly queriesPerMin: number;
+	/** `topicTraffic.childCohortCount` — `> 0` means this tier has promoted (descend territory). */
+	readonly childCohortCount: number;
+	/** Providers the seeker needs. */
+	readonly wantCount: number;
+	/** Patience budget left at this tier (drains across walked tiers — the client tracks it). */
+	readonly patienceMsRemaining: number;
+	/** Running estimate of the fraction of returned providers that pass the seeker's filter (decays from 1.0). */
+	readonly filterAcceptRatio: number;
+	/** Assumed mean `wantCount` of competing seekers (small constant or learned). */
+	readonly meanWantCount: number;
+}
+
+/** The outcome of {@link decide}. `hangOut` carries the poll cadence for the requery loop. */
+export type SeekerDecision =
+	| { readonly action: "done" }
+	| { readonly action: "hangOut"; readonly requeryIntervalMs: number }
+	| { readonly action: "escalate" };
+
+/** `expectedNewMatches ≈ arrivalsPerMin × filterAcceptRatio × (patienceMsRemaining / 60000)`. */
+export function expectedNewMatches(inputs: SeekerDecisionInputs): number {
+	return inputs.arrivalsPerMin * inputs.filterAcceptRatio * (inputs.patienceMsRemaining / 60_000);
+}
+
+/** `contentionFactor ≈ min(1 + (queriesPerMin × meanWantCount) / max(arrivalsPerMin, 1), cap)`. */
+export function contentionFactor(inputs: SeekerDecisionInputs, cfg: HangOutConfig): number {
+	const raw = 1 + (inputs.queriesPerMin * inputs.meanWantCount) / Math.max(inputs.arrivalsPerMin, 1);
+	return Math.min(raw, cfg.contentionFactorCap);
+}
+
+/** The hang-out feasibility threshold `wantCount × contentionFactor`. */
+export function hangOutThreshold(inputs: SeekerDecisionInputs, cfg: HangOutConfig): number {
+	return inputs.wantCount * contentionFactor(inputs, cfg);
+}
+
+/**
+ * Decide whether the seeker is `done` (immediate match), should `hangOut` (feasible to wait here), or
+ * should `escalate` (walk one tier toward the root). Pure — see the module header for the rule.
+ */
+export function decide(inputs: SeekerDecisionInputs, cfg: HangOutConfig): SeekerDecision {
+	if (inputs.currentMatches >= inputs.wantCount) {
+		return { action: "done" };
+	}
+	const projected = inputs.currentMatches + expectedNewMatches(inputs);
+	if (projected >= hangOutThreshold(inputs, cfg)) {
+		return { action: "hangOut", requeryIntervalMs: cfg.requeryIntervalMs };
+	}
+	return { action: "escalate" };
+}
+
+// --- filterAcceptRatio running refinement (`docs/matchmaking.md` §Decision rule / §Edge cases 4) ---
+
+/**
+ * Running yield accumulator for `filterAcceptRatio`. The ratio starts at `filter_accept_ratio_initial`
+ * (1.0, used before any observation) and is refined to the cumulative `matched / returned` over the
+ * walk: after two cohorts that each return ~10% matchable providers it settles near 0.1, collapsing
+ * `expectedNewMatches` for a pathological filter (edge case 4).
+ */
+export interface FilterAcceptRatioState {
+	/** Total filter-matched providers observed across queries so far. */
+	readonly matched: number;
+	/** Total providers returned across queries so far. */
+	readonly returned: number;
+}
+
+/** A fresh (zero-observation) {@link FilterAcceptRatioState}. */
+export function newFilterAcceptRatioState(): FilterAcceptRatioState {
+	return { matched: 0, returned: 0 };
+}
+
+/** Fold one query's yield (`matched` of `returned`) into the running state. */
+export function observeYield(state: FilterAcceptRatioState, matched: number, returned: number): FilterAcceptRatioState {
+	return { matched: state.matched + matched, returned: state.returned + returned };
+}
+
+/**
+ * The current `filterAcceptRatio`: cumulative `matched / returned`, or `initial` (1.0) before any
+ * providers have been returned (so the first hang-out estimate is optimistic, then refines).
+ */
+export function filterAcceptRatio(state: FilterAcceptRatioState, initial: number = FILTER_ACCEPT_RATIO_INITIAL): number {
+	return state.returned > 0 ? state.matched / state.returned : initial;
+}
+
+/** The default assumed competing-seeker `meanWantCount` (re-exported for the walk client). */
+export const DEFAULT_MEAN_WANT_COUNT = MEAN_WANT_COUNT_DEFAULT;

package/src/matchmaking/seeker.ts

@@ -0,0 +1,86 @@
+/**
+ * Matchmaking — seeker registration state (db-core, transport-agnostic).
+ *
+ * A {@link MatchmakingSeeker} owns the short-lived seeker state for one topic and builds the signed
+ * {@link SeekerAppPayloadV1} that the db-p2p `seeker-manager` registers at cohort-topic tier **T2**
+ * with a short TTL (`seeker_ttl`, default 10 s — `docs/matchmaking.md` §Seeker query). The seeker
+ * registers briefly so other seekers can find it (collective assembly) and the cohort sees active
+ * demand.
+ *
+ * This module holds *registration* state only. The `QueryV1` issuance and the hang-out-vs-continue
+ * decision live in the pure {@link import("./seeker-walk.js").decide} engine and the db-p2p
+ * `seeker-walk-client` that drives the walk; the capability filter is {@link import("./capability-filter.js").matchesFilter}.
+ *
+ * Crypto-free: signing is an injected callback, matching {@link MatchmakingProvider}.
+ */
+
+import { randomBytes } from "@noble/hashes/utils.js";
+import { seekerSigningPayload, type CapabilityFilter, type SeekerAppPayloadV1, encodeSeekerAppPayload } from "./wire.js";
+
+/** Construction inputs for a {@link MatchmakingSeeker}. */
+export interface MatchmakingSeekerOptions {
+	/** The matchmaking topic this seeker is querying. */
+	readonly topicId: Uint8Array;
+	/** Number of providers desired (integer `>= 1`). */
+	readonly wantCount: number;
+	/** Multiaddr or PeerId-based callback (collective-assembly use). */
+	readonly contactHint: string;
+	/** Optional capability filter (evaluated cohort-side in the next ticket; carried here). */
+	readonly filter?: CapabilityFilter;
+	/** Opt into arrival pushes; default false (poll path). Consumed by the next ticket. */
+	readonly pushOnArrival?: boolean;
+	/** Sign the canonical registration image; resolves the base64url signature. */
+	readonly sign: (payload: Uint8Array) => Promise<string>;
+	/** 16-byte registration correlation id (not signature-bound); default fresh CSPRNG bytes. */
+	readonly correlationId?: Uint8Array;
+	/** CSPRNG source (injectable for deterministic tests). Default `@noble/hashes` `randomBytes`. */
+	readonly randomBytes?: (n: number) => Uint8Array;
+}
+
+/** Live seeker state + signed-payload builder for one matchmaking topic (registration only). */
+export class MatchmakingSeeker {
+	readonly topicId: Uint8Array;
+	readonly correlationId: Uint8Array;
+	private readonly wantCount: number;
+	private readonly contactHint: string;
+	private readonly filter?: CapabilityFilter;
+	private readonly pushOnArrival?: boolean;
+	private readonly sign: (payload: Uint8Array) => Promise<string>;
+
+	constructor(options: MatchmakingSeekerOptions) {
+		if (!Number.isInteger(options.wantCount) || options.wantCount < 1) {
+			throw new RangeError(`matchmaking seeker: wantCount must be an integer >= 1, got ${options.wantCount}`);
+		}
+		this.topicId = options.topicId;
+		this.wantCount = options.wantCount;
+		this.contactHint = options.contactHint;
+		this.filter = options.filter;
+		this.pushOnArrival = options.pushOnArrival;
+		this.sign = options.sign;
+		const rand = options.randomBytes ?? randomBytes;
+		this.correlationId = options.correlationId ?? rand(16);
+	}
+
+	/** Build the signed {@link SeekerAppPayloadV1} for this seeker's registration. */
+	async buildAppPayload(): Promise<SeekerAppPayloadV1> {
+		const signature = await this.sign(seekerSigningPayload(this.topicId, this.wantCount));
+		const payload: SeekerAppPayloadV1 = {
+			kind: "match-seeker",
+			wantCount: this.wantCount,
+			contactHint: this.contactHint,
+			signature,
+		};
+		if (this.filter !== undefined) {
+			payload.filter = this.filter;
+		}
+		if (this.pushOnArrival !== undefined) {
+			payload.pushOnArrival = this.pushOnArrival;
+		}
+		return payload;
+	}
+
+	/** Build the opaque bytes for the cohort-topic `RegisterV1.appPayload` slot. */
+	async appPayloadBytes(): Promise<Uint8Array> {
+		return encodeSeekerAppPayload(await this.buildAppPayload());
+	}
+}