@pithy-sh/rating 0.1.0

package/src/config/config.ts

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { RatingAlgorithm } from "../algorithm/algorithm";
+import { algorithmBounds, registeredAlgorithmIds, resolveAlgorithm } from "../algorithm/registry";
+import {
+  RatingInvalidParamsError,
+  RatingUnknownAlgorithmError,
+  RatingUnsupportedPlayerCountError,
+} from "../error/errors";
+
+/**
+ * The rating 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 names a rating **algorithm** by id (`elo`, `glicko`, `trueskill`, or one an adopter registered),
+ * carries that algorithm's own `algoParams` tuning, and points at a named **pool** it reads and writes.
+ * The tracker holds two distinct numbers per player per pool — a skill rating (MMR, the matchmaking
+ * input) and a monotonic experience total (XP, the visible progression). This config is validated at
+ * assembly by {@link validateRatingGames}, the same way multiplayer's `validateGames` rejects a bad game.
+ */
+
+/** A game key / pool name is a URL path segment, so it is kebab-case and lowercase. */
+const KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const RatingXpAward = z
+  .object({
+    win: z.number().nonnegative().describe("Experience the winner is awarded."),
+    draw: z.number().nonnegative().describe("Experience each player is awarded on a draw."),
+    loss: z
+      .number()
+      .nonnegative()
+      .describe("Experience a non-winner is awarded — often 0, but a participation point is fine."),
+  })
+  .describe("Experience awarded per outcome, folded into each player's monotonic XP total.");
+export type RatingXpAward = z.output<typeof RatingXpAward>;
+
+export const RatingLevel = z
+  .object({
+    key: z.string().min(1).describe("The level's stable id — a rank label like `bronze` or `veteran`."),
+    from: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("The XP total at which this level begins. Levels list worst to best."),
+  })
+  .describe("One rung of the XP level ladder — the label a player earns once their XP total reaches `from`.");
+export type RatingLevel = z.output<typeof RatingLevel>;
+
+export const RatingGame = 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. It is a URL path segment and the outcome's game reference.",
+      ),
+    algorithm: z
+      .string()
+      .min(1)
+      .describe(
+        "Which rating algorithm rates this game: a built-in (`elo` — 1v1, transparent; `glicko` — Glicko-2, 1v1 with uncertainty; `trueskill` — any format, teams) or an id registered with `registerRatingAlgorithm`.",
+      ),
+    algoParams: z
+      .unknown()
+      .optional()
+      .describe(
+        "The chosen algorithm's tuning block (K-factor, volatility constraint, prior μ/σ). Validated at assembly by the algorithm; omit to take its defaults.",
+      ),
+    players: z
+      .number()
+      .int()
+      .min(2)
+      .default(2)
+      .describe(
+        "How many players a rated result of this game has (default 2). The chosen algorithm constrains the range — `elo`/`glicko` are 1v1 only, `trueskill` is any count.",
+      ),
+    teams: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether a result carries a team grouping, so the rating pools each team's skill. Only `trueskill` supports teams; wiring it to another algorithm fails at assembly.",
+      ),
+    pool: z
+      .string()
+      .regex(KEY_PATTERN, "A pool name is lowercase, digits, and dashes.")
+      .optional()
+      .describe(
+        "The rating pool this game reads and writes. Defaults to the game key (a rating per game). Set a shared name (e.g. `global`) to pool ratings across several games or modes.",
+      ),
+    sharedRoomCounts: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether games played in a shared room with a friend count toward the ranked ladder (XP / rank). Off by default, so friends cannot farm each other to climb. Skill rating (MMR) always updates from a real result regardless of this flag.",
+      ),
+    hideSkill: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Whether the skill rating (MMR) is hidden from players. When on, a player-facing read returns XP, rank, and games but not the raw skill number; matchmaking still uses it internally.",
+      ),
+    xp: RatingXpAward.optional().describe(
+      "Experience awarded per outcome. Omit for a game that grants no XP (rating only).",
+    ),
+    levels: z
+      .array(RatingLevel)
+      .optional()
+      .describe("An optional XP level ladder, listed worst to best, deriving a rank/level from the XP total."),
+  })
+  .describe("One rated game: its algorithm, roster, pool, and experience awards.");
+export type RatingGame = z.output<typeof RatingGame>;
+
+export const RatingConfig = z
+  .object({
+    games: z
+      .array(RatingGame)
+      .min(1, "A rating capability needs at least one game — configure at least one.")
+      .describe("The rated games. Each names an algorithm, a pool, and its experience awards."),
+    serverAuthoritative: z
+      .boolean()
+      .default(true)
+      .describe(
+        "When true (default), recording an outcome requires the record scope — only a trusted server may write ratings. A client cannot report that it won.",
+      ),
+    recordScope: z
+      .string()
+      .min(1)
+      .default("rating:record")
+      .describe("The scope a caller must hold to record an outcome when `serverAuthoritative` is on."),
+  })
+  .describe("The rating capability's configuration — its games and how outcomes are authorized.")
+  .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 RatingConfig = z.output<typeof RatingConfig>;
+export type RatingConfigInput = z.input<typeof RatingConfig>;
+
+/** A game whose algorithm is resolved and whose params are parsed — the runtime-ready form. */
+export interface ResolvedRatingGame {
+  /** The game's config (with `pool` defaulted to the key). */
+  game: RatingGame & { pool: string };
+  /** The resolved algorithm instance. */
+  algorithm: RatingAlgorithm;
+  /** The parsed, defaulted algorithm params. */
+  params: unknown;
+}
+
+/**
+ * Validate every game against the algorithm registry — the assembly-time gate, mirroring multiplayer's
+ * `validateGames`. An unknown algorithm, a roster outside the algorithm's supported player count, a team
+ * format on an algorithm that cannot rate teams, or invalid `algoParams` all fail here, on deploy, not on
+ * the first recorded game. Requires the built-ins (or an adopter's algorithms) to be registered first.
+ */
+export function validateRatingGames(config: RatingConfig): ResolvedRatingGame[] {
+  return config.games.map((game) => {
+    const algorithm = resolveAlgorithm(game.algorithm);
+    if (!algorithm) {
+      throw new RatingUnknownAlgorithmError({
+        message: `Game "${game.key}" uses unknown algorithm "${game.algorithm}".`,
+        action: `Use one of: ${registeredAlgorithmIds().join(", ") || "(none registered)"}, or register one with registerRatingAlgorithm().`,
+        detail: `No rating algorithm registered for id "${game.algorithm}".`,
+      });
+    }
+    assertPlayerCount(game, algorithm);
+    if (game.teams && !algorithm.supportsTeams) {
+      throw new RatingUnsupportedPlayerCountError({
+        message: `Game "${game.key}" is a team format, but "${algorithm.id}" cannot rate teams.`,
+        action: "Use `trueskill` for team games.",
+        detail: `Algorithm "${algorithm.id}" has supportsTeams=false.`,
+      });
+    }
+    const params = parseParams(game, algorithm);
+    return { game: { ...game, pool: game.pool ?? game.key }, algorithm, params };
+  });
+}
+
+/** The roster size must fall within the algorithm's supported range. */
+function assertPlayerCount(game: RatingGame, algorithm: RatingAlgorithm): void {
+  const { min, max } = algorithmBounds(algorithm);
+  if (game.players < min || game.players > max) {
+    const upper = max === Number.POSITIVE_INFINITY ? "" : `–${max}`;
+    throw new RatingUnsupportedPlayerCountError({
+      message: `Game "${game.key}" sets ${game.players} players, but "${algorithm.id}" supports ${min}${upper}.`,
+      action: "Use `trueskill` for N-player or team games; `elo` and `glicko` are 1v1 only.",
+      detail: `Algorithm "${algorithm.id}" player bounds [${min}, ${max}] exclude ${game.players}.`,
+    });
+  }
+}
+
+/** Parse the `algoParams` block against the algorithm's schema, surfacing a Zod failure as a config error. */
+function parseParams(game: RatingGame, algorithm: RatingAlgorithm): unknown {
+  const parsed = algorithm.params.safeParse(game.algoParams ?? {});
+  if (!parsed.success) {
+    throw new RatingInvalidParamsError({
+      message: `Game "${game.key}" has invalid algoParams for "${algorithm.id}".`,
+      action: "Fix the game's `algoParams` block in pithy.config.ts.",
+      detail: `algoParams failed validation: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}.`,
+    });
+  }
+  return parsed.data;
+}
+
+/** The resolved game for a key, or undefined. */
+export function resolveGame(games: readonly ResolvedRatingGame[], key: string): ResolvedRatingGame | undefined {
+  return games.find((g) => g.game.key === key);
+}
+
+/** Every distinct pool name the configured games read or write. */
+export function configuredPools(games: readonly ResolvedRatingGame[]): string[] {
+  return [...new Set(games.map((g) => g.game.pool))];
+}

