@pithy-sh/multiplayer 0.1.0

package/src/error/errors.ts

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/multiplayer` throw sugar. The `multiplayer/*` codes live in core's closed `KitErrorPayload`
+ * union (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/leaderboard` and
+ * `@pithy-sh/media`. Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface MultiplayerErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+export class MultiplayerGameNotFoundError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/game_not_found",
+        status: 404,
+        message: args.message ?? "That game does not exist.",
+        action: args.action ?? "Check the game key against the `games` list in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MultiplayerSessionNotFoundError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/session_not_found",
+        status: 404,
+        message: args.message ?? "That session does not exist.",
+        action: args.action ?? "Create a session first, then share its id with the other player.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MultiplayerNotAMemberError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/not_a_member",
+        status: 403,
+        message: args.message ?? "You are not a member of this session.",
+        action: args.action ?? "Join the session before acting in it.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MultiplayerSessionFullError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/session_full",
+        status: 409,
+        message: args.message ?? "This session is full.",
+        action: args.action ?? "Create a new session — this one already has both players.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MultiplayerInvalidTransitionError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/invalid_transition",
+        status: 409,
+        message: args.message ?? "That action is not allowed right now.",
+        action:
+          args.action ?? "Check the session's phase before acting — you may have already committed, or it may be over.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class MultiplayerInvalidMoveError extends PithyError {
+  constructor(args: MultiplayerErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "multiplayer/invalid_move",
+        status: 400,
+        message: args.message ?? "That move is not allowed.",
+        action: args.action ?? "Commit the exact number of distinct moves the game requires, each from its move set.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/game/builtins.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { battleGame } from "./games/battle";
+import { connectNGame } from "./games/connectN";
+import { crapsGame } from "./games/craps";
+import { registerGameModel } from "./model";
+
+/**
+ * Registers the built-in example games — imported for its side effect by the capability and the Durable
+ * Object, so all three `kind`s resolve without either one importing the games directly. A bare
+ * `import "../game/builtins"` is a side-effect import and is never tree-shaken away.
+ *
+ * These are *example games* built on the reusable pattern helpers (`simultaneous`, `turnBased`,
+ * `wageringTable`) — they show how to layer a game, and an adopter adds their own the same way, with
+ * `registerGameModel(myGame)` at worker load.
+ */
+export const BUILT_IN_GAMES = [battleGame, connectNGame, crapsGame];
+
+for (const game of BUILT_IN_GAMES) registerGameModel(game);

package/src/game/effects.ts

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+
+/**
+ * A ledger operation a game model asks the session to perform — the wager seam.
+ *
+ * A model's `apply`/`resolve` are pure: they cannot touch a database. So instead of moving money
+ * themselves, they *declare* the movements as effects, and the Durable Object settles them through
+ * `@pithy-sh/ledger` after the transition. That keeps the model deterministic (a requirement for
+ * replay and provable fairness) while still letting a game hold a stake, capture a loss, or pay a win.
+ *
+ * Every effect carries a `ref` — the ledger's idempotency key. Because a model is deterministic, a replayed
+ * transition re-emits effects with the *same* refs, so applying them twice is a no-op: a payout pays once.
+ * Build refs stably from `ctx.sessionId` and the game's own state (`${sessionId}:round-3:alice:stake`).
+ */
+export type LedgerEffect =
+  | {
+      readonly op: "credit";
+      readonly userId: string;
+      readonly currency: string;
+      readonly amount: number;
+      readonly ref: string;
+      readonly memo?: string;
+    }
+  | {
+      readonly op: "debit";
+      readonly userId: string;
+      readonly currency: string;
+      readonly amount: number;
+      readonly ref: string;
+      readonly memo?: string;
+    }
+  | {
+      readonly op: "hold";
+      readonly userId: string;
+      readonly currency: string;
+      readonly amount: number;
+      readonly ref: string;
+    }
+  | { readonly op: "release"; readonly ref: string }
+  | { readonly op: "capture"; readonly ref: string; readonly amount?: number; readonly memo?: string }
+  | {
+      readonly op: "transfer";
+      readonly from: string;
+      readonly to: string;
+      readonly currency: string;
+      readonly amount: number;
+      readonly ref: string;
+      readonly memo?: string;
+    };
+
+/**
+ * Settle a model's declared effects. `@pithy-sh/ledger` is an *optional* peer, loaded by dynamic import
+ * only when a game actually emits effects — a game with no wagering never touches it, and a deployment
+ * without the ledger never resolves the import. Applied **before** the DO commits the new game state
+ * (see the DO): a hold that a player cannot cover throws here, so the wagering action is rejected and the
+ * state never advances.
+ */
+export async function applyLedgerEffects(d1: D1Database, effects: readonly LedgerEffect[]): Promise<void> {
+  if (effects.length === 0) return;
+  const { openLedger } = await import("@pithy-sh/ledger/src/ledger");
+  const ledger = openLedger(d1);
+  for (const effect of effects) {
+    switch (effect.op) {
+      case "credit":
+        await ledger.credit(effect.userId, effect.currency, effect.amount, effect.ref, { memo: effect.memo });
+        break;
+      case "debit":
+        await ledger.debit(effect.userId, effect.currency, effect.amount, effect.ref, { memo: effect.memo });
+        break;
+      case "hold":
+        await ledger.hold(effect.userId, effect.currency, effect.amount, effect.ref);
+        break;
+      case "release":
+        await ledger.release(effect.ref);
+        break;
+      case "capture":
+        await ledger.capture(effect.ref, { amount: effect.amount, memo: effect.memo });
+        break;
+      case "transfer":
+        await ledger.transfer(effect.from, effect.to, effect.currency, effect.amount, effect.ref, {
+          memo: effect.memo,
+        });
+        break;
+    }
+  }
+}

