@voltro/plugin-matchmaking 0.0.0-stage → 0.88.0

package/LICENSE

@@ -0,0 +1,61 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. The license covers use by your
+authorised named users only, up to the number of seats (or other billing metric)
+your plan or order covers; each named user must be an identified individual
+using their own personal account, and accounts, access credentials and seats
+must not be shared. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -1,3 +1,273 @@
-# Temporary Holding Version
+# Matchmaking foundations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This implementation is **built**. It contains queue descriptions, pure matching
+policies and an installable SQL solo-ticket admission adapter.
+
+## Take
+
+`@voltro/plugin-matchmaking/queue` exports `defineQueue` and `runQueueMatch`;
+`./strategies` exports `fifo`, `skillWindow`, `regionLatency`, `composite` and
+`validateMatchOutput`. The root also exports these functions and `packTeams`.
+The server root also exports `matchmakingPlugin(options)` and `MatchmakingPort`.
+The factory installs three admission tables and the enqueue/cancel/status RPCs;
+it requires explicit `queues`, trusted `prepareTicket` and transactional `admit`
+callbacks. No default skill/policy provider, Director or Room allocation exists
+yet. A queue descriptor alone does not activate matching. Browser descriptors
+import `./rpc`, errors from `./errors`; the root now includes server-only code.
+
+```ts
+import { Schema } from 'effect'
+import { defineQueue } from '@voltro/plugin-matchmaking/queue'
+import { skillWindow } from '@voltro/plugin-matchmaking/strategies'
+
+const ticket = Schema.Struct({
+  skill: Schema.Number,
+  region: Schema.String,
+  latencies: Schema.Record(Schema.String, Schema.Number),
+})
+
+const queue = defineQueue({
+  name: 'ranked-2v2', room: 'arena', ticket,
+  teams: { count: 2, size: 2 },
+  pools: { byRegion: attributes => attributes.region },
+  matchFunction: skillWindow({ initialWindow: 100, growPerSecond: 25,
+    maxWindow: 600, latencyMaxMs: 120 }),
+  minQuality: { initial: 0.8, after: [[30000, 0.5], [90000, 0]] },
+})
+```
+
+`runQueueMatch(queue, { tickets, now, avoid })` takes server-owned ticket evidence
+and an explicit clock. Tickets contain `id`, `tenantId`, `queue`, `members`,
+`createdAt`, `attributes`; this is a pure Director input, not a player RPC state
+payload. The function schema-checks attributes without silently coercing data,
+partitions through the captured pool callback, executes the actual matching slot
+and validates its output. Ticket tenant mixing, duplicate ticket/subject IDs,
+future creation times, sparse arrays, non-JSON attributes and budgets refuse.
+Object key order does not change JSON identity.
+
+## Parties
+
+`matchmakingPlugin({ …, parties: { maxPartySize?, partyInviteTtlMs? } })` installs
+ephemeral SQL parties (default size 8, max 256; invites live 10 minutes by default).
+Routes under `matchmaking.parties.*`: `create` (idempotent per `requestId`, the caller
+becomes leader; `approval: 'leader' | 'open'`), `invite` (leader only), `join`
+(needs a live invite unless the party is open; `party_full` at capacity), `leave`,
+`kick` and `transferLeader` (leader only), `setReady`, plus the live queries
+`mine` (the caller's party or `null`) and `invites`. Hooks in `./web`: `useParty`,
+`usePartyInvites`, `useCreateParty`, `useInviteToParty`, `useJoinParty`,
+`useLeaveParty`, `useKickFromParty`, `useSetPartyReady`, `useTransferPartyLeader`, and the
+presentational `PartyPanel` (en/de `partyLabels`).
+
+A subject belongs to at most one party per tenant (`already_in_party`). When the
+leader leaves, the longest-standing member takes over; the last member leaving
+dissolves the party and its invites. `PartyMembershipPort` answers current
+membership for other plugins. Export adds `parties` (own membership, sent and
+received invites); erase leaves the party first, then deletes invites, then runs
+the ticket hook.
+
+Party search: the leader calls `matchmaking.parties.search({ partyId, queue,
+requestId, preferences })` (`useSearchAsParty`) once every member is ready
+(`party_not_ready` otherwise). One ticket lists all members and every member's claim
+points at it, so nobody can search alone meanwhile (`already_searching`). Members read
+it with `matchmaking.status`; `mine` reports it as `searchTicketId`. Any member stops
+it with `matchmaking.parties.cancelSearch` (`useCancelPartySearch`); the solo
+`matchmaking.cancel` refuses party tickets. Join, leave, kick, leader transfer and
+withdrawn readiness cancel an open search in the same transaction. The leader's
+`prepareTicket` result stands for the party. Locks go party → member claims (sorted)
+→ queue. The `party.invited` event and presence remain open.
+
+### Server roster composition
+
+Resolve `PartyRosterPort` from `./port` through the scoped Effect context for
+trusted server composition. `read(tenantId, partyId)` returns `null` for a missing
+party in that tenant, otherwise a detached, frozen
+`{ tenantId, partyId, leaderId, memberIds }` snapshot (leader first, remaining IDs
+in stable order). The default reader locks the party before its members, matching
+the writers' order without writing admission counters, tickets or timestamps.
+Current leader transfer, privacy erasure and final-member dissolution are observed.
+Malformed/corrupt membership refuses instead of returning a partial roster.
+
+This adds no player RPC. The caller must authorize its operation and resolve
+actual member Subjects and current World locations. IDs do not imply Subject
+kinds or movement authority; a snapshot is not a lease. A durable World command
+must retain its original captured members on replay. Reads created before binding,
+queued across rebinding/deactivation, or completed after a binding change refuse
+with `unavailable`. Full replacements supply this separate port in their scoped
+Layer; `fakePartyRosterLayer(read)` in `./testing` accepts the complete reader and
+fails closed when omitted. The existing membership port is unchanged.
+
+## Configure
+
+| Option | Default | Authoring budget |
+|---|---|---|
+| `teams` | required | At most 64 teams, 256 players/team, 4,096 total slots |
+| `maxTickets` | 10,000 | Maximum supplied tickets; not accepted Director capacity |
+| `maxSearchNodes` | 100,000 | Branch inspections shared across policies and partitions |
+| `maxAvoidPairs` | 10,000 | Maximum supplied symmetric exclusion pairs |
+| `maxAttributeBytes` | 16,384 | UTF-8 JSON bytes per ticket; JSON depth at most 32 |
+| `minQuality` | initial 0, no steps | Non-increasing quality floor with strictly increasing wait times |
+| `cycleMs` | 1,000 | Descriptor only; no scheduler is installed |
+| `ticketTtlMs` | 300,000 | SQL ticket lifetime; owner-triggered expiry, no sweep job yet |
+| `maxPreferencesBytes` | 4,096 | Bounded JSON preference intent; at most 65,536 bytes |
+| `maxExportRows` | 10,000 | Refuses an incomplete privacy export/erase; at most 100,000 rows |
+
+Rules, schedules and callback selection are captured at description time.
+A matching call copies/fixes its ticket data; the solver owns no clock, timer,
+connection, store or per-process authoritative ticket registry. Parties are
+indivisible. Parties larger than a team stay in leftovers. The iterative solver
+backtracks when first-fit packing fails and stops at the configured branch budget,
+returning `exhausted`, `searchNodes` and every unassigned ticket. These counters
+are algorithm observations, not measured CPU duration or throughput.
+
+## Hook
+
+`matchmaking.enqueue` and `matchmaking.cancel` are Actions: the adapter owns
+their SQL transactions. `matchmaking.status` is a reactive Query on the ticket
+table; the executor checks the verified caller and exact tenant/owner. The wire
+accepts only `{ queue, requestId, preferences }`, never authoritative attributes,
+party members, state or assignments. Required `prepareTicket` resolves trusted
+attributes before SQL; required `admit` rechecks durable eligibility inside the
+borrowed transaction. Actual default Social/Sanctions integration is still open.
+
+Subject and queue admission rows serialize one live solo search across queues
+and the live queue cap. Exact request receipts return the committed ticket before
+calling either provider again, through the subject erase fence; changed intent
+refuses. Cancel is repeatable. Starting a new intention expires the owner’s old
+expired search atomically. Status is read-only and may show `open` after its
+`expiresAt` until a new intention or future sweep persists expiry.
+
+`./web` provides `useEnqueueMatchmaking`, `useCancelMatchmaking` and
+`useMatchmakingStatus(ticketId, apiName)`. Actions are explicit; absent ticket
+selection keeps the subscription idle. No hidden polling/retry/auto-enqueue is
+installed. Assignment events, listener revocation, workflow triggers, ordinary
+queue discovery and the combined `useMatchmaking` lobby remain unfinished.
+A pure match result grants no seat/session/token. SQL is ticket truth; no hot
+index or additional authoritative per-process ticket registry is introduced.
+
+## Override
+
+`fifo()` prefers canonical oldest-ticket/ID order and returns quality 1.
+`skillWindow()` grows the permitted skill spread using the oldest candidate's
+waiting time, up to `maxWindow`; quality is `1 - spread / maxWindow` (or 1 for
+zero spread/zero maximum). With `latencyMaxMs`, all candidates need the same
+region and bounded latency evidence for that region. `regionLatency()` applies
+that region rule and uses `1 - worstLatency / latencyMaxMs`, with quality 1 at
+zero latency/zero maximum. These caller-supplied values are not verified network
+measurements. Skill and latency providers remain author/server authority.
+
+`composite([first, second])` applies policies to leftovers in order, sharing the
+original search budget. Every custom result is checked for full team size,
+whole original tickets, disjoint assignment, explicit complete leftovers,
+configured minimum quality and exclusion pairs. Missing/forged/foreign tickets
+refuse; no automatic fallback overwrites a failed slot. An `avoid` pair excludes
+the two subjects from the entire match, including opposite teams and the same
+party. Actual `SocialBlockPort` acquisition remains future work; this pure input
+alone does not establish integration with Social or Sanctions.
+
+## Extend or replace
+
+`./port` exports the three-method `MatchmakingPort`; routes resolve that Tag
+from their Effect context, so a replacement Layer uses the same RPC contract.
+`./testing` exports `fakeMatchmakingService`/`fakeMatchmakingLayer`, with missing
+methods failing closed. The default service clears on plugin deactivation and
+one plugin instance refuses binding another app store.
+
+`./server` exports `dataStoreMatchmakingTickets`, `TicketAdmissionOptions` and
+the ticket/subject-admission/queue-admission table handles. This standalone
+adapter borrows the supplied DataStore and exposes the same service plus
+export/erase. Tables are `_voltro_mm_tickets`, `_voltro_mm_subject_admission`
+and `_voltro_mm_queue_admission`. Export projects only the target’s ticket DTOs;
+erase deletes those tickets and retains a redacted hashed subject fence with no
+plain subject ID or active ticket pointer. Peers and queue budgets remain. The
+fence prevents recreation after adapter reopening; this is not a compliance
+claim. All privacy hooks refuse bounded incomplete work rather than silently
+truncate.
+
+## Panel and GM
+
+The read-only process `/status` inspect endpoint reports captured
+queue/admission budgets, required author slots and the default adapter binding.
+It does not read SQL or enumerate tickets/players/attributes.
+`directorInstalled:false` expressly means matching/allocation is unfinished. The
+shared bilingual Matchmaking page is wired into both Local and Cloud dashboards,
+their current instance/replica selection and the shared AppInspector feature
+catalog. Cloud uses authorized app-scoped plugin-inventory validation; Local
+uses the existing read credential transport. Unknown/malformed snapshots fail
+instead of becoming empty data. Reload remains focusable while duplicate refresh
+admission is guarded. No live queue-depth/match counters, GM writes or capacity
+claim exists yet; these remain open alongside templates/manifests and
+allocation-aware panel additions.
+
+## Tests
+
+`./testing` exports `matchmakingInputFixture` and `matchFunctionFixture`, using
+actual pure policies. Adapter/plugin tests additionally author actual
+transactional rollback, intent/identity capture, port replacement, caps and
+erase. Six native fixtures (PostgreSQL, MySQL, MariaDB, MSSQL, SQLite, Turso)
+each author SQL roundtrip, two-pool owner/queue races, rollback, successor
+expiry and privacy; missing fixture credentials fail rather than become
+acceptance skips. No native fixture has run.
+
+## Trusted SQL Director planning
+
+The installed `plugin.matchmaking.plan(subject, { tenantId, queue })` facade and
+`dataStoreMatchmakingTickets(...).director.plan(...)` now implement the read/
+planning stage over the same borrowed SQL ticket store. `./server` additionally
+exports `dataStoreMatchmakingPlanner(store, { queues, avoidPairs, now })` for an
+explicit server-owned composition. Queue/callback selection is captured with the
+same single declaration-capture implementation used by admission. The stage
+requires a trusted system Subject; human, anonymous and external service callers
+refuse. No player planning route or new port authority is added.
+
+```ts
+import { Effect, Schema } from 'effect'
+import { systemSubject } from '@voltro/protocol'
+import { matchmakingPlugin } from '@voltro/plugin-matchmaking'
+import { defineQueue } from '@voltro/plugin-matchmaking/queue'
+import { fifo } from '@voltro/plugin-matchmaking/strategies'
+
+export const matchmaking = matchmakingPlugin({
+  queues: [defineQueue({ name: 'duels', room: 'arena', ticket: Schema.Struct({ skill: Schema.Number }),
+    teams: { count: 2, size: 1 }, matchFunction: fifo<{ readonly skill: number }>() })],
+  prepareTicket: () => Effect.succeed({ skill: 100 }),
+  admit: () => Effect.void,
+})
+// In trusted server code, after this same plugin has bound its SQL adapter:
+const proposal = matchmaking.matchmaking.plan(systemSubject('queue-planning'), { tenantId: 'game', queue: 'duels' })
+```
+
+This thin example's skill/admission rules are intentionally author supplied;
+production default Players/Sanctions bindings remain unfinished. Planning reads
+only current tenant/queue open tickets with expiry strictly after the captured
+clock. A complete scan over `maxTickets` refuses instead of returning a truncated
+queue. It validates actual SQL roster/scope/time and detached attribute budgets,
+then runs the real queue partition/match/output admission. It returns proposals,
+complete leftovers, search-node count/exhaustion and observation scope/time.
+These are read observations, not ticket claims, assignments or measured capacity.
+Repeated reads can propose the same tickets. A later writer must atomically
+recheck/claim all original tickets and admit an idempotent Room allocation.
+No singleton workflow, debounce/timer, SQL claim/assignment, allocation/retry,
+backfill or event settlement is activated by this facade.
+
+`avoidPairs(context)` is a captured Effect slot with immutable scoped candidate
+records, explicit `maxPairs` and the actual DataStore read query capability; it
+exposes no mutators. Root, `./server` and browser-safe `./strategies` export the
+single `defaultMatchmakingAvoidPairs`, whose empty policy is for an app without a
+block provider. `./testing` supplies `matchmakingAvoidPairsFixture(query)` using
+the actual supplied read capability. A custom provider's pairs pass the same
+bounded pure matcher validation; its typed refusal retains the error code.
+Automatic optional Social block binding/shadow-pool enforcement remains open;
+empty defaults are not evidence that an installed Social plugin is integrated.
+Both dashboards report actual default/custom provider selection while keeping
+`directorInstalled: false`. No queue depth/player data is in inspection.
+
+The plan contains owner/attribute data for trusted processing only; do not put
+it in a workflow payload/result or expose it to clients. A durable Director
+needs opaque persisted identities and privacy-aware settlement. Plugin
+deactivation clears the owned facade; ordinary client routing still resolves
+MatchmakingPort and keeps its existing replacement semantics.
+
+
+## Production license admission
+
+Declare the actual `licensingPlugin()` before this plugin in the API app. Production and staging activation require its verified active or grace deployment-wide license to grant `matchmaking`. Explicit development/test mode stays free without recurring per-instance notices; CLI owns the actual template first-boot receipt. Tenant-scoped licenses refuse until actual tenant-bound authority exists. This server-only gate preserves normal schema, store binding and cleanup; it runs before the original activation hook, not before schema/store binding.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.