@pithy-sh/rating 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/rating
+
+Skill and experience for your games. Two numbers per player, per pool: a skill rating that moves both ways with every result and feeds matchmaking, and an experience total that only ever rises and drives rank.
+
+They are separate on purpose. One number cannot both rank a player fairly and reward them for turning up — a ladder that pays out for playing stops estimating strength, and a rating that only estimates strength has nothing to show a player who is not winning yet.
+
+```sh
+pithy add rating
+```
+
+**Documentation: [pithy.sh/docs/capabilities/rating](https://pithy.sh/docs/capabilities/rating).** Overview, adding it, using it, and the reference: the algorithms, pools.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/docs/algorithms.md

@@ -0,0 +1,43 @@
+# Choosing a rating algorithm
+
+_The reader's version of this page is [pithy.sh/docs/capabilities/rating/algorithms](https://pithy.sh/docs/capabilities/rating/algorithms). This copy ships in the package because `packages/rating/pithy.manifest.json` sends an adopter to it by name._
+
+The rating tracker holds two numbers per player per pool. Skill rating (MMR) is the matchmaking input — it moves up and down with each result, weighted by opponent strength, and can be hidden from players. Experience (XP) is the visible progression — a monotonic total that only ever rises and drives rank and level. This document is about the first number: which algorithm computes it.
+
+Three algorithms ship behind one seam. Each declares the player counts it supports, and the tracker rejects at assembly a game that wires a 1v1-only algorithm to an N-player game — the same way a bad game config fails on deploy rather than at 3am. You choose one per game and set its pool; you can register your own with `registerRatingAlgorithm`.
+
+## The one-line answer
+
+Rating a 1v1 game and you want it simple and transparent? Use `elo`. Rating a 1v1 game where players play infrequently and you care about rating accuracy? Use `glicko`. Rating anything else — free-for-alls, teams, any count above two? Use `trueskill`. It is the only built-in that fits this package's N-player games.
+
+## `elo`
+
+One number per player, and nothing else. A win moves both players by `K × (actual − expected)`, where the expected score comes from the rating gap. Beating a stronger player earns more than beating a weaker one; that is the whole model. `K` (the K-factor, default 32) is the single dial — larger `K` reacts faster and swings harder, smaller `K` is steadier.
+
+Elo is 1v1 only. It has no notion of uncertainty, so a brand-new player and a veteran with a thousand games are treated identically at the same rating — the new player's number just takes many games to find its level. Reach for Elo when you want a rating players can understand at a glance and you do not need fast convergence.
+
+Supports: 2 players. Skill number: the rating itself.
+
+## `glicko` (Glicko-2)
+
+Elo's successor, and still 1v1. Alongside the rating it tracks a rating deviation (RD) — how confident the system is — and a volatility — how erratic the player's recent results have been. A result from a high-RD player moves their rating a lot and their opponent's a little; RD shrinks as they play and grows back while they are idle. That is why Glicko re-converges fast for infrequent players: a returning player is treated as uncertain and finds their level in a handful of games rather than dozens.
+
+The volatility is solved each game by an iteration (the crux of Glicko-2) and is constrained by the system constant `τ` (default 0.5) — smaller `τ` damps volatility swings. The skill number this tracker exposes and buckets on is `rating − 2·RD`, a conservative estimate that treats an uncertain player as weaker until they have proven otherwise, which keeps new and returning players out of lopsided matches.
+
+Supports: 2 players. Skill number: `rating − 2·RD`.
+
+## `trueskill`
+
+The Bayesian one, and the only built-in that rates more than two players. Each player is a Gaussian belief — a mean skill `μ` and an uncertainty `σ`. A game is evidence that shifts every participant's belief: winners' `μ` rises, losers' falls, and everyone's `σ` shrinks toward certainty. It handles 1v1, N-player free-for-alls (each player is a team of one), and teams (a team's skill is the sum of its members', and the result is distributed back across them).
+
+Matchmaking buckets on `μ − 3·σ`, a conservative rank that stays low until the system is confident. Constants: `β` (skill class width, default `σ0/2`) sets how much a single game can prove, `τ` (dynamics, default `σ0/100`) lets ratings drift over time so a long-dormant player is not frozen, and the draw probability shapes how a tie is interpreted. This built-in uses the standard sequential approximation for more than two teams — see the source for the exact method.
+
+Supports: 2 or more players; teams. Skill number: `μ − 3·σ`.
+
+## Pools
+
+An algorithm rates a pool, not a game directly. A pool is a named bucket of ratings; a game reads and writes one. Point several games at one pool (`global`) for a single cross-game rating, or give each game its own pool (the default — the pool defaults to the game key) for independent ladders. A pool is rated by a single algorithm; matchmaking buckets on the configured pool's skill number.
+
+## Registering your own
+
+The seam is `RatingAlgorithm` (`@pithy-sh/rating/src/algorithm/algorithm`): declare an `id`, a `params` schema with defaults, a `state` schema, the player counts you support, and pure `initial` / `update` / `skill` functions. Register it with `registerRatingAlgorithm` before the capability assembles, then name its `id` in a game. The tracker validates your params and player bounds exactly as it does the built-ins.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pithy-sh/rating",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/rating"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "docs",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@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,42 @@
+{
+  "name": "rating",
+  "package": "@pithy-sh/rating",
+  "requiredBindings": [{ "type": "d1", "name": "DB" }],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth"],
+  "migrationNamespace": "rating",
+  "whenToEnable": "Two numbers per player, per pool, in your own D1: a skill rating (MMR) that moves both ways with every result and feeds matchmaking, and an experience total (XP) that only ever rises and drives rank. They are separate on purpose — one number cannot both rank a player fairly and reward them for turning up. The algorithm is a choice rather than a hardcode: `elo` (1v1, transparent, one tunable), `glicko` (Glicko-2, 1v1, carrying an uncertainty term so a player returning on stale form is not rated as if they never left), and `trueskill` (any roster, and the only one that rates teams) ship built in, and registerRatingAlgorithm takes your own. Wiring a 1v1-only algorithm to a four-player game fails on deploy, not on the first recorded result. Pools are named, so several games can share one ladder or each can keep its own — and a pool is what @pithy-sh/matchmaking buckets its open queue on, which makes this the skill source that capability needs. Recording an outcome is server-authoritative by default and needs the rating:record scope, so a device cannot report that it won. This is the input system @pithy-sh/leaderboard deliberately left out: a leaderboard ranks what has happened, a rating estimates what will. Ratings bind to an authenticated player, so add auth too — without it every route is denied.",
+  "scaffold": [
+    "Add a `rating({ games: [...] })` block to pithy.config.ts and declare at least one game.",
+    "Give each game a `key` and an `algorithm` (`elo`, `glicko`, `trueskill`, or one you registered), and optionally `players`, `teams`, a shared `pool`, an `xp` award per outcome, and a `levels` ladder. `elo` and `glicko` rate 1v1 only; `trueskill` rates any roster and is the only one that rates teams.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_rating_ratings.",
+    "Add `@pithy-sh/auth` if it is not already installed. A rating belongs to an authenticated player; without auth every route is denied.",
+    "Mint a token carrying the `rating:record` scope for your trusted server, and record outcomes with it. Never put that scope on a player's token.",
+    "Call `registerRatingAlgorithm(yourAlgorithm)` in your worker entry, before the capability assembles, if none of the three built-ins fit. An unknown algorithm id fails at assembly.",
+    "Add `@pithy-sh/matchmaking` and point a game's `skillPool` at a pool declared here to bucket its open queue on skill.",
+    "Read packages/rating/docs/algorithms.md before choosing. A stored rating means nothing under a different model, so the choice is immutable in practice."
+  ],
+  "configOptions": [
+    {
+      "key": "games",
+      "default": [{ "key": "duel", "algorithm": "elo", "xp": { "win": 20, "draw": 10, "loss": 0 } }],
+      "describe": "Every rated game this app runs. Replace this example — a 1v1 duel rated by Elo, in a pool named after the key, awarding XP on top. `key` is a URL path segment and the outcome's game reference; `algorithm` names a built-in (`elo`, `glicko`, `trueskill`) or one you registered; `pool` shares a ladder across games and defaults to the key. At least one game is required."
+    },
+    {
+      "key": "serverAuthoritative",
+      "default": true,
+      "describe": "Require the record scope to post an outcome. On by default: a rating a client can write is a rating a client can invent, and the whole ladder is downstream of it. Turn it off only if you accept that a player's device can report that it won."
+    },
+    {
+      "key": "basePath",
+      "default": "/rating",
+      "describe": "Where the rating routes mount. Outcomes are recorded at POST `<basePath>/games/:game/outcomes`, and a standing is read under `<basePath>/games/:game`."
+    },
+    {
+      "key": "recordScope",
+      "default": "rating:record",
+      "describe": "The scope a caller must hold to record an outcome while `serverAuthoritative` is on. Mint it for your trusted server's token and never for a player's."
+    }
+  ]
+}

package/src/algorithm/algorithm.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { z } from "zod";
+
+/**
+ * The rating-algorithm seam — the one contract that keeps the tracker's storage, config, and HTTP
+ * surface generic while the *math* of turning a game's result into new numbers stays pluggable.
+ *
+ * It is the deliberate mirror of `@pithy-sh/multiplayer`'s game-model registry (`game/model.ts`): a
+ * `RatingAlgorithm` is looked up by `id` from a {@link registerRatingAlgorithm registry}, it declares the
+ * player counts it supports, and the config layer rejects at assembly a game that wires a 1v1-only
+ * algorithm (`elo`/`glicko`) to an N-player game — the same shape as multiplayer's `validateGames`.
+ *
+ * Three built-ins ship (`elo`, `glicko`, `trueskill`); an adopter registers their own the same way. The
+ * seam is code, not data: an algorithm's logic is imported into the worker bundle, while only its per-
+ * player {@link RatingAlgorithm.state state} (a serializable, Zod-validated blob) lives in D1.
+ */
+
+/** One player's entry into a rated result: who they are and their rating state *before* the game. */
+export interface RatingEntry<State = unknown> {
+  /** The player's authenticated user id (the `pithy_auth_users.id` UUID from `AuthContext`). */
+  playerId: string;
+  /** The player's current rating state in the game's pool — {@link RatingAlgorithm.initial} for a newcomer. */
+  state: State;
+}
+
+/**
+ * The result of one rated game, in the model-neutral shape every algorithm consumes. Placement is a
+ * finishing place per player: `1` is the winner, ties share a place. For a 1v1 win, the winner is place
+ * `1` and the loser place `2`; a draw makes both place `1`. Free-for-all and team formats express their
+ * full ordering the same way.
+ */
+export interface RatedOutcome {
+  /** Each player's finishing place (1-based). Equal values are a tie. Every entered player must appear. */
+  ranks: Record<string, number>;
+  /**
+   * Optional team grouping: player id → team id. Present only for a team format (TrueSkill), where a
+   * team's players share a placement and the update pools their skill. Absent for 1v1 / free-for-all.
+   */
+  teams?: Record<string, string>;
+}
+
+/**
+ * One rating algorithm — a pluggable implementation of "given everyone's state and how the game finished,
+ * what is everyone's new state?" `State` is the per-player blob persisted between games; `Params` is the
+ * algorithm's declarative tuning (K-factor, volatility constraint, prior μ/σ), validated at assembly and
+ * threaded into every call — the exact analog of a multiplayer model's `rules` block.
+ */
+export interface RatingAlgorithm<State = unknown, Params = unknown> {
+  /** The discriminator that matches a game config's `algorithm`. Unique per registered algorithm. */
+  id: string;
+  /** Validates and types the algorithm's tuning block (`algoParams` in config). Must supply defaults. */
+  params: z.ZodType<Params>;
+  /** Validates and types the persisted per-player state — round-tripped through D1 on every read. */
+  state: z.ZodType<State>;
+  /** The fewest players a single rated game supports. `elo`/`glicko` = 2; `trueskill` = 2. */
+  minPlayers: number;
+  /** The most players a single rated game supports. `elo`/`glicko` = 2; `trueskill` = `Infinity`. */
+  maxPlayers: number;
+  /** Whether the algorithm can rate team formats (a `teams` grouping). Only `trueskill`. */
+  supportsTeams: boolean;
+  /** A brand-new player's starting state, from the (defaulted) params. */
+  initial(params: Params): State;
+  /**
+   * Recompute every participant's state from one game's outcome. Pure — no clock, no storage, no RNG.
+   * Returns the new state for every entered player, keyed by `playerId`; the caller persists each.
+   */
+  update(params: Params, entries: readonly RatingEntry<State>[], outcome: RatedOutcome): Record<string, State>;
+  /**
+   * The single comparable number the API exposes and matchmaking buckets on. Conservative where the
+   * algorithm models uncertainty: `elo` = rating; `glicko` = rating − 2·RD; `trueskill` = μ − 3·σ.
+   */
+  skill(params: Params, state: State): number;
+}

package/src/algorithm/builtins/elo.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { RatingUnsupportedPlayerCountError } from "../../error/errors";
+import type { RatedOutcome, RatingAlgorithm, RatingEntry } from "../algorithm";
+
+/**
+ * Elo — the classic 1v1 rating. One number per player, no modeled uncertainty: a game nudges the pair
+ * toward or away from each other by `k · (actual − expected)`, where `expected` is the logistic of the
+ * rating gap over a 400-point scale. Deterministic and symmetric — the winner's gain equals the loser's
+ * loss. 1v1 only; N-player and team formats use `trueskill`.
+ */
+
+/** One Elo player's persisted state: a single rating number, round-tripped through D1 between games. */
+export const EloState = z
+  .object({
+    rating: z
+      .number()
+      .describe("The player's current Elo rating — higher is stronger. Newcomers start at `initialRating`."),
+  })
+  .describe("The per-player Elo state persisted between games: just the rating number.");
+export type EloState = z.output<typeof EloState>;
+
+/** Elo's declarative tuning: the K-factor (volatility) and the newcomer's starting rating. */
+export const EloParams = z
+  .object({
+    k: z
+      .number()
+      .positive()
+      .default(32)
+      .describe(
+        "The K-factor — the maximum rating swing from a single game. Higher reacts faster; lower is more stable. Default 32.",
+      ),
+    initialRating: z
+      .number()
+      .default(1500)
+      .describe("The rating a brand-new player enters the pool with. The conventional Elo midpoint is 1500."),
+  })
+  .describe(
+    "Elo's tuning block: K-factor and starting rating. Every field defaults, so `EloParams.parse({})` yields the standard tuning.",
+  );
+export type EloParams = z.output<typeof EloParams>;
+
+/** The 1v1 score of `a` against `b` from their finishing places: lower place is better. Win 1, draw 0.5, loss 0. */
+function scoreFromRanks(aRank: number, bRank: number): number {
+  if (aRank < bRank) return 1;
+  if (aRank > bRank) return 0;
+  return 0.5;
+}
+
+/** The classic Elo algorithm — a single instance registered by `id`, not a factory. */
+export const elo: RatingAlgorithm<EloState, EloParams> = {
+  id: "elo",
+  params: EloParams,
+  state: EloState,
+  minPlayers: 2,
+  maxPlayers: 2,
+  supportsTeams: false,
+
+  initial(params: EloParams): EloState {
+    return { rating: params.initialRating };
+  },
+
+  update(
+    params: EloParams,
+    entries: readonly RatingEntry<EloState>[],
+    outcome: RatedOutcome,
+  ): Record<string, EloState> {
+    if (entries.length !== 2) {
+      throw new RatingUnsupportedPlayerCountError({
+        detail: `elo.update expected exactly 2 entries, got ${entries.length}.`,
+      });
+    }
+    const a = entries[0];
+    const b = entries[1];
+    if (a === undefined || b === undefined) {
+      throw new RatingUnsupportedPlayerCountError({
+        detail: `elo.update expected exactly 2 entries, got ${entries.length}.`,
+      });
+    }
+    const ratingA = a.state.rating;
+    const ratingB = b.state.rating;
+
+    const expectedA = 1 / (1 + 10 ** ((ratingB - ratingA) / 400));
+    const expectedB = 1 - expectedA;
+
+    const rankA = outcome.ranks[a.playerId];
+    const rankB = outcome.ranks[b.playerId];
+    if (rankA === undefined || rankB === undefined) {
+      throw new RatingUnsupportedPlayerCountError({
+        detail: "elo.update requires a rank for each of its two players.",
+      });
+    }
+    const scoreA = scoreFromRanks(rankA, rankB);
+    const scoreB = scoreFromRanks(rankB, rankA);
+
+    return {
+      [a.playerId]: { rating: ratingA + params.k * (scoreA - expectedA) },
+      [b.playerId]: { rating: ratingB + params.k * (scoreB - expectedB) },
+    };
+  },
+
+  skill(_params: EloParams, state: EloState): number {
+    return state.rating;
+  },
+};

package/src/algorithm/builtins/glicko.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import type { RatingAlgorithm, RatingEntry } from "../algorithm";
+
+/**
+ * Glicko-2 — Mark Glickman's rating system, 1v1 only. A player carries a `rating` (the Elo-scale
+ * estimate), a `rd` (rating deviation — the uncertainty band around that estimate), and a `vol`
+ * (volatility — how erratic the player's results are). A game shrinks `rd` (we learn), and the
+ * outcome plus expectation nudges `rating`. All the interesting math lives in {@link glicko.update}.
+ *
+ * Reference: Glickman, "Example of the Glicko-2 system" (glicko.net/glicko/glicko2.pdf). Constants:
+ * the Glicko-2 internal scale factor is 173.7178 and the anchor rating is 1500.
+ */
+
+/** The Glicko-2 scale factor converting between the public Elo scale and the internal (μ, φ) scale. */
+const SCALE = 173.7178;
+/** The public-scale anchor rating that maps to internal μ = 0. */
+const ANCHOR = 1500;
+/** Convergence tolerance for the volatility (Illinois) iteration. */
+const CONVERGENCE = 1e-6;
+
+/** One player's persisted Glicko-2 state: their rating, its deviation, and their volatility. */
+export const GlickoState = z
+  .object({
+    rating: z.number().describe("The player's Glicko rating on the public Elo scale (anchored at 1500)."),
+    rd: z
+      .number()
+      .positive()
+      .describe("Rating deviation — the uncertainty band around the rating; shrinks with each game."),
+    vol: z
+      .number()
+      .positive()
+      .describe("Volatility — how erratic the player's results are; governs how fast rating can move."),
+  })
+  .describe("A single player's Glicko-2 rating state, persisted between games.");
+export type GlickoState = z.output<typeof GlickoState>;
+
+/** The Glicko-2 tuning block. Every field defaults, so `GlickoParams.parse({})` yields the standard defaults. */
+export const GlickoParams = z
+  .object({
+    tau: z
+      .number()
+      .positive()
+      .default(0.5)
+      .describe("System constant τ, constraining volatility change over time (typical 0.3–1.2; smaller = steadier)."),
+    initialRating: z.number().default(1500).describe("A newcomer's starting rating on the public Elo scale."),
+    initialRd: z
+      .number()
+      .positive()
+      .default(350)
+      .describe("A newcomer's starting rating deviation (maximal uncertainty)."),
+    initialVol: z.number().positive().default(0.06).describe("A newcomer's starting volatility."),
+  })
+  .describe("Glicko-2 tuning parameters, each defaulted to Glickman's recommended values.");
+export type GlickoParams = z.output<typeof GlickoParams>;
+
+/** g(φ): the impact-of-opponent-uncertainty factor. A more uncertain opponent counts for less. */
+function g(phi: number): number {
+  return 1 / Math.sqrt(1 + (3 * phi * phi) / (Math.PI * Math.PI));
+}
+
+/** E(μ, μ_j, φ_j): the expected score of the player against the opponent. */
+function expectedScore(mu: number, muJ: number, phiJ: number): number {
+  return 1 / (1 + Math.exp(-g(phiJ) * (mu - muJ)));
+}
+
+/**
+ * Solve the new volatility σ' via the Illinois (regula-falsi) algorithm on Glickman's f(x).
+ * `phi`, `v`, `delta` are already on the internal scale; `sigma` is the current volatility; `tau` the constant.
+ */
+function newVolatility(sigma: number, phi: number, v: number, delta: number, tau: number): number {
+  const a = Math.log(sigma * sigma);
+  const deltaSq = delta * delta;
+  const phiSq = phi * phi;
+  const tauSq = tau * tau;
+
+  const f = (x: number): number => {
+    const ex = Math.exp(x);
+    const num = ex * (deltaSq - phiSq - v - ex);
+    const den = 2 * (phiSq + v + ex) * (phiSq + v + ex);
+    return num / den - (x - a) / tauSq;
+  };
+
+  let A = a;
+  let B: number;
+  if (deltaSq > phiSq + v) {
+    B = Math.log(deltaSq - phiSq - v);
+  } else {
+    let k = 1;
+    while (f(a - k * tau) < 0) {
+      k++;
+    }
+    B = a - k * tau;
+  }
+
+  let fA = f(A);
+  let fB = f(B);
+  while (Math.abs(B - A) > CONVERGENCE) {
+    const C = A + ((A - B) * fA) / (fB - fA);
+    const fC = f(C);
+    if (fC * fB <= 0) {
+      A = B;
+      fA = fB;
+    } else {
+      fA = fA / 2;
+    }
+    B = C;
+    fB = fC;
+  }
+
+  return Math.exp(A / 2);
+}
+
+/** Run the Glicko-2 single-game update for one player (rating r, rd, vol) against one opponent, given score s. */
+function updateOne(player: GlickoState, opponent: GlickoState, s: number, tau: number): GlickoState {
+  const mu = (player.rating - ANCHOR) / SCALE;
+  const phi = player.rd / SCALE;
+  const sigma = player.vol;
+  const muJ = (opponent.rating - ANCHOR) / SCALE;
+  const phiJ = opponent.rd / SCALE;
+
+  const gJ = g(phiJ);
+  const e = expectedScore(mu, muJ, phiJ);
+  const v = 1 / (gJ * gJ * e * (1 - e));
+  const delta = v * gJ * (s - e);
+
+  const sigmaPrime = newVolatility(sigma, phi, v, delta, tau);
+
+  const phiStar = Math.sqrt(phi * phi + sigmaPrime * sigmaPrime);
+  const phiPrime = 1 / Math.sqrt(1 / (phiStar * phiStar) + 1 / v);
+  const muPrime = mu + phiPrime * phiPrime * gJ * (s - e);
+
+  return {
+    rating: SCALE * muPrime + ANCHOR,
+    rd: SCALE * phiPrime,
+    vol: sigmaPrime,
+  };
+}
+
+/** Per-pair score from placements: lower place is better. 1 for a win, 0.5 for a tie, 0 for a loss. */
+function scoreOf(myRank: number, theirRank: number): number {
+  if (myRank < theirRank) return 1;
+  if (myRank === theirRank) return 0.5;
+  return 0;
+}
+
+export const glicko: RatingAlgorithm<GlickoState, GlickoParams> = {
+  id: "glicko",
+  params: GlickoParams,
+  state: GlickoState,
+  minPlayers: 2,
+  maxPlayers: 2,
+  supportsTeams: false,
+  initial(params) {
+    return { rating: params.initialRating, rd: params.initialRd, vol: params.initialVol };
+  },
+  update(params, entries, outcome) {
+    const [a, b] = entries as readonly [RatingEntry<GlickoState>, RatingEntry<GlickoState>];
+    const rankA = outcome.ranks[a.playerId];
+    const rankB = outcome.ranks[b.playerId];
+    if (rankA === undefined || rankB === undefined) {
+      throw new InternalError({ detail: "glicko update received an outcome missing a player's rank." });
+    }
+    const sA = scoreOf(rankA, rankB);
+    const sB = scoreOf(rankB, rankA);
+    return {
+      [a.playerId]: updateOne(a.state, b.state, sA, params.tau),
+      [b.playerId]: updateOne(b.state, a.state, sB, params.tau),
+    };
+  },
+  // Conservative skill: rating minus two deviations. A wide RD (an unproven player) is discounted,
+  // so matchmaking and leaderboards rank on what we are confident the player is at least worth.
+  skill(_params, state) {
+    return state.rating - 2 * state.rd;
+  },
+};