package/src/data/rating.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One player's standing in one rating pool — the row in `pithy_rating_ratings`. It carries the tracker's
+ * **two distinct numbers**: `skill` (the MMR the matchmaker buckets on, up and down, opponent-weighted)
+ * and `xp` (the monotonic experience total that only ever rises). The algorithm-specific `state` blob is
+ * the source of `skill`; it is stored opaque here and validated against the resolving algorithm's own
+ * `state` schema on read (defense in depth — this table cannot know which algorithm owns a pool).
+ */
+export const RatingRecord = z
+  .object({
+    id: z.number().int().describe("Autoincrement PK. Internal only."),
+    pool: z.string().describe("The rating pool this row belongs to. A pool is rated by a single algorithm."),
+    userId: z
+      .string()
+      .describe("The player's authenticated user id (`pithy_auth_users.id`), never a client-supplied id."),
+    algorithm: z
+      .string()
+      .describe("The algorithm id that produced `state` — recorded so a read validates the blob correctly."),
+    state: sqliteJson(z.unknown()).describe(
+      "The algorithm's per-player rating state (Elo `{rating}`, Glicko-2 `{rating,rd,vol}`, TrueSkill `{mu,sigma}`), stored as JSON and re-validated by the algorithm on read.",
+    ),
+    skill: z
+      .number()
+      .describe(
+        "The conservative comparable skill number (`algorithm.skill(state)`), denormalized so matchmaking buckets and reads never re-derive it.",
+      ),
+    xp: z.number().describe("The player's monotonic experience total in this pool — only ever rises."),
+    games: z.number().int().describe("How many rated games this player has completed in this pool."),
+    updatedAt: SQLiteDate.describe("When this row last changed."),
+  })
+  .describe("One player's rating and experience in one pool.");
+
+export type RatingRecord = z.output<typeof RatingRecord>;
+export type RatingRecordRow = z.input<typeof RatingRecord>;

