@pithy-sh/leaderboard 0.1.0

package/src/rank/query.ts

@@ -0,0 +1,208 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { boundParameterBudget, MAX_BOUND_PARAMETERS } from "@pithy-sh/core/src/data/boundParameters";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { type Expression, type SqlBool, sql } from "kysely";
+import type { LeaderboardBoard } from "../config/config";
+import { LeaderboardEntry } from "../data/entry";
+import { LEADERBOARD_ENTRIES_TABLE, type LeaderboardDatabase } from "../data/tables";
+import { MAX_SEGMENT_SIZE, SEGMENT_FIXED_PARAMETERS } from "./segment";
+import { classifyTier } from "./tiers";
+
+/**
+ * Ranked reads: top-N, my-rank, and around-me.
+ *
+ * Two things shape every query here.
+ *
+ * **No window functions.** `RANK() OVER` and `ROW_NUMBER() OVER` are undocumented on D1 — Cloudflare's
+ * SQL reference neither supports nor denies them. They do execute under Miniflare, 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. A local pass is therefore not evidence
+ * about production, so ranking is built on plain `COUNT(*)` and `ORDER BY` instead. See docs/costs.md.
+ *
+ * **The ordering is total.** Score, then earliest `achievedAt`, then `userId`. Because no two entries can
+ * tie, a rank is exactly "how many entries beat you, plus one" — so dense-vs-competition ranking never
+ * arises and neither is implemented. It also means a top-N page can number its own rows from the offset
+ * rather than asking the database to rank them.
+ */
+
+/**
+ * The members a segment query may bind, or a refusal naming the cap.
+ *
+ * The HTTP boundary refuses an oversized segment already, which is why this was never a live defect —
+ * and is exactly why it is worth fixing anyway. `topEntries` and `rankOf` are exported: an adopter
+ * calling them directly got no such refusal, and a 120-friend segment reached D1 with 124 parameters.
+ * A rule enforced at one of several entrances is not enforced (#250).
+ *
+ * A refusal rather than a silent truncation: a segment is a *set of people*, and quietly ranking 80 of
+ * somebody's 120 friends would be a wrong answer presented as a right one.
+ */
+function segmentMembers(segment: readonly string[]): string[] {
+  if (segment.length > Math.min(MAX_SEGMENT_SIZE, boundParameterBudget(SEGMENT_FIXED_PARAMETERS))) {
+    throw new ValidationError({
+      message: `A segment is capped at ${MAX_SEGMENT_SIZE} players.`,
+      action: `Rank at most ${MAX_SEGMENT_SIZE} players at a time.`,
+      detail: `A segment of ${segment.length} exceeds the cap of ${MAX_SEGMENT_SIZE}; D1 accepts ${MAX_BOUND_PARAMETERS} bound parameters and a segment query spends ${SEGMENT_FIXED_PARAMETERS} of them before a single member.`,
+    });
+  }
+  return [...segment];
+}
+
+export interface RankedEntry {
+  userId: string;
+  score: number;
+  achievedAt: Date;
+  rank: number;
+  tier: string | null;
+}
+
+export interface ReadOptions {
+  /** Restrict the board to these players — a friends or cohort view over the same store, not a second board. */
+  segment?: readonly string[];
+}
+
+/**
+ * "Strictly better than this entry", in the board's direction.
+ *
+ * Spelled out as an OR-of-ANDs rather than a row-value comparison (`(score, achieved_at) > (?, ?)`)
+ * because the sort directions are mixed — score descends while achievedAt ascends — and SQLite's
+ * row-value shortcut only applies when every key sorts the same way.
+ */
+function betterThan(board: LeaderboardBoard, score: number, achievedAt: number, userId: string): Expression<SqlBool> {
+  const scoreBeats = board.direction === "desc" ? sql<SqlBool>`score > ${score}` : sql<SqlBool>`score < ${score}`;
+  return sql<SqlBool>`(
+    ${scoreBeats}
+    OR (score = ${score} AND achieved_at < ${achievedAt})
+    OR (score = ${score} AND achieved_at = ${achievedAt} AND user_id < ${userId})
+  )`;
+}
+
+function decorate(board: LeaderboardBoard, entry: LeaderboardEntry, rank: number): RankedEntry {
+  return {
+    userId: entry.userId,
+    score: entry.score,
+    achievedAt: entry.achievedAt,
+    rank,
+    tier: classifyTier(board.tiers, board.direction, entry.score),
+  };
+}
+
+/**
+ * A page of the board, best first. Ranks are numbered from the offset: the ordering is total, so row
+ * `n` of an offset page is rank `offset + n + 1` by construction — no count, no window function.
+ */
+export async function topEntries(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  limit: number,
+  offset = 0,
+  options: ReadOptions = {},
+): Promise<RankedEntry[]> {
+  let query = db
+    .selectFrom(LEADERBOARD_ENTRIES_TABLE)
+    .selectAll()
+    .where("boardId", "=", board.key)
+    .where("windowKey", "=", windowKey)
+    // Only entries the player consented to show and a moderator has not hidden are ever ranked.
+    .where("visible", "=", 1)
+    .where("hidden", "=", 0);
+  if (options.segment) {
+    if (options.segment.length === 0) return [];
+    query = query.where("userId", "in", segmentMembers(options.segment));
+  }
+  const rows = await query
+    .orderBy("score", board.direction === "desc" ? "desc" : "asc")
+    .orderBy("achievedAt", "asc")
+    .orderBy("userId", "asc")
+    .limit(limit)
+    .offset(offset)
+    .execute();
+  return rows.map((row, index) => decorate(board, LeaderboardEntry.parse(row), offset + index + 1));
+}
+
+/**
+ * The player's own rank, or null if they have no visible entry.
+ *
+ * When `materialized` is set the stored rank column is read — one indexed point read, and the reason
+ * `rank: { materialize }` exists. Otherwise the rank is counted live: correct always, free under ~10k
+ * players, and O(rank position) in billed rows because D1 bills rows *scanned*, not returned. A stale
+ * materialized rank is deliberate; the player's own score beside it is always live.
+ */
+export async function rankOf(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  userId: string,
+  materialized: boolean,
+  options: ReadOptions = {},
+): Promise<{ entry: LeaderboardEntry; rank: number | null; tier: string | null } | null> {
+  const row = await db
+    .selectFrom(LEADERBOARD_ENTRIES_TABLE)
+    .selectAll()
+    .where("boardId", "=", board.key)
+    .where("windowKey", "=", windowKey)
+    .where("userId", "=", userId)
+    .executeTakeFirst();
+  if (!row) return null;
+  const entry = LeaderboardEntry.parse(row);
+  const tier = classifyTier(board.tiers, board.direction, entry.score);
+  // A hidden or unconsented entry is not on the board, so it has no rank — but the player still gets
+  // their own score back, which is why this is a null rank rather than a 404.
+  if (!entry.visible || entry.hidden) return { entry, rank: null, tier };
+  // A segment view has no meaningful materialized rank: the stored column ranks the whole board.
+  if (materialized && !options.segment) return { entry, rank: entry.rank ?? null, tier };
+  if (options.segment?.length === 0) return { entry, rank: null, tier };
+
+  const counted = await rankCountQuery(db, board, windowKey, entry, options).executeTakeFirst();
+  return { entry, rank: Number(counted?.better ?? 0) + 1, tier };
+}
+
+/**
+ * The live-rank count: how many visible entries beat this one. Exported so `plan.workers.test.ts` can
+ * compile the real query and read D1's own `EXPLAIN QUERY PLAN` for it — a plan test that hand-wrote the
+ * SQL would only prove that the hand-written SQL is indexed.
+ */
+export function rankCountQuery(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  entry: Pick<LeaderboardEntry, "score" | "achievedAt" | "userId">,
+  options: ReadOptions = {},
+) {
+  let query = db
+    .selectFrom(LEADERBOARD_ENTRIES_TABLE)
+    .select(({ fn }) => fn.countAll<number>().as("better"))
+    .where("boardId", "=", board.key)
+    .where("windowKey", "=", windowKey)
+    // Only entries the player consented to show and a moderator has not hidden are ever ranked.
+    .where("visible", "=", 1)
+    .where("hidden", "=", 0);
+  if (options.segment && options.segment.length > 0) {
+    query = query.where("userId", "in", segmentMembers(options.segment));
+  }
+  return query.where(betterThan(board, entry.score, entry.achievedAt.getTime(), entry.userId));
+}
+
+/**
+ * The slice of the board centered on a player: `radius` entries either side of them.
+ *
+ * Built on the total ordering — find the player's rank, then page the board around it — so it needs no
+ * second index and no window function. Rank is always counted live here even when the board is
+ * materialized: an "around me" page whose neighbors came from a stale rank column would show players
+ * who are no longer next to you.
+ */
+export async function entriesAround(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  userId: string,
+  radius: number,
+  options: ReadOptions = {},
+): Promise<RankedEntry[]> {
+  const own = await rankOf(db, board, windowKey, userId, false, options);
+  if (!own || own.rank === null) return [];
+  const offset = Math.max(0, own.rank - radius - 1);
+  return topEntries(db, board, windowKey, radius * 2 + 1, offset, options);
+}

