@pithy-sh/leaderboard 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/leaderboard
+
+Rank your players. Submit a score, read the standings — daily through all-time.
+
+Boards run in your Cloudflare account, on your D1, against your data. Closed windows stay as long as you say, in plain SQL you can join against your own tables. There is no Pithy service in the path and no Pithy bill.
+
+```sh
+pithy add leaderboard
+```
+
+**Documentation: [pithy.sh/docs/capabilities/leaderboard](https://pithy.sh/docs/capabilities/leaderboard).** Overview, adding it, using it, and the reference: boards and windows, ranking modes, what it costs.
+
+_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/costs.md

@@ -0,0 +1,102 @@
+# What a leaderboard costs
+
+_The reader's version of this page is [pithy.sh/docs/capabilities/leaderboard/costs](https://pithy.sh/docs/capabilities/leaderboard/costs). This copy ships in the package because `packages/leaderboard/src/config/config.ts` sends an adopter to it by name._
+
+**As of 2026-07-16.** Cloudflare's [D1 pricing page](https://developers.cloudflare.com/d1/platform/pricing/) is the authority. Prices, included allowances, and limits can change at any time, and the allowances do most of the work in the numbers below — a change to the 25 billion rows-read allowance alone would move every boundary in this table. Nothing here is a Cloudflare quote, and none of it is a bill you can plan against to the dollar. It is directional engine guidance.
+
+**Pithy never bills you.** This is Cloudflare metering your own Cloudflare account, on prices Pithy does not set and cannot control. We take no cut of any of it.
+
+**We are not the cheapest option, and this page is not a sales pitch.** The free platform SDKs — Game Center, Play Games Services, Steam — cost nothing at any scale, and PlayFab is a few times cheaper than us. See [pithy.sh/docs/capabilities/leaderboard/differentiation](https://pithy.sh/docs/capabilities/leaderboard/differentiation) for the full comparison; the short version is that you pay here for cross-platform reach and for owning your data in your own SQL, not for a lower bill. This page exists so you can see that bill before you commit — the mode you pick at 1,000 players decides what it looks like at a million, and growth is the good outcome that still has a cost.
+
+## The table
+
+| Players | `rank: "live"` | `materialize` daily | `materialize` hourly | Storage | Upserts/sec |
+|---:|---:|---:|---:|---:|---:|
+| 1,000 | **$0** | $0 | $0 | 0.00 GB | ~0 |
+| 10,000 | **$0** | $0 | $0 | 0.00 GB | 2 |
+| 100,000 | **$765** | **$49** | $256 | 0.03 GB | 17 |
+| 1,000,000 | **$75,825** | **$940** | $3,010 | 0.30 GB | **174** |
+| 10,000,000 | **$7,508,925** | **$9,850** | $30,550 | 3.00 GB | **1,736** |
+
+Per month, USD. Reproduce it yourself: `bun run --filter @pithy-sh/leaderboard costs`.
+
+## Reading it
+
+**Live rank is free to ~10k players and ruinous past 100k.** Under about ten thousand players the 25B/month read allowance absorbs everything, so `rank: "live"` is correct and costs nothing. That is most adopters, and it is the default. Do not engineer anything.
+
+**Live rank is quadratic.** D1 bills rows *scanned*, not returned — "a query that filters on an unindexed column may return fewer rows to your Worker, but is still required to read (scan) more rows". A live rank counts every entry that beats you, so each check scans a slice of the board that grows with the board, while the number of checks grows with the player count too. Ten times the players is about a hundred times the read bill. That is the whole shape of the first column.
+
+**Materialization is the fix, and it is pure D1.** Roughly $75,825 becomes $940 at a million players. It is not a different database, a different engine, or a different product — it is a stored rank column and a cron. Refresh cadence is a continuous dial trading staleness for cost, and it stops paying for itself somewhere between hourly and every fifteen minutes. Your own score stays live in both modes, which hides most of the staleness from the player who cares most about it.
+
+**Past ~1M players the dominant term flips.** At ten million, materialized-daily is $9,850/month, of which **$8,950 is submission writes** — not the refresh. Beyond that point no cadence tuning helps. Only fewer windows or fewer submissions do.
+
+**Storage never binds.** Three gigabytes at ten million players, against a 10 GB cap.
+
+## The table is the worst case. Your board does better.
+
+Every figure above assumes *every* submission writes. On the default `best` board it doesn't: a submission that fails to beat a player's stored score is skipped by the upsert's `WHERE` guard and writes **zero rows** (`trackActivity: false`, the default). Since submission writes are the dominant term — 85% of the bill past a million players — and most submissions don't improve a player's best, a real board pays a fraction of the table.
+
+At a million players, materialize-daily by how often submissions actually improve:
+
+| improving submissions | materialize daily |
+|---:|---:|
+| 100% (worst case, the table) | $940 |
+| 50% | ~$580 |
+| 20% (typical) | **~$220** |
+
+That guard is the single biggest cost lever in the capability, and it is on by default. Its only cost is that `submittedAt` then tracks a player's last *improving* submission rather than their last submission of any kind — nothing in ranking depends on it. Set `trackActivity: true` on a board to write on every submission and keep `submittedAt` a true last-seen timestamp, at full write cost. `sum` and `latest` boards always write, since every submission changes the score.
+
+## The write model, measured
+
+The write figures rest on one number: rows written per submission per window. It is **measured, not guessed** — `src/entry/writeAmplification.workers.test.ts` reads D1's own `meta.rows_written` for the real upsert and fails if it moves:
+
+- A steady-state improving submission writes **2** rows: the entry row and the rank index. The unique-player index doesn't change on an update, so it costs nothing.
+- The first-ever submission for a player writes **3** (both indexes), amortized to almost nothing across their submissions.
+- A guarded non-improving submission writes **0**.
+
+The entries table uses a plain `INTEGER PRIMARY KEY`, not `AUTOINCREMENT`, on purpose: autoincrement would add a `sqlite_sequence` write to *every* upsert — even a guarded no-op, because SQLite reserves the sequence value before it detects the conflict — turning the free no-op back into a billed one. A one-line schema choice keeps the lever sharp.
+
+## The two walls sit in different places
+
+**Cost says materialize past ~100k. Throughput says shard past ~1M.**
+
+Throughput is the harder wall, and the one the cost column hides. D1 executes one query at a time per database, and its docs describe a write as taking "several milliseconds" — which implies a practical ceiling somewhere near **200 upserts/sec**. At a million players the *average* is already 174/sec, about 87% of it, and any peak goes over. At ten million it is more than eight times over.
+
+So **one D1 database tops out around a million players regardless of what it costs.** Cloudflare's endorsed answer past that is horizontal scale-out: shard into smaller per-tenant databases. The 10 GB per-database cap **cannot be increased**, which is the same message from the other direction.
+
+## Assumptions
+
+Change any of these and the table moves.
+
+- 5 submissions and 5 rank checks per player per day.
+- 3 windows per board set (say daily + weekly + all-time).
+- A 30-day month.
+- 2 rows written per *writing* submission per window — the entry row and the rank index — measured, not assumed (see below). The published table assumes every submission writes; the default guarded board writes only for the minority that improve.
+- A live rank check scans half the board (the average mid-table player).
+- ~100 bytes per row.
+
+## What is cited and what is ours
+
+**Cloudflare's, cited:** the unit prices (rows read 25B/mo included then $0.001/M; rows written 50M/mo then $1.00/M; storage 5 GB then $0.75/GB-mo), that billing counts rows *scanned* rather than returned, that D1 is single-threaded, and the 10 GB per-database cap.
+
+**Ours, inferred — do not quote these as Cloudflare figures:**
+
+- The half-board scan depth for a live rank check, the submission/check rates, and the window count.
+- The **~200 upserts/sec ceiling**. Cloudflare publishes **no** writes/sec ceiling. This is our arithmetic on "several milliseconds" per write against a single thread.
+- The **improve rate** — how many submissions actually beat a player's best and therefore write. The table's worst case assumes 100%; a real board is far lower. The *per-write* cost, by contrast, is measured against D1's own `meta.rows_written` (2 rows for a writing submission, 0 for a guarded no-op), not inferred.
+
+Cloudflare also publishes **no cap on rows read**, which is worth sitting with: an un-materialized rank query on a large board runs the bill up without ever erroring. Nothing fails. The invoice just arrives.
+
+Cloudflare documents **no rank-materialization pattern** either. The chunked refresh in this package is entirely adopter-built engineering — which is precisely why it is in the package instead of in your repo.
+
+## A note on window functions
+
+`RANK() OVER` and `ROW_NUMBER() OVER` are **undocumented** on D1: Cloudflare's SQL reference neither supports nor denies them.
+
+We probed it. Both execute under Miniflare's local D1. But Miniflare also rejects `sqlite_version()` with `not authorized to use function`, which proves D1 runs a function authorizer whose production allowlist is not visible from local — so a local pass is not evidence about production.
+
+Ranking therefore does **not** use window functions. It uses `COUNT(*)` with an explicit predicate and a total ordering, which is documented SQL everywhere it runs. `src/rank/plan.workers.test.ts` reads D1's own `EXPLAIN QUERY PLAN` to prove the ranking index is actually chosen, because an index that silently stops being used is a cost regression, not a test failure — the answer stays right and the bill goes up.
+
+## This page will drift
+
+Re-run the model on each release: `bun run --filter @pithy-sh/leaderboard costs`. The arithmetic is committed as a script (`scripts/costModel.ts`), not hand-maths in this prose, and `scripts/costModel.test.ts` pins every figure above. If a price or an assumption moves, those tests fail — and this page is wrong until both are updated together.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pithy-sh/leaderboard",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/leaderboard"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "docs",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "costs": "bun scripts/costModel.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "croner": "^10.0.1",
+    "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,36 @@
+{
+  "name": "leaderboard",
+  "package": "@pithy-sh/leaderboard",
+  "requiredBindings": [{ "type": "d1", "name": "DB" }],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth"],
+  "migrationNamespace": "leaderboard",
+  "whenToEnable": "Rank your players. Submit a score, read the standings, read your own rank — daily, weekly, calendar-month, calendar-year, or all-time, because a board's window is a CRON expression rather than a fixed list. Boards are config, not database rows. Everything lives in your own D1: closed windows stay for as many windows as you ask for, in plain SQL you can join against your own tables — no platform SDK offers either. One board serves iOS, Android, and web, which is why writes are server-authoritative by default: submissions need the board's submit scope, so a player's device cannot post a score it invented. Entries bind to an authenticated user, so add auth too — without it every route is denied. Read docs/costs.md before you pick a `rank` mode: live rank is correct and free under ~10k players and grows quadratically after that.",
+  "scaffold": [
+    "Add a `leaderboard({ boards: [...] })` block to pithy.config.ts and define at least one board.",
+    "Give each board a `key`, a `direction` (`desc` = highest wins, `asc` = lowest wins), and optionally a `window` CRON (`0 0 * * *` daily, `0 0 1 * *` calendar month). Omit `window` for an all-time board.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_leaderboard_entries and pithy_leaderboard_boards.",
+    "Add `@pithy-sh/auth` if it is not already installed. Leaderboard entries bind to an authenticated user; without auth every route is denied.",
+    "Mint a token carrying the `leaderboard:submit` scope for your trusted server, and submit scores with it. Never put that scope on a player's token.",
+    "Deploy the rank worker (a cron-triggered Workflow) if `rank` is `{ materialize }` or any board sets `retain`/`retainDays`. It can be its own worker or folded into your app worker — it just needs a cron trigger. A live board set that keeps everything (the default) needs no worker.",
+    "Read packages/leaderboard/docs/costs.md before going to production. The `rank` mode you pick at 1k players decides whether 1M costs $1,030 or $75,825."
+  ],
+  "configOptions": [
+    {
+      "key": "boards",
+      "default": [{ "key": "high-scores", "direction": "desc" }],
+      "describe": "Every board this app ranks. Replace this example — an all-time board where the highest score wins, which is the smallest board that works and the one shape that needs no rank worker at all. `key` is a URL path segment; `direction` is `desc` (highest wins) or `asc` (lowest wins) and is immutable once entries land, because flipping it would reinterpret every stored score. Add a `window` CRON (`0 0 * * *` daily, `0 0 1 * *` calendar month) to make the board periodic. At least one board is required."
+    },
+    {
+      "key": "rank",
+      "default": "live",
+      "describe": "How rank is computed: `live` (default — counted per request, always correct, $0 under ~10k players, quadratic past that) or `{ materialize: '<cron>' }` (a stored rank column refreshed on a schedule, the documented path past ~100k players). A player's own score stays live in both modes, which hides most of the staleness."
+    },
+    {
+      "key": "serverAuthoritative",
+      "default": true,
+      "describe": "Require the `leaderboard:submit` scope to post a score. On by default, inverting the vendor norm — every platform that offers server-authoritative writes ships it off. Turn it off only if you accept that a player's device can post any score it likes."
+    }
+  ]
+}

package/src/board/registry.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LeaderboardBoard } from "../config/config";
+import { LeaderboardBoardRecord } from "../data/boardRecord";
+import { LEADERBOARD_BOARDS_TABLE, type LeaderboardDatabase } from "../data/tables";
+import { LeaderboardBoardImmutableError } from "../error/errors";
+
+/**
+ * The board drift guard.
+ *
+ * `store`, `direction`, `aggregation`, and `window` are create-time and immutable on every vendor
+ * surveyed, and for good reason: each one is the lens through which stored scores are read, so changing
+ * one reinterprets data rather than reconfiguring behavior. Flip `direction` and last place becomes
+ * first. Switch `best` to `sum` and the number in the column stops meaning what it meant. Change `window`
+ * and new scores key into windows that do not line up with the stored ones. Move a board to a different
+ * `store` and its scores live in a different place entirely.
+ *
+ * Pithy cannot enforce that in the type system, because a board is config the adopter edits freely and
+ * redeploys. So the first entry on a board records those fields, and every later write checks against the
+ * record. The failure is loud and immediate instead of a silently corrupted board.
+ *
+ * This is the answer to the issue's open question: a board definition is *not* migratable. There is no
+ * `pithy migrate` story for a board, because there is no safe automatic reinterpretation of the scores
+ * already stored. Changing one of these fields means a new board key.
+ */
+export async function assertBoardDefinition(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  now: Date,
+): Promise<void> {
+  let recorded = await db
+    .selectFrom(LEADERBOARD_BOARDS_TABLE)
+    .selectAll()
+    .where("boardKey", "=", board.key)
+    .executeTakeFirst();
+
+  if (!recorded) {
+    const row = LeaderboardBoardRecord.encode({
+      id: 0,
+      boardKey: board.key,
+      store: board.store,
+      direction: board.direction,
+      aggregation: board.aggregation,
+      window: board.window ?? null,
+      createdAt: now,
+    }) as Record<string, unknown>;
+    delete row.id;
+    // `OR IGNORE`, not a plain insert: two first-ever submissions can race here, and losing that race is
+    // not an error on its own — but the winner may have recorded a *different* definition (a config
+    // change to an immutable field landed between the two requests, mid-deploy). So we do not return on
+    // the insert; we re-read the row that actually won and fall through to the drift check below. That
+    // closes the window where a divergent first submission would otherwise skip the guard entirely.
+    await db
+      .insertInto(LEADERBOARD_BOARDS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: the encoded row is the schema's `z.input` side.
+      .values(row as any)
+      .onConflict((oc) => oc.column("boardKey").doNothing())
+      .execute();
+    recorded = await db
+      .selectFrom(LEADERBOARD_BOARDS_TABLE)
+      .selectAll()
+      .where("boardKey", "=", board.key)
+      .executeTakeFirst();
+    if (!recorded) {
+      // The row we just inserted-or-ignored is gone — only possible if retention or an admin deleted the
+      // whole board between the insert and this read. Treat it as transient rather than corrupting data.
+      throw new LeaderboardBoardImmutableError({
+        message: "That board's definition could not be confirmed. Retry.",
+        detail: `Board "${board.key}" record vanished immediately after insert; a concurrent delete is the likely cause.`,
+      });
+    }
+  }
+
+  const previous = LeaderboardBoardRecord.parse(recorded);
+  const drifted: string[] = [];
+  if (previous.store !== board.store) {
+    drifted.push(`store ${previous.store} → ${board.store}`);
+  }
+  if (previous.direction !== board.direction) {
+    drifted.push(`direction ${previous.direction} → ${board.direction}`);
+  }
+  if (previous.aggregation !== board.aggregation) {
+    drifted.push(`aggregation ${previous.aggregation} → ${board.aggregation}`);
+  }
+  if ((previous.window ?? null) !== (board.window ?? null)) {
+    drifted.push(`window ${previous.window ?? "all-time"} → ${board.window ?? "all-time"}`);
+  }
+  if (drifted.length > 0) {
+    throw new LeaderboardBoardImmutableError({
+      detail: `Board "${board.key}" changed after recording entries: ${drifted.join(", ")}.`,
+    });
+  }
+}

package/src/capability.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { Migration } from "kysely/migration";
+import { LeaderboardConfig, type LeaderboardConfigInput, materializeSchedule } from "./config/config";
+import { leaderboardTables } from "./data/tables";
+import { registerLeaderboardRoutes } from "./http/routes";
+import { leaderboard_0001_entries } from "./migrations/0001_entries";
+import { leaderboardExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * Where leaderboard's migrations sort in the app database. Unique per database; the registry composes
+ * keys like `0400_leaderboard_0001_entries`. Sits after media (300) and audit (250).
+ */
+export const LEADERBOARD_MIGRATION_ORDER = 400;
+
+export type LeaderboardOptions = LeaderboardConfigInput & {
+  /** Mount the routes somewhere other than `/leaderboard`. */
+  basePath?: string;
+};
+
+export interface LeaderboardCapability extends Capability {
+  leaderboardConfig: LeaderboardConfig;
+}
+
+/**
+ * The leaderboard capability: submit a score, read the standings, read your own rank — across windows.
+ *
+ * Fully optional. Config, migrations, routes, and bindings arrive only on `pithy add leaderboard`, and
+ * `pithy remove leaderboard` is the clean inverse.
+ *
+ * One store, always: D1. There is no engine flag, because Durable Objects do not fix what a leaderboard
+ * actually strains against. A DO bills rows exactly as D1 does, so a rank scan inside one costs the same;
+ * it adds request and duration billing D1 does not have; and each object is single-threaded with a soft
+ * 1,000 req/s ceiling and the same 10 GB cap, so it does not relieve hot-board serialization either.
+ * Scale is a cadence dial (`rank: { materialize }`), which is pure D1. A DO earns its place only when
+ * `live: true` ships — as a WebSocket push layer *over* D1, which is a latency play, not a store.
+ *
+ * `dependsOn` is deliberately empty. Auth is not a peer capability but a seam: the routes read
+ * `c.var.auth` through core's `AuthContext`, so without `@pithy-sh/auth` installed every route is denied
+ * rather than open. That is the right failure and it needs no dependency edge.
+ */
+export function leaderboard(options: LeaderboardOptions = { boards: [] }): LeaderboardCapability {
+  const { basePath, ...configInput } = options;
+  // Parses the board set, and validates every CRON at assembly — a typo fails on deploy, not on the
+  // first submission at 3am.
+  const resolved = LeaderboardConfig.parse(configInput);
+
+  const migrations: Record<string, Migration> = { "0001_entries": leaderboard_0001_entries };
+
+  const requiredBindings: BindingSpecInput[] = [{ type: "d1", name: "DB" }];
+
+  const capability = defineCapability({
+    name: "leaderboard",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    requiredBindings,
+    config: LeaderboardConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: leaderboardTables(),
+        migrationOrder: LEADERBOARD_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    routes: registerLeaderboardRoutes({ config: resolved, basePath }),
+    seeds: [leaderboardExampleSeed],
+  });
+
+  return Object.assign(capability, { leaderboardConfig: resolved });
+}
+
+export function isLeaderboardCapability(capability: Capability): capability is LeaderboardCapability {
+  return capability.name === "leaderboard" && "leaderboardConfig" in capability;
+}
+
+/**
+ * Whether this configuration needs the rank worker deployed.
+ *
+ * Two things need it: materialized rank (the refresh), and configured retention (the prune). Retention
+ * now defaults to keep-all, so a windowed board only needs the worker if it actually sets `retain` or
+ * `retainDays` — a board that keeps everything has nothing to prune. A live, keep-all board set needs no
+ * worker at all.
+ */
+export function needsRankWorker(config: LeaderboardConfig): boolean {
+  if (materializeSchedule(config) !== undefined) return true;
+  return config.boards.some((board) => board.retain !== undefined || board.retainDays !== undefined);
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the app `DB` database the `pithy_leaderboard_*` tables live in.
+// `cloudflare:test` types its `env` as `Cloudflare.Env`, so test bindings are declared by augmenting
+// that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+  }
+}

package/src/config/boardKey.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The board-key pattern, in the one module that has no reason to import anything (#430).
+ *
+ * Both `config/config.ts` and `http/schemas.ts` constrain a board key with this regex, and the schema
+ * used to take it from the config module. That module validates a board's cron window through
+ * `window/schedule.ts`, which imports `croner` — so a request schema, which a management client compiles
+ * in a browser to build a call, was dragging a cron parser in to spell one regex. `croner` runs in a
+ * browser perfectly well, and that is exactly why widening the allowlist would have been the wrong fix:
+ * the rule is what a browser build may reach, not what it can survive.
+ *
+ * A board key is a URL path segment (`/leaderboard/<key>/top`), so it is kebab-case and lowercase.
+ */
+export const BOARD_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;