@voltro/plugin-matchmaking 0.0.0-stage → 0.87.0

package/dist/index.d.ts

@@ -0,0 +1,523 @@
+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 { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare type AvoidPair = readonly [string, string];
+
+/** Ordered policies consume disjoint proposals, sharing the original branch budget. */
+export declare const composite: <A = Readonly<Record<string, unknown>>>(functions: ReadonlyArray<MatchFunction<A>>) => MatchFunction<A>;
+
+/** Intentions only: the server derives leader, members, capacity and expiry. */
+export declare interface CreatePartyIntent {
+    readonly requestId: string;
+    readonly maxSize?: number;
+    readonly approval?: 'open' | 'leader';
+}
+
+/** SQL-owned ephemeral parties: one party per subject, leader-governed, gone with its last member. */
+export declare const dataStoreParties: (store: DataStore, offered?: PartyOptions) => {
+    service: PartyService;
+    exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, MatchmakingError, never>;
+    eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, MatchmakingError, never>;
+    prepareSearch: (tx: DataStore, subject: Subject, partyId: string) => Promise<ReadonlyArray<string>>;
+    previewRoster: (subject: Subject, partyId: string) => Promise<ReadonlyArray<string>>;
+    readRoster: (tenantId: string, partyId: string) => Effect.Effect<PartyRoster | null, MatchmakingError>;
+};
+
+/** 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;
+
+export declare const defineQueue: <S extends Schema.Codec<unknown, unknown>>(input: QueueDefinition<S>) => QueueDescriptor<S>;
+
+/** Players send a queue preference intent; never skill, members, state or assignments. */
+export declare interface EnqueueIntent {
+    readonly queue: string;
+    readonly requestId: string;
+    readonly preferences: Readonly<Record<string, unknown>>;
+}
+
+export declare const fifo: <A = Readonly<Record<string, unknown>>>() => MatchFunction<A>;
+
+export declare type MatchFunction<A = Readonly<Record<string, unknown>>> = (input: MatchInput<A>) => MatchOutput<A>;
+
+export 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 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;
+}>;
+
+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>;
+
+/** A scheduled Director run: `runKey` makes the run idempotent; `maxPairs` bounds tenant×queue work per run. */
+export declare const MatchmakingDirectorPayload: Schema.Struct<{
+    readonly runKey: Schema.NonEmptyString;
+    readonly maxPairs: Schema.Number;
+}>;
+
+export declare type MatchmakingDirectorPayload = typeof MatchmakingDirectorPayload.Type;
+
+export declare class MatchmakingDirectorPort extends MatchmakingDirectorPort_base {
+}
+
+declare const MatchmakingDirectorPort_base: Context.ServiceClass<MatchmakingDirectorPort, "@voltro/MatchmakingDirectorPort", MatchmakingDirectorService>;
+
+export declare const MatchmakingDirectorResult: Schema.Struct<{
+    readonly cycles: Schema.Number;
+    readonly assigned: Schema.Number;
+    readonly skipped: Schema.Number;
+    readonly failed: Schema.Number;
+}>;
+
+export declare type MatchmakingDirectorResult = typeof MatchmakingDirectorResult.Type;
+
+/** One Director pass over every tenant and queue with open tickets: plan, then assign. */
+export declare interface MatchmakingDirectorService {
+    readonly run: (input: MatchmakingDirectorPayload) => Effect.Effect<MatchmakingDirectorResult, MatchmakingError>;
+}
+
+/** The `matchmaking.director` workflow body: one Director run through the installed port. */
+export declare const matchmakingDirectorWorkflowExecutor: (payload: MatchmakingDirectorPayload) => Effect.Effect<MatchmakingDirectorResult, MatchmakingError, MatchmakingDirectorPort>;
+
+export 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;
+}>;
+
+/** Ephemeral groups: a party disappears with its last member. `admission` is the party writer fence. */
+export declare const matchmakingPartiesTable: Table<"_voltro_mm_parties", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly leaderId: ColumnBuilder<string, "text", boolean>;
+    readonly requestKey: ColumnBuilder<string, "text", boolean>;
+    readonly maxSize: ColumnBuilder<number, "integer", boolean>;
+    readonly approval: ColumnBuilder<"open" | "leader", "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+export declare const matchmakingPartyInvitesTable: Table<"_voltro_mm_party_invites", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly partyId: ColumnBuilder<string, "text", boolean>;
+    readonly inviteeId: ColumnBuilder<string, "text", boolean>;
+    readonly inviterId: ColumnBuilder<string, "text", boolean>;
+    readonly expiresAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+/** One row per (tenant, subject): the ID omits the party, so a subject is in at most one party. */
+export declare const matchmakingPartyMembersTable: Table<"_voltro_mm_party_members", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly partyId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly role: ColumnBuilder<"member" | "leader", "text", boolean>;
+    readonly ready: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly joinedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>;
+
+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;
+}
+
+/** Ticket installation; the Director cycle (plan, then assign) is called by trusted server code. */
+export declare interface MatchmakingPlugin extends VoltroPlugin {
+    /** Trusted Director facade of this installed adapter, never a player RPC. */
+    readonly matchmaking: {
+        readonly plan: (subject: Subject, input: MatchmakingPlanInput) => Effect.Effect<MatchmakingPlan, MatchmakingError>;
+        /** Claim, allocate and record the plan's proposals. Requires `allocator`. */
+        readonly assign: (subject: Subject, plan: MatchmakingPlan) => Effect.Effect<MatchmakingAssignResult, MatchmakingError>;
+        /** One Director cycle for a queue: `plan` then `assign`. */
+        readonly cycle: (subject: Subject, input: MatchmakingPlanInput) => Effect.Effect<MatchmakingAssignResult, MatchmakingError>;
+    };
+}
+
+export declare const matchmakingPlugin: (input: MatchmakingPluginOptions) => MatchmakingPlugin;
+
+export declare interface MatchmakingPluginOptions extends TicketAdmissionOptions {
+    /** Party sizes and invite lifetime; parties share the ticket clock unless `now` is given. */
+    readonly parties?: PartyOptions;
+    /** Room seats for accepted matches (`roomsAllocator` from `@voltro/plugin-matchmaking/rooms`). Omitted: the Director only plans. */
+    readonly allocator?: MatchmakingRoomAllocator;
+    /** Failed allocations before a ticket expires. Default 3. */
+    readonly maxAllocationAttempts?: number;
+}
+
+export declare class MatchmakingPort extends MatchmakingPort_base {
+}
+
+declare const MatchmakingPort_base: Context.ServiceClass<MatchmakingPort, "@voltro/MatchmakingPort", MatchmakingService>;
+
+/** 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. */
+export 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>;
+}
+
+/** System21 inventory: replaceable rules and ports with their fakes. */
+export declare const matchmakingSystemContract: {
+    readonly slots: {
+        readonly avoidPairs: {
+            readonly defaultExport: "defaultMatchmakingAvoidPairs";
+            readonly fixtureExport: "matchmakingAvoidPairsSlotFixture";
+        };
+    };
+    readonly ports: {
+        readonly MatchmakingPort: {
+            readonly tagExport: "MatchmakingPort";
+            readonly fakeLayerExport: "matchmakingFakeLayer";
+            readonly fixtureExport: "matchmakingPortFixture";
+        };
+        readonly PartyMembershipPort: {
+            readonly tagExport: "PartyMembershipPort";
+            readonly fakeLayerExport: "partyMembershipFakeLayer";
+            readonly fixtureExport: "partyMembershipPortFixture";
+        };
+        readonly PartyRosterPort: {
+            readonly tagExport: "PartyRosterPort";
+            readonly fakeLayerExport: "partyRosterFakeLayer";
+            readonly fixtureExport: "partyRosterPortFixture";
+        };
+        readonly MatchmakingDirectorPort: {
+            readonly tagExport: "MatchmakingDirectorPort";
+            readonly fakeLayerExport: "matchmakingDirectorFakeLayer";
+            readonly fixtureExport: "matchmakingDirectorPortFixture";
+        };
+    };
+    readonly events: readonly [];
+};
+
+export 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 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;
+}
+
+export declare interface MatchProposal<A = Readonly<Record<string, unknown>>> {
+    readonly teams: ReadonlyArray<ReadonlyArray<MatchTicket<A>>>;
+    readonly quality: number;
+}
+
+export 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]>;
+    };
+}
+
+export 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;
+}
+
+/** Exact whole-party packing with an explicit search budget. No IO or recursion. */
+export declare const packTeams: <A>(input: MatchInput<A>, accept?: TeamAdmission<A>) => PackTeamsResult<A>;
+
+export declare interface PackTeamsResult<A> {
+    readonly teams: ReadonlyArray<ReadonlyArray<MatchTicket<A>>> | null;
+    readonly searchNodes: number;
+    readonly exhausted: boolean;
+}
+
+export declare type Party = typeof PartySchema.Type;
+
+export declare type PartyInvite = typeof PartyInviteSchema.Type;
+
+declare const PartyInviteSchema: Schema.Struct<{
+    readonly partyId: Schema.String;
+    readonly inviterId: Schema.String;
+    readonly expiresAt: Schema.Number;
+}>;
+
+export declare class PartyMembershipPort extends PartyMembershipPort_base {
+}
+
+declare const PartyMembershipPort_base: Context.ServiceClass<PartyMembershipPort, "@voltro/PartyMembershipPort", PartyMembershipService>;
+
+/** Chat and other plugins ask current party membership here, never party SQL. */
+export declare interface PartyMembershipService {
+    readonly isMember: (subject: Subject, partyId: string) => Effect.Effect<boolean, MatchmakingError>;
+}
+
+export declare interface PartyOptions {
+    /** Default and upper size for new parties (1..256). */
+    readonly maxPartySize?: number;
+    /** Invite lifetime in milliseconds (default 10 minutes, max 1 day). */
+    readonly partyInviteTtlMs?: number;
+    readonly now?: () => number;
+}
+
+/** 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 const PartySchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly leaderId: Schema.String;
+    readonly maxSize: Schema.Number;
+    readonly approval: Schema.Literals<readonly ["open", "leader"]>;
+    readonly createdAt: Schema.Number;
+    readonly members: Schema.$Array<Schema.Struct<{
+        readonly subjectId: Schema.String;
+        readonly role: Schema.Literals<readonly ["leader", "member"]>;
+        readonly ready: Schema.Boolean;
+        readonly joinedAt: Schema.Number;
+    }>>;
+    /** The open party search ticket, readable by every member through `matchmaking.status`. */
+    readonly searchTicketId: Schema.NullOr<Schema.String>;
+}>;
+
+export declare interface PartyService {
+    readonly create: (subject: Subject, intent: CreatePartyIntent) => Effect.Effect<Party, MatchmakingError>;
+    readonly mine: (subject: Subject) => Effect.Effect<Party | null, MatchmakingError>;
+    readonly invites: (subject: Subject) => Effect.Effect<ReadonlyArray<PartyInvite>, MatchmakingError>;
+    readonly invite: (subject: Subject, intent: PartyTargetIntent) => Effect.Effect<PartyInvite, MatchmakingError>;
+    readonly join: (subject: Subject, partyId: string) => Effect.Effect<Party, MatchmakingError>;
+    readonly leave: (subject: Subject, partyId: string) => Effect.Effect<void, MatchmakingError>;
+    readonly kick: (subject: Subject, intent: PartyTargetIntent) => Effect.Effect<Party, MatchmakingError>;
+    readonly setReady: (subject: Subject, input: {
+        readonly partyId: string;
+        readonly ready: boolean;
+    }) => Effect.Effect<Party, MatchmakingError>;
+    readonly transferLeader: (subject: Subject, intent: PartyTargetIntent) => Effect.Effect<Party, MatchmakingError>;
+    /** Trusted port read: true only while `subject` currently belongs to `partyId` in its own tenant. */
+    readonly isMember: (subject: Subject, partyId: string) => Effect.Effect<boolean, MatchmakingError>;
+    /** Any member stops the party's open search; every member claim is released with it. */
+    readonly cancelSearch: (subject: Subject, partyId: string) => Effect.Effect<Party, MatchmakingError>;
+}
+
+export declare const partyTables: readonly [ Table<"_voltro_mm_parties", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly leaderId: ColumnBuilder<string, "text", boolean>;
+    readonly requestKey: ColumnBuilder<string, "text", boolean>;
+    readonly maxSize: ColumnBuilder<number, "integer", boolean>;
+    readonly approval: ColumnBuilder<"open" | "leader", "text", boolean>;
+    readonly admission: ColumnBuilder<number, "integer", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_mm_party_members", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly partyId: ColumnBuilder<string, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string, "text", boolean>;
+    readonly role: ColumnBuilder<"member" | "leader", "text", boolean>;
+    readonly ready: ColumnBuilder<boolean, "boolean", boolean>;
+    readonly joinedAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>, Table<"_voltro_mm_party_invites", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tenantId: ColumnBuilder<string, "text", boolean>;
+    readonly partyId: ColumnBuilder<string, "text", boolean>;
+    readonly inviteeId: ColumnBuilder<string, "text", boolean>;
+    readonly inviterId: ColumnBuilder<string, "text", boolean>;
+    readonly expiresAt: ColumnBuilder<Date, "timestamp", boolean>;
+}>, true, never>];
+
+export declare interface PartyTargetIntent {
+    readonly partyId: string;
+    readonly subjectId: string;
+}
+
+export declare interface QueueDefinition<S extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly room: string;
+    readonly ticket: S;
+    readonly teams: MatchQueueRules['teams'];
+    readonly matchFunction: MatchFunction<(S)["Type"]>;
+    readonly pools?: {
+        readonly byRegion: (attributes: (S)["Type"]) => string;
+    } | undefined;
+    readonly minQuality?: MatchQueueRules['minQuality'];
+    readonly maxTickets?: number;
+    readonly maxSearchNodes?: number;
+    readonly maxAvoidPairs?: number;
+    readonly maxAttributeBytes?: number;
+    readonly cycleMs?: number;
+    readonly ticketTtlMs?: number;
+}
+
+export 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;
+}
+
+export declare const regionLatency: (options: {
+    readonly latencyMaxMs: number;
+}) => <A extends Readonly<Record<string, unknown>>>(input: MatchInput<A>) => MatchOutput<A>;
+
+/** Capture and bound party options before any store is bound. */
+export declare const resolvePartyOptions: (offered?: PartyOptions) => Readonly<{
+    maxPartySize: number;
+    partyInviteTtlMs: number;
+    now: () => number;
+}>;
+
+/** Pure schema-bound partition and slot admission. It does not acquire SQL tickets or reserve Rooms. */
+export declare const runQueueMatch: <S extends Schema.Codec<unknown, unknown>>(queue: QueueDescriptor<S>, input: {
+    readonly tickets: ReadonlyArray<MatchTicket<S["Type"]>>;
+    readonly now: number;
+    readonly avoid: ReadonlyArray<AvoidPair>;
+}) => MatchOutput<S["Type"]>;
+
+export declare const skillWindow: (options: SkillWindowOptions) => <A extends Readonly<Record<string, unknown>>>(input: MatchInput<A>) => MatchOutput<A>;
+
+export declare interface SkillWindowOptions {
+    readonly initialWindow: number;
+    readonly growPerSecond: number;
+    readonly maxWindow: number;
+    readonly latencyMaxMs?: number;
+}
+
+export declare type TeamAdmission<A> = (teams: ReadonlyArray<ReadonlyArray<MatchTicket<A>>>) => boolean;
+
+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;
+}
+
+/** Reject custom slot fabrication, overlapping assignments and omitted leftovers. */
+export declare const validateMatchOutput: <A>(raw: MatchInput<A>, output: MatchOutput<A>) => MatchOutput<A>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,12 @@
+import { MatchmakingError as e } from "./errors.js";
+import { packTeams as t } from "./packing.js";
+import { defaultMatchmakingAvoidPairs as n } from "./avoidPairs.js";
+import { composite as r, fifo as i, regionLatency as a, skillWindow as o, validateMatchOutput as s } from "./strategies.js";
+import { defineQueue as c, runQueueMatch as l } from "./queue.js";
+import { MatchmakingDirectorPort as u, MatchmakingPort as d, PartyMembershipPort as f, PartyRosterPort as p } from "./port.js";
+import { matchmakingPartiesTable as m, matchmakingPartyInvitesTable as h, matchmakingPartyMembersTable as g, partyTables as _ } from "./party.entity.js";
+import { dataStoreParties as v, resolvePartyOptions as y } from "./parties.js";
+import { MatchmakingDirectorPayload as b, MatchmakingDirectorResult as x } from "./directorContract.js";
+import { matchmakingPlugin as S, matchmakingSystemContract as C } from "./plugin.js";
+import { matchmakingDirectorWorkflowExecutor as w } from "./directorWorkflow.js";
+export { b as MatchmakingDirectorPayload, u as MatchmakingDirectorPort, x as MatchmakingDirectorResult, e as MatchmakingError, d as MatchmakingPort, f as PartyMembershipPort, p as PartyRosterPort, r as composite, v as dataStoreParties, n as defaultMatchmakingAvoidPairs, c as defineQueue, i as fifo, w as matchmakingDirectorWorkflowExecutor, m as matchmakingPartiesTable, h as matchmakingPartyInvitesTable, g as matchmakingPartyMembersTable, S as matchmakingPlugin, C as matchmakingSystemContract, t as packTeams, _ as partyTables, a as regionLatency, y as resolvePartyOptions, l as runQueueMatch, o as skillWindow, s as validateMatchOutput };