package/src/rank/retryPolicy.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What the rank refresh retries, and what it refuses to.**
+ *
+ * The answer is short because the refresh's world is: every step it runs — the journalled context, the
+ * prune, and one keyset page of ranking per step — talks to D1 and to nothing else. There is no
+ * provider, no bucket, no model, no second account. So there is no `leaderboard/*` code this pass can
+ * usefully re-drive, and the record is empty on purpose (pithy-sh/pithy#348).
+ *
+ * **An empty record is a statement, not an omission.** Core still answers for D1 through `withD1Retry`'s
+ * vocabulary — busy, timed out, connection lost, storage reset, internal — so a database under
+ * contention is re-driven with the step's much longer backoff, and nothing about that is restated here:
+ * one D1 vocabulary, in core, or the two drift. What the empty record adds is the other half — that
+ * leaderboard has looked at its own codes and retries none of them.
+ *
+ * ## Terminal, and why
+ *
+ * - **`leaderboard/invalid_schedule`** — a board's window CRON will not parse. It is config, it is
+ *   identical on the next attempt, and it wants the adopter to edit `pithy.config.ts`.
+ * - **`validation/invalid_input`** — a board whose keyset cursor or rank shape the materializer refuses.
+ *   Deterministic in the row it read.
+ * - **`leaderboard/board_not_found`, `leaderboard/board_immutable`** and the rest of the submit-path
+ *   codes. They belong to a request; a refresh that somehow raised one has found a bug, and a bug
+ *   surfaces faster than it backs off.
+ *
+ * **The cron is the outer retry, and that is why terminal is cheap here.** A refresh fires on a
+ * schedule, takes an advisory lock, and re-ranks from the top; a run that fails releases its lock in a
+ * `finally` and the next fire does the whole job again. So a fault that stops one run costs one
+ * interval, where five platform attempts against an answer that cannot change cost the interval *and*
+ * hold the lock through it — which is the one thing that makes the next fire skip too.
+ */
+export const leaderboardWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "leaderboard",
+  retryable: {},
+};

