@pithy-sh/multiplayer 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,17 @@
+# @pithy-sh/multiplayer
+
+Authoritative, turn-based multiplayer sessions on Cloudflare. The server holds the game state no client can be trusted with, resolves it, and writes a durable result to your own D1.
+
+Sessions infrastructure plus pluggable game models. The session is the same for every game; what a *game* is lives behind a `GameModel`. Three example games ship, and you can register your own.
+
+```sh
+pithy add multiplayer
+```
+
+**Documentation: [pithy.sh/docs/capabilities/multiplayer](https://pithy.sh/docs/capabilities/multiplayer).** Overview, adding it, using it, and the reference: sessions, the game-model seam, hidden state, randomness.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value, the same as `@pithy-sh/auth` and `@pithy-sh/leaderboard`. The root `LICENSE` covers it.

package/docs/costs.md

@@ -0,0 +1,41 @@
+# Multiplayer costs
+
+_The reader's version of this page is [pithy.sh/docs/capabilities/multiplayer](https://pithy.sh/docs/capabilities/multiplayer). This copy ships in the package because `packages/multiplayer/scripts/costModel.ts` sends an adopter to it by name._
+
+Rates as of **2026-07-16**. Cloudflare's [Durable Objects pricing](https://developers.cloudflare.com/durable-objects/platform/pricing/) is the authority — this page explains how a session maps onto it, and carries the two caveats that make a naive estimate wrong. When the two disagree, Cloudflare is right.
+
+A multiplayer session is one Durable Object. You pay for three things: requests, duration, and storage. The shape of the bill is dominated by one fact — **a session waiting on a player's turn hibernates, and a hibernating object bills no duration.** Turn-based, asynchronous play is the quadrant where a Durable Object is genuinely excellent, and it is the only quadrant this capability serves.
+
+## The 20:1 WebSocket caveat
+
+This is the number that makes a headline estimate wrong, so it comes first.
+
+Cloudflare bills WebSocket *messages* as requests, but applies a **20:1 ratio for billing**: *"for compute requests billing-only, a 20:1 ratio is applied to incoming WebSocket messages to factor in smaller messages for real-time communication."* Twenty inbound WebSocket messages bill as one request.
+
+A cost model built off the headline $0.15 per million request rate, counting every WebSocket frame as a request, **overstates a chatty session by up to 20×.** Getting this wrong is a brand risk, not a rounding error — Pithy publishes honest cost models, so a figure here that ignored the 20:1 ratio would be worse than no figure.
+
+A turn-based session is not chatty. A few players, a handful of messages each — a create, a join, an action per turn, a resolve. Even before the 20:1 discount, a whole session is a few dozen billable events, whatever the game model.
+
+## Duration bills the full 128 MB, and only while awake
+
+Duration is `GB-s = seconds × 128 MB ÷ 1 GB`. The 128 MB is fixed: **you pay for the full allocation regardless of how little memory the session actually uses**, so per-object duration cost is memory-independent. There is no saving to chase in a smaller state.
+
+The saving to chase is hibernation. Duration is billed *"while the Durable Object is actively running or is idle in memory but unable to hibernate."* A session that has both players' commits and is waiting on nothing resolves and goes terminal. A session waiting on a slow player **hibernates between messages and bills no duration** — which is why this capability uses the WebSocket Hibernation API, alarms instead of timers, and holds nothing important in memory. A single `setInterval` anywhere would forfeit all of it: timers prevent hibernation entirely, pinning the object in memory and billing duration continuously.
+
+This is also why real-time action netcode is out of scope. A fixed high-rate tick loop must wake constantly, so it never hibernates and bills duration the whole match — the exact cost this capability is designed to avoid.
+
+## Storage
+
+Session state lives in the object's SQLite-backed storage. Rows are billed exactly as D1 rows, and each object caps at 10 GB. A duel's state is tiny — metadata, two commits, one outcome — and the object is a natural place to let it expire; the durable *result* is a single row in your app's D1 (`pithy_multiplayer_results`), joinable beside your own tables.
+
+## Cheap idle sessions are a platform primitive, not a Pithy feature
+
+An idle, hibernating session costing effectively nothing is a property of Durable Objects — anyone building on a DO gets it. It is not a Pithy differentiator, and this page does not claim it as one. What Pithy adds is the wiring (the DO binding, the class migration tag, the per-environment namespaces) and the authority (hidden state, commit-reveal resolution) on top — not the idle economics.
+
+## Run the model
+
+```
+bun run --filter @pithy-sh/multiplayer costs
+```
+
+`scripts/costModel.ts` estimates a monthly bill from a session volume and a per-session message count, applying the 20:1 ratio and the free tiers. It is a planning aid, not a quote — Cloudflare's live pricing is the authority, and the free tiers and rates move.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@pithy-sh/multiplayer",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/multiplayer"
+  },
+  "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",
+    "costs": "bun scripts/costModel.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "peerDependencies": {
+    "@pithy-sh/leaderboard": "workspace:*",
+    "@pithy-sh/ledger": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@pithy-sh/leaderboard": {
+      "optional": true
+    },
+    "@pithy-sh/ledger": {
+      "optional": true
+    }
+  },
+  "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"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/leaderboard": "workspace:*",
+    "@pithy-sh/ledger": "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,41 @@
+{
+  "name": "multiplayer",
+  "package": "@pithy-sh/multiplayer",
+  "requiredBindings": [
+    {
+      "type": "durable_object",
+      "name": "SESSIONS",
+      "className": "MultiplayerSession",
+      "classModule": "@pithy-sh/multiplayer/src/session/durableObject"
+    },
+    { "type": "d1", "name": "DB" }
+  ],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth", "leaderboard", "ledger"],
+  "migrationNamespace": "multiplayer",
+  "whenToEnable": "Run authoritative, turn-based multiplayer sessions — the server holds the game state no client can be trusted with, resolves it, and writes a durable result to your own D1. This is the one thing a relay cannot do. Games are pluggable game models: three example games ship — `battle` (secret simultaneous moves), `connect-n` (turn-based grid: tic-tac-toe, Connect Four, gomoku), and `craps` (a wagering table) — each built on a reusable pattern helper (`simultaneous`, `turnBased`, `wageringTable`) you can layer your own game on, and you register games with `registerGameModel`. Supports N players. It also provides a wagering stack: provably-fair server-side randomness (a committed-then-revealed seed feeding a deterministic dice/shuffle stream), persistent `table` sessions where players buy in and cash out between rounds, and ledger-settled bets (a bet holds a stake, a resolution captures a loss or pays a win) — pair it with `@pithy-sh/ledger`. Pithy's first Durable Object — the CLI wires the DO binding and its class migration tag for you, across dev, staging, production, and preview branches, which no library does. It is NOT rooms, chat, presence, or real-time action netcode: Cloudflare's PartyServer already ships those. It takes no position on whether wagered units map to money, or the regulation that implies — that is yours. Sessions bind to an authenticated user, so add auth too — without it every route is denied.",
+  "scaffold": [
+    "Add a `multiplayer({ games: [...] })` block to pithy.config.ts and define at least one game.",
+    "Give each game a `key`, a `kind` (`battle`, `connect-n`, or `craps`, or a game you registered), an optional `mode` (`match` default, or `table` for a persistent multi-round table), an optional `players` count, and a `rules` block. A `battle`'s rules are its move catalogs; a `connect-n`'s are `{ rows, cols, connect }`; a `craps`'s are `{ currency, minBet, maxBet }`.",
+    "The CLI has already written the Durable Object export into your worker entry: `export { MultiplayerSession } from \"@pithy-sh/multiplayer/src/session/durableObject\";` — wrangler's `class_name` resolves against your worker's `main`. No hand-editing.",
+    "To ship a game the examples don't cover, layer it on the closest pattern helper (`simultaneous`/`turnBased`/`wageringTable`) or the raw `GameModel` seam, and call `registerGameModel(myGame)` in your worker entry before the DO handles requests.",
+    "The CLI has already added the `SESSIONS` durable_object binding and the `MultiplayerSession` class migration tag (`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.",
+    "Run `pithy migrate` to create pithy_multiplayer_results.",
+    "Add `@pithy-sh/auth` if it is not already installed. Sessions bind to an authenticated user; without auth every route is denied.",
+    "Optionally set a game's `leaderboard: { board, points }` to publish results to a `@pithy-sh/leaderboard` board. Install leaderboard and configure the matching board.",
+    "Read packages/multiplayer/docs/costs.md before production: a hibernating session waiting on a turn bills nothing, but the 20:1 WebSocket-message ratio and 128 MB duration billing shape the bill of an active session."
+  ],
+  "configOptions": [
+    {
+      "key": "games",
+      "default": [{ "key": "tic-tac-toe", "kind": "connect-n", "rules": { "rows": 3, "cols": 3, "connect": 3 } }],
+      "describe": "Every game this app runs. Replace this example — it is tic-tac-toe, the smallest game that actually plays: the built-in `connect-n` model on a 3x3 board where three in a line wins, two players, no wagering and no ledger. `kind` names a model (`battle`, `connect-n`, `craps`, or one you register with `registerGameModel`) and `rules` is that model's own block. At least one game is required."
+    },
+    {
+      "key": "basePath",
+      "default": "/multiplayer",
+      "describe": "Where the multiplayer routes mount. Sessions are created at POST `<basePath>/games/:game`, joined and played (`/action`) under `<basePath>/sessions/:id`."
+    }
+  ]
+}

