@pithy-sh/rating 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { Context, Hono } from "hono";
+import type { RatingConfig, ResolvedRatingGame } from "../config/config";
+import { resolveGame } from "../config/config";
+import { ratingStore } from "../data/store";
+import { ratingDatabase } from "../data/tables";
+import { RatingGameNotFoundError } from "../error/errors";
+import { classifyLevel } from "../experience/xp";
+import { recordOutcome } from "../record/record";
+import { requireAuth, requireRecordScope } from "./guard";
+import { RatingGameParams, RatingPlayerParams, RecordOutcomeBody } from "./schemas";
+
+/**
+ * The rating capability's HTTP surface. Three routes, every one `requireAuth()`-gated — there is no
+ * public surface:
+ *
+ * | Method | Path                                  | Strategy            | Validates |
+ * |--------|---------------------------------------|---------------------|-----------|
+ * | POST   | /rating/games/:game/outcomes          | bearer \| session + record scope | param `RatingGameParams`, json `RecordOutcomeBody` |
+ * | GET    | /rating/games/:game/me                | bearer \| session   | param `RatingGameParams` |
+ * | GET    | /rating/games/:game/players/:userId   | bearer \| session   | param `RatingPlayerParams` |
+ *
+ * Validators run **after** the guards, so an unauthenticated or unscoped caller is still denied 401/403
+ * whatever it sends. A param schema bounds the segment's shape only — resolving the key against the
+ * configured games stays in the handler, and an unknown game is still a `rating/game_not_found` 404.
+ *
+ * Recording is server-authoritative by default: a client cannot report a win. Reads honor the game's
+ * `hideSkill` flag — a hidden rating returns XP, rank, and games but a `null` skill number.
+ */
+export interface RatingRoutesOptions {
+  /** The resolved, validated games. */
+  games: readonly ResolvedRatingGame[];
+  /** The resolved config (for auth mode + scope). */
+  config: RatingConfig;
+  /** Mount the routes somewhere other than `/rating`. */
+  basePath?: string;
+}
+
+/** A player-facing view of a standing. `skill` is null when the game hides it. */
+interface RatingView {
+  pool: string;
+  userId: string;
+  skill: number | null;
+  xp: number;
+  level: string | null;
+  games: number;
+  provisional: boolean;
+}
+
+export function registerRatingRoutes(options: RatingRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? "/rating";
+  const { games, config } = options;
+
+  return (app) => {
+    app.post(
+      `${base}/games/:game/outcomes`,
+      requireAuth(),
+      requireRecordScope(config.serverAuthoritative, config.recordScope),
+      zValidator("param", RatingGameParams, validationHook),
+      zValidator("json", RecordOutcomeBody, validationHook),
+      async (c) => {
+        const resolved = game(games, c.req.valid("param").game);
+        const body = c.req.valid("json");
+        const recorded = await recordOutcome(ratingStore(ratingDatabase(dbOf(c))), resolved, {
+          ranks: body.ranks,
+          teams: body.teams,
+          sharedRoom: body.sharedRoom,
+          at: new Date(),
+        });
+        return c.json({ game: resolved.game.key, pool: resolved.game.pool, players: recorded }, 201);
+      },
+    );
+
+    app.get(
+      `${base}/games/:game/me`,
+      requireAuth(),
+      zValidator("param", RatingGameParams, validationHook),
+      async (c) => {
+        const resolved = game(games, c.req.valid("param").game);
+        return c.json(await view(c, resolved, userId(c)));
+      },
+    );
+
+    app.get(
+      `${base}/games/:game/players/:userId`,
+      requireAuth(),
+      zValidator("param", RatingPlayerParams, validationHook),
+      async (c) => {
+        const params = c.req.valid("param");
+        const resolved = game(games, params.game);
+        return c.json(await view(c, resolved, params.userId));
+      },
+    );
+  };
+}
+
+/** Build a player's view for a game's pool, applying the game's `hideSkill` flag. Provisional if unrated. */
+async function view(c: Context<PithyHonoEnv>, resolved: ResolvedRatingGame, player: string): Promise<RatingView> {
+  const { game: cfg, algorithm, params } = resolved;
+  const record = await ratingStore(ratingDatabase(dbOf(c))).get(cfg.pool, player);
+  const skill = record ? record.skill : algorithm.skill(params, algorithm.initial(params));
+  const xp = record?.xp ?? 0;
+  return {
+    pool: cfg.pool,
+    userId: player,
+    skill: cfg.hideSkill ? null : skill,
+    xp,
+    level: cfg.levels ? classifyLevel(cfg.levels, xp) : null,
+    games: record?.games ?? 0,
+    provisional: record === undefined,
+  };
+}
+
+function game(games: readonly ResolvedRatingGame[], key: string): ResolvedRatingGame {
+  const resolved = resolveGame(games, key);
+  if (!resolved) throw new RatingGameNotFoundError({ detail: `No game "${key}" is configured.` });
+  return resolved;
+}
+
+function userId(c: Context<PithyHonoEnv>): string {
+  const auth = c.var.auth;
+  if (!auth) throw new InternalError({ detail: "requireAuth() must run before a handler reads the user id." });
+  return auth.userId;
+}
+
+function dbOf(c: Context<PithyHonoEnv>): D1Database {
+  const db = c.env.DB as D1Database | undefined;
+  if (!db) throw new InternalError({ detail: "The rating routes require a `DB` D1 binding." });
+  return db;
+}

