@optimystic/db-p2p 0.13.4 → 0.14.0

package/dist/src/matchmaking/module.js

@@ -0,0 +1,221 @@
+/**
+ * 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, } from "@optimystic/db-core";
+import { MatchmakingProviderManager } from "./provider-manager.js";
+import { MatchmakingSeekerManager } from "./seeker-manager.js";
+import { SeekerWalkClient } from "./seeker-walk-client.js";
+/**
+ * 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 {
+    deps;
+    anchor;
+    manager;
+    constructor(deps) {
+        this.deps = deps;
+        this.anchor = deps.anchor ?? createMatchTopicAnchor();
+    }
+    /** The live registration handle, or `undefined` before the first {@link register}. */
+    get registration() {
+        return this.manager?.registration;
+    }
+    /** Register the provider at `topic` with the signed payload, at cohort-topic tier T2. */
+    async register(topic, reg) {
+        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() {
+        await this.manager?.renew();
+    }
+    /** Update the live capacity budget and push it by re-registering (`RenewV1` cannot carry a payload). */
+    async setCapacity(budget) {
+        await this.requireManager().setCapacity(budget);
+    }
+    /** Signal "available but at capacity" (`capacityBudget = 0`) by re-registering. */
+    async signalFull() {
+        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() {
+        await this.manager?.withdraw();
+    }
+    requireManager() {
+        if (this.manager === undefined) {
+            throw new Error("MatchmakingProviderSession: register() must precede setCapacity()/signalFull()");
+        }
+        return this.manager;
+    }
+}
+/**
+ * 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 {
+    deps;
+    anchor;
+    manager;
+    constructor(deps) {
+        this.deps = deps;
+        this.anchor = deps.anchor ?? createMatchTopicAnchor();
+    }
+    /** Resolve the `topicId` for a topic ref. */
+    topicIdFor(topic) {
+        return this.anchor.topicId(topic.kind, topic.label);
+    }
+    /** Register the seeker briefly at `topic` (cohort-topic T2, short TTL). */
+    async register(topic, reg) {
+        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() {
+        await this.manager?.withdraw();
+    }
+    /** Issue a one-shot `QueryV1` against the topic's cohort (resolved from `q.topicId`). */
+    async query(q) {
+        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, want) {
+        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(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()];
+    }
+}
+/**
+ * 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) {
+    return {
+        async walk(req) {
+            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) {
+            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 };
+        },
+    };
+}
+//# sourceMappingURL=module.js.map

package/dist/src/matchmaking/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../src/matchmaking/module.ts"],"names":[],"mappings":"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"}

package/dist/src/matchmaking/protocols.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const MATCHMAKING_BASE: "/optimystic/matchmaking/1.0.0";
+/** `QueryV1` / `QueryReplyV1` — a seeker's query for a cohort's locally-held provider/seeker registrations. */
+export declare const PROTOCOL_MATCHMAKING_QUERY: "/optimystic/matchmaking/1.0.0/query";
+/** The matchmaking protocol IDs in registration order. */
+export interface MatchmakingProtocols {
+    readonly query: string;
+}
+/** Default (network-agnostic) protocol IDs, matching `docs/matchmaking.md`. */
+export declare const DEFAULT_MATCHMAKING_PROTOCOLS: MatchmakingProtocols;
+/**
+ * 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 declare function makeMatchmakingProtocols(networkName?: string): MatchmakingProtocols;
+/** All matchmaking protocol IDs as an array (for `node.handle` / `unhandle` over the set). */
+export declare function matchmakingProtocolList(p: MatchmakingProtocols): string[];
+//# sourceMappingURL=protocols.d.ts.map

package/dist/src/matchmaking/protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/protocols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,EAAG,+BAAwC,CAAC;AAEzE,+GAA+G;AAC/G,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAE/E,0DAA0D;AAC1D,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,EAAE,oBAE3C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,SAAY,GAAG,oBAAoB,CAKtF;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAEzE"}

package/dist/src/matchmaking/protocols.js

@@ -0,0 +1,42 @@
+/**
+ * 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";
+/** `QueryV1` / `QueryReplyV1` — a seeker's query for a cohort's locally-held provider/seeker registrations. */
+export const PROTOCOL_MATCHMAKING_QUERY = `${MATCHMAKING_BASE}/query`;
+/** Default (network-agnostic) protocol IDs, matching `docs/matchmaking.md`. */
+export const DEFAULT_MATCHMAKING_PROTOCOLS = {
+    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") {
+    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) {
+    return [p.query];
+}
+//# sourceMappingURL=protocols.js.map

package/dist/src/matchmaking/protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../../../src/matchmaking/protocols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAAwC,CAAC;AAEzE,+GAA+G;AAC/G,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,gBAAgB,QAAiB,CAAC;AAO/E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAyB;IAClE,KAAK,EAAE,0BAA0B;CACjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAW,GAAG,SAAS;IAC/D,MAAM,IAAI,GAAG,eAAe,WAAW,oBAAoB,CAAC;IAC5D,OAAO;QACN,KAAK,EAAE,GAAG,IAAI,QAAQ;KACtB,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,uBAAuB,CAAC,CAAuB;IAC9D,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAClB,CAAC"}

package/dist/src/matchmaking/provider-manager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 { 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 declare class MatchmakingProviderManager {
+    private readonly service;
+    private readonly provider;
+    private readonly ttlMs;
+    private handle?;
+    constructor(options: MatchmakingProviderManagerOptions);
+    /** The live registration handle, or `undefined` before the first {@link register}. */
+    get registration(): RegistrationHandle | undefined;
+    /** Register (or re-register) the provider at tier T2 with the current signed payload. */
+    register(): Promise<RegistrationHandle>;
+    /** Run one renewal cycle (keep-alive touch). No-op before the first {@link register}. */
+    renew(): Promise<void>;
+    /** Set the live capacity budget and push it by re-registering (`RenewV1` cannot carry payload). */
+    setCapacity(budget: number): Promise<RegistrationHandle>;
+    /** Signal "available but at capacity" (`capacityBudget = 0`) and push it by re-registering. */
+    signalFull(): Promise<RegistrationHandle>;
+    /** 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). */
+    withdraw(): Promise<void>;
+}
+//# sourceMappingURL=provider-manager.d.ts.map

package/dist/src/matchmaking/provider-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-manager.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/provider-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAA+B,KAAK,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhK,oEAAoE;AACpE,MAAM,WAAW,iCAAiC;IACjD,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,+EAA+E;AAC/E,qBAAa,0BAA0B;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAqB;gBAExB,OAAO,EAAE,iCAAiC;IAMtD,sFAAsF;IACtF,IAAI,YAAY,IAAI,kBAAkB,GAAG,SAAS,CAEjD;IAED,yFAAyF;IACnF,QAAQ,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAW7C,yFAAyF;IACnF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,mGAAmG;IAC7F,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAK9D,+FAA+F;IACzF,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAK/C;gHAC4G;IACtG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAM/B"}

package/dist/src/matchmaking/provider-manager.js

@@ -0,0 +1,74 @@
+/**
+ * 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 } from "@optimystic/db-core";
+/** Wires one matchmaking provider to the cohort-topic substrate at tier T2. */
+export class MatchmakingProviderManager {
+    service;
+    provider;
+    ttlMs;
+    handle;
+    constructor(options) {
+        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() {
+        return this.handle;
+    }
+    /** Register (or re-register) the provider at tier T2 with the current signed payload. */
+    async register() {
+        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() {
+        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) {
+        this.provider.setCapacity(budget);
+        return this.register();
+    }
+    /** Signal "available but at capacity" (`capacityBudget = 0`) and push it by re-registering. */
+    async signalFull() {
+        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() {
+        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;
+//# sourceMappingURL=provider-manager.js.map

package/dist/src/matchmaking/provider-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-manager.js","sourceRoot":"","sources":["../../../src/matchmaking/provider-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAgG,MAAM,qBAAqB,CAAC;AAchK,+EAA+E;AAC/E,MAAM,OAAO,0BAA0B;IACrB,OAAO,CAAqB;IAC5B,QAAQ,CAAsB;IAC9B,KAAK,CAAS;IACvB,MAAM,CAAsB;IAEpC,YAAY,OAA0C;QACrD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,uBAAuB,CAAC;IAC/I,CAAC;IAED,sFAAsF;IACtF,IAAI,YAAY;QACf,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,QAAQ;QACb,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YACzC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;YAC9B,IAAI,EAAE,IAAI,CAAC,EAAE;YACb,UAAU;YACV,GAAG,EAAE,IAAI,CAAC,KAAK;SACf,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO;QACR,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,mGAAmG;IACnG,KAAK,CAAC,WAAW,CAAC,MAAc;QAC/B,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED,+FAA+F;IAC/F,KAAK,CAAC,UAAU;QACf,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED;gHAC4G;IAC5G,KAAK,CAAC,QAAQ;QACb,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;IACF,CAAC;CACD;AAED,yGAAyG;AACzG,MAAM,uBAAuB,GAAG,MAAM,CAAC"}

package/dist/src/matchmaking/query-handler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Matchmaking — cohort-side `QueryV1` handler (db-p2p, wires the substrate store to the query reply).
+ *
+ * `docs/matchmaking.md` §Seeker query / §Capability filter. When a seeker dials a cohort with a
+ * {@link QueryV1}, the cohort returns its **locally-known direct registrations** for the topic, with the
+ * capability filter applied. This handler is the thin db-p2p binding: it reads the cohort's local
+ * {@link RegistrationRecord}s, decodes each one's `appState` into a provider/seeker payload, and hands
+ * them to the pure db-core {@link evaluateQuery} (filter + truncation + entry building). It then
+ * attaches the substrate's `topicTraffic` snapshot, the `cohortEpoch`, and the cohort **primary's**
+ * single-member reply signature (NOT a threshold signature — the reply is advisory; the seeker
+ * re-validates each entry's `registrationSig` via `verifyProviderEntry`).
+ *
+ * The handler is transport-light on purpose: the records, traffic, epoch, and signer are all injected,
+ * so it unit-tests without a live libp2p stack (mock-tier e2e is a documented follow-on). The FRET host
+ * supplies `records = store.listByTopic(topicId)`, `topicTraffic` from the cohort `TrafficCounters`,
+ * the current `cohortEpoch`, and a `sign` bound to this node's peer key.
+ */
+import { type QueryReplyV1, type QueryV1, type RegistrationRecord, type TopicTrafficV1 } from "@optimystic/db-core";
+/** Everything the {@link handleMatchmakingQuery} needs from the cohort substrate, all injected. */
+export interface CohortQueryContext {
+    /** The cohort's local registration records for the queried topic (e.g. `store.listByTopic(topicId)`). */
+    readonly records: readonly RegistrationRecord[];
+    /** The substrate's current traffic barometer for the topic (from the cohort `TrafficCounters`). */
+    readonly topicTraffic: TopicTrafficV1;
+    /** The current cohort epoch (32 bytes). */
+    readonly cohortEpoch: Uint8Array;
+    /** Sign the canonical reply image with the cohort primary's peer key; resolves the base64url signature. */
+    readonly sign: (payload: Uint8Array) => Promise<string>;
+    /** Optional logger for records whose `appState` fails to decode (skipped, not fatal). */
+    readonly log?: (formatter: string, ...args: unknown[]) => void;
+}
+/** Build the advisory {@link QueryReplyV1} for `query` from the cohort's local registrations. */
+export declare function handleMatchmakingQuery(query: QueryV1, ctx: CohortQueryContext): Promise<QueryReplyV1>;
+//# sourceMappingURL=query-handler.d.ts.map

package/dist/src/matchmaking/query-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-handler.d.ts","sourceRoot":"","sources":["../../../src/matchmaking/query-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAON,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,MAAM,qBAAqB,CAAC;AAG7B,mGAAmG;AACnG,MAAM,WAAW,kBAAkB;IAClC,yGAAyG;IACzG,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;IACtC,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,yFAAyF;IACzF,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED,iGAAiG;AACjG,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAwC3G"}

package/dist/src/matchmaking/query-handler.js

@@ -0,0 +1,62 @@
+/**
+ * Matchmaking — cohort-side `QueryV1` handler (db-p2p, wires the substrate store to the query reply).
+ *
+ * `docs/matchmaking.md` §Seeker query / §Capability filter. When a seeker dials a cohort with a
+ * {@link QueryV1}, the cohort returns its **locally-known direct registrations** for the topic, with the
+ * capability filter applied. This handler is the thin db-p2p binding: it reads the cohort's local
+ * {@link RegistrationRecord}s, decodes each one's `appState` into a provider/seeker payload, and hands
+ * them to the pure db-core {@link evaluateQuery} (filter + truncation + entry building). It then
+ * attaches the substrate's `topicTraffic` snapshot, the `cohortEpoch`, and the cohort **primary's**
+ * single-member reply signature (NOT a threshold signature — the reply is advisory; the seeker
+ * re-validates each entry's `registrationSig` via `verifyProviderEntry`).
+ *
+ * The handler is transport-light on purpose: the records, traffic, epoch, and signer are all injected,
+ * so it unit-tests without a live libp2p stack (mock-tier e2e is a documented follow-on). The FRET host
+ * supplies `records = store.listByTopic(topicId)`, `topicTraffic` from the cohort `TrafficCounters`,
+ * the current `cohortEpoch`, and a `sign` bound to this node's peer key.
+ */
+import { bytesToB64url, decodeMatchAppPayload, evaluateQuery, queryReplySigningPayload, } from "@optimystic/db-core";
+import { bytesToPeerIdString } from "../cohort-topic/peer-codec.js";
+/** Build the advisory {@link QueryReplyV1} for `query` from the cohort's local registrations. */
+export async function handleMatchmakingQuery(query, ctx) {
+    const providers = [];
+    const seekers = [];
+    for (const rec of ctx.records) {
+        if (rec.appState === undefined) {
+            continue;
+        }
+        const participantId = bytesToPeerIdString(rec.participantId);
+        let payload;
+        try {
+            payload = decodeMatchAppPayload(rec.appState);
+        }
+        catch (err) {
+            // A record whose appState isn't a matchmaking payload (or is malformed) is not ours to serve;
+            // skip it rather than fail the whole reply. Logged so it is never silently swallowed.
+            ctx.log?.("matchmaking query handler: skipping undecodable record for %s: %o", participantId, err);
+            continue;
+        }
+        if (payload.kind === "match-provider") {
+            providers.push({ participantId, attachedAt: rec.attachedAt, payload });
+        }
+        else {
+            seekers.push({ participantId, attachedAt: rec.attachedAt, payload });
+        }
+    }
+    const evaluated = evaluateQuery(query, providers, seekers);
+    const unsigned = {
+        v: 1,
+        truncated: evaluated.truncated,
+        cohortEpoch: bytesToB64url(ctx.cohortEpoch),
+        topicTraffic: ctx.topicTraffic,
+    };
+    if (evaluated.providers !== undefined) {
+        unsigned.providers = evaluated.providers;
+    }
+    if (evaluated.seekers !== undefined) {
+        unsigned.seekers = evaluated.seekers;
+    }
+    const signature = await ctx.sign(queryReplySigningPayload(unsigned));
+    return { ...unsigned, signature };
+}
+//# sourceMappingURL=query-handler.js.map

package/dist/src/matchmaking/query-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-handler.js","sourceRoot":"","sources":["../../../src/matchmaking/query-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,wBAAwB,GAOxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAgBpE,iGAAiG;AACjG,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAc,EAAE,GAAuB;IACnF,MAAM,SAAS,GAAgC,EAAE,CAAC;IAClD,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,SAAS;QACV,CAAC;QACD,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC7D,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACJ,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,8FAA8F;YAC9F,sFAAsF;YACtF,GAAG,CAAC,GAAG,EAAE,CAAC,mEAAmE,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;YACnG,SAAS;QACV,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;YACvC,SAAS,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;IACF,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAoC;QACjD,CAAC,EAAE,CAAC;QACJ,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC;QAC3C,YAAY,EAAE,GAAG,CAAC,YAAY;KAC9B,CAAC;IACF,IAAI,SAAS,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACvC,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC;IAC1C,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrC,QAAQ,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IACtC,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrE,OAAO,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,CAAC;AACnC,CAAC"}