package/dist/inspect.js

@@ -0,0 +1,41 @@
+import { matchmakingError as e } from "./errors.js";
+import { defaultMatchmakingAvoidPairs as t } from "./avoidPairs.js";
+//#region src/inspect.ts
+var n = (n, r, i = Date.now()) => {
+	if (!Number.isSafeInteger(i) || i < 0 || i > 864e13) throw e("unavailable");
+	return {
+		observedAt: i,
+		bound: r,
+		directorInstalled: !1,
+		maxPreferencesBytes: n.maxPreferencesBytes ?? 4096,
+		maxExportRows: n.maxExportRows ?? 1e4,
+		slots: {
+			prepareTicket: "custom",
+			admit: "custom",
+			avoidPairs: n.avoidPairs === void 0 || n.avoidPairs === t ? "default" : "custom"
+		},
+		queues: n.queues.map((e) => ({
+			name: e.name,
+			room: e.room,
+			teams: e.teams,
+			maxTickets: e.maxTickets,
+			maxSearchNodes: e.maxSearchNodes,
+			maxAvoidPairs: e.maxAvoidPairs,
+			maxAttributeBytes: e.maxAttributeBytes,
+			cycleMs: e.cycleMs,
+			ticketTtlMs: e.ticketTtlMs,
+			matchFunction: "custom",
+			partitioned: e.pools !== void 0
+		})),
+		tables: [
+			"_voltro_mm_tickets",
+			"_voltro_mm_subject_admission",
+			"_voltro_mm_queue_admission",
+			"_voltro_mm_parties",
+			"_voltro_mm_party_members",
+			"_voltro_mm_party_invites"
+		]
+	};
+};
+//#endregion
+export { n as matchmakingStatus };