package/src/http/schemas.ts

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * HTTP-boundary shapes for the rating routes. Declared on the route line with
+ * `zValidator(target, Schema, validationHook)`, so a malformed request becomes a
+ * `validation/invalid_input` 400 before any handler runs, never an unhandled throw.
+ *
+ * The param schemas are **shape** checks, not existence checks: they bound what may reach a store or a
+ * config lookup. Resolving a game key against the configured games stays in the handler, and an unknown
+ * game is still a `rating/game_not_found` 404.
+ */
+
+/**
+ * A game key is a URL path segment, so it is lowercase, digits, and dashes — the same shape
+ * `RatingGame.key` enforces at config assembly. A key that cannot be configured cannot resolve, so
+ * bounding the segment here rejects it a step earlier without narrowing what already works.
+ */
+const GAME_KEY = /^[a-z0-9][a-z0-9-]*$/;
+
+export const RatingGameParams = z
+  .object({
+    game: z
+      .string()
+      .max(64)
+      .regex(GAME_KEY, "A game key is lowercase, digits, and dashes — it is a URL path segment.")
+      .describe("The configured game the request addresses. Resolved against the games in the handler."),
+  })
+  .describe("The path params of a game-scoped rating route.");
+export type RatingGameParams = z.output<typeof RatingGameParams>;
+
+export const RatingPlayerParams = z
+  .object({
+    game: z
+      .string()
+      .max(64)
+      .regex(GAME_KEY, "A game key is lowercase, digits, and dashes — it is a URL path segment.")
+      .describe("The configured game the request addresses. Resolved against the games in the handler."),
+    userId: z
+      .string()
+      .min(1)
+      .max(200)
+      .describe("The player whose standing is read. Opaque to this capability — bounded, not parsed."),
+  })
+  .describe("The path params of a read of one player's standing in a game.");
+export type RatingPlayerParams = z.output<typeof RatingPlayerParams>;
+
+export const RecordOutcomeBody = z
+  .object({
+    ranks: z
+      .record(z.string(), z.number().int().min(1))
+      .describe("Each player's finishing place, keyed by user id — 1 is the winner, ties share a place."),
+    teams: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe("Optional team grouping (player id → team id), for a team format."),
+    sharedRoom: z
+      .boolean()
+      .optional()
+      .describe("Whether the game was played in a shared room with a friend. Gates XP/rank, never the skill rating."),
+  })
+  .describe("The body of a record-outcome request — the result of one rated game.");
+export type RecordOutcomeBody = z.output<typeof RecordOutcomeBody>;

