@voltro/plugin-matchmaking 0.0.0-stage → 0.88.0

package/dist/plugin.js

@@ -0,0 +1,257 @@
+import { MatchmakingError as e, matchmakingError as t } from "./errors.js";
+import { MatchmakingDirectorPort as n, MatchmakingPort as r, PartyMembershipPort as i, PartyRosterPort as a } from "./port.js";
+import { partyTables as o } from "./party.entity.js";
+import { matchmakingAssignmentsTable as s, matchmakingTicketsTable as c } from "./tickets.entity.js";
+import { matchmakingQueuesTable as l, matchmakingSubjectsTable as u } from "./admission.entity.js";
+import { dataStoreParties as d, resolvePartyOptions as f } from "./parties.js";
+import { dataStoreMatchmakingAssigner as p, readMatchmakingAssignments as m } from "./assignment.js";
+import { dataStoreMatchmakingTickets as h, resolveTicketAdmissionOptions as g } from "./service.js";
+import { BASE_NAME as _, assignmentsDescriptor as v, cancelDescriptor as y, enqueueDescriptor as b, estimateDescriptor as x, matchmakingRpcClientImports as ee, partyCancelSearchDescriptor as te, partyCreateDescriptor as ne, partyInviteDescriptor as re, partyInvitesDescriptor as ie, partyJoinDescriptor as ae, partyKickDescriptor as oe, partyLeaveDescriptor as se, partyMineDescriptor as S, partyRpcClientImports as C, partySearchDescriptor as w, partySetReadyDescriptor as T, partyTransferLeaderDescriptor as E, statusDescriptor as D } from "./rpc.js";
+import { matchmakingStatus as O } from "./inspect.js";
+import { Effect as k, Layer as A, Option as j } from "effect";
+import { defineLicensedGamePlugin as M } from "@voltro/plugin-licensing/gate";
+import { fileURLToPath as N } from "node:url";
+import { and as P, eq as F, gt as I, queryFor as L } from "@voltro/database";
+import { systemSubject as ce } from "@voltro/protocol";
+// src/plugin.ts
+var R = (e) => k.flatMap(k.serviceOption(r), (n) => j.isNone(n) ? k.fail(t("unavailable")) : e(n.value)), z = {
+	slots: { avoidPairs: {
+		defaultExport: "defaultMatchmakingAvoidPairs",
+		fixtureExport: "matchmakingAvoidPairsSlotFixture"
+	} },
+	ports: {
+		MatchmakingPort: {
+			tagExport: "MatchmakingPort",
+			fakeLayerExport: "matchmakingFakeLayer",
+			fixtureExport: "matchmakingPortFixture"
+		},
+		PartyMembershipPort: {
+			tagExport: "PartyMembershipPort",
+			fakeLayerExport: "partyMembershipFakeLayer",
+			fixtureExport: "partyMembershipPortFixture"
+		},
+		PartyRosterPort: {
+			tagExport: "PartyRosterPort",
+			fakeLayerExport: "partyRosterFakeLayer",
+			fixtureExport: "partyRosterPortFixture"
+		},
+		MatchmakingDirectorPort: {
+			tagExport: "MatchmakingDirectorPort",
+			fakeLayerExport: "matchmakingDirectorFakeLayer",
+			fixtureExport: "matchmakingDirectorPortFixture"
+		}
+	},
+	events: []
+}, B = (j) => {
+	let z = g(j), B = f({
+		...j.parties,
+		now: j.parties?.now ?? z.now ?? Date.now
+	}), V, H, U, W, G = j.allocator, K = j.maxAllocationAttempts, q = (e) => k.suspend(() => U === void 0 ? k.fail(t("unavailable")) : e(U.service)), le = (e, n) => {
+		let r = U;
+		if (r === void 0) return k.fail(t("unavailable"));
+		let i = r.readRoster(e, n);
+		return k.suspend(() => U === r ? i.pipe(k.flatMap((e) => U === r ? k.succeed(e) : k.fail(t("unavailable")))) : k.fail(t("unavailable")));
+	}, J = (e) => k.suspend(() => H === void 0 ? k.fail(t("unavailable")) : e(H)), Y = (e, n, r) => {
+		try {
+			let t = structuredClone(e), i = structuredClone(n);
+			return J((e) => r(e.service, t, i));
+		} catch {
+			return k.fail(t("invalid_input"));
+		}
+	}, ue = {
+		enqueue: (e, t) => Y(e, t, (e, t, n) => e.enqueue(t, n)),
+		cancel: (e, t) => Y(e, t, (e, t, n) => e.cancel(t, n)),
+		status: (e, t) => Y(e, t, (e, t, n) => e.status(t, n)),
+		estimate: (e, n) => Y(e, n, (e, n, r) => e.estimate ? e.estimate(n, r) : k.fail(t("unavailable")))
+	}, X = ce("matchmaking.director"), de = (e) => k.gen(function* () {
+		if (V === void 0 || W === void 0) return yield* k.fail(t("unavailable"));
+		let n = V, r = (z.now ?? Date.now)(), i = yield* k.tryPromise({
+			try: () => n.query(L(c).where(P(F("state", "open"), I("expiresAt", new Date(r)))).orderBy("createdAt", "asc").limit(e.maxPairs * 64).descriptor),
+			catch: () => t("unavailable")
+		}), a = [...new Map(i.map((e) => [JSON.stringify([e.tenantId, e.queue]), {
+			tenantId: String(e.tenantId),
+			queue: String(e.queue)
+		}])).values()].slice(0, e.maxPairs), o = 0, s = 0, l = 0;
+		for (let e of a) {
+			let t = yield* Q(X, e).pipe(k.flatMap((e) => W.assign(X, e)));
+			o += t.assigned.length, s += t.skipped, l += t.failed;
+		}
+		return {
+			cycles: a.length,
+			assigned: o,
+			skipped: s,
+			failed: l
+		};
+	}), Z = [
+		{
+			...b,
+			execute: (e, t) => R((n) => n.enqueue(t.request.subject, e))
+		},
+		{
+			...y,
+			execute: (e, t) => R((n) => n.cancel(t.request.subject, e.ticketId))
+		},
+		{
+			...D,
+			execute: (e, t) => R((n) => n.status(t.request.subject, e.ticketId))
+		},
+		{
+			...x,
+			execute: (e, n) => R((r) => r.estimate ? r.estimate(n.request.subject, e.queue) : k.fail(t("unavailable")))
+		},
+		{
+			...v,
+			execute: (e, n) => k.suspend(() => {
+				let e = n.request.subject;
+				if (V === void 0) return k.fail(t("unavailable"));
+				if (e.type !== "user" || typeof e.tenantId != "string") return k.fail(t("identity_required"));
+				let r = V, i = e.tenantId, a = e.id;
+				return k.tryPromise({
+					try: () => m(r, i, a),
+					catch: () => t("unavailable")
+				});
+			})
+		},
+		{
+			...ne,
+			execute: (e, t) => q((n) => n.create(t.request.subject, e))
+		},
+		{
+			...re,
+			execute: (e, t) => q((n) => n.invite(t.request.subject, e))
+		},
+		{
+			...ae,
+			execute: (e, t) => q((n) => n.join(t.request.subject, e.partyId))
+		},
+		{
+			...se,
+			execute: (e, t) => q((n) => n.leave(t.request.subject, e.partyId))
+		},
+		{
+			...oe,
+			execute: (e, t) => q((n) => n.kick(t.request.subject, e))
+		},
+		{
+			...T,
+			execute: (e, t) => q((n) => n.setReady(t.request.subject, e))
+		},
+		{
+			...E,
+			execute: (e, t) => q((n) => n.transferLeader(t.request.subject, e))
+		},
+		{
+			...w,
+			execute: (e, n) => k.suspend(() => H === void 0 || U === void 0 ? k.fail(t("unavailable")) : H.enqueueGroup(n.request.subject, {
+				queue: e.queue,
+				requestId: e.requestId,
+				preferences: e.preferences
+			}, e.partyId, (t) => U.prepareSearch(t, n.request.subject, e.partyId), () => U.previewRoster(n.request.subject, e.partyId)))
+		},
+		{
+			...te,
+			execute: (e, t) => q((n) => n.cancelSearch(t.request.subject, e.partyId))
+		},
+		{
+			...S,
+			execute: (e, t) => q((e) => e.mine(t.request.subject))
+		},
+		{
+			...ie,
+			execute: (e, t) => q((e) => e.invites(t.request.subject))
+		}
+	], fe = M({
+		name: _,
+		description: "SQL-owned solo search admission with a replaceable ticket port.",
+		permissions: ["store:write", "inspect:read"],
+		routes: Z,
+		rpcClientDescriptors: [...ee, ...C],
+		inspectEndpoints: [{
+			method: "GET",
+			path: "/status",
+			scope: "process",
+			description: "Captured queue/admission budgets and process binding; no ticket or player enumeration.",
+			handler: () => k.try({
+				try: () => ({
+					kind: "json",
+					data: O(z, H !== void 0, (z.now ?? Date.now)())
+				}),
+				catch: () => t("unavailable")
+			})
+		}],
+		services: A.mergeAll(A.succeed(r, ue), A.succeed(i, { isMember: (e, t) => q((n) => n.isMember(e, t)) }), A.succeed(a, { read: le }), A.succeed(n, { run: (e) => de(e) })),
+		...G === void 0 ? {} : { sources: N(new URL("./director-app", "" + import.meta.url)) },
+		errorSchemas: [{
+			schema: e,
+			import: {
+				module: "@voltro/plugin-matchmaking/errors",
+				name: "MatchmakingError"
+			}
+		}],
+		extendSchema: { tables: [
+			c,
+			u,
+			l,
+			s,
+			...o
+		] },
+		subjectPrivacy: {
+			tables: [
+				c.tableName,
+				u.tableName,
+				l.tableName,
+				s.tableName,
+				...o.map((e) => e.tableName)
+			],
+			kinds: ["user", "guest"]
+		},
+		bindDataStore: (e) => {
+			if (V !== void 0 && V !== e) throw Error("Matchmaking plugin instance cannot cross app stores");
+			V = e, H = h(e, z), U = d(e, B), W = G === void 0 ? void 0 : p(e, {
+				allocator: G,
+				...K === void 0 ? {} : { maxAttempts: K },
+				now: z.now ?? Date.now
+			});
+		},
+		onExport: (e, n) => J((t) => t.exportSubject({
+			subjectId: e,
+			tenantId: n.tenantId,
+			kind: n.kind
+		})).pipe(k.zip(k.suspend(() => U === void 0 ? k.fail(t("unavailable")) : U.exportSubject({
+			subjectId: e,
+			tenantId: n.tenantId,
+			kind: n.kind
+		}))), k.map(([e, t]) => ({
+			...e,
+			parties: t
+		}))),
+		onErase: (e, n) => k.suspend(() => U === void 0 ? k.fail(t("unavailable")) : U.eraseSubject({
+			subjectId: e,
+			tenantId: n.tenantId,
+			kind: n.kind
+		})).pipe(k.andThen(J((t) => t.eraseSubject({
+			subjectId: e,
+			tenantId: n.tenantId,
+			kind: n.kind
+		})))),
+		onDeactivate: () => k.sync(() => {
+			H = void 0, U = void 0, W = void 0, V = void 0;
+		})
+	}), Q = (e, n) => {
+		try {
+			let t = structuredClone(e), r = structuredClone(n);
+			return J((e) => e.director.plan(t, r));
+		} catch {
+			return k.fail(t("invalid_input"));
+		}
+	}, $ = (e, n) => k.suspend(() => W === void 0 ? k.fail(t("unavailable")) : W.assign(e, n)), pe = (e, t) => k.flatMap(Q(e, t), (t) => $(e, t));
+	return {
+		...fe,
+		matchmaking: Object.freeze({
+			plan: Q,
+			assign: $,
+			cycle: pe
+		})
+	};
+};
+export { B as matchmakingPlugin, z as matchmakingSystemContract };