package/src/game/games/battle.ts

@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MultiplayerInvalidMoveError } from "../../error/errors";
+import type { ModelOutcome } from "../model";
+import { simultaneous } from "../patterns/simultaneous";
+
+/**
+ * Battle — the flagship **simultaneous** game (built on the {@link simultaneous} pattern).
+ *
+ * Each player secretly picks offensive and defensive moves; when everyone has, the server resolves them
+ * together. An offensive move scores its power unless *any* opponent's chosen defense blocks it — which is
+ * what makes hidden state load-bearing, and generalizes cleanly from a 2-player duel to an N-player
+ * free-for-all. The whole game is a config (the move catalogs) plus a scoring function; the simultaneous
+ * lifecycle and the hidden-state boundary come from the pattern.
+ */
+
+export const OffenseMove = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .describe("The move's stable name — what a player names in their submission, and what a defense blocks."),
+    power: z
+      .number()
+      .nonnegative()
+      .describe("Points this move scores against opponents when it lands (i.e. no opponent blocked it)."),
+  })
+  .describe("One offensive move a player may pick — a name and the points it scores if unblocked.");
+export type OffenseMove = z.infer<typeof OffenseMove>;
+
+export const DefenseMove = z
+  .object({
+    name: z.string().min(1).describe("The move's stable name — what a player names in their submission."),
+    blocks: z
+      .string()
+      .min(1)
+      .describe(
+        "The offensive move name this defense neutralizes. Must reference an offensive move that exists in this game.",
+      ),
+  })
+  .describe("One defensive move a player may pick — a name and the offensive move it blocks.");
+export type DefenseMove = z.infer<typeof DefenseMove>;
+
+export const BattleConfig = z
+  .object({
+    offense: z
+      .object({
+        pick: z.number().int().min(0).describe("Exactly how many distinct offensive moves a player picks."),
+        moves: z.array(OffenseMove).describe("The offensive catalog a player picks from."),
+      })
+      .describe("The offensive moves each player picks, and how many."),
+    defense: z
+      .object({
+        pick: z.number().int().min(0).describe("Exactly how many distinct defensive moves a player picks."),
+        moves: z.array(DefenseMove).describe("The defensive catalog a player picks from."),
+      })
+      .describe("The defensive moves each player picks, and how many. Set `pick: 0` for an offense-only game."),
+  })
+  .describe("The battle game's rules — the offensive and defensive move catalogs and pick counts.")
+  .check((ctx) => {
+    const { offense, defense } = ctx.value;
+    const offenseNames = offense.moves.map((m) => m.name);
+    const uniqueOffense = new Set(offenseNames);
+    if (uniqueOffense.size !== offenseNames.length)
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["offense", "moves"],
+        message: "Duplicate offensive move names.",
+      });
+    if (offense.pick > uniqueOffense.size)
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["offense", "pick"],
+        message: `Asks for ${offense.pick} offensive moves but only ${uniqueOffense.size} exist.`,
+      });
+    const defenseNames = defense.moves.map((m) => m.name);
+    const uniqueDefense = new Set(defenseNames);
+    if (uniqueDefense.size !== defenseNames.length)
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["defense", "moves"],
+        message: "Duplicate defensive move names.",
+      });
+    if (defense.pick > uniqueDefense.size)
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["defense", "pick"],
+        message: `Asks for ${defense.pick} defensive moves but only ${uniqueDefense.size} exist.`,
+      });
+    for (let i = 0; i < defense.moves.length; i++) {
+      const move = defense.moves[i] as DefenseMove;
+      if (!uniqueOffense.has(move.blocks))
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["defense", "moves", i, "blocks"],
+          message: `Defense "${move.name}" blocks "${move.blocks}", which is not an offensive move.`,
+        });
+    }
+  });
+export type BattleConfig = z.output<typeof BattleConfig>;
+
+/** One player's secret picks — the submission a battle player commits. */
+export const Move = z
+  .object({
+    offense: z
+      .array(z.string())
+      .describe("The offensive move names picked — exactly `offense.pick`, distinct, from the set."),
+    defense: z
+      .array(z.string())
+      .describe("The defensive move names picked — exactly `defense.pick`, distinct, from the set."),
+  })
+  .describe("One player's secret battle picks.");
+export type Move = z.infer<typeof Move>;
+
+/** Validate one pick list: exact count, distinct, and every name from the allowed set. Throws otherwise. */
+function assertPicks(kind: "offensive" | "defensive", picks: string[], pick: number, allowed: Set<string>): void {
+  if (picks.length !== pick)
+    throw new MultiplayerInvalidMoveError({
+      message: `Pick exactly ${pick} ${kind} move${pick === 1 ? "" : "s"}.`,
+      detail: `Expected ${pick} ${kind} moves, got ${picks.length}.`,
+    });
+  if (new Set(picks).size !== picks.length)
+    throw new MultiplayerInvalidMoveError({
+      message: `Your ${kind} moves must be distinct.`,
+      detail: `Duplicate ${kind} moves.`,
+    });
+  for (const name of picks) {
+    if (!allowed.has(name))
+      throw new MultiplayerInvalidMoveError({
+        message: `"${name}" is not one of this game's ${kind} moves.`,
+        detail: `${kind} move "${name}" not in set.`,
+      });
+  }
+}
+
+/** Validate a battle submission against the config. Throws {@link MultiplayerInvalidMoveError} on any violation. */
+export function validateMove(config: BattleConfig, move: Move): void {
+  assertPicks("offensive", move.offense, config.offense.pick, new Set(config.offense.moves.map((m) => m.name)));
+  assertPicks("defensive", move.defense, config.defense.pick, new Set(config.defense.moves.map((m) => m.name)));
+}
+
+/** Score every player's picks: an offense scores unless any opponent's defense blocks it; highest wins, ties draw. */
+export function scoreBattle(
+  config: BattleConfig,
+  submissions: Record<string, Move>,
+  players: readonly string[],
+): ModelOutcome {
+  const power = new Map(config.offense.moves.map((m) => [m.name, m.power]));
+  const blocksByDefense = new Map(config.defense.moves.map((d) => [d.name, d.blocks]));
+  const scoreFor = (me: string): number => {
+    const blocked = new Set<string>();
+    for (const other of players) {
+      if (other === me) continue;
+      for (const name of submissions[other]?.defense ?? []) {
+        const blocks = blocksByDefense.get(name);
+        if (blocks) blocked.add(blocks);
+      }
+    }
+    return (submissions[me]?.offense ?? []).reduce(
+      (sum, move) => sum + (blocked.has(move) ? 0 : (power.get(move) ?? 0)),
+      0,
+    );
+  };
+  const scores: Record<string, number> = {};
+  for (const player of players) scores[player] = scoreFor(player);
+  const top = Math.max(...players.map((p) => scores[p] as number));
+  const leaders = players.filter((p) => scores[p] === top);
+  const draw = leaders.length !== 1;
+  return { scores, winnerUserId: draw ? null : (leaders[0] as string), draw };
+}
+
+export const battleGame = simultaneous<BattleConfig, Move>({
+  kind: "battle",
+  config: BattleConfig,
+  submission: Move,
+  minPlayers: 2,
+  validate: (config, move) => validateMove(config, move),
+  score: (ctx, submissions) => scoreBattle(ctx.config, submissions, ctx.players),
+});