package/src/rank/segment.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The segment cap, in the one module that has no reason to import anything (#430).
+ *
+ * `http/schemas.ts` states the same bound a caller is refused by, so it needs this number — and it used
+ * to reach it through `rank/query.ts`, which builds the SQL and therefore pulls Kysely, `kysely-d1` and
+ * `@cloudflare/workers-types` behind it. A request schema is a client's business: a management client
+ * building a call must be able to compile the shape it may send, in a browser, with no Worker types in
+ * reach. So the number moved and the query kept the query.
+ *
+ * **The relationship this number only means something against lives elsewhere, on purpose.**
+ * `boundParameterBudget` is in `@pithy-sh/core/src/data/boundParameters`, which imports `D1Database` for
+ * the guard beside it, so importing it here would put the data layer back under a browser program by a
+ * shorter route. `rank/query.workers.test.ts` asserts `MAX_SEGMENT_SIZE <=
+ * boundParameterBudget(SEGMENT_FIXED_PARAMETERS)` where the budget is already in scope, and that
+ * assertion is what ties these two constants to D1's ceiling. Moving them without it detaches the cap
+ * from the limit it exists for, which is #250 with no symptom until real data arrives.
+ */
+
+/**
+ * What a segment query binds besides the members: 4 filters (boardId, windowKey, visible, hidden) plus
+ * the 6 of `betterThan` (score twice, achieved_at twice, score and userId again). `rankOf` within a
+ * segment is the tightest path, so its overhead is the one that sets the cap.
+ */
+export const SEGMENT_FIXED_PARAMETERS = 10;
+
+/**
+ * Cap on a segment's member count.
+ *
+ * `boundParameterBudget(SEGMENT_FIXED_PARAMETERS)` is 90 — the most D1 would take. 80 is deliberately
+ * inside it, so that adding one more filter to a segment query is a change to `rank/query.ts` rather
+ * than a change to what every caller may pass. `segmentMembers` asserts the relationship rather than
+ * trusting it, and `boundParameters.test.ts` in core owns the arithmetic itself.
+ */
+export const MAX_SEGMENT_SIZE = 80;

package/src/rank/tiers.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LeaderboardTier, ScoreDirection } from "../config/config";
+
+/**
+ * Classify a score into one of the board's tiers, or null if it reaches none.
+ *
+ * Tiers are a read-side classification over the score already stored — no tier column, no write-side
+ * cost, and no second board type. Config validates that tiers are listed worst to best in the board's
+ * direction, so the last one the score qualifies for is the best one it qualifies for.
+ *
+ * This is not the bucketed-cohort model (Duolingo leagues, Clash Royale arenas), which needs durable
+ * per-window cohort assignment and provably cannot be a view over a global board. That is deferred.
+ */
+export function classifyTier(
+  tiers: readonly LeaderboardTier[] | undefined,
+  direction: ScoreDirection,
+  score: number,
+): string | null {
+  if (!tiers || tiers.length === 0) return null;
+  let reached: string | null = null;
+  for (const tier of tiers) {
+    const qualifies = direction === "desc" ? score >= tier.from : score <= tier.from;
+    if (!qualifies) break;
+    reached = tier.key;
+  }
+  return reached;
+}

