@pithy-sh/matchmaking 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @pithy-sh/matchmaking
+
+Find competitors. Room codes, direct invites, a friend graph, and a skill-bucketed queue — every path lands two or more players in the same authoritative [`@pithy-sh/multiplayer`](../multiplayer) session.
+
+Multiplayer gives you a session once players are in it. This is how they get there. Four ways, one output: a session id.
+
+**Documentation: [pithy.sh/docs/capabilities/matchmaking](https://pithy.sh/docs/capabilities/matchmaking).** Overview, adding it, provisioning, using it, and the reference: the four ways in, the queue and its sweep.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## Add it
+
+```bash
+pithy add matchmaking
+```
+
+That installs the package and writes four bindings into every environment of your Worker's `wrangler.jsonc` — `DB`, `MATCHMAKING`, and the `QUEUE` and `PRESENCE` Durable Object namespaces — together with the `new_sqlite_classes` class migration tags the two Durable Objects need. **That wiring is the reason this is a capability rather than a snippet.** A DO binding is one entry; a DO class migration tag is another, in a different block, repeated per environment, and getting it wrong deploys a Worker whose class does not exist.
+
+One binding it writes without an id: a `kv_namespaces` entry has no name field, so `pithy add` prints the name to give the `MATCHMAKING` namespace in each environment. Create it in your account under that name and paste the id in.
+
+`pithy add` also writes both classes into your worker entry, so wrangler's `class_name` resolves against it:
+
+```ts
+export { MatchmakingQueue } from "@pithy-sh/matchmaking/src/queue/durableObject";
+export { MatchmakingPresence } from "@pithy-sh/matchmaking/src/presence/durableObject";
+```
+
+Each from its own module, never from the package entry point. That entry point is what `pithy.config.ts` imports, and that file is loaded by every Node-side `pithy` command — a Durable Object on that path imports `cloudflare:workers` and takes `pithy upgrade` down with it.
+
+Finally:
+
+```bash
+pithy migrate
+```
+
+**This section stays here.** `src/capability.test.ts` holds those two export lines against the Durable Object classes the capability actually binds, and against the module each must come from. An instruction naming the package entry point would name a module that does not export them — a Worker that fails at bundle time, on the line the docs told somebody to write.
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/docs/costs.md

@@ -0,0 +1,49 @@
+# Matchmaking costs
+
+_The reader's version of this page is [pithy.sh/docs/build/games/what-a-queue-costs](https://pithy.sh/docs/build/games/what-a-queue-costs). This copy ships in the package because `packages/cli/src/capabilities/catalog.ts` sends an adopter to it by name._
+
+Two Durable Objects, one KV prefix, two D1 tables. Cloudflare's [Durable Objects pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/) is the authority for the first, and when the two disagree Cloudflare is right. This page does not restate rates — it says how a pairing layer maps onto them, and names the one setting that changes the answer.
+
+[`@pithy-sh/multiplayer`'s costs page](../../multiplayer/docs/costs.md) already records the two platform facts both capabilities inherit, and they are not repeated here: **WebSocket messages bill at a 20:1 ratio**, and **duration bills the full 128 MB, only while an object is awake**. Read that page first. What follows is what matchmaking adds.
+
+## The presence object is a hibernating socket, and that is the whole cost model
+
+Presence is one Durable Object holding every online player's WebSocket through the Hibernation API. A hibernating object bills no duration, so a thousand players sitting in a menu with the app open cost nothing to hold — you pay for the events that actually flow, discounted 20:1.
+
+That is only true because of what the object refuses to do. It keeps no in-memory connection registry (the live set is read back from `getWebSockets()`), stashes the authenticated identity with `serializeAttachment` rather than in a field, and never calls `ws.accept()` or sets a timer. A single `setInterval` anywhere in it would pin it in memory and bill duration continuously, for every player online, forever.
+
+It is one shared object, so its ceiling is a single object's: a soft **~1,000 requests/second**. Notifications do not approach that, but it is the number to plan against — it is a throughput ceiling, not a bill.
+
+## The queue object bills for waiting, and `sweepSeconds` is the dial
+
+The open queue is one Durable Object per game, and it is the only thing here that wakes up on its own. While anyone is waiting, a single alarm is armed at `now + sweepSeconds`; the alarm wakes the object, re-attempts pairing, widens every waiting player's skill band, and re-arms. Each wake is a request, plus the duration of a short handler.
+
+So the cost of an idle queue is zero and the cost of a *waiting* queue is `sweepSeconds`:
+
+| `sweepSeconds` | Wakes per waiting minute, per game | What it buys |
+|---|---|---|
+| 1 | 60 | Bands widen almost continuously. Pairing latency is dominated by who arrives, not by the sweep. |
+| 5 (default) | 12 | A player waits at most 5 seconds past the moment their band grew wide enough. |
+| 15 | 4 | A fifth of the default's wakes. Noticeable on a thin queue where the band is what unblocks the match. |
+
+**An empty queue clears its alarm.** The handler deletes the alarm the moment the waiting list drains, and the last player to leave deletes it too — so a game nobody is queueing for wakes zero times and bills nothing, whatever `sweepSeconds` says. That is why the number is a per-waiting-minute rate rather than a standing charge.
+
+Two things are not in the table because they do not change with it. A match forms on `enqueue` when an opponent is already waiting, without waiting for a sweep — the sweep exists to widen bands, not to pair. And storage is read fresh and Zod-parsed per handler by design: an eviction costs a read, and holding state in memory to avoid it would cost the hibernation that makes the whole object cheap.
+
+**One object per game, addressed by game key.** Ten games are ten coordinators, each with its own alarm and its own waiting list, and each idle one bills nothing. That is also the sharding: a game's pairing throughput is one object's, so a game expecting more than a single object can carry wants splitting into region- or bracket-keyed games rather than a bigger `sweepSeconds`.
+
+## Room codes are KV, and priced like it
+
+A room code is one KV write when the room opens, one read per join attempt, and one write per redemption to decrement the counter. It expires on its TTL at no cost — nothing sweeps it, and there is no row left behind.
+
+`ttlSeconds` does not change the bill; `maxUses` bounds it, since it caps the redeem writes one shared code can cause. KV was chosen here for exactly this shape: a short-lived pointer with a TTL and a counter is what the store is for, and it is the only thing in this capability that looks like that.
+
+## D1 is two small tables
+
+Invites and the friend graph, billed as rows read and written like every other D1 table. An invite is a row per invitation, resolved by an index on the invitee; a friendship is one row per pair, indexed from both sides so a lookup is one read rather than a scan. Neither grows with play — they grow with the social graph, which is a much slower number.
+
+## What to watch
+
+- **`sweepSeconds`, per game.** The only setting on this page that bills while nothing is happening. Raise it for a thin queue that pairs on arrival anyway; lower it only where band-widening is genuinely what pairs people.
+- **A presence connection that never closes.** Hibernation makes an idle socket free, not a leaked one — a client that reconnects without closing leaves sockets in the set for the object to iterate on every push.
+- **Chatty presence traffic.** Three event types ship, all server-pushed and small. Adding a client-driven heartbeat over this socket would put its messages through the 20:1 ratio and the object's request ceiling both; use the platform's own ping instead.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pithy-sh/matchmaking",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/matchmaking"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "docs",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/rating": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@pithy-sh/auth": {
+      "optional": true
+    },
+    "@pithy-sh/rating": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/rating": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,56 @@
+{
+  "name": "matchmaking",
+  "package": "@pithy-sh/matchmaking",
+  "requiredBindings": [
+    { "type": "d1", "name": "DB" },
+    { "type": "kv", "name": "MATCHMAKING" },
+    {
+      "type": "durable_object",
+      "name": "QUEUE",
+      "className": "MatchmakingQueue",
+      "classModule": "@pithy-sh/matchmaking/src/queue/durableObject"
+    },
+    {
+      "type": "durable_object",
+      "name": "PRESENCE",
+      "className": "MatchmakingPresence",
+      "classModule": "@pithy-sh/matchmaking/src/presence/durableObject"
+    }
+  ],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth", "rating", "multiplayer"],
+  "migrationNamespace": "matchmaking",
+  "whenToEnable": "How players find each other. @pithy-sh/multiplayer gives you an authoritative session once players are in it; this is the four ways they get there, and every one of them ends at a session id. A room code — short, shareable, short-lived, limited-use — for playing with someone who is already beside you. A direct invite by email or screen name, pending until the invitee accepts. A symmetric friend graph formed by mutual accept. And an open queue: one Durable Object per game pairs waiting players, bucketed by Cloudflare's own edge geolocation and by skill read from @pithy-sh/rating, widening each player's skill band the longer they wait until any opponent qualifies. A second Durable Object holds every online player's WebSocket and pushes match-found, invite-received, and friend-request in real time, over the Hibernation API so a connection waiting on nothing bills no duration. Two Durable Objects means two bindings and two class migration tags across every environment, and the CLI writes all of it — that wiring is the reason this is a capability rather than a snippet. Nothing here is a hard dependency: without auth every route is denied, without rating the queue buckets by region alone, without multiplayer session minting is off. Add auth at minimum, and read packages/matchmaking/docs/costs.md before production — a presence socket is cheap and a busy queue's alarm cadence is the dial that decides how cheap.",
+  "scaffold": [
+    "Add a `matchmaking({ games: [...] })` block to pithy.config.ts and declare at least one game.",
+    "Give each game a `key`, a `players` count, an optional `skillPool` naming a @pithy-sh/rating pool, and a `snapshot` — the `kind` and `rules` of the @pithy-sh/multiplayer game a formed match is minted into. Tune `roomCodes` and `queue` per game.",
+    "The CLI has already written both Durable Object exports into your worker entry: `export { MatchmakingQueue } from \"@pithy-sh/matchmaking/src/queue/durableObject\";` and `export { MatchmakingPresence } from \"@pithy-sh/matchmaking/src/presence/durableObject\";` — wrangler's `class_name` resolves against your worker's `main`. Each comes from its own module, never from the package entry point, which pithy.config.ts loads in Node. No hand-editing.",
+    "The CLI has already added the QUEUE and PRESENCE durable_object bindings and their class migration tags (`new_sqlite_classes`) to wrangler.jsonc for every environment. No hand-editing.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Create the MATCHMAKING KV namespace in your Cloudflare account under the name `pithy add` printed for each environment, and paste its id into the entry add already wrote. A kv_namespaces entry has no name field, so the title can only live in the account. Room codes live there under a TTL; nothing else does.",
+    "Run `pithy migrate` to create pithy_matchmaking_invites and pithy_matchmaking_friends.",
+    "Add `@pithy-sh/auth` if it is not already installed. Every route binds to an authenticated player; without auth all of them are denied.",
+    "Add `@pithy-sh/multiplayer` and bind its SESSIONS Durable Object namespace. Without it every pairing path still runs and none of them can mint the session it exists to produce.",
+    "Add `@pithy-sh/rating` and name one of its pools as a game's `skillPool` to bucket the open queue on skill. Without it the queue buckets by region only.",
+    "Read packages/matchmaking/docs/costs.md before production. The queue's `sweepSeconds` is the alarm cadence, and it is the one setting that decides whether a waiting queue costs anything."
+  ],
+  "configOptions": [
+    {
+      "key": "games",
+      "default": [
+        { "key": "duel", "snapshot": { "kind": "connect-n", "rules": { "rows": 3, "cols": 3, "connect": 3 } } }
+      ],
+      "describe": "Every game players are matched into. Replace this example — a two-player duel that mints a 3x3 connect-3 multiplayer session, which is the smallest game that actually plays. `key` is a URL path segment; `snapshot` is the multiplayer game the match becomes; add `skillPool` to bucket the queue on a rating pool. At least one game is required."
+    },
+    {
+      "key": "friends",
+      "default": true,
+      "describe": "Whether the friend graph — request, accept, decline, remove — is mounted. Turn it off for a game where players only ever meet through a code or the queue, and its routes and tables go unused."
+    },
+    {
+      "key": "basePath",
+      "default": "/matchmaking",
+      "describe": "Where the matchmaking routes mount. Rooms, invites, friends, and the queue live under it, and the presence WebSocket is at `<basePath>/presence`."
+    }
+  ]
+}

package/src/capability.ts

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { Migration } from "kysely/migration";
+import { MatchmakingConfig, type MatchmakingConfigInput } from "./config/config";
+import { matchmakingTables } from "./data/tables";
+import { registerMatchmakingRoutes } from "./http/routes";
+import { ROOM_PREFIX, Room, RoomKey } from "./kv/rooms";
+import { matchmaking_0001_matchmaking } from "./migrations/0001_matchmaking";
+import { matchmakingExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * Where matchmaking's migrations sort in the app database. Unique per database; the registry composes keys
+ * like `0700_matchmaking_0001_matchmaking`. Sits after rating (600).
+ */
+export const MATCHMAKING_MIGRATION_ORDER = 700;
+
+export type MatchmakingOptions = MatchmakingConfigInput & {
+  /** Mount the routes somewhere other than `/matchmaking`. */
+  basePath?: string;
+};
+
+export interface MatchmakingCapability extends Capability {
+  matchmakingConfig: MatchmakingConfig;
+}
+
+/**
+ * The matchmaking capability: find competitors and land in an authoritative multiplayer session. Room
+ * codes, direct invites, a symmetric friend graph, and an open queue bucketed by region and skill —
+ * every path outputs a `@pithy-sh/multiplayer` session id.
+ *
+ * Optional peers, all reached as seams (never hard `dependsOn`): `@pithy-sh/auth` (identity — reads
+ * `c.var.auth`, resolves invite targets), `@pithy-sh/rating` (skill for queue bucketing), and
+ * `@pithy-sh/multiplayer` (the `SESSIONS` binding, read at runtime to mint sessions). Absent any of them,
+ * matchmaking degrades: denied without auth, region-only queue without rating, session-minting disabled
+ * without multiplayer.
+ */
+export function matchmaking(options: MatchmakingOptions = { games: [] }): MatchmakingCapability {
+  const { basePath, ...configInput } = options;
+  const resolved = MatchmakingConfig.parse(configInput);
+
+  const migrations: Record<string, Migration> = { "0001_matchmaking": matchmaking_0001_matchmaking };
+
+  const requiredBindings: BindingSpecInput[] = [
+    { type: "d1", name: "DB" },
+    { type: "kv", name: "MATCHMAKING" },
+    {
+      type: "durable_object",
+      name: "QUEUE",
+      className: "MatchmakingQueue",
+      classModule: "@pithy-sh/matchmaking/src/queue/durableObject",
+    },
+    {
+      type: "durable_object",
+      name: "PRESENCE",
+      className: "MatchmakingPresence",
+      classModule: "@pithy-sh/matchmaking/src/presence/durableObject",
+    },
+  ];
+
+  const capability = defineCapability({
+    name: "matchmaking",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    requiredBindings,
+    config: MatchmakingConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: matchmakingTables(),
+        migrationOrder: MATCHMAKING_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    kvNamespaces: {
+      matchmaking: {
+        binding: "MATCHMAKING",
+        stores: {
+          rooms: { prefix: ROOM_PREFIX, key: RoomKey, value: Room },
+        },
+      },
+    },
+    routes: registerMatchmakingRoutes({ config: resolved, basePath }),
+    seeds: [matchmakingExampleSeed],
+  });
+
+  return Object.assign(capability, { matchmakingConfig: resolved });
+}
+
+export function isMatchmakingCapability(c: Capability): c is MatchmakingCapability {
+  return c.name === "matchmaking" && "matchmakingConfig" in c;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`. `cloudflare:test` types its `env` as `Cloudflare.Env`, so test
+// bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    MATCHMAKING: KVNamespace;
+    QUEUE: DurableObjectNamespace<import("./queue/durableObject").MatchmakingQueue>;
+    PRESENCE: DurableObjectNamespace<import("./presence/durableObject").MatchmakingPresence>;
+    SESSIONS?: DurableObjectNamespace;
+  }
+}

package/src/code/room.ts

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { KVNamespace } from "@cloudflare/workers-types";
+import type { MatchmakingGame } from "../config/config";
+import { MatchmakingInvalidCodeError, MatchmakingRoomFullError, MatchmakingRoomNotFoundError } from "../error/errors";
+import { roomStore } from "../kv/rooms";
+import type { SessionMinter } from "../session/minter";
+
+/**
+ * Room codes — the zero-discovery, play-with-a-friend path. A host opens a room: a multiplayer session is
+ * minted (host as creator) and a short, shareable code (`WXYZ-1234`) is stored in KV pointing at it, with
+ * a TTL and a limited-use counter. Others redeem the code to join the same session. See the workflow
+ * implementation for the code alphabet (ambiguous characters excluded) and the redeem/decrement logic.
+ */
+
+/** The result of opening a room. */
+export interface RoomCreation {
+  /** The shareable join code. */
+  code: string;
+  /** The multiplayer session the room joins players into. */
+  sessionId: string;
+}
+
+/** The result of redeeming a room code. */
+export interface RoomJoin {
+  /** The multiplayer session the joiner was seated into. */
+  sessionId: string;
+  /** Redemptions the code has left after this join. */
+  usesRemaining: number;
+}
+
+/** Unambiguous letters for the code prefix — I and O are excluded (they read as 1 and 0). */
+const CODE_LETTERS = "ABCDEFGHJKLMNPQRSTUVWXYZ";
+/** Unambiguous digits for the code suffix — 0 and 1 are excluded (they read as O and I/L). */
+const CODE_DIGITS = "23456789";
+/** The canonical shape a normalized code takes: four letters, a dash, four digits. */
+const CANONICAL = /^[A-Z]{4}-[0-9]{4}$/;
+/** The same shape without its dash — tolerated on input and repaired to canonical. */
+const DASHLESS = /^[A-Z]{4}[0-9]{4}$/;
+
+/** Normalize and validate a raw room code (uppercase, canonical form). Throws `matchmaking/invalid_code`. */
+export function normalizeCode(raw: string): string {
+  const cleaned = raw.toUpperCase().replace(/\s+/g, "");
+  if (CANONICAL.test(cleaned)) return cleaned;
+  if (DASHLESS.test(cleaned)) return `${cleaned.slice(0, 4)}-${cleaned.slice(4)}`;
+  throw new MatchmakingInvalidCodeError({ detail: `Malformed room code: "${raw}".` });
+}
+
+/** Draw `count` characters from `alphabet` using the CSPRNG. */
+function pick(alphabet: string, count: number): string {
+  const bytes = new Uint8Array(count);
+  crypto.getRandomValues(bytes);
+  let out = "";
+  for (const byte of bytes) {
+    out += alphabet[byte % alphabet.length];
+  }
+  return out;
+}
+
+/** Generate a fresh canonical room code (`WXYZ-1234`) from the unambiguous alphabets. */
+function generateCode(): string {
+  return `${pick(CODE_LETTERS, 4)}-${pick(CODE_DIGITS, 4)}`;
+}
+
+/** Open a room: mint a session with `hostId` as creator, store a fresh code in KV, return both. */
+export async function createRoom(
+  namespace: KVNamespace,
+  game: MatchmakingGame,
+  minter: SessionMinter,
+  hostId: string,
+  now: Date,
+): Promise<RoomCreation> {
+  const sessionId = await minter.mint(game.snapshot, game.players, [hostId]);
+  const ttlSeconds = game.roomCodes.ttlSeconds;
+  const store = roomStore(namespace, ttlSeconds);
+
+  let code = generateCode();
+  while ((await store.get({ code })) !== null) {
+    code = generateCode();
+  }
+
+  await store.put(
+    { code },
+    {
+      code,
+      gameKey: game.key,
+      hostId,
+      sessionId,
+      usesRemaining: game.roomCodes.maxUses,
+      createdAt: now,
+      expiresAt: new Date(now.getTime() + ttlSeconds * 1000),
+    },
+  );
+
+  return { code, sessionId };
+}
+
+/**
+ * Redeem a code: seat `userId` into the room's session, decrement uses, re-persist with a TTL recomputed
+ * from the room's `expiresAt` (so redeeming does not extend the window). The room value carries everything
+ * needed — session id, uses, expiry — so no game config is required here. Throws room_not_found/room_full.
+ *
+ * Concurrency note: this is a read-modify-write over KV, which has no compare-and-swap, so two simultaneous
+ * redemptions of the same code can both read the same `usesRemaining` and both decrement it — a code can be
+ * redeemed slightly past `maxUses`. This is intentional and harmless: the multiplayer session's own roster
+ * cap is the real guard (an extra joiner past the roster is rejected with `multiplayer/session_full`), so an
+ * over-redeemed code cannot over-seat a session; the only effect is that a raced code may outlive its use
+ * count by a redemption or two. Making it strictly atomic would mean moving room state into D1 (an atomic
+ * `UPDATE … WHERE uses > 0`) or a per-code Durable Object; not worth it for this guarantee.
+ */
+export async function joinRoom(
+  namespace: KVNamespace,
+  minter: SessionMinter,
+  code: string,
+  userId: string,
+  now: Date,
+): Promise<RoomJoin> {
+  // A placeholder TTL just to read — the write below rebuilds the store with the correct remaining window.
+  const room = await roomStore(namespace, 60).get({ code });
+  if (room === null) {
+    throw new MatchmakingRoomNotFoundError({ detail: `No room for code "${code}".` });
+  }
+  if (room.usesRemaining <= 0) {
+    throw new MatchmakingRoomFullError({ detail: `Room "${code}" is spent.` });
+  }
+
+  await minter.join(room.sessionId, userId);
+
+  // Recompute the TTL from the room's own expiry so redeeming never extends the window. KV's floor is 60.
+  const remaining = Math.max(60, Math.ceil((room.expiresAt.getTime() - now.getTime()) / 1000));
+  const usesRemaining = room.usesRemaining - 1;
+  await roomStore(namespace, remaining).put({ code }, { ...room, usesRemaining });
+
+  return { sessionId: room.sessionId, usesRemaining };
+}

package/src/config/config.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The matchmaking capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field is
+ * `.describe()`d (CLAUDE.md §Config). A game declares how many players form a match, an optional
+ * `@pithy-sh/rating` pool to bucket the open queue on, and the `snapshot` used to mint the
+ * `@pithy-sh/multiplayer` session a match resolves into. Room codes, the queue, and abuse protection are
+ * configured per game and per capability.
+ */
+
+/** A game key is a URL path segment, so it is kebab-case and lowercase. */
+const KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** The minimal multiplayer `GameSnapshot` matchmaking needs to mint a session when a match forms. */
+export const MatchmakingSnapshot = z
+  .object({
+    kind: z
+      .string()
+      .min(1)
+      .describe("The multiplayer game-model kind the session runs — a `kind` registered in @pithy-sh/multiplayer."),
+    mode: z
+      .enum(["match", "table"])
+      .default("match")
+      .describe("The multiplayer session lifecycle — a one-off `match` or a long-lived `table`."),
+    turnTimeoutMs: z
+      .number()
+      .int()
+      .min(1000)
+      .nullable()
+      .default(null)
+      .describe("The session's per-turn deadline in ms, or null for no deadline. Passed through to the session."),
+    rules: z
+      .unknown()
+      .describe("The multiplayer game-model's `rules` block, passed through to the minted session unchanged."),
+  })
+  .describe("How to mint the multiplayer session a formed match resolves into.");
+export type MatchmakingSnapshot = z.output<typeof MatchmakingSnapshot>;
+
+/** Room-code settings — the zero-discovery, play-with-a-friend path. */
+export const MatchmakingRoomCodes = z
+  .object({
+    enabled: z.boolean().default(true).describe("Whether a host may open a room and share a join code."),
+    ttlSeconds: z
+      .number()
+      .int()
+      .min(60)
+      .default(900)
+      .describe("How long a room code stays valid, in seconds (KV TTL; floor 60). Default 15 minutes."),
+    maxUses: z
+      .number()
+      .int()
+      .positive()
+      .default(9)
+      .describe("How many times a code may be redeemed before it is spent — bounds abuse of a shared code."),
+  })
+  .describe("Room-code settings: a short, shareable, short-lived, limited-use join code.");
+export type MatchmakingRoomCodes = z.output<typeof MatchmakingRoomCodes>;
+
+/** Open-queue settings — the skill/region-bucketed pairing coordinator. */
+export const MatchmakingQueueSettings = z
+  .object({
+    enabled: z.boolean().default(true).describe("Whether players may enqueue for open matchmaking in this game."),
+    initialBand: z
+      .number()
+      .nonnegative()
+      .default(100)
+      .describe(
+        "The initial skill band half-width — a waiting player first matches only others within ±band of their skill.",
+      ),
+    widenPerSecond: z
+      .number()
+      .nonnegative()
+      .default(50)
+      .describe(
+        "How much the skill band widens for every second a player waits — relaxes the match the longer they wait.",
+      ),
+    maxWaitSeconds: z
+      .number()
+      .int()
+      .positive()
+      .default(120)
+      .describe(
+        "After this wait the band is unbounded — the player matches any available opponent in their region bucket.",
+      ),
+    sweepSeconds: z
+      .number()
+      .int()
+      .positive()
+      .default(5)
+      .describe("How often, in seconds, the coordinator re-attempts pairing and widens bands (its alarm cadence)."),
+  })
+  .describe("Open-queue pairing settings: how the skill band starts and widens over time.");
+export type MatchmakingQueueSettings = z.output<typeof MatchmakingQueueSettings>;
+
+export const MatchmakingGame = z
+  .object({
+    key: z
+      .string()
+      .regex(KEY_PATTERN, "A game key is lowercase, digits, and dashes — it is a URL path segment.")
+      .describe("The game's stable id, unique across the app. A URL path segment."),
+    players: z.number().int().min(2).default(2).describe("How many players form a match in this game (default 2)."),
+    skillPool: z
+      .string()
+      .optional()
+      .describe(
+        "The @pithy-sh/rating pool to bucket the open queue on. Omit to bucket by region only (no skill matching).",
+      ),
+    snapshot: MatchmakingSnapshot.describe("How the multiplayer session is minted when a match forms."),
+    roomCodes: MatchmakingRoomCodes.prefault({}).describe("Room-code settings for this game."),
+    queue: MatchmakingQueueSettings.prefault({}).describe("Open-queue settings for this game."),
+  })
+  .describe("One matchmaking game: its roster size, skill pool, session snapshot, and pairing settings.");
+export type MatchmakingGame = z.output<typeof MatchmakingGame>;
+
+/** Room-code join abuse protection — opt-in, off by default. */
+export const MatchmakingAbuse = z
+  .object({
+    turnstile: z
+      .boolean()
+      .default(false)
+      .describe("Gate room-code join with a Turnstile humanity check (needs @pithy-sh/turnstile). Off by default."),
+    rateLimit: z.boolean().default(false).describe("Rate-limit room-code join attempts per user. Off by default."),
+  })
+  .describe("Opt-in abuse protection for room-code join.");
+export type MatchmakingAbuse = z.output<typeof MatchmakingAbuse>;
+
+export const MatchmakingConfig = z
+  .object({
+    games: z
+      .array(MatchmakingGame)
+      .min(1, "A matchmaking capability needs at least one game — configure at least one.")
+      .describe("The matchmaking games. Each declares its roster, skill pool, and session snapshot."),
+    friends: z.boolean().default(true).describe("Whether the friend graph (requests, accepts, removal) is enabled."),
+    abuse: MatchmakingAbuse.prefault({}).describe("Room-code join abuse protection (off by default)."),
+  })
+  .describe("The matchmaking capability's configuration.")
+  .check((ctx) => {
+    const seen = new Set<string>();
+    for (const game of ctx.value.games) {
+      if (seen.has(game.key)) {
+        ctx.issues.push({
+          code: "custom",
+          input: game.key,
+          path: ["games"],
+          message: `Duplicate game key "${game.key}" — each game key must be unique.`,
+        });
+      }
+      seen.add(game.key);
+    }
+  });
+export type MatchmakingConfig = z.output<typeof MatchmakingConfig>;
+export type MatchmakingConfigInput = z.input<typeof MatchmakingConfig>;
+
+/** The configured game for a key, or undefined. */
+export function resolveGame(config: MatchmakingConfig, key: string): MatchmakingGame | undefined {
+  return config.games.find((g) => g.key === key);
+}