@pithy-sh/leaderboard 0.1.2 → 0.1.3

package/dist/http/routes.d.ts

@@ -0,0 +1,46 @@
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { Context, Hono } from "hono";
+import type { LeaderboardConfig } from "../config/config";
+import { type HandlerDeps } from "./handlers";
+/**
+ * The leaderboard routes, each declaring both how a caller is verified and what it may send:
+ *
+ *   GET    /leaderboard                          → list boards    (bearer | session) — takes nothing
+ *   POST   /leaderboard/:board                   → submit a score (bearer | session + submit scope)
+ *                                                  param BoardParam, json SubmitScoreBody
+ *   GET    /leaderboard/:board/top               → top-N page     (bearer | session)
+ *                                                  param BoardParam, query TopQuery
+ *   POST   /leaderboard/:board/segment           → friends/cohort (bearer | session)
+ *                                                  param BoardParam, json SegmentBody
+ *   GET    /leaderboard/:board/me                → my rank        (bearer | session)
+ *                                                  param BoardParam, query WindowQuery
+ *   GET    /leaderboard/:board/around            → around me      (bearer | session)
+ *                                                  param BoardParam, query AroundQuery
+ *   PUT    /leaderboard/:board/me/visibility     → my consent     (bearer | session)
+ *                                                  param BoardParam, query WindowQuery, json VisibilityBody
+ *   PUT    /leaderboard/:board/entries/:userId/hidden → hide entry (bearer | session + admin scope)
+ *                                                  param EntryParam, query WindowQuery, json HideBody
+ *   DELETE /leaderboard/:board/entries/:userId   → remove entry   (bearer | session + admin scope)
+ *                                                  param EntryParam, query WindowQuery
+ *
+ * Every route is gated by {@link requireAuth} — there is no public leaderboard surface, because an entry
+ * with no authenticated player has nothing to key on. Submit additionally requires the board's submit
+ * scope while `serverAuthoritative` is on (the default), and the two moderation routes require the admin
+ * scope. Turnstile, if the adopter runs it, stacks on top as middleware — it is a humanity check, not an
+ * identity, so it never replaces any of the above.
+ *
+ * Validators sit **after** the guards, never before: who you are is decided before what you sent, so an
+ * unauthorised request with a malformed body is still a 401. They sit **before** the handler, which is
+ * what moves a malformed request ahead of the board lookup — an unknown board sent a bad body now answers
+ * 400 rather than 404. The request was never well-formed enough to have a board.
+ */
+export interface LeaderboardRoutesOptions {
+    config: LeaderboardConfig;
+    basePath?: string;
+    /** Test seam: resolve handler deps from the request context. Defaults to the env-based resolver. */
+    resolveDeps?: (c: Context<PithyHonoEnv>, write: boolean) => HandlerDeps & {
+        bookmark(): string | null;
+    };
+}
+export declare function registerLeaderboardRoutes(options: LeaderboardRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/http/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAG7E,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,OAAO,EACL,KAAK,WAAW,EAUjB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,OAAO,KAAK,WAAW,GAAG;QAAE,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACzG;AA2BD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,wBAAwB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAqG9G"}

package/dist/http/routes.js

@@ -0,0 +1,60 @@
+import { BOOKMARK_HEADER, leaderboardSession, readBookmark } from "../session/bookmark.js";
+import { requireAdminScope, requireAuth, requireSubmitScope } from "./guard.js";
+import { hideEntry, listBoards, readAround, readOwnRank, readSegment, readTop, removeEntry, setOwnVisibility, submitScore } from "./handlers.js";
+import { AroundQuery, BoardParam, EntryParam, HideBody, SegmentBody, SubmitScoreBody, TopQuery, VisibilityBody, WindowQuery } from "./schemas.js";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { zValidator } from "@hono/zod-validator";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+//#region src/http/routes.ts
+function defaultResolveDeps(config) {
+	return (c, write) => {
+		const d1 = c.env.DB;
+		if (!d1) throw new InternalError({
+			message: "The leaderboard is not configured.",
+			action: "Bind a D1 database named DB in wrangler.jsonc.",
+			detail: "The leaderboard capability requires a `DB` D1 binding; none was present on env."
+		});
+		const session = leaderboardSession(d1, readBookmark(c.req.raw.headers), write ? "first-primary" : "first-unconstrained");
+		const auth = c.var.auth;
+		if (!auth) throw new InternalError({ detail: "requireAuth() must run before a leaderboard handler resolves deps." });
+		return {
+			config,
+			db: session.db,
+			userId: auth.userId,
+			now: () => /* @__PURE__ */ new Date(),
+			bookmark: session.bookmark
+		};
+	};
+}
+function registerLeaderboardRoutes(options) {
+	const base = options.basePath ?? "/leaderboard";
+	const resolve = options.resolveDeps ?? defaultResolveDeps(options.config);
+	const { serverAuthoritative, submitScope, adminScope } = options.config;
+	/** Run a handler and return its JSON, attaching the session's bookmark for the client to echo back. */
+	const respond = async (c, write, run, status = 200) => {
+		const deps = resolve(c, write);
+		const body = await run(deps);
+		const bookmark = deps.bookmark();
+		if (bookmark) c.header(BOOKMARK_HEADER, bookmark);
+		return c.json(body, status);
+	};
+	return (app) => {
+		app.get(base, requireAuth(), (c) => respond(c, false, (deps) => listBoards(deps)));
+		app.post(`${base}/:board/segment`, requireAuth(), zValidator("param", BoardParam, validationHook), zValidator("json", SegmentBody, validationHook), (c) => respond(c, false, (deps) => readSegment(deps, c.req.valid("param").board, c.req.valid("json"))));
+		app.get(`${base}/:board/top`, requireAuth(), zValidator("param", BoardParam, validationHook), zValidator("query", TopQuery, validationHook), (c) => respond(c, false, (deps) => readTop(deps, c.req.valid("param").board, c.req.valid("query"))));
+		app.get(`${base}/:board/me`, requireAuth(), zValidator("param", BoardParam, validationHook), zValidator("query", WindowQuery, validationHook), (c) => respond(c, false, (deps) => readOwnRank(deps, c.req.valid("param").board, c.req.valid("query"))));
+		app.get(`${base}/:board/around`, requireAuth(), zValidator("param", BoardParam, validationHook), zValidator("query", AroundQuery, validationHook), (c) => respond(c, false, (deps) => readAround(deps, c.req.valid("param").board, c.req.valid("query"))));
+		app.put(`${base}/:board/me/visibility`, requireAuth(), zValidator("param", BoardParam, validationHook), zValidator("query", WindowQuery, validationHook), zValidator("json", VisibilityBody, validationHook), (c) => respond(c, true, (deps) => setOwnVisibility(deps, c.req.valid("param").board, c.req.valid("query"), c.req.valid("json"))));
+		app.put(`${base}/:board/entries/:userId/hidden`, requireAuth(), requireAdminScope(adminScope), zValidator("param", EntryParam, validationHook), zValidator("query", WindowQuery, validationHook), zValidator("json", HideBody, validationHook), (c) => {
+			const { board, userId } = c.req.valid("param");
+			return respond(c, true, (deps) => hideEntry(deps, board, userId, c.req.valid("query"), c.req.valid("json")));
+		});
+		app.delete(`${base}/:board/entries/:userId`, requireAuth(), requireAdminScope(adminScope), zValidator("param", EntryParam, validationHook), zValidator("query", WindowQuery, validationHook), (c) => {
+			const { board, userId } = c.req.valid("param");
+			return respond(c, true, (deps) => removeEntry(deps, board, userId, c.req.valid("query")));
+		});
+		app.post(`${base}/:board`, requireAuth(), requireSubmitScope(serverAuthoritative, submitScope), zValidator("param", BoardParam, validationHook), zValidator("json", SubmitScoreBody, validationHook), (c) => respond(c, true, (deps) => submitScore(deps, c.req.valid("param").board, c.req.valid("json")), 201));
+	};
+}
+//#endregion
+export { registerLeaderboardRoutes };

package/dist/http/schemas.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const BoardParam: z.ZodObject<{
+    board: z.ZodString;
+}, z.core.$strip>;
+export type BoardParam = z.infer<typeof BoardParam>;
+export declare const EntryParam: z.ZodObject<{
+    board: z.ZodString;
+    userId: z.ZodString;
+}, z.core.$strip>;
+export type EntryParam = z.infer<typeof EntryParam>;
+export declare const SubmitScoreBody: z.ZodObject<{
+    score: z.ZodNumber;
+}, z.core.$strip>;
+export type SubmitScoreBody = z.infer<typeof SubmitScoreBody>;
+export declare const WindowQuery: z.ZodObject<{
+    window: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WindowQuery = z.infer<typeof WindowQuery>;
+export declare const TopQuery: z.ZodObject<{
+    window: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type TopQuery = z.infer<typeof TopQuery>;
+export declare const AroundQuery: z.ZodObject<{
+    window: z.ZodOptional<z.ZodString>;
+    radius: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type AroundQuery = z.infer<typeof AroundQuery>;
+export declare const SegmentBody: z.ZodObject<{
+    userIds: z.ZodArray<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SegmentBody = z.infer<typeof SegmentBody>;
+export declare const VisibilityBody: z.ZodObject<{
+    visible: z.ZodBoolean;
+}, z.core.$strip>;
+export type VisibilityBody = z.infer<typeof VisibilityBody>;
+export declare const HideBody: z.ZodObject<{
+    hidden: z.ZodBoolean;
+}, z.core.$strip>;
+export type HideBody = z.infer<typeof HideBody>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/http/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,UAAU;;iBAW0C,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,UAAU;;;iBAQ0C,CAAC;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,eAAe;;iBAOwE,CAAC;AACrG,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,WAAW;;iBAS4B,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;iBASwB,CAAC;AAC9C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,WAAW;;;iBAQ2C,CAAC;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,WAAW;;;;;iBAgB2B,CAAC;AACpD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,cAAc;;iBAMqE,CAAC;AACjG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,QAAQ;;iBAI6E,CAAC;AACnG,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC"}

package/dist/http/schemas.js

@@ -0,0 +1,36 @@
+import { BOARD_KEY_PATTERN } from "../config/boardKey.js";
+import "../rank/segment.js";
+import { z } from "zod";
+//#region src/http/schemas.ts
+/**
+* The HTTP boundary shapes. Everything a client can send is parsed through one of these before it
+* reaches a handler — declared on the route line with `zValidator(target, Schema, validationHook)`, so
+* reading a route tells you what it takes.
+*
+* Note what is absent from {@link SubmitScoreBody}: `userId`, `achievedAt`, and `rank`. The player comes
+* from the AuthContext seam, the clock comes from the server, and the rank is derived — a client that
+* could set any of them could score as someone else, backdate its way past the tiebreak, or simply
+* declare itself first. Server-authoritative is not only about who may call submit; it is about which
+* fields a caller may name at all.
+*/
+/** A player id is opaque to us — it comes from the adopter's auth provider — so it is bounded, not shaped. */
+const MAX_USER_ID_LENGTH = 256;
+const BoardParam = z.object({ board: z.string().min(1).max(64).regex(BOARD_KEY_PATTERN, "A board key is lowercase, digits, and dashes — it is a URL path segment.").describe("Which board the route addresses. A shape check only: the same pattern config already enforces on every board key, so nothing that resolves today is rejected. Whether the key is *configured* stays the handler's 404.") }).describe("The board a `/leaderboard/:board` route addresses.");
+const EntryParam = BoardParam.extend({ userId: z.string().min(1).max(MAX_USER_ID_LENGTH).describe("The player whose entry a moderation route targets. Bounded in length, not in charset — player ids are minted by your auth provider, so we cap what reaches the store rather than guess its format.") }).describe("The board and player a moderation route addresses.");
+const SubmitScoreBody = z.object({ score: z.number().finite().describe("The score to submit. Folded into the player's entry by the board's aggregation.") }).describe("A score submission. The player, the window, and the timestamp are all server-derived.");
+const WindowQuery = z.object({ window: z.string().optional().describe("Which window to read — the ISO key of a closed window, or omit for the one open now. Reading your own history is the point: these windows live in your D1 for as long as `retain` says, which no platform SDK offers.") }).describe("Selects the window a read applies to.");
+const TopQuery = WindowQuery.extend({
+	limit: z.coerce.number().int().min(1).max(100).default(20).describe("How many entries to return, capped at 100 — a page, not the whole board."),
+	offset: z.coerce.number().int().min(0).default(0).describe("How many entries to skip. Ranks number from here.")
+}).describe("A page of a board, best first.");
+const AroundQuery = WindowQuery.extend({ radius: z.coerce.number().int().min(1).max(25).default(5).describe("How many entries to return either side of the player.") }).describe("The slice of a board centered on the calling player.");
+const SegmentBody = z.object({
+	userIds: z.array(z.string().min(1)).min(1).max(80, `A segment is capped at 80 players: D1 allows 100 bound parameters per query and each member costs one.`).describe("The players to rank among — a friends list or any cohort. A collection dimension over the same store, not a second board."),
+	limit: z.number().int().min(1).max(100).default(20).describe("How many entries to return."),
+	offset: z.number().int().min(0).default(0).describe("How many entries to skip."),
+	window: z.string().optional().describe("Which window to read; omit for the one open now.")
+}).describe("A friends or cohort view of a board.");
+const VisibilityBody = z.object({ visible: z.boolean().describe("Whether this player consents to appear on the board. Gates every read, including segments.") }).describe("A player's own consent to be shown. Theirs to set — a submission never resets it.");
+const HideBody = z.object({ hidden: z.boolean().describe("Whether to hide this entry from every read. The score is kept, not deleted.") }).describe("A moderator's hide toggle. Separate from player consent so a player cannot undo it.");
+//#endregion
+export { AroundQuery, BoardParam, EntryParam, HideBody, SegmentBody, SubmitScoreBody, TopQuery, VisibilityBody, WindowQuery };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The package entrypoint — the surface `pithy add leaderboard` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, and the read shapes an app renders. Every
+ * other module is imported by deep path (`@pithy-sh/leaderboard/src/...`); this is the documented
+ * contract, not a barrel over the package.
+ */
+export { isLeaderboardCapability, LEADERBOARD_MIGRATION_ORDER, type LeaderboardCapability, type LeaderboardOptions, leaderboard, needsRankWorker, } from "./capability";
+export { LeaderboardBoard, LeaderboardConfig, type LeaderboardConfigInput, LeaderboardRank, LeaderboardStore, LeaderboardTier, materializeSchedule, resolveBoard, ScoreAggregation, ScoreDirection, } from "./config/config";
+export { LeaderboardEntry } from "./data/entry";
+export type { OwnRank } from "./http/handlers";
+export type { RankedEntry } from "./rank/query";
+export { MAX_SEGMENT_SIZE } from "./rank/segment";
+export { classifyTier } from "./rank/tiers";
+export { BOOKMARK_HEADER } from "./session/bookmark";
+export { ALL_TIME_WINDOW, previousWindowKeys, windowKeyAt } from "./window/schedule";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,2BAA2B,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,WAAW,EACX,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+import { ALL_TIME_WINDOW, previousWindowKeys, windowKeyAt } from "./window/schedule.js";
+import { LeaderboardBoard, LeaderboardConfig, LeaderboardRank, LeaderboardStore, LeaderboardTier, ScoreAggregation, ScoreDirection, materializeSchedule, resolveBoard } from "./config/config.js";
+import { LeaderboardEntry } from "./data/entry.js";
+import { BOOKMARK_HEADER } from "./session/bookmark.js";
+import { MAX_SEGMENT_SIZE } from "./rank/segment.js";
+import { classifyTier } from "./rank/tiers.js";
+import { LEADERBOARD_MIGRATION_ORDER, isLeaderboardCapability, leaderboard, needsRankWorker } from "./capability.js";
+export { ALL_TIME_WINDOW, BOOKMARK_HEADER, LEADERBOARD_MIGRATION_ORDER, LeaderboardBoard, LeaderboardConfig, LeaderboardEntry, LeaderboardRank, LeaderboardStore, LeaderboardTier, MAX_SEGMENT_SIZE, ScoreAggregation, ScoreDirection, classifyTier, isLeaderboardCapability, leaderboard, materializeSchedule, needsRankWorker, previousWindowKeys, resolveBoard, windowKeyAt };

package/dist/migrations/0001_entries.d.ts

@@ -0,0 +1,8 @@
+import type { Migration } from "kysely/migration";
+/**
+ * The leaderboard tables: player entries, and the board drift guard.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+ */
+export declare const leaderboard_0001_entries: Migration;
+//# sourceMappingURL=0001_entries.d.ts.map

package/dist/migrations/0001_entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0001_entries.d.ts","sourceRoot":"","sources":["../../src/migrations/0001_entries.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,SA0EtC,CAAC"}

package/dist/migrations/0001_entries.js

@@ -0,0 +1,33 @@
+//#region src/migrations/0001_entries.ts
+/**
+* The leaderboard tables: player entries, and the board drift guard.
+*
+* camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+*/
+const leaderboard_0001_entries = {
+	up: async (db) => {
+		await db.schema.createTable("pithyLeaderboardEntries").addColumn("id", "integer", (c) => c.primaryKey()).addColumn("boardId", "text", (c) => c.notNull()).addColumn("windowKey", "text", (c) => c.notNull()).addColumn("userId", "text", (c) => c.notNull()).addColumn("score", "real", (c) => c.notNull()).addColumn("achievedAt", "integer", (c) => c.notNull()).addColumn("submittedAt", "integer", (c) => c.notNull()).addColumn("visible", "integer", (c) => c.notNull().defaultTo(1)).addColumn("hidden", "integer", (c) => c.notNull().defaultTo(0)).addColumn("rank", "integer").execute();
+		await db.schema.createIndex("pithyLeaderboardEntriesPlayerIdx").on("pithyLeaderboardEntries").columns([
+			"boardId",
+			"windowKey",
+			"userId"
+		]).unique().execute();
+		await db.schema.createIndex("pithyLeaderboardEntriesRankIdx").on("pithyLeaderboardEntries").columns([
+			"boardId",
+			"windowKey",
+			"score",
+			"achievedAt"
+		]).execute();
+		await db.schema.createTable("pithyLeaderboardBoards").addColumn("id", "integer", (c) => c.primaryKey()).addColumn("boardKey", "text", (c) => c.notNull().unique()).addColumn("store", "text", (c) => c.notNull().defaultTo("d1")).addColumn("direction", "text", (c) => c.notNull()).addColumn("aggregation", "text", (c) => c.notNull()).addColumn("window", "text").addColumn("createdAt", "integer", (c) => c.notNull()).execute();
+		await db.schema.createTable("pithyLeaderboardLocks").addColumn("name", "text", (c) => c.primaryKey()).addColumn("holder", "text", (c) => c.notNull()).addColumn("acquiredAt", "integer", (c) => c.notNull()).execute();
+	},
+	down: async (db) => {
+		await db.schema.dropTable("pithyLeaderboardLocks").execute();
+		await db.schema.dropTable("pithyLeaderboardBoards").execute();
+		await db.schema.dropIndex("pithyLeaderboardEntriesRankIdx").execute();
+		await db.schema.dropIndex("pithyLeaderboardEntriesPlayerIdx").execute();
+		await db.schema.dropTable("pithyLeaderboardEntries").execute();
+	}
+};
+//#endregion
+export { leaderboard_0001_entries };

package/dist/rank/lock.d.ts

@@ -0,0 +1,37 @@
+import { type LeaderboardDatabase } from "../data/tables";
+/**
+ * The rank-refresh advisory lock: at most one refresh runs at a time.
+ *
+ * Why it exists: the materialize refresh writes ranks in chunks, not atomically. If a cron fired again
+ * before a refresh finished, two passes would run concurrently and their chunked writes would interleave
+ * into an incoherent rank set — duplicate or gapped rank numbers — until the next fire corrected it. The
+ * lock serializes them: a second instance that cannot acquire it simply skips, and the pass it would have
+ * done is redundant anyway (the holder is already producing fresh ranks).
+ *
+ * The lock lives in D1, not in DO or KV, because the refresh already has the `DB` binding and D1's
+ * single-threaded execution makes the acquire genuinely atomic — the whole point.
+ */
+/** The one lock name the refresh uses. A single-row lock; there is no per-board locking. */
+export declare const REFRESH_LOCK = "rank-refresh";
+/**
+ * How long a held lock stays valid before it is treated as abandoned by a crashed instance.
+ *
+ * A refresh that finishes releases the lock immediately, so this only matters when an instance dies
+ * mid-pass. It must be comfortably longer than any real refresh so a slow-but-alive instance is never
+ * stolen from; one hour is far past the ~5-minute worst case at the ~1M-player shard boundary. Override
+ * with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that.
+ */
+export declare const DEFAULT_LOCK_STALE_MS: number;
+/**
+ * Try to take the refresh lock for `holder`, returning whether it was acquired.
+ *
+ * Atomic on D1's single thread: the upsert either inserts the row (no holder yet) or, on conflict, takes
+ * it over only if the current holder's lock is older than `staleMs` — a fresh lock is left untouched.
+ * A concurrent second caller therefore either finds no row and loses the insert race, or finds a fresh
+ * lock and is refused by the `WHERE`. Either way it reads back a `holder` that is not its own and knows
+ * to stand down.
+ */
+export declare function acquireRefreshLock(db: LeaderboardDatabase, holder: string, now: Date, staleMs?: number): Promise<boolean>;
+/** Release the lock if `holder` still holds it. A no-op if it was already reclaimed or released. */
+export declare function releaseRefreshLock(db: LeaderboardDatabase, holder: string): Promise<void>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/rank/lock.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEnF;;;;;;;;;;;GAWG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,IAAI,EACT,OAAO,GAAE,MAA8B,GACtC,OAAO,CAAC,OAAO,CAAC,CAuBlB;AAED,oGAAoG;AACpG,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F"}

package/dist/rank/lock.js

@@ -0,0 +1,54 @@
+import { LeaderboardLock } from "../data/lock.js";
+import { LEADERBOARD_LOCKS_TABLE } from "../data/tables.js";
+//#region src/rank/lock.ts
+/**
+* The rank-refresh advisory lock: at most one refresh runs at a time.
+*
+* Why it exists: the materialize refresh writes ranks in chunks, not atomically. If a cron fired again
+* before a refresh finished, two passes would run concurrently and their chunked writes would interleave
+* into an incoherent rank set — duplicate or gapped rank numbers — until the next fire corrected it. The
+* lock serializes them: a second instance that cannot acquire it simply skips, and the pass it would have
+* done is redundant anyway (the holder is already producing fresh ranks).
+*
+* The lock lives in D1, not in DO or KV, because the refresh already has the `DB` binding and D1's
+* single-threaded execution makes the acquire genuinely atomic — the whole point.
+*/
+/** The one lock name the refresh uses. A single-row lock; there is no per-board locking. */
+const REFRESH_LOCK = "rank-refresh";
+/**
+* How long a held lock stays valid before it is treated as abandoned by a crashed instance.
+*
+* A refresh that finishes releases the lock immediately, so this only matters when an instance dies
+* mid-pass. It must be comfortably longer than any real refresh so a slow-but-alive instance is never
+* stolen from; one hour is far past the ~5-minute worst case at the ~1M-player shard boundary. Override
+* with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that.
+*/
+const DEFAULT_LOCK_STALE_MS = 36e5;
+/**
+* Try to take the refresh lock for `holder`, returning whether it was acquired.
+*
+* Atomic on D1's single thread: the upsert either inserts the row (no holder yet) or, on conflict, takes
+* it over only if the current holder's lock is older than `staleMs` — a fresh lock is left untouched.
+* A concurrent second caller therefore either finds no row and loses the insert race, or finds a fresh
+* lock and is refused by the `WHERE`. Either way it reads back a `holder` that is not its own and knows
+* to stand down.
+*/
+async function acquireRefreshLock(db, holder, now, staleMs = DEFAULT_LOCK_STALE_MS) {
+	const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - staleMs));
+	const row = LeaderboardLock.encode({
+		name: REFRESH_LOCK,
+		holder,
+		acquiredAt: now
+	});
+	await db.insertInto(LEADERBOARD_LOCKS_TABLE).values(row).onConflict((oc) => oc.column("name").doUpdateSet({
+		holder,
+		acquiredAt: LeaderboardLock.shape.acquiredAt.encode(now)
+	}).where("pithyLeaderboardLocks.acquiredAt", "<", staleBefore)).execute();
+	return (await db.selectFrom(LEADERBOARD_LOCKS_TABLE).select("holder").where("name", "=", REFRESH_LOCK).executeTakeFirst())?.holder === holder;
+}
+/** Release the lock if `holder` still holds it. A no-op if it was already reclaimed or released. */
+async function releaseRefreshLock(db, holder) {
+	await db.deleteFrom(LEADERBOARD_LOCKS_TABLE).where("name", "=", REFRESH_LOCK).where("holder", "=", holder).execute();
+}
+//#endregion
+export { DEFAULT_LOCK_STALE_MS, REFRESH_LOCK, acquireRefreshLock, releaseRefreshLock };

package/dist/rank/materialize.d.ts

@@ -0,0 +1,95 @@
+import type { LeaderboardBoard } from "../config/config";
+import { type LeaderboardDatabase } from "../data/tables";
+/**
+ * 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.
+ */
+export declare 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.
+ */
+export declare const RANK_CHUNK_SIZE: number;
+/**
+ * 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.
+ */
+export declare const REFRESH_BATCH_CHUNKS = 2000;
+/** The last entry a chunk ranked — where the next chunk (or the next batch's step) resumes. */
+export interface Keyset {
+    score: number;
+    achievedAt: number;
+    userId: string;
+}
+export interface RefreshResult {
+    /** The cumulative number of entries ranked, including any `startRank` carried in from a prior batch. */
+    ranked: number;
+    /** How many chunks ran in this call. */
+    chunks: number;
+    /** True when the board is fully ranked; false when `maxChunks` stopped this batch mid-board. */
+    complete: boolean;
+    /**
+     * Where the next batch resumes, or null when the board is complete. Passing this back as `resumeAfter`
+     * (with `startRank` set to `ranked`) continues the pass exactly where it left off — the seam that makes
+     * a board rankable across many bounded steps of a Workflow, rather than one unbounded invocation.
+     */
+    cursor: Keyset | null;
+}
+export interface RefreshOptions {
+    /**
+     * Rows per keyset step. Defaults to {@link RANK_CHUNK_SIZE}; lower it to be gentler on a hot database.
+     *
+     * It carries no bound-parameter ceiling — the update chunks itself — so the only thing refused is a
+     * value that is not a count. A `chunkSize` of 0 used to report a board complete having ranked nobody.
+     */
+    chunkSize?: number;
+    /** Stop cleanly once this many chunks have run, whether or not the board is finished. Default: no cap. */
+    maxChunks?: number;
+    /** Resume the keyset walk after this entry — the `cursor` a prior batch returned. */
+    resumeAfter?: Keyset;
+    /** The rank already assigned before this batch, so numbering continues rather than restarting at 1. */
+    startRank?: number;
+}
+/**
+ * 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.
+ */
+export declare function refreshWindowRanks(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, options?: RefreshOptions): Promise<RefreshResult>;
+//# sourceMappingURL=materialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../src/rank/materialize.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAgE,CAAC;AAE7F;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,+FAA+F;AAC/F,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,MAAM,WAAW,aAAa;IAC5B,wGAAwG;IACxG,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAkFxB"}

package/dist/rank/materialize.js

@@ -0,0 +1,140 @@
+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 };