package/src/game/games/connectN.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { MultiplayerInvalidMoveError } from "../../error/errors";
+import type { ModelOutcome } from "../model";
+import { turnBased } from "../patterns/turnBased";
+
+/**
+ * Connect-N — the flagship **turn-based** game (built on the {@link turnBased} pattern).
+ *
+ * Players take turns claiming empty cells; the first to line up `connect` cells in a row — horizontal,
+ * vertical, or diagonal — wins. It is a whole family in one config: tic-tac-toe is `3×3 connect 3`, Connect
+ * Four is `7×6 connect 4`, gomoku is `15×15 connect 5`. The whole game is a config plus how a move changes
+ * the board and how a win is detected; the turn order and advancement come from the pattern.
+ */
+
+export const ConnectNConfig = z
+  .object({
+    rows: z.number().int().min(1).describe("Board height in cells."),
+    cols: z.number().int().min(1).describe("Board width in cells."),
+    connect: z
+      .number()
+      .int()
+      .min(2)
+      .describe("How many of a player's cells in a line (row, column, or diagonal) wins."),
+  })
+  .describe("The connect-n game's rules — board size and the line length that wins.")
+  .check((ctx) => {
+    const { rows, cols, connect } = ctx.value;
+    if (connect > Math.max(rows, cols))
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["connect"],
+        message: `connect ${connect} is longer than the board's ${Math.max(rows, cols)} — no line could ever win.`,
+      });
+  });
+export type ConnectNConfig = z.output<typeof ConnectNConfig>;
+
+/** The board state (turn tracking is the turn-based pattern's, not here). */
+export const BoardState = z
+  .object({
+    board: z
+      .array(z.array(z.string().nullable()))
+      .describe("Row-major grid; each cell is the user id that claimed it, or null."),
+    moves: z.number().int().describe("How many cells have been claimed — the board is full at rows×cols."),
+  })
+  .describe("The connect-n board.");
+export type BoardState = z.infer<typeof BoardState>;
+
+/** One move: the cell to claim. */
+export const GridMove = z
+  .object({
+    row: z.number().int().describe("The 0-indexed row of the cell to claim."),
+    col: z.number().int().describe("The 0-indexed column of the cell to claim."),
+  })
+  .describe("A connect-n move — the cell a player claims on their turn.");
+export type GridMove = z.infer<typeof GridMove>;
+
+/** The user id who owns a winning line of `connect`, or null. Scans right, down, and both diagonals. */
+export function findWinner(board: (string | null)[][], connect: number): string | null {
+  const rows = board.length;
+  const cols = board[0]?.length ?? 0;
+  const directions = [
+    [0, 1],
+    [1, 0],
+    [1, 1],
+    [1, -1],
+  ] as const;
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const owner = board[r]?.[c];
+      if (!owner) continue;
+      for (const [dr, dc] of directions) {
+        let run = 1;
+        while (run < connect && board[r + dr * run]?.[c + dc * run] === owner) run++;
+        if (run >= connect) return owner;
+      }
+    }
+  }
+  return null;
+}
+
+export const connectNGame = turnBased<ConnectNConfig, BoardState, GridMove>({
+  kind: "connect-n",
+  config: ConnectNConfig,
+  game: BoardState,
+  move: GridMove,
+  minPlayers: 2,
+
+  start: (ctx) => ({
+    board: Array.from({ length: ctx.config.rows }, () =>
+      Array.from({ length: ctx.config.cols }, () => null as string | null),
+    ),
+    moves: 0,
+  }),
+
+  play(ctx, state, playerId, move) {
+    const { row, col } = move;
+    if (row < 0 || row >= ctx.config.rows || col < 0 || col >= ctx.config.cols) {
+      throw new MultiplayerInvalidMoveError({
+        message: "That cell is off the board.",
+        detail: `(${row}, ${col}) outside ${ctx.config.rows}×${ctx.config.cols}.`,
+      });
+    }
+    if (state.board[row]?.[col]) {
+      throw new MultiplayerInvalidMoveError({
+        message: "That cell is already taken.",
+        detail: `(${row}, ${col}) is claimed by ${state.board[row]?.[col]}.`,
+      });
+    }
+    const board = state.board.map((r) => [...r]);
+    (board[row] as (string | null)[])[col] = playerId;
+    return { game: { board, moves: state.moves + 1 } };
+  },
+
+  isEnd: (ctx, state) =>
+    findWinner(state.board, ctx.config.connect) !== null || state.moves >= ctx.config.rows * ctx.config.cols,
+
+  score(ctx, state): ModelOutcome {
+    const winner = findWinner(state.board, ctx.config.connect);
+    const scores: Record<string, number> = {};
+    for (const player of ctx.players) scores[player] = player === winner ? 1 : 0;
+    return { scores, winnerUserId: winner, draw: winner === null };
+  },
+});