package/src/data/store.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { RatingRecord } from "./rating";
+import { RATING_RATINGS_TABLE, type RatingDatabase } from "./tables";
+
+/**
+ * The rating store — the only place that reads and writes `pithy_rating_ratings`. Reads decode with
+ * `RatingRecord.parse` (SQLite row → app shape); writes encode with `RatingRecord.encode` then upsert on
+ * the unique `(pool, userId)` pair, so recording the same roster twice updates in place rather than
+ * duplicating. The round-trip rule (CLAUDE.md §Data layer) is honored on every path.
+ */
+export interface RatingStore {
+  /** A player's standing in a pool, or undefined if they have no rated games there yet. */
+  get(pool: string, userId: string): Promise<RatingRecord | undefined>;
+  /** Every existing standing for a set of players in a pool (a game's roster). Missing players are absent. */
+  getMany(pool: string, userIds: readonly string[]): Promise<RatingRecord[]>;
+  /** Insert or update a player's standing, keyed on `(pool, userId)`. */
+  upsert(record: RatingRecord): Promise<void>;
+}
+
+export function ratingStore(db: RatingDatabase): RatingStore {
+  return {
+    async get(pool, userId) {
+      const row = await db
+        .selectFrom(RATING_RATINGS_TABLE)
+        .selectAll()
+        .where("pool", "=", pool)
+        .where("userId", "=", userId)
+        .executeTakeFirst();
+      return row ? RatingRecord.parse(row) : undefined;
+    },
+
+    async getMany(pool, userIds) {
+      if (userIds.length === 0) return [];
+      // A roster is as big as the game says it is: `players` has a minimum of two and no maximum, and
+      // the docs promise any count. So the roster is chunked against D1's cap rather than assumed to
+      // fit — one parameter per player, plus the pool. Unchunked, a 120-player game failed every
+      // `recordResult`, and no two-player test could have said so (#250).
+      const records: RatingRecord[] = [];
+      for (const chunk of chunkByBoundParameters(userIds, 1)) {
+        const rows = await db
+          .selectFrom(RATING_RATINGS_TABLE)
+          .selectAll()
+          .where("pool", "=", pool)
+          .where("userId", "in", chunk)
+          .execute();
+        for (const row of rows) records.push(RatingRecord.parse(row));
+      }
+      return records;
+    },
+
+    async upsert(record) {
+      const row = RatingRecord.encode(record) as Record<string, unknown>;
+      delete row.id;
+      await db
+        .insertInto(RATING_RATINGS_TABLE)
+        .values(row as never)
+        .onConflict((oc) =>
+          oc.columns(["pool", "userId"]).doUpdateSet({
+            algorithm: record.algorithm,
+            state: RatingRecord.shape.state.encode(record.state),
+            skill: record.skill,
+            xp: record.xp,
+            games: record.games,
+            updatedAt: RatingRecord.shape.updatedAt.encode(record.updatedAt),
+          }),
+        )
+        .execute();
+    },
+  };
+}

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 { RatingRecord } from "./rating";
+
+/**
+ * The rating capability's tables. One table today — `pithy_rating_ratings` — holding both numbers per
+ * player per pool. Table names are camelCase constants; core's `createDatabase` installs the mandatory
+ * `CamelCasePlugin`, so query code never types the snake_case `pithy_rating_*` columns.
+ */
+
+export const RATING_RATINGS_TABLE = "pithyRatingRatings";
+
+export function ratingTables(): Record<string, z.ZodObject> {
+  return { [RATING_RATINGS_TABLE]: RatingRecord };
+}
+
+type RatingTables = { [RATING_RATINGS_TABLE]: typeof RatingRecord };
+export type RatingDatabase = Kysely<DatabaseSchema<RatingTables>>;
+
+export function ratingDatabase(d1: D1Database): RatingDatabase {
+  return createDatabase(d1, { [RATING_RATINGS_TABLE]: RatingRecord }) as unknown as RatingDatabase;
+}

