@pithy-sh/leaderboard 0.1.2 → 0.1.3

package/dist/rank/query.d.ts

@@ -0,0 +1,50 @@
+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,140 @@
+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,33 @@
+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,37 @@
+//#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,33 @@
+/**
+ * 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,35 @@
+//#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,13 @@
+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,22 @@
+//#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,59 @@
+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"}

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

@@ -0,0 +1,57 @@
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import type { D1Database } from "@cloudflare/workers-types";
+/**
+ * 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 declare class RankRefreshWorkflow extends WorkflowEntrypoint<RankWorkerEnv, unknown> {
+    run(_event: WorkflowEvent<unknown>, step: WorkflowStep): Promise<void>;
+}
+declare const _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.
+     */
+    scheduled(_controller: unknown, env: RankWorkerEnv): Promise<void>;
+};
+export default _default;
+//# sourceMappingURL=worker.entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker.entry.d.ts","sourceRoot":"","sources":["../../src/rank/worker.entry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAW5D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,UAAU,aAAa;IACrB,EAAE,EAAE,UAAU,CAAC;IACf,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2GAA2G;IAC3G,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,kGAAkG;IAClG,YAAY,EAAE;QAAE,MAAM,CAAC,OAAO,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CACvE;AAED,qBAAa,mBAAoB,SAAQ,kBAAkB,CAAC,aAAa,EAAE,OAAO,CAAC;IAClE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+DpF;CACF;;IAGC;;;;;;OAMG;IACG,SAAS,cAAc,OAAO,OAAO,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC"}

package/dist/rank/worker.entry.js

@@ -0,0 +1,63 @@
+import { windowKeyAt } from "../window/schedule.js";
+import { LeaderboardConfig } from "../config/config.js";
+import { leaderboardDatabase } from "../data/tables.js";
+import { acquireRefreshLock, releaseRefreshLock } from "./lock.js";
+import { REFRESH_BATCH_CHUNKS, refreshWindowRanks } from "./materialize.js";
+import { leaderboardWorkflowRetry } from "./retryPolicy.js";
+import { pruneBoards } from "../retention/prune.js";
+import { materializedBoards } from "./worker.js";
+import { WorkflowEntrypoint } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+//#region src/rank/worker.entry.ts
+var RankRefreshWorkflow = class extends WorkflowEntrypoint {
+	async run(_event, step) {
+		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) : void 0;
+		const ctx = await steps.do("refresh-context", async () => ({
+			holder: crypto.randomUUID(),
+			nowMs: Date.now()
+		}));
+		const now = new Date(ctx.nowMs);
+		if (!await acquireRefreshLock(db, ctx.holder, now, staleMs)) return;
+		try {
+			await steps.do("prune", () => pruneBoards(db, config.boards, now));
+			for (const board of materializedBoards(config)) {
+				const window = windowKeyAt(board.window, now);
+				let cursor = null;
+				let startRank = 0;
+				let batch = 0;
+				for (;;) {
+					const from = cursor ?? void 0;
+					const result = 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;
+					if (!cursor) break;
+				}
+			}
+		} finally {
+			await releaseRefreshLock(db, ctx.holder);
+		}
+	}
+};
+var worker_entry_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, env) {
+	await env.RANK_REFRESH.create();
+} };
+//#endregion
+export { RankRefreshWorkflow, worker_entry_default as default };

package/dist/rank/worker.js

@@ -0,0 +1,52 @@
+import { windowKeyAt } from "../window/schedule.js";
+import { materializeSchedule } from "../config/config.js";
+import { leaderboardDatabase } from "../data/tables.js";
+import { refreshWindowRanks } from "./materialize.js";
+import { pruneBoards } from "../retention/prune.js";
+//#region src/rank/worker.ts
+/** The boards a refresh pass must rank: only materialized ones. Live boards compute rank per request. */
+function materializedBoards(config) {
+	return materializeSchedule(config) === void 0 ? [] : 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.
+*/
+async function runRankPass(d1, config, now) {
+	const db = leaderboardDatabase(d1);
+	const pruned = await pruneBoards(db, config.boards, now);
+	const refreshed = [];
+	for (const board of materializedBoards(config)) {
+		const window = windowKeyAt(board.window, now);
+		let result;
+		try {
+			result = await refreshWindowRanks(db, board, window);
+		} catch {
+			refreshed.push({
+				state: "unavailable",
+				board: board.key,
+				window
+			});
+			continue;
+		}
+		refreshed.push({
+			state: "refreshed",
+			board: board.key,
+			window,
+			...result
+		});
+	}
+	return {
+		pruned,
+		refreshed
+	};
+}
+//#endregion
+export { materializedBoards, runRankPass };