@optimystic/db-core 0.21.0 → 0.24.0

package/src/matchmaking/provider.ts

@@ -1,123 +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;
-}
+/**
+ * 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

@@ -1,105 +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;
-}
+/**
+ * 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;
+}