package/src/capability.ts

@@ -0,0 +1,102 @@
+// 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 "./game/builtins";
+import { MultiplayerConfig, type MultiplayerConfigInput, validateGames } from "./config/config";
+import { multiplayerTables } from "./data/tables";
+import { registerMultiplayerRoutes } from "./http/routes";
+import { multiplayer_0001_results } from "./migrations/0001_results";
+import { multiplayerExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * Where multiplayer's migrations sort in the app database. Unique per database; the registry composes
+ * keys like `0500_multiplayer_0001_results`. Sits after leaderboard (400).
+ */
+export const MULTIPLAYER_MIGRATION_ORDER = 500;
+
+/** The Durable Object namespace binding name, and the class it is backed by — the CLI wires both. */
+export const MULTIPLAYER_SESSIONS_BINDING = "SESSIONS";
+export const MULTIPLAYER_SESSION_CLASS = "MultiplayerSession";
+/**
+ * The module the class is exported from — what the CLI writes the Worker entry's re-export against.
+ *
+ * Its own module, never `src/index`: the entry point is what an adopter's `pithy.config.ts` imports, and
+ * a Durable Object on that path imports `cloudflare:workers` and takes every Node-side command down with
+ * it (#172).
+ */
+export const MULTIPLAYER_SESSION_MODULE = "@pithy-sh/multiplayer/src/session/durableObject";
+
+export type MultiplayerOptions = MultiplayerConfigInput & {
+  /** Mount the routes somewhere other than `/multiplayer`. */
+  basePath?: string;
+};
+
+export interface MultiplayerCapability extends Capability {
+  multiplayerConfig: MultiplayerConfig;
+}
+
+/**
+ * The multiplayer capability: authoritative, turn-based, two-player commit-reveal sessions.
+ *
+ * Fully optional. Config, migrations, routes, and bindings arrive only on `pithy add multiplayer`, and
+ * `pithy remove multiplayer` is the clean inverse — including the Durable Object binding and its class
+ * migration tag.
+ *
+ * This is Pithy's first Durable Object. Live session state — membership, hidden commits, the alarm-driven
+ * commit deadline — lives in the DO's own storage, where authority and hidden state belong. D1 holds only
+ * the durable *result*, joinable beside the adopter's own tables. The one thing a relay cannot do — hold
+ * state neither client can read and resolve it — is the whole reason the capability exists.
+ *
+ * `dependsOn` is deliberately empty. Auth is a seam, not a peer: the routes read `c.var.auth` through
+ * core's `AuthContext`, so without `@pithy-sh/auth` every route is denied rather than open. Leaderboard is
+ * an *optional* one-way sink: a game may publish its result to a board, loaded by dynamic import so
+ * `@pithy-sh/leaderboard` is never a hard dependency.
+ */
+export function multiplayer(options: MultiplayerOptions = { games: [] }): MultiplayerCapability {
+  const { basePath, ...configInput } = options;
+  // Parse the game set at assembly, then validate each game against its model — an unknown `kind`, a roster
+  // outside the model's bounds, or an invalid `rules` block fails on deploy, not on the first session.
+  const resolved = MultiplayerConfig.parse(configInput);
+  const games = validateGames(resolved);
+
+  const migrations: Record<string, Migration> = { "0001_results": multiplayer_0001_results };
+
+  const requiredBindings: BindingSpecInput[] = [
+    {
+      type: "durable_object",
+      name: MULTIPLAYER_SESSIONS_BINDING,
+      className: MULTIPLAYER_SESSION_CLASS,
+      classModule: MULTIPLAYER_SESSION_MODULE,
+    },
+    { type: "d1", name: "DB" },
+  ];
+
+  const capability = defineCapability({
+    name: "multiplayer",
+    // 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: MultiplayerConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: multiplayerTables(),
+        migrationOrder: MULTIPLAYER_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    routes: registerMultiplayerRoutes({ games, basePath }),
+    seeds: [multiplayerExampleSeed],
+  });
+
+  return Object.assign(capability, { multiplayerConfig: resolved });
+}
+
+export function isMultiplayerCapability(capability: Capability): capability is MultiplayerCapability {
+  return capability.name === "multiplayer" && "multiplayerConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,16 @@
+// 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`: the `SESSIONS` Durable Object namespace the sessions live in, and
+// the app `DB` database the `pithy_multiplayer_*` tables live in. `cloudflare:test` types its `env` as
+// `Cloudflare.Env`, so test bindings are declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    // Typed with the session class so `env.SESSIONS.get(id)` yields a stub with the RPC methods.
+    SESSIONS: DurableObjectNamespace<import("./session/durableObject").MultiplayerSession>;
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MultiplayerGameNotFoundError, MultiplayerInvalidMoveError } from "../error/errors";
+import { type GameModel, playerBounds, registeredKinds, resolveModel } from "../game/model";
+
+/**
+ * The multiplayer capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field is
+ * `.describe()`d: the descriptions feed the self-documenting CLI (CLAUDE.md §Config).
+ *
+ * A game is generic. It names a **model** by `kind` — one of the two fundamental turn-based shapes,
+ * `commit-reveal` (simultaneous, hidden) or `sequential` (turn-order, shared state), or a model an adopter
+ * registered — and carries that model's own `rules` block. The session infrastructure (membership,
+ * lifecycle, hidden state, alarms, the durable result, the leaderboard publish) is the same for every game;
+ * only the `rules` and the model behind them differ. That is the whole point: the package is authoritative
+ * turn-based *sessions*, and the game models are pluggable.
+ */
+
+/** A game key is a URL path segment (`/multiplayer/games/<key>`), so it is kebab-case and lowercase. */
+const GAME_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const MultiplayerLeaderboard = z
+  .object({
+    board: z
+      .string()
+      .min(1)
+      .describe(
+        "The `@pithy-sh/leaderboard` board key a resolved session publishes to. Must match a board configured in the leaderboard capability, and the leaderboard capability must be installed — publishing is one-way, so multiplayer depends on leaderboard, never the reverse.",
+      ),
+    window: z
+      .string()
+      .optional()
+      .describe(
+        "A UTC CRON expression for the board's window (`0 0 * * *` daily), matching the leaderboard board's own `window`. Omit for an all-time board. Publishing writes into the window open at resolution time.",
+      ),
+    direction: z
+      .enum(["asc", "desc"])
+      .default("desc")
+      .describe("The board's sort direction, matching the leaderboard board — `desc` = highest points win."),
+    aggregation: z
+      .enum(["best", "latest", "sum"])
+      .default("sum")
+      .describe(
+        "How the board folds repeat results, matching the leaderboard board. `sum` accumulates points across sessions.",
+      ),
+    points: z
+      .object({
+        win: z.number().describe("Points the winner is awarded."),
+        draw: z.number().describe("Points each player is awarded on a draw."),
+        loss: z.number().describe("Points a non-winner is awarded — often 0, but a participation point is fine."),
+      })
+      .describe("The points each outcome awards, folded into the board by its aggregation."),
+  })
+  .describe("Optional one-way publish of a session's result to a leaderboard board.");
+export type MultiplayerLeaderboard = z.output<typeof MultiplayerLeaderboard>;
+
+export const MultiplayerGame = z
+  .object({
+    key: z
+      .string()
+      .regex(GAME_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. It is a URL path segment and the session's game reference.",
+      ),
+    kind: z
+      .string()
+      .min(1)
+      .describe(
+        "Which game to run: a built-in example (`battle` — simultaneous secret moves; `connect-n` — turn-based grid, i.e. tic-tac-toe/Connect Four/gomoku; `craps` — a wagering table) or a game registered with `registerGameModel`. The three built-ins are built on reusable pattern helpers (`simultaneous`, `turnBased`, `wageringTable`) that you can layer your own game on.",
+      ),
+    mode: z
+      .enum(["match", "table"])
+      .default("match")
+      .describe(
+        "The session lifecycle. `match` (default): a fixed roster fills, plays one game to a result, and ends — a duel, a hand of a card game. `table`: a long-lived session that runs many rounds; players join and leave *between* rounds (a buy-in, a cash-out), the model settles each round, and the table stays open until it is closed or empty — a poker or craps table.",
+      ),
+    players: z
+      .number()
+      .int()
+      .min(2)
+      .default(2)
+      .describe(
+        "In `match` mode, exactly how many players a session needs before play begins (default 2). In `table` mode, the maximum number of seats. The chosen model constrains the range.",
+      ),
+    turnTimeoutMs: z
+      .number()
+      .int()
+      .min(1000)
+      .optional()
+      .describe(
+        "How long, in ms, players have to act once play begins before the session is abandoned. Enforced by a Durable Object alarm — never a timer, which would forfeit hibernation. Omit to let a session wait indefinitely (it hibernates and costs nothing while it waits).",
+      ),
+    leaderboard: MultiplayerLeaderboard.optional().describe(
+      "If set, a resolved session publishes its result to this leaderboard board. Requires `@pithy-sh/leaderboard`.",
+    ),
+    rules: z
+      .unknown()
+      .describe(
+        "The model-specific rules block. Its shape is defined by the game's `kind` and validated against that model's schema at assembly (a `commit-reveal` game's move catalog, a `sequential` game's board size, …). Fails on deploy, not on the first move.",
+      ),
+  })
+  .describe("One game definition — a model reference (`kind`), a roster size, and that model's `rules` block.");
+export type MultiplayerGame = z.output<typeof MultiplayerGame>;
+
+export const MultiplayerConfig = z
+  .object({
+    games: z
+      .array(MultiplayerGame)
+      .min(1, "A multiplayer capability with no games does nothing — configure at least one.")
+      .describe("Every game this app runs. Games are config, not database rows."),
+  })
+  .describe("Configuration for the multiplayer capability — the game set, each naming a pluggable game model.")
+  .check((ctx) => {
+    const keys = ctx.value.games.map((g) => g.key);
+    const duplicates = [...new Set(keys.filter((key, i) => keys.indexOf(key) !== i))];
+    if (duplicates.length > 0) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["games"],
+        message: `Duplicate game keys: ${duplicates.join(", ")}. Two games sharing a key would collide.`,
+      });
+    }
+  });
+export type MultiplayerConfig = z.output<typeof MultiplayerConfig>;
+export type MultiplayerConfigInput = z.input<typeof MultiplayerConfig>;
+
+/** A game with its `rules` validated against its model — the shape the DO and routes carry. */
+export interface ResolvedGame extends Omit<MultiplayerGame, "rules"> {
+  /** The model-specific rules, parsed by the model's schema. */
+  rules: unknown;
+}
+
+/**
+ * Validate every game against its model: the `kind` must resolve to a registered model, the roster size
+ * must fall within the model's player bounds, and the `rules` block must parse against the model's schema.
+ * Runs once at assembly (the capability factory), so a typo or an out-of-range roster fails on deploy, not
+ * on the first session. Returns the games with their `rules` parsed.
+ */
+export function validateGames(config: MultiplayerConfig): ResolvedGame[] {
+  return config.games.map((game) => {
+    const model = resolveModel(game.kind);
+    if (!model) {
+      throw new MultiplayerGameNotFoundError({
+        message: `Game "${game.key}" uses unknown model "${game.kind}".`,
+        action: `Use one of: ${registeredKinds().join(", ") || "(none registered)"}, or register a model with registerGameModel().`,
+        detail: `No game model registered for kind "${game.kind}".`,
+      });
+    }
+    assertPlayerCount(game, model);
+    const rules = parseRules(game, model);
+    return { ...game, rules };
+  });
+}
+
+/** The roster size must fall within the model's supported range. */
+function assertPlayerCount(game: MultiplayerGame, model: GameModel): void {
+  const { min, max } = playerBounds(model);
+  if (game.players < min || game.players > max) {
+    const upper = max === Number.POSITIVE_INFINITY ? "" : `–${max}`;
+    throw new MultiplayerInvalidMoveError({
+      message: `Game "${game.key}" sets ${game.players} players, but "${model.kind}" supports ${min}${upper}.`,
+      detail: `Model "${model.kind}" player bounds [${min}, ${max}] exclude ${game.players}.`,
+    });
+  }
+}
+
+/** Parse the `rules` block against the model's schema, surfacing a Zod failure as a config error. */
+function parseRules(game: MultiplayerGame, model: GameModel): unknown {
+  const parsed = model.config.safeParse(game.rules);
+  if (!parsed.success) {
+    throw new MultiplayerInvalidMoveError({
+      message: `Game "${game.key}" has invalid rules for model "${model.kind}".`,
+      action: "Fix the game's `rules` block in pithy.config.ts.",
+      detail: `Rules failed validation: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}.`,
+    });
+  }
+  return parsed.data;
+}
+
+/** The game with this key, or undefined. Game keys come from config, so an unknown key is a 404. */
+export function resolveGame(games: readonly ResolvedGame[], key: string): ResolvedGame | undefined {
+  return games.find((game) => game.key === key);
+}