package/src/rank/worker.entry.ts

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import type { D1Database } from "@cloudflare/workers-types";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { LeaderboardConfig } from "../config/config";
+import { leaderboardDatabase } from "../data/tables";
+import { pruneBoards } from "../retention/prune";
+import { windowKeyAt } from "../window/schedule";
+import { acquireRefreshLock, releaseRefreshLock } from "./lock";
+import { type Keyset, REFRESH_BATCH_CHUNKS, type RefreshResult, refreshWindowRanks } from "./materialize";
+import { leaderboardWorkflowRetry } from "./retryPolicy";
+import { materializedBoards } from "./worker";
+
+/**
+ * The leaderboard rank refresh, as a cron-triggered Cloudflare Workflow.
+ *
+ * Why a Workflow rather than a plain `scheduled()` pass: a Worker invocation is wall-clock bounded, so
+ * an earlier design capped each run at ~64k entries and re-ranked from the top every tick — a board
+ * bigger than that never fully ranked. A Workflow step has unlimited wall-clock and does not burn CPU
+ * while awaiting D1 (all our work is D1 I/O), so a board of any size ranks across a series of bounded,
+ * individually-durable steps. Each step checkpoints the keyset cursor; a crash resumes from the last
+ * completed step instead of restarting. The 64k ceiling is gone.
+ *
+ * At-most-one at a time: a refresh takes a D1 advisory lock before it starts and releases it when done.
+ * If a cron fires again while a refresh is still running (a cron faster than the refresh takes), the
+ * second instance cannot take the lock and skips — so two passes never interleave their chunked writes
+ * into an incoherent rank set. A crashed instance's lock ages out (see `lock.ts`) so the next fire
+ * reclaims it.
+ *
+ * Why it does NOT require a dedicated worker: this is a Workflow class plus a `scheduled()` handler plus
+ * one cron trigger. `pithy add leaderboard` deploys it as its own small worker by default (the template
+ * in `wrangler.jsonc`), but the same three pieces can be merged into the adopter's app worker — the
+ * capability contributes the Workflow through its manifest. A cron trigger is the one hard requirement;
+ * a separate worker is not.
+ *
+ * Cost: on Workers Paid this stays inside the free allowances at any realistic cadence — a run is a
+ * handful of steps (one prune + a few per board), storage is zero (all state is D1), and idle/awaiting
+ * steps incur no CPU. Even firing every minute is well under the 500k-steps/month and 10M-requests/month
+ * included tiers.
+ */
+
+interface RankWorkerEnv {
+  DB: D1Database;
+  /** The resolved leaderboard config, as JSON. The board set is config; this worker needs the same one. */
+  LEADERBOARD_CONFIG: string;
+  /** Optional override for how long a held refresh lock stays valid before it is reclaimed (see lock.ts). */
+  LEADERBOARD_LOCK_STALE_MS?: string;
+  /** The Workflow binding — this worker's own class, used by `scheduled()` to start an instance. */
+  RANK_REFRESH: { create(options?: { id?: string }): Promise<unknown> };
+}
+
+export class RankRefreshWorkflow extends WorkflowEntrypoint<RankWorkerEnv, unknown> {
+  override async run(_event: WorkflowEvent<unknown>, step: WorkflowStep): Promise<void> {
+    // Every step below runs under `leaderboardWorkflowRetry`. Its record is empty and that is the whole
+    // statement: this refresh talks to D1 and to nothing else, core answers for D1's transient
+    // vocabulary, and leaderboard retries none of its own codes. See `retryPolicy.ts` — and note that
+    // terminal is cheap here precisely because the lock is released in the `finally` below, so the next
+    // cron fire does the whole job rather than skipping on a lock a doomed run was still holding.
+    const steps = classifiedSteps(step, leaderboardWorkflowRetry, NonRetryableError);
+    const config = LeaderboardConfig.parse(JSON.parse(this.env.LEADERBOARD_CONFIG));
+    const db = leaderboardDatabase(this.env.DB);
+    const staleMs = this.env.LEADERBOARD_LOCK_STALE_MS ? Number(this.env.LEADERBOARD_LOCK_STALE_MS) : undefined;
+
+    // Mint this instance's identity and its clock ONCE, in a memoized step, and read them from the step's
+    // return value. A replay does not re-run the step body, so it reuses the same holder token and the
+    // same `now` — recomputing `now` could cross a window boundary mid-refresh, and a fresh token would
+    // orphan the lock.
+    const ctx: { holder: string; nowMs: number } = await steps.do("refresh-context", async () => ({
+      holder: crypto.randomUUID(),
+      nowMs: Date.now(),
+    }));
+    const now = new Date(ctx.nowMs);
+
+    // Acquire and release run OUTSIDE steps, deliberately — the one place this file does side effects
+    // outside a step. Both are idempotent D1 ops, and re-running them on every replay is exactly what
+    // keeps the lock state honest: acquire re-validates against live D1 (an instance whose stale lock was
+    // reclaimed while it was interrupted re-checks, sees the lock is no longer its own, and stands down,
+    // instead of resuming on a memoized "acquired" and writing concurrently); release re-converges the
+    // same way. A memoized acquire/release step would instead freeze a stale decision across the replay.
+    if (!(await acquireRefreshLock(db, ctx.holder, now, staleMs))) return;
+
+    try {
+      // Prune first, in its own durable step, so the refresh never ranks rows about to be deleted.
+      await steps.do("prune", () => pruneBoards(db, config.boards, now));
+
+      for (const board of materializedBoards(config)) {
+        // Only the open window is refreshed; a closed window's ranks were finalized while it was open.
+        const window = windowKeyAt(board.window, now);
+        let cursor: Keyset | null = null;
+        let startRank = 0;
+        let batch = 0;
+        // One step per batch of ~64k entries, threading the cursor. A board of any size completes across
+        // however many steps it needs; each is independently retried by the Workflow runtime.
+        for (;;) {
+          const from: Keyset | undefined = cursor ?? undefined;
+          const result: RefreshResult = await steps.do(`refresh:${board.key}:${batch}`, () =>
+            refreshWindowRanks(db, board, window, {
+              maxChunks: REFRESH_BATCH_CHUNKS,
+              resumeAfter: from,
+              startRank,
+            }),
+          );
+          if (result.complete) break;
+          cursor = result.cursor;
+          startRank = result.ranked;
+          batch += 1;
+          // A batch that stopped without a cursor cannot resume — bail rather than loop forever.
+          if (!cursor) break;
+        }
+      }
+    } finally {
+      // Release even if a step threw, so a failure does not wedge the lock until it ages out. Outside a
+      // step (see the acquire note) so a replay re-releases rather than skipping a memoized release.
+      await releaseRefreshLock(db, ctx.holder);
+    }
+  }
+}
+
+export default {
+  /**
+   * Cron entry: start one rank-refresh Workflow instance per fire. Each instance re-ranks from the top;
+   * the checkpointing is within an instance (resume on crash), not across fires (a fire is a fresh full
+   * refresh). If a fire lands while a previous refresh is still running, the new instance takes no lock
+   * and exits immediately, so overlapping instances never write concurrently — see the lock acquisition
+   * in `run()` above.
+   */
+  async scheduled(_controller: unknown, env: RankWorkerEnv): Promise<void> {
+    await env.RANK_REFRESH.create();
+  },
+};