package/dist/packing.js

@@ -0,0 +1,72 @@
+import { matchmakingError as e } from "./errors.js";
+import { captureMatchInput as t } from "./contract.js";
+//#region src/packing.ts
+var n = (t, n) => {
+	let { count: r, size: i } = t.queue.teams, a = r * i, o = t.tickets, s = /* @__PURE__ */ new Map();
+	for (let [e, n] of t.avoid) s.has(e) || s.set(e, /* @__PURE__ */ new Set()), s.has(n) || s.set(n, /* @__PURE__ */ new Set()), s.get(e).add(n), s.get(n).add(e);
+	let c = Array(o.length + 1).fill(0);
+	for (let e = o.length - 1; e >= 0; e--) c[e] = c[e + 1] + o[e].members.length;
+	let l = Array.from({ length: r }, () => []), u = Array(r).fill(0), d = /* @__PURE__ */ new Set(), f = [{
+		index: 0,
+		next: 0,
+		added: null
+	}], p = 0, m = 0, h = () => {
+		let e = f.pop();
+		if (e.added !== null) {
+			let { team: t, ticket: n } = e.added;
+			l[t].pop(), u[t] = u[t] - n.members.length, p -= n.members.length, n.members.forEach((e) => d.delete(e));
+		}
+	};
+	for (; f.length > 0;) {
+		let g = f[f.length - 1];
+		if (p === a) {
+			let t = Object.freeze(l.map((e) => Object.freeze([...e]))), r = n === void 0 || n(t);
+			if (typeof r != "boolean") throw e("invalid_proposal");
+			if (r) return Object.freeze({
+				teams: t,
+				searchNodes: m,
+				exhausted: !1
+			});
+			h();
+			continue;
+		}
+		if (g.index >= o.length || c[g.index] < a - p || g.next > r) {
+			h();
+			continue;
+		}
+		if (m === t.queue.maxSearchNodes) return Object.freeze({
+			teams: null,
+			searchNodes: m,
+			exhausted: !0
+		});
+		let _ = g.next++, v = o[g.index];
+		if (m++, _ === r) {
+			f.push({
+				index: g.index + 1,
+				next: 0,
+				added: null
+			});
+			continue;
+		}
+		if (u[_] + v.members.length > i) continue;
+		let y = new Set(v.members);
+		v.members.some((e) => [...s.get(e) ?? []].some((e) => d.has(e) || y.has(e))) || (l[_].push(v), u[_] = u[_] + v.members.length, p += v.members.length, v.members.forEach((e) => d.add(e)), f.push({
+			index: g.index + 1,
+			next: 0,
+			added: {
+				team: _,
+				ticket: v
+			}
+		}));
+	}
+	return Object.freeze({
+		teams: null,
+		searchNodes: m,
+		exhausted: !1
+	});
+}, r = (r, i) => {
+	if (i !== void 0 && typeof i != "function") throw e("invalid_input");
+	return n(t(r), i);
+};
+//#endregion
+export { n as packCapturedTeams, r as packTeams };