package/src/data/result.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/** The set of terminal states a session's result row records. A session ends resolved or abandoned. */
+export const SessionResultStatus = z
+  .enum(["resolved", "abandoned"])
+  .describe(
+    "The terminal state this result records: `resolved` (a winner or draw) or `abandoned` (timed out or quit).",
+  );
+export type SessionResultStatus = z.infer<typeof SessionResultStatus>;
+
+/**
+ * One session's durable result — the row in `pithy_multiplayer_results`. Written exactly once, when a
+ * session reaches a terminal state; the session's authority lives in its Durable Object, but the *record*
+ * of what happened outlives the object here in D1, joinable against the adopter's own tables.
+ *
+ * `z.output` is the app shape (Dates, booleans, parsed JSON); `z.input` is the SQLite row (ms-epoch, 0|1,
+ * JSON strings). All JS↔SQLite conversion runs through the core codecs (CLAUDE.md §Data layer) — no raw
+ * `0/1`, epoch, `new Date()`, or `JSON.stringify` in query code.
+ *
+ * `sessionId` is the Durable Object id (hex), unique per session, and the natural key a result is
+ * addressed by — `id` is an internal autoincrement never exposed.
+ */
+export const MultiplayerResult = z
+  .object({
+    id: z.number().int().describe("Autoincrement primary key. Internal only; results are addressed by sessionId."),
+    sessionId: z.string().describe("The Durable Object id (hex) of the session this result belongs to. Unique."),
+    gameKey: z.string().describe("The game this session played, from `games` in pithy.config.ts."),
+    status: SessionResultStatus.describe("The terminal state — resolved or abandoned."),
+    players: sqliteJson(z.array(z.string())).describe(
+      "The authenticated user ids of the session's members, in join order.",
+    ),
+    scores: sqliteJson(z.record(z.string(), z.number()))
+      .nullable()
+      .describe("Each player's final score, keyed by user id. Null on an abandoned session, which is never scored."),
+    winnerUserId: z
+      .string()
+      .nullable()
+      .describe("The winning player's user id. Null on a draw, and null on an abandoned session."),
+    draw: SQLiteBoolean.describe("Whether the session ended level. False on an abandoned session."),
+    createdAt: SQLiteDate.describe("When the session was created."),
+    resolvedAt: SQLiteDate.describe("When the session reached its terminal state and this row was written."),
+  })
+  .describe("One session's durable result — the row in `pithy_multiplayer_results`.");
+export type MultiplayerResult = z.output<typeof MultiplayerResult>;
+export type MultiplayerResultRow = z.input<typeof MultiplayerResult>;

