@optimystic/db-core 0.21.0 → 0.24.0

package/src/matchmaking/seeker-walk.ts

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

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

package/src/matchmaking/topic-anchor.ts

@@ -1,90 +1,90 @@
-/**
- * Matchmaking — stable topic anchor.
- *
- * Transcribed from `docs/matchmaking.md` §Anchor:
- *
- * ```
- * topicId(kind, label) = H(kind ‖ label ‖ "match")
- * ```
- *
- * Unlike reactivity, matchmaking topics do **not** rotate — a task or capability label has a stable
- * identity over its useful lifetime, so the anchor is a pure function of `(kind, label)`.
- *
- * `kind` namespaces the topic so unrelated label spaces never collide; `label` is application-defined
- * (capability name, proposal hash, task-type id). The resulting `topicId` is fed verbatim into
- * cohort-topic tier addressing (`coord_d(self, topicId)`), so it is derived with the **same** hash
- * primitive cohort-topic uses for `coord_d` input — db-core's own {@link IRingHash} (SHA-256 truncated
- * to the ring width), **not** a FRET import. At the default `ringBits = 256` the anchor is a 32-byte
- * value, matching the cohort-topic `topicId` width.
- *
- * Concatenation is delimiter-free, exactly as the spec writes it. This is unambiguous because `kind`
- * is drawn from a closed set ({@link MATCH_TOPIC_KINDS}) in which no member is a prefix of another, so
- * `kind ‖ label` can never alias a different `(kind, label)` pair. The trailing `"match"` literal
- * domain-separates matchmaking anchors from any other application that might hash the same label.
- */
-
-import { createRingHash } from "../cohort-topic/ring-hash.js";
-import type { IRingHash } from "../cohort-topic/ports.js";
-
-/**
- * The category of a matchmaking topic. Namespaces the `label` space so unrelated topics never
- * collide on the ring (`docs/matchmaking.md` §Anchor).
- *
- * - `task` — a work-task type id; long-lived, matures a deep tree.
- * - `capability` — a capability name (storage class, region, hardware feature); long-lived.
- * - `quorum` — a voting-proposal hash; short-lived, forms a shallow tree that demotes once closed.
- * - `capacity-class` — a capacity bucket for capacity gossip.
- */
-export type MatchTopicKind = "task" | "capability" | "quorum" | "capacity-class";
-
-/** Every matchmaking topic kind. Validated against on the seeker/provider build path. */
-export const MATCH_TOPIC_KINDS: readonly MatchTopicKind[] = ["task", "capability", "quorum", "capacity-class"];
-
-/** Domain-separation suffix mixed into every matchmaking anchor. */
-const MATCH_SUFFIX = "match";
-
-const utf8 = new TextEncoder();
-
-/** Derives the stable `topicId` for a matchmaking `(kind, label)` pair. */
-export interface MatchTopicAnchor {
-	/** `H(kind ‖ label ‖ "match")` — the cohort-topic `topicId` for this matchmaking topic. */
-	topicId(kind: MatchTopicKind, label: string): Uint8Array;
-}
-
-/** True iff `kind` is one of the closed {@link MATCH_TOPIC_KINDS}. */
-export function isMatchTopicKind(kind: string): kind is MatchTopicKind {
-	return (MATCH_TOPIC_KINDS as readonly string[]).includes(kind);
-}
-
-class HashMatchTopicAnchor implements MatchTopicAnchor {
-	constructor(private readonly hash: IRingHash) {}
-
-	topicId(kind: MatchTopicKind, label: string): Uint8Array {
-		if (!isMatchTopicKind(kind)) {
-			throw new RangeError(`matchmaking topicId: unknown kind ${JSON.stringify(kind)}`);
-		}
-		const kindBytes = utf8.encode(kind);
-		const labelBytes = utf8.encode(label);
-		const suffixBytes = utf8.encode(MATCH_SUFFIX);
-		const input = new Uint8Array(kindBytes.length + labelBytes.length + suffixBytes.length);
-		input.set(kindBytes, 0);
-		input.set(labelBytes, kindBytes.length);
-		input.set(suffixBytes, kindBytes.length + labelBytes.length);
-		return this.hash.H(input);
-	}
-}
-
-/**
- * Build a {@link MatchTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
- * instance it binds to FRET's `RING_BITS`, so the anchor and cohort-topic routing keys line up; the
- * default constructs db-core's own {@link createRingHash} (256-bit SHA-256), which is byte-identical
- * to what the cohort-topic host uses.
- */
-export function createMatchTopicAnchor(hash: IRingHash = createRingHash()): MatchTopicAnchor {
-	return new HashMatchTopicAnchor(hash);
-}
-
-/** One-shot convenience: `H(kind ‖ label ‖ "match")` over the default db-core ring hash. */
-export function matchTopicId(kind: MatchTopicKind, label: string, hash: IRingHash = createRingHash()): Uint8Array {
-	return createMatchTopicAnchor(hash).topicId(kind, label);
-}
+/**
+ * Matchmaking — stable topic anchor.
+ *
+ * Transcribed from `docs/matchmaking.md` §Anchor:
+ *
+ * ```
+ * topicId(kind, label) = H(kind ‖ label ‖ "match")
+ * ```
+ *
+ * Unlike reactivity, matchmaking topics do **not** rotate — a task or capability label has a stable
+ * identity over its useful lifetime, so the anchor is a pure function of `(kind, label)`.
+ *
+ * `kind` namespaces the topic so unrelated label spaces never collide; `label` is application-defined
+ * (capability name, proposal hash, task-type id). The resulting `topicId` is fed verbatim into
+ * cohort-topic tier addressing (`coord_d(self, topicId)`), so it is derived with the **same** hash
+ * primitive cohort-topic uses for `coord_d` input — db-core's own {@link IRingHash} (SHA-256 truncated
+ * to the ring width), **not** a FRET import. At the default `ringBits = 256` the anchor is a 32-byte
+ * value, matching the cohort-topic `topicId` width.
+ *
+ * Concatenation is delimiter-free, exactly as the spec writes it. This is unambiguous because `kind`
+ * is drawn from a closed set ({@link MATCH_TOPIC_KINDS}) in which no member is a prefix of another, so
+ * `kind ‖ label` can never alias a different `(kind, label)` pair. The trailing `"match"` literal
+ * domain-separates matchmaking anchors from any other application that might hash the same label.
+ */
+
+import { createRingHash } from "../cohort-topic/ring-hash.js";
+import type { IRingHash } from "../cohort-topic/ports.js";
+
+/**
+ * The category of a matchmaking topic. Namespaces the `label` space so unrelated topics never
+ * collide on the ring (`docs/matchmaking.md` §Anchor).
+ *
+ * - `task` — a work-task type id; long-lived, matures a deep tree.
+ * - `capability` — a capability name (storage class, region, hardware feature); long-lived.
+ * - `quorum` — a voting-proposal hash; short-lived, forms a shallow tree that demotes once closed.
+ * - `capacity-class` — a capacity bucket for capacity gossip.
+ */
+export type MatchTopicKind = "task" | "capability" | "quorum" | "capacity-class";
+
+/** Every matchmaking topic kind. Validated against on the seeker/provider build path. */
+export const MATCH_TOPIC_KINDS: readonly MatchTopicKind[] = ["task", "capability", "quorum", "capacity-class"];
+
+/** Domain-separation suffix mixed into every matchmaking anchor. */
+const MATCH_SUFFIX = "match";
+
+const utf8 = new TextEncoder();
+
+/** Derives the stable `topicId` for a matchmaking `(kind, label)` pair. */
+export interface MatchTopicAnchor {
+	/** `H(kind ‖ label ‖ "match")` — the cohort-topic `topicId` for this matchmaking topic. */
+	topicId(kind: MatchTopicKind, label: string): Uint8Array;
+}
+
+/** True iff `kind` is one of the closed {@link MATCH_TOPIC_KINDS}. */
+export function isMatchTopicKind(kind: string): kind is MatchTopicKind {
+	return (MATCH_TOPIC_KINDS as readonly string[]).includes(kind);
+}
+
+class HashMatchTopicAnchor implements MatchTopicAnchor {
+	constructor(private readonly hash: IRingHash) {}
+
+	topicId(kind: MatchTopicKind, label: string): Uint8Array {
+		if (!isMatchTopicKind(kind)) {
+			throw new RangeError(`matchmaking topicId: unknown kind ${JSON.stringify(kind)}`);
+		}
+		const kindBytes = utf8.encode(kind);
+		const labelBytes = utf8.encode(label);
+		const suffixBytes = utf8.encode(MATCH_SUFFIX);
+		const input = new Uint8Array(kindBytes.length + labelBytes.length + suffixBytes.length);
+		input.set(kindBytes, 0);
+		input.set(labelBytes, kindBytes.length);
+		input.set(suffixBytes, kindBytes.length + labelBytes.length);
+		return this.hash.H(input);
+	}
+}
+
+/**
+ * Build a {@link MatchTopicAnchor} over the injected hash. db-p2p passes the same {@link IRingHash}
+ * instance it binds to FRET's `RING_BITS`, so the anchor and cohort-topic routing keys line up; the
+ * default constructs db-core's own {@link createRingHash} (256-bit SHA-256), which is byte-identical
+ * to what the cohort-topic host uses.
+ */
+export function createMatchTopicAnchor(hash: IRingHash = createRingHash()): MatchTopicAnchor {
+	return new HashMatchTopicAnchor(hash);
+}
+
+/** One-shot convenience: `H(kind ‖ label ‖ "match")` over the default db-core ring hash. */
+export function matchTopicId(kind: MatchTopicKind, label: string, hash: IRingHash = createRingHash()): Uint8Array {
+	return createMatchTopicAnchor(hash).topicId(kind, label);
+}