package/src/error/errors.ts

@@ -0,0 +1,130 @@
+// 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/rating` throw sugar. The `rating/*` 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/multiplayer`. 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 RatingErrorArgs {
+  /** 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;
+}
+
+/** A game wires a rating algorithm id that no one registered. Thrown at assembly. */
+export class RatingUnknownAlgorithmError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/unknown_algorithm",
+        status: 400,
+        message: args.message ?? "That rating algorithm does not exist.",
+        action:
+          args.action ?? "Use a built-in (elo, glicko, trueskill) or register one with registerRatingAlgorithm().",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A game's roster or team format falls outside the chosen algorithm's support. Thrown at assembly. */
+export class RatingUnsupportedPlayerCountError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/unsupported_player_count",
+        status: 400,
+        message: args.message ?? "This algorithm cannot rate that game's shape.",
+        action: args.action ?? "Use trueskill for N-player or team games; elo and glicko are 1v1 only.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A game's `algoParams` block failed the algorithm's own validation. Thrown at assembly. */
+export class RatingInvalidParamsError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/invalid_params",
+        status: 400,
+        message: args.message ?? "The algorithm's tuning is invalid.",
+        action: args.action ?? "Fix the game's `algoParams` block in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A request referenced a game key that is not configured. */
+export class RatingGameNotFoundError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/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,
+    );
+  }
+}
+
+/** A request referenced a rating pool no game configures. */
+export class RatingPoolNotFoundError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/pool_not_found",
+        status: 404,
+        message: args.message ?? "That rating pool does not exist.",
+        action: args.action ?? "Reference a pool a configured game reads or writes.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The authenticated caller lacks the server-authoritative record scope. */
+export class RatingRecordForbiddenError extends PithyError {
+  constructor(args: RatingErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "rating/record_forbidden",
+        status: 403,
+        message: args.message ?? "You may not record game outcomes.",
+        action: args.action ?? "Record outcomes from a trusted server holding the record scope.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/experience/xp.ts

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { RatingLevel, RatingXpAward } from "../config/config";
+
+/**
+ * Experience is the visible progression — a monotonic total that only ever rises, distinct from the
+ * skill rating that moves both ways. This module owns the two pure rules: how an award folds into the
+ * total, and how a total classifies into a rank/level.
+ */
+
+/** A player's outcome in a single game, for the purpose of an XP award. */
+export type XpOutcome = "win" | "draw" | "loss";
+
+/** Fold an award into the running total. XP never decreases: a negative award is clamped to zero. */
+export function awardXp(current: number, award: number): number {
+  return current + Math.max(0, award);
+}
+
+/** The XP a given outcome is worth under a game's award table. */
+export function xpFor(award: RatingXpAward, outcome: XpOutcome): number {
+  return award[outcome];
+}
+
+/**
+ * The rank/level a total earns, from a worst-to-best ladder — the best rung whose `from` the total has
+ * reached, or `null` when it has not reached the first rung. The ladder is sorted defensively so order in
+ * config never changes the answer.
+ */
+export function classifyLevel(levels: readonly RatingLevel[], xp: number): string | null {
+  let current: string | null = null;
+  for (const level of [...levels].sort((a, b) => a.from - b.from)) {
+    if (xp >= level.from) current = level.key;
+  }
+  return current;
+}

package/src/http/guard.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+import { RatingRecordForbiddenError } from "../error/errors";
+
+/**
+ * Route guards over the `AuthContext` seam. Copied — not imported from `@pithy-sh/auth` — so the rating
+ * capability keeps `dependsOn` empty: without auth installed, `c.var.auth` is null and every guarded
+ * route is denied rather than open (the leaderboard pattern).
+ */
+
+/** Deny any request without a resolved identity. The first handler on every rating route. */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}
+
+/**
+ * Gate outcome recording behind the record scope when the capability is server-authoritative. A client
+ * cannot report that it won; only a trusted server holding the scope may write ratings.
+ */
+export function requireRecordScope(serverAuthoritative: boolean, scope: string): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (serverAuthoritative && !c.var.auth?.scopes.includes(scope)) {
+      throw new RatingRecordForbiddenError({ detail: `Recording an outcome requires the "${scope}" scope.` });
+    }
+    await next();
+  };
+}