package/dist/port.d.ts

@@ -0,0 +1,116 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** 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>>;
+}
+
+/** A scheduled Director run: `runKey` makes the run idempotent; `maxPairs` bounds tenant×queue work per run. */
+declare const MatchmakingDirectorPayload: Schema.Struct<{
+    readonly runKey: Schema.NonEmptyString;
+    readonly maxPairs: Schema.Number;
+}>;
+
+declare type MatchmakingDirectorPayload = typeof MatchmakingDirectorPayload.Type;
+
+export declare class MatchmakingDirectorPort extends MatchmakingDirectorPort_base {
+}
+
+declare const MatchmakingDirectorPort_base: Context.ServiceClass<MatchmakingDirectorPort, "@voltro/MatchmakingDirectorPort", MatchmakingDirectorService>;
+
+declare const MatchmakingDirectorResult: Schema.Struct<{
+    readonly cycles: Schema.Number;
+    readonly assigned: Schema.Number;
+    readonly skipped: Schema.Number;
+    readonly failed: Schema.Number;
+}>;
+
+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>;
+}
+
+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 class MatchmakingPort extends MatchmakingPort_base {
+}
+
+declare const MatchmakingPort_base: Context.ServiceClass<MatchmakingPort, "@voltro/MatchmakingPort", MatchmakingService>;
+
+/** 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>;
+}
+
+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 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>;
+}
+
+/** 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>;
+}
+
+export { }

package/dist/port.js

@@ -0,0 +1,4 @@
+import { Context as e } from "effect";
+// src/port.ts
+var t = class extends e.Service()("@voltro/MatchmakingPort") {}, n = class extends e.Service()("@voltro/PartyMembershipPort") {}, r = class extends e.Service()("@voltro/PartyRosterPort") {}, i = class extends e.Service()("@voltro/MatchmakingDirectorPort") {};
+export { i as MatchmakingDirectorPort, t as MatchmakingPort, n as PartyMembershipPort, r as PartyRosterPort };

package/dist/queue.d.ts

@@ -0,0 +1,91 @@
+import { Schema } from 'effect';
+
+declare type AvoidPair = readonly [string, string];
+
+export declare const defineQueue: <S extends Schema.Codec<unknown, unknown>>(input: QueueDefinition<S>) => QueueDescriptor<S>;
+
+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>;
+}
+
+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;
+}
+
+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;
+}
+
+/** 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 { }

package/dist/queue.js

@@ -0,0 +1,79 @@
+import { matchmakingError as e } from "./errors.js";
+import { captureMatchInput as t, captureQueueRules as n, sameJson as r } from "./contract.js";
+import { validateMatchOutput as i } from "./strategies.js";
+import { Schema as a } from "effect";
+// src/queue.ts
+var o = (t) => {
+	if (!t || typeof t != "object") throw e("invalid_queue");
+	let r = n({
+		name: t.name,
+		teams: t.teams,
+		maxTickets: t.maxTickets ?? 1e4,
+		maxSearchNodes: t.maxSearchNodes ?? 1e5,
+		maxAvoidPairs: t.maxAvoidPairs ?? 1e4,
+		maxAttributeBytes: t.maxAttributeBytes ?? 16384,
+		minQuality: t.minQuality ?? {
+			initial: 0,
+			after: []
+		}
+	}), i = t.cycleMs ?? 1e3, o = t.ticketTtlMs ?? 3e5;
+	if (typeof t.room != "string" || !t.room.trim() || t.room.length > 256 || t.room.includes("\0") || typeof t.matchFunction != "function" || t.pools !== void 0 && typeof t.pools.byRegion != "function" || !Number.isSafeInteger(i) || i < 1 || i > 864e5 || !Number.isSafeInteger(o) || o < i || o > 864e5) throw e("invalid_queue");
+	try {
+		a.decodeUnknownSync(t.ticket);
+	} catch {
+		throw e("invalid_queue");
+	}
+	return Object.freeze({
+		...r,
+		kind: "matchmaking.queue",
+		room: t.room,
+		ticket: t.ticket,
+		matchFunction: t.matchFunction,
+		pools: t.pools === void 0 ? void 0 : Object.freeze({ byRegion: t.pools.byRegion }),
+		cycleMs: i,
+		ticketTtlMs: o
+	});
+}, s = (n, o) => {
+	let s = t({
+		...o,
+		queue: n
+	}), c = a.decodeUnknownSync(n.ticket, { onExcessProperty: "error" }), l = /* @__PURE__ */ new Map();
+	for (let t of s.tickets) {
+		let i, a;
+		try {
+			i = c(t.attributes), a = n.pools === void 0 ? "all" : n.pools.byRegion(t.attributes);
+		} catch {
+			throw e("invalid_input");
+		}
+		if (typeof a != "string" || !a.trim() || a.length > 256 || a.includes("\0") || !r(i, t.attributes)) throw e("invalid_input");
+		l.has(a) || l.set(a, []), l.get(a).push(t);
+	}
+	let u = [], d = [], f = 0, p = !1;
+	for (let t of l.values()) {
+		if (f === s.queue.maxSearchNodes) {
+			d.push(...t), p = !0;
+			continue;
+		}
+		let r = Object.freeze({
+			...s,
+			tickets: Object.freeze(t),
+			queue: Object.freeze({
+				...s.queue,
+				maxSearchNodes: s.queue.maxSearchNodes - f
+			})
+		}), a;
+		try {
+			a = i(r, n.matchFunction(r));
+		} catch {
+			throw e("invalid_proposal");
+		}
+		u.push(...a.proposals), d.push(...a.leftover), f += a.searchNodes, p ||= a.exhausted;
+	}
+	return d.sort((e, t) => e.createdAt - t.createdAt || (e.id < t.id ? -1 : +(e.id > t.id))), Object.freeze({
+		proposals: Object.freeze(u),
+		leftover: Object.freeze(d),
+		searchNodes: f,
+		exhausted: p
+	});
+};
+export { o as defineQueue, s as runQueueMatch };

