@voltro/plugin-matchmaking 0.0.0-stage → 0.88.0

package/dist/server.d.ts

@@ -0,0 +1,337 @@
+import { ColumnBuilder } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { Table } from '@voltro/database';
+import { YieldableError } from 'effect/Cause';
+
+declare type AvoidPair = readonly [string, string];
+
+/**
+ * The Director's write stage (Plan 04 §3). Per accepted proposal: fence every member,
+ * claim all its tickets `open → matched` at once, allocate seats outside SQL, then record
+ * the assignment and close the tickets `assigned`. A proposal with any changed ticket is
+ * skipped whole; a failed allocation reopens its tickets with `attempts + 1`.
+ */
+export declare const dataStoreMatchmakingAssigner: (store: DataStore, options: MatchmakingAssignerOptions) => {
+    assign: (subject: Subject, plan: MatchmakingPlan) => Effect.Effect<MatchmakingAssignResult, MatchmakingError>;
+};
+
+/** Trusted read/planning stage of a Director. It borrows the installed SQL store
+ * and calls the real queue function. Proposals claim no tickets or Room seats;
+ * a later writer must recheck and atomically claim every original ticket. */
+export declare const dataStoreMatchmakingPlanner: (store: DataStore, options: MatchmakingPlanningOptions) => {
+    plan: (subject: Subject, original: MatchmakingPlanInput) => Effect.Effect<MatchmakingPlan, MatchmakingError>;
+};
+
+/** SQL tickets: solo searches plus leader-owned party searches. Matching/assignment and HotStore indexing remain separate work. */
+export declare const dataStoreMatchmakingTickets: (store: DataStore, input: TicketAdmissionOptions) => {
+    service: MatchmakingService;
+    enqueueGroup: (subject: Subject, intent: EnqueueIntent, partyId: string, verify: (tx: DataStore) => Promise<ReadonlyArray<string>>, preview: () => Promise<ReadonlyArray<string>>) => Effect.Effect<MatchmakingTicket, MatchmakingError>;
+    director: {
+        plan: (subject: Subject, original: MatchmakingPlanInput) => Effect.Effect< MatchmakingPlan, MatchmakingError>;
+    };
+    exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<{
+        tickets: {
+            readonly id: string;
+            readonly queue: string;
+            readonly state: "open" | "expired" | "matched" | "cancelled" | "assigned";
+            readonly members: readonly string[];
+            readonly attributes: {
+                readonly [x: string]: unknown;
+            };
+            readonly createdAt: number;
+            readonly expiresAt: number;
+            readonly closedAt: number | null;
+            readonly metadata: {
+                readonly [x: string]: unknown;
+            };
+        }[];
+        assignments: readonly {
+            readonly ticketId: string;
+            readonly queue: string;
+            readonly roomId: string;
+            readonly sessionId: string;
+            readonly createdAt: number;
+        }[];
+    }, MatchmakingError, never>;
+    eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, MatchmakingError, never>;
+};
+
+/** Empty policy for an app without a block provider. Automatic optional Social
+ * port binding is separate integration work; it is not inferred here. */
+export declare const defaultMatchmakingAvoidPairs: MatchmakingAvoidPairs;
+
+/** Players send a queue preference intent; never skill, members, state or assignments. */
+declare interface EnqueueIntent {
+    readonly queue: string;
+    readonly requestId: string;
+    readonly preferences: Readonly<Record<string, unknown>>;
+}
+
+declare type MatchFunction<A = Readonly<Record<string, unknown>>> = (input: MatchInput<A>) => MatchOutput<A>;
+
+declare interface MatchInput<A = Readonly<Record<string, unknown>>> {
+    readonly tickets: ReadonlyArray<MatchTicket<A>>;
+    readonly now: number;
+    readonly queue: MatchQueueRules;
+    readonly avoid: ReadonlyArray<AvoidPair>;
+}
+
+export declare interface MatchmakingAllocation {
+    readonly roomId: string;
+    /** Every member's seat session id; tokens stay with Rooms. */
+    readonly seats: Readonly<Record<string, string>>;
+}
+
+/** What the allocator must create for one accepted proposal: a Room with a seat per member. */
+export declare interface MatchmakingAllocationRequest {
+    readonly tenantId: string;
+    readonly queue: string;
+    /** Stable per proposal: the same tickets always yield the same key, so allocation can be idempotent. */
+    readonly requestId: string;
+    /** Member subject ids per team, in proposal order. */
+    readonly teams: ReadonlyArray<ReadonlyArray<string>>;
+}
+
+export declare interface MatchmakingAssignerOptions {
+    readonly allocator: MatchmakingRoomAllocator;
+    /** Failed allocations before a ticket expires. Default 3. */
+    readonly maxAttempts?: number;
+    readonly now?: () => number;
+}
+
+declare type MatchmakingAssignment = typeof MatchmakingAssignmentSchema.Type;
+
+declare const MatchmakingAssignmentSchema: Schema.Struct<{
+    readonly ticketId: Schema.String;
+    readonly queue: Schema.String;
+    readonly roomId: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly createdAt: Schema.Number;
+}>;
+
+/** One row per member of a matched ticket: the Room and that member's seat session (never a token). */
+export declare const matchmakingAssignmentsTable: Table<"_voltro_mm_assignments", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly ticketId: ColumnBuilder<string, "text", boolean>;
+    readonly queue: ColumnBuilder<string, "text", boolean>;
+    readonly roomId: ColumnBuilder<string, "text", boolean>;
+    readonly sessionId: ColumnBuilder<string, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+export declare interface MatchmakingAssignResult {
+    readonly assigned: ReadonlyArray<{
+        readonly requestId: string;
+        readonly roomId: string;
+        readonly tickets: ReadonlyArray<string>;
+    }>;
+    /** Proposals whose tickets changed before the claim (cancelled, expired, taken by another Director). */
+    readonly skipped: number;
+    /** Proposals whose allocation failed; their tickets are open again (or expired at the limit). */
+    readonly failed: number;
+}
+
+export declare interface MatchmakingAvoidContext {
+    readonly tenantId: string;
+    readonly queue: string;
+    readonly tickets: ReadonlyArray<MatchTicket>;
+    readonly maxPairs: number;
+    readonly query: DataStore['query'];
+}
+
+export declare type MatchmakingAvoidPairs = (context: MatchmakingAvoidContext) => Effect.Effect<ReadonlyArray<AvoidPair>, MatchmakingError>;
+
+declare class MatchmakingError extends MatchmakingError_base {
+}
+
+declare const MatchmakingError_base: Schema.Class<MatchmakingError, Schema.TaggedStruct<"MatchmakingError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_queue", "invalid_proposal", "unavailable", "identity_required", "not_found", "already_searching", "conflict", "queue_full", "erased", "export_limit", "forbidden", "party_full", "already_in_party", "party_not_ready"]>;
+}>, YieldableError>;
+
+declare type MatchmakingEstimate = typeof MatchmakingEstimateSchema.Type;
+
+/** Expected wait in a queue: the median time recent searches of this tenant waited until matched, from up to
+ * `samples` searches matched in the last 30 minutes. `waitMs` is null with fewer than three such searches. */
+declare const MatchmakingEstimateSchema: Schema.Struct<{
+    readonly queue: Schema.String;
+    readonly waitMs: Schema.NullOr<Schema.Number>;
+    readonly samples: Schema.Number;
+}>;
+
+export declare interface MatchmakingPlan extends MatchOutput {
+    readonly tenantId: string;
+    readonly queue: string;
+    readonly observedAt: number;
+}
+
+export declare interface MatchmakingPlanInput {
+    readonly tenantId: string;
+    readonly queue: string;
+}
+
+export declare interface MatchmakingPlanningOptions {
+    readonly queues: ReadonlyArray<QueueDescriptor<any>>;
+    readonly avoidPairs: MatchmakingAvoidPairs;
+    readonly now: () => number;
+}
+
+export declare const matchmakingQueuesTable: Table<"_voltro_mm_queue_admission", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly queue: ColumnBuilder<string, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+}>, true, never>;
+
+/** Room seats for a match. `roomsAllocator` (`@voltro/plugin-matchmaking/rooms`) is the Rooms implementation. */
+export declare interface MatchmakingRoomAllocator {
+    readonly allocate: (request: MatchmakingAllocationRequest) => Effect.Effect<MatchmakingAllocation, MatchmakingError>;
+    /** Undo a completed allocation the assignment could not record. */
+    readonly release: (request: MatchmakingAllocationRequest, allocation: MatchmakingAllocation) => Effect.Effect<void, MatchmakingError>;
+}
+
+/** Queries wrap status reactively; this port owns no transport or poll timer. */
+declare interface MatchmakingService {
+    readonly enqueue: (subject: Subject, input: EnqueueIntent) => Effect.Effect<MatchmakingTicket, MatchmakingError>;
+    readonly cancel: (subject: Subject, ticketId: string) => Effect.Effect<void, MatchmakingError>;
+    readonly status: (subject: Subject, ticketId: string) => Effect.Effect<MatchmakingTicket, MatchmakingError>;
+    /** Median recent wait in a declared queue for the caller's tenant. Optional for replacement ports: without it
+     * `matchmaking.estimate` answers `unavailable`. */
+    readonly estimate?: (subject: Subject, queue: string) => Effect.Effect<MatchmakingEstimate, MatchmakingError>;
+}
+
+export declare const matchmakingSubjectsTable: Table<"_voltro_mm_subject_admission", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string | null, "text", boolean>;
+    readonly activeTicketId: ColumnBuilder<string | null, "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly erased: ColumnBuilder<boolean, "boolean", boolean>;
+}>, true, never>;
+
+declare type MatchmakingTicket = typeof MatchmakingTicketSchema.Type;
+
+declare const MatchmakingTicketSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly queue: Schema.String;
+    readonly state: Schema.Literals<readonly ["open", "matched", "assigned", "cancelled", "expired"]>;
+    readonly members: Schema.$Array<Schema.String>;
+    readonly attributes: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly createdAt: Schema.Number;
+    readonly expiresAt: Schema.Number;
+    readonly closedAt: Schema.NullOr<Schema.Number>;
+    readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+
+export declare const matchmakingTicketsTable: Table<"_voltro_mm_tickets", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly queue: ColumnBuilder<string, "text", boolean>;
+    readonly requestKey: ColumnBuilder<string, "text", boolean>;
+    /** Set for a party search: the leader owns the row, every member's claim points at it. */
+    readonly partyId: ColumnBuilder<string | null, "text", boolean>;
+    readonly members: ColumnBuilder<unknown, "json", boolean>;
+    readonly attributes: ColumnBuilder<unknown, "json", boolean>;
+    readonly state: ColumnBuilder<"open" | "expired" | "matched" | "cancelled" | "assigned", "text", boolean>;
+    /** Failed allocations; a ticket expires after the queue's limit. */
+    readonly attempts: ColumnBuilder<number, "integer", true>;
+    readonly matchedAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly expiresAt: ColumnBuilder<Date, "timestamp", boolean>;
+    readonly closedAt: ColumnBuilder<Date | null, "timestamp", boolean>;
+    readonly metadata: ColumnBuilder<unknown, "json", boolean>;
+}>, true, never>;
+
+declare interface MatchOutput<A = Readonly<Record<string, unknown>>> {
+    readonly proposals: ReadonlyArray<MatchProposal<A>>;
+    readonly leftover: ReadonlyArray<MatchTicket<A>>;
+    /** Deterministic branch inspections, not a runtime or throughput measurement. */
+    readonly searchNodes: number;
+    readonly exhausted: boolean;
+}
+
+declare interface MatchProposal<A = Readonly<Record<string, unknown>>> {
+    readonly teams: ReadonlyArray<ReadonlyArray<MatchTicket<A>>>;
+    readonly quality: number;
+}
+
+declare interface MatchQueueRules {
+    readonly name: string;
+    readonly teams: {
+        readonly count: number;
+        readonly size: number;
+    };
+    readonly maxTickets: number;
+    readonly maxSearchNodes: number;
+    readonly maxAvoidPairs: number;
+    readonly maxAttributeBytes: number;
+    readonly minQuality: {
+        readonly initial: number;
+        readonly after: ReadonlyArray<readonly [number, number]>;
+    };
+}
+
+declare interface MatchTicket<A = Readonly<Record<string, unknown>>> {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly queue: string;
+    readonly members: ReadonlyArray<string>;
+    readonly createdAt: number;
+    readonly attributes: A;
+}
+
+/** A detached current SQL roster. It contains IDs, never inferred Subject kinds. */
+export declare interface PartyRoster {
+    readonly tenantId: string;
+    readonly partyId: string;
+    readonly leaderId: string;
+    readonly memberIds: ReadonlyArray<string>;
+}
+
+export declare class PartyRosterPort extends PartyRosterPort_base {
+}
+
+declare const PartyRosterPort_base: Context.ServiceClass<PartyRosterPort, "@voltro/PartyRosterPort", PartyRosterService>;
+
+/** Trusted server composition only. The caller must authorize the operation;
+ * this read is not a player route or authority to move the returned members. */
+export declare interface PartyRosterService {
+    readonly read: (tenantId: string, partyId: string) => Effect.Effect<PartyRoster | null, MatchmakingError>;
+}
+
+declare interface QueueDescriptor<S extends Schema.Codec<unknown, unknown>> extends MatchQueueRules {
+    readonly kind: 'matchmaking.queue';
+    readonly room: string;
+    readonly ticket: S;
+    readonly matchFunction: MatchFunction<(S)["Type"]>;
+    readonly pools: {
+        readonly byRegion: (attributes: (S)["Type"]) => string;
+    } | undefined;
+    readonly cycleMs: number;
+    readonly ticketTtlMs: number;
+}
+
+/** The caller's own seats from assignments, newest first. */
+export declare const readMatchmakingAssignments: (store: Pick<DataStore, "query">, tenantId: string, subjectId: string, limit?: number) => Promise<ReadonlyArray<MatchmakingAssignment>>;
+
+export declare interface TicketAdmissionOptions {
+    readonly queues: ReadonlyArray<QueueDescriptor<any>>;
+    /** Resolve trusted skill/latency/policy attributes before SQL; no client state is copied. */
+    readonly prepareTicket: (subject: Subject, queue: QueueDescriptor<any>, preferences: EnqueueIntent['preferences']) => Effect.Effect<Readonly<Record<string, unknown>>, MatchmakingError>;
+    /** Re-check durable eligibility in the exact borrowed transaction after writer admission. */
+    readonly admit: (subject: Subject, queue: QueueDescriptor<any>, tx: DataStore) => Effect.Effect<void, MatchmakingError>;
+    readonly maxPreferencesBytes?: number;
+    readonly maxExportRows?: number;
+    readonly avoidPairs?: MatchmakingAvoidPairs;
+    readonly now?: () => number;
+}
+
+export { }

package/dist/server.js

@@ -0,0 +1,8 @@
+import { defaultMatchmakingAvoidPairs as e } from "./avoidPairs.js";
+import { PartyRosterPort as t } from "./port.js";
+import { matchmakingAssignmentsTable as n, matchmakingTicketsTable as r } from "./tickets.entity.js";
+import { matchmakingQueuesTable as i, matchmakingSubjectsTable as a } from "./admission.entity.js";
+import { dataStoreMatchmakingAssigner as o, readMatchmakingAssignments as s } from "./assignment.js";
+import { dataStoreMatchmakingPlanner as c } from "./director.js";
+import { dataStoreMatchmakingTickets as l } from "./service.js";
+export { t as PartyRosterPort, o as dataStoreMatchmakingAssigner, c as dataStoreMatchmakingPlanner, l as dataStoreMatchmakingTickets, e as defaultMatchmakingAvoidPairs, n as matchmakingAssignmentsTable, i as matchmakingQueuesTable, a as matchmakingSubjectsTable, r as matchmakingTicketsTable, s as readMatchmakingAssignments };