@pithy-sh/leaderboard 0.1.2 → 0.1.4

package/dist/rank/materialize.js

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { sql } from "kysely";
+import { boundParameterBudget, chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+//#region src/rank/materialize.ts
+/**
+* The rank refresh pass — what `rank: { materialize }` buys and what it costs.
+*
+* A full-table rank rewrite is the obvious implementation and the wrong one. D1 executes one query at a
+* time per database and caps a query at 30 seconds; a single `UPDATE` over a large board would hold the
+* only thread for its whole duration and risk the documented `overloaded` error for every live
+* submission behind it. So the pass is chunked: many small, bounded statements the runtime can
+* interleave with real traffic.
+*
+* A chunk is a **pacing** unit: how much of the board one keyset step walks, kept well inside D1's
+* 30-second per-query limit. It is no longer also the width of a statement — the bulk update sizes
+* itself against D1's bound-parameter cap through core's arithmetic, so a chunk of any size is written
+* in as many statements as it takes. That separation is the fix for #250: `chunkSize` was unvalidated,
+* and `chunkSize: 40` bound 120 and broke the pass with no warning that a limit was even involved.
+*
+* Chunks walk the board by keyset, not by `OFFSET`: an offset page makes SQLite count past every row it
+* skips, so an offset walk is quadratic in billed rows — the very cost `materialize` exists to avoid.
+*
+* Cloudflare documents no rank-materialization pattern. All of this is adopter-built, which is exactly
+* why it lives in the package instead of in every adopter's repo.
+*/
+/**
+* What one ranked row costs the bulk update: `WHEN id`, `THEN rank`, and the id again in the `IN` list.
+*
+* The cap itself is not restated here. It was, and a second copy of a platform limit is how a limit goes
+* stale in one place and not the other — `MAX_BOUND_PARAMETERS` lives in `@pithy-sh/core`, once.
+*/
+const RANK_PARAMETERS_PER_ROW = 3;
+/**
+* Rows per chunk by default: as many as one update statement can carry, from core's budget.
+*
+* Derived rather than written out, so it moves if the platform does. Any other size works — the update
+* chunks itself — and this is simply the size at which a chunk is exactly one statement.
+*/
+const RANK_CHUNK_SIZE = Math.floor(boundParameterBudget(0) / 3);
+/**
+* Chunks a refresh ranks before it checkpoints its cursor. `2000 * 33` is ~66k entries per Workflow step.
+*
+* The batch cap is stated here rather than in `worker.entry.ts`, which is the module that passes it as
+* `maxChunks`. That module imports `cloudflare:workers`, so anything it exports is unreachable from a
+* plain Node process, and a constant that reads as ordinary is exactly how #172 and #180 happened twice:
+* a Node-side caller imports the number, gets workerd behind it, and the failure surfaces as
+* `Could not load pithy.config.ts` — naming the config rather than the import. A pure value belongs in a
+* pure module. `configEntrypoints.test.ts` is what holds that.
+*/
+const REFRESH_BATCH_CHUNKS = 2e3;
+/**
+* Narrow a selected `achievedAt` to its stored epoch.
+*
+* The column's decode-side input is a union (`number | string | Date`) so the codec stays
+* encode-compatible, but a chunk selects raw columns rather than parsing whole rows — D1 always hands
+* back the stored integer. This keeps the keyset arithmetic honest without paying to parse every row.
+*/
+function toEpoch(value) {
+	return value instanceof Date ? value.getTime() : Number(value);
+}
+/**
+* Recompute the stored rank for one board and window, best first.
+*
+* Ranks are positions in the total ordering, so a chunk needs no counting — the first chunk's first row
+* is rank 1 and every chunk continues the count. The pass is **resumable**: with no `maxChunks` it ranks
+* the whole board; with a `maxChunks` batch cap it ranks that many chunks, returns a `cursor`, and the
+* caller feeds the cursor (and `startRank: ranked`) back to continue. That is what lets a board of any
+* size be ranked across a series of bounded, individually-durable Workflow steps — there is no longer a
+* per-invocation ceiling on how many entries a board can have.
+*/
+async function refreshWindowRanks(db, board, windowKey, options = {}) {
+	const chunkSize = options.chunkSize ?? RANK_CHUNK_SIZE;
+	if (!Number.isInteger(chunkSize) || chunkSize < 1) throw new ValidationError({
+		message: "The rank refresh was asked for an impossible chunk size.",
+		action: "Pass a whole number of one or more, or omit chunkSize for the default.",
+		detail: `refreshWindowRanks received chunkSize=${chunkSize}; it must be a positive integer.`
+	});
+	const maxChunks = options.maxChunks ?? Number.POSITIVE_INFINITY;
+	const descending = board.direction === "desc";
+	let after = options.resumeAfter;
+	let ranked = options.startRank ?? 0;
+	let chunks = 0;
+	while (chunks < maxChunks) {
+		let query = db.selectFrom(LEADERBOARD_ENTRIES_TABLE).select([
+			"id",
+			"score",
+			"achievedAt",
+			"userId"
+		]).where("boardId", "=", board.key).where("windowKey", "=", windowKey).where("visible", "=", 1).where("hidden", "=", 0);
+		if (after) {
+			const scoreWorse = descending ? sql`score < ${after.score}` : sql`score > ${after.score}`;
+			query = query.where(sql`(
+          ${scoreWorse}
+          OR (score = ${after.score} AND achieved_at > ${after.achievedAt})
+          OR (score = ${after.score} AND achieved_at = ${after.achievedAt} AND user_id > ${after.userId})
+        )`);
+		}
+		const rows = await query.orderBy("score", descending ? "desc" : "asc").orderBy("achievedAt", "asc").orderBy("userId", "asc").limit(chunkSize).execute();
+		if (rows.length === 0) return {
+			ranked,
+			chunks,
+			complete: true,
+			cursor: null
+		};
+		let written = 0;
+		for (const group of chunkRowsByBoundParameters(rows, 3)) {
+			const base = ranked + written;
+			let cases = sql``;
+			group.forEach((row, index) => {
+				cases = sql`${cases} WHEN ${row.id} THEN ${base + index + 1}`;
+			});
+			await db.updateTable(LEADERBOARD_ENTRIES_TABLE).set({ rank: sql`CASE id ${cases} END` }).where("id", "in", group.map((row) => row.id)).execute();
+			written += group.length;
+		}
+		ranked += rows.length;
+		chunks += 1;
+		const last = rows[rows.length - 1];
+		if (!last) break;
+		after = {
+			score: last.score,
+			achievedAt: toEpoch(last.achievedAt),
+			userId: last.userId
+		};
+		if (rows.length < chunkSize) return {
+			ranked,
+			chunks,
+			complete: true,
+			cursor: null
+		};
+	}
+	return {
+		ranked,
+		chunks,
+		complete: false,
+		cursor: after ?? null
+	};
+}
+//#endregion
+export { RANK_CHUNK_SIZE, RANK_PARAMETERS_PER_ROW, REFRESH_BATCH_CHUNKS, refreshWindowRanks };

package/dist/rank/query.d.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { LeaderboardBoard } from "../config/config";
+import { LeaderboardEntry } from "../data/entry";
+import { type LeaderboardDatabase } from "../data/tables";
+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[];
+}
+/**
+ * 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 declare function topEntries(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, limit: number, offset?: number, options?: ReadOptions): Promise<RankedEntry[]>;
+/**
+ * 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 declare function rankOf(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, userId: string, materialized: boolean, options?: ReadOptions): Promise<{
+    entry: LeaderboardEntry;
+    rank: number | null;
+    tier: string | null;
+} | null>;
+/**
+ * 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 declare function rankCountQuery(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, entry: Pick<LeaderboardEntry, "score" | "achievedAt" | "userId">, options?: ReadOptions): import("kysely").SelectQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<import("../data/tables").LeaderboardTables>, "pithyLeaderboardEntries", {
+    better: number;
+}>;
+/**
+ * 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 declare function entriesAround(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, userId: string, radius: number, options?: ReadOptions): Promise<RankedEntry[]>;
+//# sourceMappingURL=query.d.ts.map

package/dist/rank/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/rank/query.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AA2CrF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,8GAA8G;IAC9G,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AA4BD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,SAAI,EACV,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,WAAW,EAAE,CAAC,CAqBxB;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CAoBvF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAC,EAChE,OAAO,GAAE,WAAgB;;GAc1B;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,WAAW,EAAE,CAAC,CAKxB"}

package/dist/rank/query.js

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardEntry } from "../data/entry.js";
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables.js";
+import "./segment.js";
+import { classifyTier } from "./tiers.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { sql } from "kysely";
+import { MAX_BOUND_PARAMETERS, boundParameterBudget } from "@pithy-sh/core/src/data/boundParameters";
+//#region src/rank/query.ts
+/**
+* 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) {
+	if (segment.length > Math.min(80, boundParameterBudget(10))) throw new ValidationError({
+		message: `A segment is capped at 80 players.`,
+		action: `Rank at most 80 players at a time.`,
+		detail: `A segment of ${segment.length} exceeds the cap of 80; D1 accepts ${MAX_BOUND_PARAMETERS} bound parameters and a segment query spends 10 of them before a single member.`
+	});
+	return [...segment];
+}
+/**
+* "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, score, achievedAt, userId) {
+	const scoreBeats = board.direction === "desc" ? sql`score > ${score}` : sql`score < ${score}`;
+	return sql`(
+    ${scoreBeats}
+    OR (score = ${score} AND achieved_at < ${achievedAt})
+    OR (score = ${score} AND achieved_at = ${achievedAt} AND user_id < ${userId})
+  )`;
+}
+function decorate(board, entry, rank) {
+	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.
+*/
+async function topEntries(db, board, windowKey, limit, offset = 0, options = {}) {
+	let query = db.selectFrom(LEADERBOARD_ENTRIES_TABLE).selectAll().where("boardId", "=", board.key).where("windowKey", "=", windowKey).where("visible", "=", 1).where("hidden", "=", 0);
+	if (options.segment) {
+		if (options.segment.length === 0) return [];
+		query = query.where("userId", "in", segmentMembers(options.segment));
+	}
+	return (await query.orderBy("score", board.direction === "desc" ? "desc" : "asc").orderBy("achievedAt", "asc").orderBy("userId", "asc").limit(limit).offset(offset).execute()).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.
+*/
+async function rankOf(db, board, windowKey, userId, materialized, options = {}) {
+	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);
+	if (!entry.visible || entry.hidden) return {
+		entry,
+		rank: null,
+		tier
+	};
+	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.
+*/
+function rankCountQuery(db, board, windowKey, entry, options = {}) {
+	let query = db.selectFrom(LEADERBOARD_ENTRIES_TABLE).select(({ fn }) => fn.countAll().as("better")).where("boardId", "=", board.key).where("windowKey", "=", windowKey).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.
+*/
+async function entriesAround(db, board, windowKey, userId, radius, options = {}) {
+	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);
+}
+//#endregion
+export { entriesAround, rankCountQuery, rankOf, topEntries };

package/dist/rank/retryPolicy.d.ts

@@ -0,0 +1,35 @@
+// 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 declare const leaderboardWorkflowRetry: WorkflowRetryPolicy;
+//# sourceMappingURL=retryPolicy.d.ts.map

package/dist/rank/retryPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryPolicy.d.ts","sourceRoot":"","sources":["../../src/rank/retryPolicy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBAGtC,CAAC"}

package/dist/rank/retryPolicy.js

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/rank/retryPolicy.ts
+/**
+* **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.
+*/
+const leaderboardWorkflowRetry = {
+	capability: "leaderboard",
+	retryable: {}
+};
+//#endregion
+export { leaderboardWorkflowRetry };

package/dist/rank/segment.d.ts

@@ -0,0 +1,35 @@
+// 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 declare 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 declare const MAX_SEGMENT_SIZE = 80;
+//# sourceMappingURL=segment.d.ts.map

package/dist/rank/segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment.d.ts","sourceRoot":"","sources":["../../src/rank/segment.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC"}

package/dist/rank/segment.js

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/rank/segment.ts
+/**
+* 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.
+*/
+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.
+*/
+const MAX_SEGMENT_SIZE = 80;
+//#endregion
+export { MAX_SEGMENT_SIZE, SEGMENT_FIXED_PARAMETERS };

package/dist/rank/tiers.d.ts

@@ -0,0 +1,15 @@
+// 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 declare function classifyTier(tiers: readonly LeaderboardTier[] | undefined, direction: ScoreDirection, score: number): string | null;
+//# sourceMappingURL=tiers.d.ts.map

package/dist/rank/tiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/rank/tiers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EAC7C,SAAS,EAAE,cAAc,EACzB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CASf"}

package/dist/rank/tiers.js

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/rank/tiers.ts
+/**
+* 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.
+*/
+function classifyTier(tiers, direction, score) {
+	if (!tiers || tiers.length === 0) return null;
+	let reached = null;
+	for (const tier of tiers) {
+		if (!(direction === "desc" ? score >= tier.from : score <= tier.from)) break;
+		reached = tier.key;
+	}
+	return reached;
+}
+//#endregion
+export { classifyTier };

package/dist/rank/worker.d.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import type { LeaderboardBoard, LeaderboardConfig } from "../config/config";
+import { type PruneOutcome } from "../retention/prune";
+import { type RefreshResult } 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 declare function materializedBoards(config: LeaderboardConfig): LeaderboardBoard[];
+/**
+ * **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 declare function runRankPass(d1: D1Database, config: LeaderboardConfig, now: Date): Promise<RankPassResult>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/rank/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/rank/worker.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,eAAe,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB,CAAC;IACC,2CAA2C;IAC3C,KAAK,EAAE,WAAW,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,aAAa,CAAC,GAClB;IACE,iFAAiF;IACjF,KAAK,EAAE,aAAa,CAAC;IACrB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,YAAY,CAAC;IACrB,0FAA0F;IAC1F,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,yGAAyG;AACzG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,EAAE,CAEhF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAsB/G"}