package/dist/queueDeclarations.js

@@ -0,0 +1,27 @@
+import { matchmakingError as e } from "./errors.js";
+import { defineQueue as t } from "./queue.js";
+// src/queueDeclarations.ts
+var n = (n) => {
+	if (!Array.isArray(n) || n.length > 256) throw e("invalid_queue");
+	let r = Array.from(n, (n) => {
+		if (!n) throw e("invalid_queue");
+		return t({
+			name: n.name,
+			room: n.room,
+			ticket: n.ticket,
+			teams: n.teams,
+			matchFunction: n.matchFunction,
+			maxTickets: n.maxTickets,
+			maxSearchNodes: n.maxSearchNodes,
+			maxAvoidPairs: n.maxAvoidPairs,
+			maxAttributeBytes: n.maxAttributeBytes,
+			minQuality: n.minQuality,
+			cycleMs: n.cycleMs,
+			ticketTtlMs: n.ticketTtlMs,
+			...n.pools === void 0 ? {} : { pools: n.pools }
+		});
+	});
+	if (new Set(r.map((e) => e.name)).size !== r.length) throw e("invalid_queue");
+	return Object.freeze(r);
+};
+export { n as captureQueueDeclarations };

package/dist/roomsAllocator.d.ts

@@ -0,0 +1,67 @@
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { resolveIdentityAuthority } from '@voltro/protocol';
+import { RoomReservePort } from '@voltro/plugin-rooms/ports';
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+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. */
+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>>;
+}
+
+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>;
+
+/** Room seats for a match. `roomsAllocator` (`@voltro/plugin-matchmaking/rooms`) is the Rooms implementation. */
+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>;
+}
+
+/**
+ * The Rooms allocator: the first member creates the Room, every other member reserves a seat
+ * in it by id. With a Rooms binding that prepares match Rooms (`prepareMatch`), the Room is
+ * created once per assignment request, so a retried allocation reuses it. Each reservation runs as that member, with authority from the app's own
+ * resolver, so Room guards apply per player. Seat tokens stay in memory for `release`;
+ * an allocation that is never released is not cleaned up here (unredeemed seats expire
+ * with the Rooms seat TTL).
+ */
+export declare const roomsAllocator: (options: RoomsAllocatorOptions) => MatchmakingRoomAllocator;
+
+export declare interface RoomsAllocatorOptions {
+    /** The installed Rooms plugin; its API binding serves the reservations. */
+    readonly rooms: {
+        readonly services: Layer.Layer<never> | Layer.Layer<RoomReservePort>;
+    };
+    /** The Room a match plays in, per queue. */
+    readonly room: (request: MatchmakingAllocationRequest) => {
+        readonly room: string;
+        readonly options: unknown;
+        readonly pool?: string;
+    };
+    /** The app's `auth` block: each member's authority is resolved for their own seat (origin `'workflow'`). */
+    readonly authority?: Parameters<typeof resolveIdentityAuthority>[2];
+    readonly getStore?: () => DataStore | undefined;
+    /** Allocations kept for `release` (their seat tokens live only here). Default 1024. */
+    readonly maxRetained?: number;
+}
+
+export { }