package/src/index.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add rating` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config/options types, the rating-algorithm seam (so an adopter can
+ * register their own), the built-in algorithms, and the read/record shapes an app renders. Every other
+ * module is imported by deep path (`@pithy-sh/rating/src/...`); this is the documented contract, not a
+ * barrel over the package.
+ */
+
+export type { RatedOutcome, RatingAlgorithm, RatingEntry } from "./algorithm/algorithm";
+export { elo } from "./algorithm/builtins/elo";
+export { glicko } from "./algorithm/builtins/glicko";
+export { trueskill } from "./algorithm/builtins/trueskill";
+export {
+  algorithmBounds,
+  registeredAlgorithmIds,
+  registerRatingAlgorithm,
+  resolveAlgorithm,
+} from "./algorithm/registry";
+export {
+  isRatingCapability,
+  RATING_MIGRATION_ORDER,
+  type RatingCapability,
+  type RatingOptions,
+  rating,
+} from "./capability";
+export {
+  configuredPools,
+  RatingConfig,
+  type RatingConfigInput,
+  RatingGame,
+  RatingLevel,
+  RatingXpAward,
+  type ResolvedRatingGame,
+  resolveGame,
+  validateRatingGames,
+} from "./config/config";
+export { RatingRecord } from "./data/rating";
+export { awardXp, classifyLevel, type XpOutcome, xpFor } from "./experience/xp";
+export { type RecordedPlayer, type RecordOutcomeInput, recordOutcome } from "./record/record";

package/src/migrations/0001_rating.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Creates `pithy_rating_ratings` — one row per (pool, player) holding the skill rating state, the
+ * denormalized conservative `skill` number, and the monotonic `xp` total. All identifiers are camelCase;
+ * the migration runner's `CamelCasePlugin` snake-cases them to `pithy_rating_*` columns.
+ *
+ * The unique `(pool, userId)` index is the upsert conflict target. The `(pool, skill)` index serves
+ * matchmaking's skill-bucketed reads and any leaderboard-style rank scan over the pool.
+ */
+export const rating_0001_rating: Migration = {
+  up: async (db: Kysely<unknown>) => {
+    await db.schema
+      .createTable("pithyRatingRatings")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("pool", "text", (c) => c.notNull())
+      .addColumn("userId", "text", (c) => c.notNull())
+      .addColumn("algorithm", "text", (c) => c.notNull())
+      .addColumn("state", "text", (c) => c.notNull())
+      .addColumn("skill", "real", (c) => c.notNull())
+      .addColumn("xp", "real", (c) => c.notNull().defaultTo(0))
+      .addColumn("games", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema
+      .createIndex("pithyRatingRatingsPlayerIdx")
+      .on("pithyRatingRatings")
+      .columns(["pool", "userId"])
+      .unique()
+      .execute();
+
+    await db.schema
+      .createIndex("pithyRatingRatingsSkillIdx")
+      .on("pithyRatingRatings")
+      .columns(["pool", "skill"])
+      .execute();
+  },
+
+  down: async (db: Kysely<unknown>) => {
+    await db.schema.dropIndex("pithyRatingRatingsSkillIdx").execute();
+    await db.schema.dropIndex("pithyRatingRatingsPlayerIdx").execute();
+    await db.schema.dropTable("pithyRatingRatings").execute();
+  },
+};

package/src/record/record.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { RatedOutcome, RatingEntry } from "../algorithm/algorithm";
+import type { ResolvedRatingGame } from "../config/config";
+import type { RatingRecord } from "../data/rating";
+import type { RatingStore } from "../data/store";
+import { awardXp, classifyLevel, type XpOutcome, xpFor } from "../experience/xp";
+
+/**
+ * Recording a game's outcome — the heart of the tracker. It loads each player's current standing in the
+ * game's pool (a newcomer starts at the algorithm's `initial`), runs the algorithm's pure `update` to get
+ * everyone's new skill state, folds in experience, and upserts each row.
+ *
+ * Two rules from the issue live here:
+ * - **Skill rating (MMR) always updates from a real result** — a game is a game.
+ * - **Experience / rank is gated**: a shared-room (friend) game counts toward XP only when the game opts
+ *   in with `sharedRoomCounts`. By default friends cannot farm each other for XP.
+ */
+
+/** The outcome to record: a placement per player, an optional team grouping, and provenance. */
+export interface RecordOutcomeInput {
+  /** Each player's finishing place (1 = winner; ties share a place). Every roster member must appear. */
+  ranks: Record<string, number>;
+  /** Optional team grouping (player id → team id), for a team format. */
+  teams?: Record<string, string>;
+  /** Whether this game was played in a shared room with a friend. Gates XP/rank, never MMR. */
+  sharedRoom?: boolean;
+  /** When the game finished. */
+  at: Date;
+}
+
+/** One player's standing after a recorded game. */
+export interface RecordedPlayer {
+  /** The player's user id. */
+  userId: string;
+  /** Their new conservative skill number (the MMR the matchmaker buckets on). */
+  skill: number;
+  /** Their new monotonic experience total in the pool. */
+  xp: number;
+  /** Their rank/level from the game's ladder, or null. */
+  level: string | null;
+  /** Their new algorithm state blob. */
+  state: unknown;
+  /** How many rated games they have now completed in the pool. */
+  games: number;
+}
+
+export async function recordOutcome(
+  store: RatingStore,
+  resolved: ResolvedRatingGame,
+  input: RecordOutcomeInput,
+): Promise<RecordedPlayer[]> {
+  const { game, algorithm, params } = resolved;
+  const playerIds = Object.keys(input.ranks);
+
+  if (playerIds.length !== game.players) {
+    throw new ValidationError({
+      message: `This game expects ${game.players} players, but the outcome names ${playerIds.length}.`,
+      action: "Report exactly the game's roster in `ranks`.",
+      detail: `Game "${game.key}" players=${game.players}, ranks has ${playerIds.length}.`,
+    });
+  }
+  if (input.teams) {
+    for (const id of playerIds) {
+      if (!(id in input.teams)) {
+        throw new ValidationError({
+          message: "Every player must be assigned to a team.",
+          action: "Include each player id in `teams`.",
+          detail: `Player "${id}" is in ranks but not teams.`,
+        });
+      }
+    }
+  }
+
+  const existing = await store.getMany(game.pool, playerIds);
+  const byUser = new Map(existing.map((record) => [record.userId, record]));
+
+  const entries: RatingEntry[] = playerIds.map((userId) => {
+    const record = byUser.get(userId);
+    const state = record ? algorithm.state.parse(record.state) : algorithm.initial(params);
+    return { playerId: userId, state };
+  });
+
+  const outcome: RatedOutcome = { ranks: input.ranks, teams: input.teams };
+  const nextStates = algorithm.update(params, entries, outcome);
+
+  const countsForXp = !input.sharedRoom || game.sharedRoomCounts;
+  const results: RecordedPlayer[] = [];
+
+  for (const userId of playerIds) {
+    const nextState = nextStates[userId];
+    if (nextState === undefined) {
+      throw new ValidationError({
+        message: "The rating algorithm did not return a state for every player.",
+        detail: `Algorithm "${algorithm.id}" omitted player "${userId}" from its update.`,
+      });
+    }
+    const prior = byUser.get(userId);
+    const priorXp = prior?.xp ?? 0;
+    const gained = game.xp && countsForXp ? xpFor(game.xp, xpOutcome(userId, input.ranks)) : 0;
+    const xp = awardXp(priorXp, gained);
+
+    const record: RatingRecord = {
+      id: 0,
+      pool: game.pool,
+      userId,
+      algorithm: algorithm.id,
+      state: nextState,
+      skill: algorithm.skill(params, nextState),
+      xp,
+      games: (prior?.games ?? 0) + 1,
+      updatedAt: input.at,
+    };
+    await store.upsert(record);
+
+    results.push({
+      userId,
+      skill: record.skill,
+      xp,
+      level: game.levels ? classifyLevel(game.levels, xp) : null,
+      state: nextState,
+      games: record.games,
+    });
+  }
+
+  return results;
+}
+
+/** A player's win/draw/loss for XP: sole top place is a win, a shared top place is a draw, else a loss. */
+function xpOutcome(userId: string, ranks: Record<string, number>): XpOutcome {
+  const mine = ranks[userId];
+  const best = Math.min(...Object.values(ranks));
+  if (mine !== best) return "loss";
+  const atBest = Object.values(ranks).filter((r) => r === best).length;
+  return atBest === 1 ? "win" : "draw";
+}

package/src/seeds/example.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { RatingRecord } from "../data/rating";
+import { RATING_RATINGS_TABLE } from "../data/tables";
+
+/**
+ * Three canonical example players in a `demo` pool rated by Elo — the same cast auth seeds. Ada leads on
+ * skill and experience, Alan trails; a shape you can read a `/rating/games/<key>/me` response against
+ * immediately after `pithy seed`. Never runs in production.
+ */
+const RATING_EXAMPLE_SEED_ORDER = 210;
+const now = () => new Date();
+
+export const ratingExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: RATING_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", RATING_RATINGS_TABLE, RatingRecord, [
+      {
+        id: 1,
+        pool: "demo",
+        userId: EXAMPLE_ADA.id,
+        algorithm: "elo",
+        state: { rating: 1560 },
+        skill: 1560,
+        xp: 120,
+        games: 8,
+        updatedAt: now(),
+      },
+      {
+        id: 2,
+        pool: "demo",
+        userId: EXAMPLE_GRACE.id,
+        algorithm: "elo",
+        state: { rating: 1500 },
+        skill: 1500,
+        xp: 90,
+        games: 6,
+        updatedAt: now(),
+      },
+      {
+        id: 3,
+        pool: "demo",
+        userId: EXAMPLE_ALAN.id,
+        algorithm: "elo",
+        state: { rating: 1440 },
+        skill: 1440,
+        xp: 60,
+        games: 5,
+        updatedAt: now(),
+      },
+    ]),
+  ],
+});

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/rating knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/rating";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";