package/src/rank/worker.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { LeaderboardBoard, LeaderboardConfig } from "../config/config";
+import { materializeSchedule } from "../config/config";
+import { leaderboardDatabase } from "../data/tables";
+import { type PruneOutcome, pruneBoards } from "../retention/prune";
+import { windowKeyAt } from "../window/schedule";
+import { type RefreshResult, refreshWindowRanks } from "./materialize";
+
+/**
+ * The rank pass, in process: the retention sweep, then the rank refresh, each board ranked to completion.
+ *
+ * This is the reusable core the {@link RankRefreshWorkflow} drives step by step, and a standalone entry
+ * point for a caller who wants the whole pass in one call (tests, a simple scheduled handler). It runs
+ * every board to completion — there is no per-invocation chunk cap, so no board-size ceiling. The
+ * Workflow adds durability and per-board checkpointing on top of these same primitives; it does not need
+ * a different pass.
+ *
+ * Order matters. Pruning first means the refresh never spends a chunk ranking rows about to be deleted,
+ * and a board whose retention just dropped a window does not briefly publish ranks for it.
+ */
+/**
+ * One board's contribution to a rank pass: what the refresh did, or that it could not be done (#371).
+ *
+ * The state rides on the value. A board that threw is not a board that ranked nobody — `ranked: 0` is a
+ * real answer about an empty window — so the numbers live behind `refreshed` and a consumer reaches them
+ * only by narrowing. Forgetting the sick board is a type error rather than a zero on a dashboard.
+ */
+export type BoardRefresh =
+  | ({
+      /** This board's open window was ranked. */
+      state: "refreshed";
+      /** The board's key, as its config declares it. */
+      board: string;
+      /** The window key that was ranked. */
+      window: string;
+    } & RefreshResult)
+  | {
+      /** This board's refresh threw. Its ranks are whatever the previous pass left. */
+      state: "unavailable";
+      /** The board's key, as its config declares it. */
+      board: string;
+      /** The window key the pass was attempting. */
+      window: string;
+    };
+
+export interface RankPassResult {
+  /** What the retention sweep deleted, and whether it reached every board. */
+  pruned: PruneOutcome;
+  /** One entry per materialized board the refresh pass touched. Empty when rank is live. */
+  refreshed: BoardRefresh[];
+}
+
+/** The boards a refresh pass must rank: only materialized ones. Live boards compute rank per request. */
+export function materializedBoards(config: LeaderboardConfig): LeaderboardBoard[] {
+  return materializeSchedule(config) === undefined ? [] : config.boards;
+}
+
+/**
+ * **Every contributor here is degraded, and none of them is load-bearing (#371).**
+ *
+ * The sweep runs first so the refresh never spends a chunk ranking rows about to be deleted — an
+ * efficiency, not a precondition. A board whose prune throws keeps its old rows a while longer and ranks
+ * correctly regardless, so the sweep failing is no reason to leave every board's ranks stale. And boards
+ * are independent of each other by construction: one board's entries, windows and ranks are its own, so a
+ * board that will not rank has no claim on any other board's pass.
+ *
+ * So one sick board costs its own line. What it must never do is read as a board that ranked nobody.
+ */
+export async function runRankPass(d1: D1Database, config: LeaderboardConfig, now: Date): Promise<RankPassResult> {
+  const db = leaderboardDatabase(d1);
+  const pruned = await pruneBoards(db, config.boards, now);
+
+  const refreshed: BoardRefresh[] = [];
+  for (const board of materializedBoards(config)) {
+    // Only the open window is refreshed. A closed window's ranks stopped moving when it closed, so the
+    // pass that ran while it was open already left them final.
+    const window = windowKeyAt(board.window, now);
+    let result: RefreshResult;
+    try {
+      result = await refreshWindowRanks(db, board, window);
+    } catch {
+      // No binding. A refresh throws out of D1 with a query and an entry's identifiers in it, and this
+      // result is rendered wherever a caller renders it — so what survives is the board key and the
+      // window, both of which are the adopter's own configuration.
+      refreshed.push({ state: "unavailable", board: board.key, window });
+      continue;
+    }
+    refreshed.push({ state: "refreshed", board: board.key, window, ...result });
+  }
+  return { pruned, refreshed };
+}