package/src/data/store.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MultiplayerResult } from "./result";
+import { MULTIPLAYER_RESULTS_TABLE, type MultiplayerDatabase } from "./tables";
+
+/**
+ * Reads and writes over `pithy_multiplayer_results`.
+ *
+ * Round-trip rule (CLAUDE.md §Data layer): read with `MultiplayerResult.parse` (decode), write with
+ * `MultiplayerResult.encode` (encode). No raw `0/1`, epoch, or `JSON.stringify` below.
+ */
+export interface ResultStore {
+  /**
+   * Persist a terminal session's result. Idempotent on `sessionId`: an at-least-once alarm retry or a
+   * double-resolve writes the row once and no more, so a session can never record two conflicting results.
+   */
+  write(result: MultiplayerResult): Promise<void>;
+  /** The result for a session, or undefined if it has not reached a terminal state. */
+  get(sessionId: string): Promise<MultiplayerResult | undefined>;
+}
+
+export function resultStore(db: MultiplayerDatabase): ResultStore {
+  return {
+    async write(result) {
+      const row = MultiplayerResult.encode({ ...result, id: 0 }) as Record<string, unknown>;
+      // `id` is a rowid alias — let SQLite assign it rather than inserting the placeholder above.
+      delete row.id;
+      await db
+        .insertInto(MULTIPLAYER_RESULTS_TABLE)
+        // biome-ignore lint/suspicious/noExplicitAny: the encoded row is the schema's `z.input` side; Kysely's insert type is derived from it.
+        .values(row as any)
+        // A terminal session writes its result exactly once; a retry must be a no-op, not a duplicate or an error.
+        .onConflict((oc) => oc.column("sessionId").doNothing())
+        .execute();
+    },
+
+    async get(sessionId) {
+      const row = await db
+        .selectFrom(MULTIPLAYER_RESULTS_TABLE)
+        .selectAll()
+        .where("sessionId", "=", sessionId)
+        .executeTakeFirst();
+      return row ? MultiplayerResult.parse(row) : undefined;
+    },
+  };
+}

package/src/data/tables.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { MultiplayerResult } from "./result";
+
+/** The results table. `CamelCasePlugin` snake-cases it to `pithy_multiplayer_results` in the DDL. */
+export const MULTIPLAYER_RESULTS_TABLE = "pithyMultiplayerResults";
+
+/** The multiplayer tables map — just the durable result log; live session state lives in the Durable Object. */
+export function multiplayerTables(): Record<string, z.ZodObject> {
+  return { [MULTIPLAYER_RESULTS_TABLE]: MultiplayerResult };
+}
+
+/** The typed Kysely database over the multiplayer tables. */
+export type MultiplayerTables = {
+  [MULTIPLAYER_RESULTS_TABLE]: typeof MultiplayerResult;
+};
+export type MultiplayerDatabase = Kysely<DatabaseSchema<MultiplayerTables>>;
+
+/** Build the multiplayer database from the `DB` binding (CamelCasePlugin installed). */
+export function multiplayerDatabase(d1: D1Database): MultiplayerDatabase {
+  return createDatabase(d1, { [MULTIPLAYER_RESULTS_TABLE]: MultiplayerResult }) as unknown as MultiplayerDatabase;
+}