package/src/rank/wrangler.jsonc

@@ -0,0 +1,53 @@
+{
+  // The leaderboard rank-refresh worker. This is a TEMPLATE, not a wrangler env-stanza file: `pithy add
+  // leaderboard` resolves it per environment — filling the `<...>` placeholders and the cron from the
+  // adopter's `rank: { materialize }` setting — and deploys each with its own config
+  // (`wrangler deploy --config <resolved>`). The adopter authors none of it.
+  //
+  // It does NOT have to be its own worker. What the refresh actually needs is three things: the
+  // `RankRefreshWorkflow` class, a `scheduled()` handler that starts an instance, and a cron trigger.
+  // This template deploys them as a small dedicated worker by default — simplest, and isolated from the
+  // request path — but the same three pieces can be folded into the adopter's app worker instead. A cron
+  // trigger is the one hard requirement; a separate worker is not.
+  //
+  // Why a Workflow rather than a plain scheduled pass: a Worker invocation is wall-clock bounded, which
+  // once capped the refresh at ~64k entries per run. A Workflow step has unlimited wall-clock and burns
+  // no CPU while awaiting D1, so a board of any size ranks across bounded, individually-durable steps
+  // that checkpoint a keyset cursor. See `worker.entry.ts`.
+  "name": "pithy-leaderboard-rank", // resolved per env → pithy-leaderboard-rank-staging / -production
+  "main": "./worker.entry.ts",
+  // The compatibility date every Worker in this repository runs on. Stated once in the repository
+  // root's `compatibility.ts` and copied here because JSONC cannot import it —
+  // `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // No public URL. This worker has no HTTP routes — it is reached only by its cron. `workers_dev: false`
+  // keeps it off workers.dev so nothing accidentally exposes a ranking rewrite to the internet.
+  "workers_dev": false,
+
+  // The app database. The same `DB` the routes write to — the rank column lives on the entries table, so
+  // there is no second store to keep in step.
+  "d1_databases": [
+    { "binding": "DB", "database_name": "<filled-at-provision>", "database_id": "<filled-at-provision>" }
+  ],
+
+  // The refresh Workflow this worker hosts and its own scheduled() handler starts.
+  "workflows": [{ "binding": "RANK_REFRESH", "name": "pithy-leaderboard-rank", "class_name": "RankRefreshWorkflow" }],
+
+  // The refresh cron. Resolved to the adopter's `rank: { materialize: <cron> }` schedule when set;
+  // otherwise hourly, which is only ever the retention sweep (one bounded DELETE per board that
+  // configures a limit — most keep everything, the default, and delete nothing).
+  "triggers": { "crons": ["<filled-at-provision>"] },
+
+  "vars": {
+    // The resolved leaderboard config, as JSON. The Workflow parses it back through `LeaderboardConfig`
+    // on each run — the board set is config, and this worker needs the same board set the routes have.
+    "LEADERBOARD_CONFIG": "<filled-at-provision>",
+    // Optional. How long a held refresh lock stays valid before a crashed instance's lock is reclaimed,
+    // in ms. Defaults to one hour — raise it only if a deployment refreshes boards that take longer than
+    // that (well past the ~1M-player shard boundary). See `rank/lock.ts`.
+    // "LEADERBOARD_LOCK_STALE_MS": "3600000",
+    "ENVIRONMENT": "<filled-at-provision>"
+  }
+}