@pithy-sh/leaderboard 0.1.2 → 0.1.4

package/dist/data/lock.d.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * A single-row advisory lock in `pithy_leaderboard_locks` — the row in the table, one per lock name.
+ *
+ * It serializes the rank-refresh Workflow: at most one instance holds the `rank-refresh` lock at a time,
+ * so two overlapping cron fires can never interleave their chunked rank writes into an incoherent set.
+ *
+ * `z.output` is the app shape (a Date); `z.input` is the SQLite row (ms-epoch). Conversion runs through
+ * the core codec, per the round-trip rule.
+ */
+export declare const LeaderboardLock: z.ZodObject<{
+    name: z.ZodString;
+    holder: z.ZodString;
+    acquiredAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type LeaderboardLock = z.output<typeof LeaderboardLock>;
+export type LeaderboardLockRow = z.input<typeof LeaderboardLock>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/data/lock.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;iBAQkC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/data/lock.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/lock.ts
+/**
+* A single-row advisory lock in `pithy_leaderboard_locks` — the row in the table, one per lock name.
+*
+* It serializes the rank-refresh Workflow: at most one instance holds the `rank-refresh` lock at a time,
+* so two overlapping cron fires can never interleave their chunked rank writes into an incoherent set.
+*
+* `z.output` is the app shape (a Date); `z.input` is the SQLite row (ms-epoch). Conversion runs through
+* the core codec, per the round-trip rule.
+*/
+const LeaderboardLock = z.object({
+	name: z.string().describe("The lock's identity — `rank-refresh` for the refresh pass. One row per name."),
+	holder: z.string().describe("A token unique to the instance currently holding the lock."),
+	acquiredAt: SQLiteDate.describe("When the current holder took the lock. A lock older than the stale horizon is treated as abandoned by a crashed instance and may be reclaimed.")
+}).describe("One advisory lock in `pithy_leaderboard_locks`.");
+//#endregion
+export { LeaderboardLock };

package/dist/data/tables.d.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import { type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { LeaderboardBoardRecord } from "./boardRecord";
+import { LeaderboardEntry } from "./entry";
+import { LeaderboardLock } from "./lock";
+/** The entry table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_entries` in the DDL. */
+export declare const LEADERBOARD_ENTRIES_TABLE = "pithyLeaderboardEntries";
+/** The board drift-guard table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_boards`. */
+export declare const LEADERBOARD_BOARDS_TABLE = "pithyLeaderboardBoards";
+/** The advisory-lock table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_locks`. */
+export declare const LEADERBOARD_LOCKS_TABLE = "pithyLeaderboardLocks";
+/** The leaderboard tables map. All are always present — none is behind a config flag. */
+export declare function leaderboardTables(): Record<string, z.ZodObject>;
+/** The typed Kysely database over the leaderboard tables. */
+export type LeaderboardTables = {
+    [LEADERBOARD_ENTRIES_TABLE]: typeof LeaderboardEntry;
+    [LEADERBOARD_BOARDS_TABLE]: typeof LeaderboardBoardRecord;
+    [LEADERBOARD_LOCKS_TABLE]: typeof LeaderboardLock;
+};
+export type LeaderboardDatabase = Kysely<DatabaseSchema<LeaderboardTables>>;
+/** Build the leaderboard database from the `DB` binding (CamelCasePlugin installed). */
+export declare function leaderboardDatabase(d1: D1Database): LeaderboardDatabase;
+//# sourceMappingURL=tables.d.ts.map

package/dist/data/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/data/tables.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAEzC,mGAAmG;AACnG,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AACnE,mGAAmG;AACnG,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AACjE,8FAA8F;AAC9F,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,yFAAyF;AACzF,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAM/D;AAED,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,yBAAyB,CAAC,EAAE,OAAO,gBAAgB,CAAC;IACrD,CAAC,wBAAwB,CAAC,EAAE,OAAO,sBAAsB,CAAC;IAC1D,CAAC,uBAAuB,CAAC,EAAE,OAAO,eAAe,CAAC;CACnD,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAE5E,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,UAAU,GAAG,mBAAmB,CAMvE"}

package/dist/data/tables.js

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardBoardRecord } from "./boardRecord.js";
+import { LeaderboardEntry } from "./entry.js";
+import { LeaderboardLock } from "./lock.js";
+import { createDatabase } from "@pithy-sh/core/src/data/db";
+//#region src/data/tables.ts
+/** The entry table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_entries` in the DDL. */
+const LEADERBOARD_ENTRIES_TABLE = "pithyLeaderboardEntries";
+/** The board drift-guard table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_boards`. */
+const LEADERBOARD_BOARDS_TABLE = "pithyLeaderboardBoards";
+/** The advisory-lock table. `CamelCasePlugin` snake-cases it to `pithy_leaderboard_locks`. */
+const LEADERBOARD_LOCKS_TABLE = "pithyLeaderboardLocks";
+/** The leaderboard tables map. All are always present — none is behind a config flag. */
+function leaderboardTables() {
+	return {
+		[LEADERBOARD_ENTRIES_TABLE]: LeaderboardEntry,
+		[LEADERBOARD_BOARDS_TABLE]: LeaderboardBoardRecord,
+		[LEADERBOARD_LOCKS_TABLE]: LeaderboardLock
+	};
+}
+/** Build the leaderboard database from the `DB` binding (CamelCasePlugin installed). */
+function leaderboardDatabase(d1) {
+	return createDatabase(d1, {
+		[LEADERBOARD_ENTRIES_TABLE]: LeaderboardEntry,
+		[LEADERBOARD_BOARDS_TABLE]: LeaderboardBoardRecord,
+		[LEADERBOARD_LOCKS_TABLE]: LeaderboardLock
+	});
+}
+//#endregion
+export { LEADERBOARD_BOARDS_TABLE, LEADERBOARD_ENTRIES_TABLE, LEADERBOARD_LOCKS_TABLE, leaderboardDatabase, leaderboardTables };

package/dist/entry/store.d.ts

@@ -0,0 +1,42 @@
+// 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";
+/**
+ * Reads and writes over `pithy_leaderboard_entries`.
+ *
+ * Every write is one `INSERT … ON CONFLICT DO UPDATE` against the `(boardId, windowKey, userId)` unique
+ * index. Folding the aggregation into the conflict clause — rather than reading the row, deciding in JS,
+ * and writing it back — is what keeps a submission a single statement: D1 is single-threaded, so a
+ * read-then-write would both double the round trips and open a race where two submissions from the same
+ * player interleave and one silently wins.
+ *
+ * Round-trip rule (CLAUDE.md §Data layer): read with `LeaderboardEntry.parse` (decode), write with
+ * `LeaderboardEntry.encode` (encode). No raw `0/1` or epoch numbers below.
+ */
+export interface EntryStore {
+    /** Fold a submission into the player's entry for this window, per the board's aggregation. */
+    submit(board: LeaderboardBoard, windowKey: string, userId: string, score: number, at: Date, visibleByDefault: boolean): Promise<void>;
+    /** The player's entry for this window, or undefined if they have never submitted. */
+    get(boardId: string, windowKey: string, userId: string): Promise<LeaderboardEntry | undefined>;
+    /** Set the player's own consent to appear. False if they have no entry. */
+    setVisibility(boardId: string, windowKey: string, userId: string, visible: boolean): Promise<boolean>;
+    /** Hide or unhide an entry as a moderator. False if they have no entry. */
+    hide(boardId: string, windowKey: string, userId: string, hidden: boolean): Promise<boolean>;
+    /** Delete an entry outright. False if they have no entry. */
+    remove(boardId: string, windowKey: string, userId: string): Promise<boolean>;
+    /** Delete entries on this board in windows chronologically before `cutoffWindow`. Returns rows deleted. */
+    pruneWindowsBefore(boardId: string, cutoffWindow: string): Promise<number>;
+}
+/**
+ * The submission upsert, as a compilable query.
+ *
+ * Exported so `writeAmplification.workers.test.ts` can compile the real statement and read D1's own
+ * `meta.rows_written` for it. The cost model in `scripts/costModel.ts` assumes a fixed number of rows
+ * written per submission, and that assumption is load-bearing for every figure in docs/costs.md — a test
+ * that measured a hand-written approximation of this SQL would only prove the approximation's cost.
+ */
+export declare function submitQuery(db: LeaderboardDatabase, board: LeaderboardBoard, windowKey: string, userId: string, score: number, at: Date, visibleByDefault: boolean): import("kysely").InsertQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<import("../data/tables").LeaderboardTables>, "pithyLeaderboardEntries", import("kysely").InsertResult>;
+export declare function entryStore(db: LeaderboardDatabase): EntryStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/entry/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/entry/store.ts"],"names":[],"mappings":"AAIA,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;AAErF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,8FAA8F;IAC9F,MAAM,CACJ,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,IAAI,EACR,gBAAgB,EAAE,OAAO,GACxB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,qFAAqF;IACrF,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IAC/F,2EAA2E;IAC3E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtG,2EAA2E;IAC3E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5F,6DAA6D;IAC7D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7E,2GAA2G;IAC3G,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,IAAI,EACR,gBAAgB,EAAE,OAAO,kMAgE1B;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,mBAAmB,GAAG,UAAU,CA4D9D"}

package/dist/entry/store.js

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardEntry } from "../data/entry.js";
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables.js";
+import { sql } from "kysely";
+//#region src/entry/store.ts
+/**
+* The submission upsert, as a compilable query.
+*
+* Exported so `writeAmplification.workers.test.ts` can compile the real statement and read D1's own
+* `meta.rows_written` for it. The cost model in `scripts/costModel.ts` assumes a fixed number of rows
+* written per submission, and that assumption is load-bearing for every figure in docs/costs.md — a test
+* that measured a hand-written approximation of this SQL would only prove the approximation's cost.
+*/
+function submitQuery(db, board, windowKey, userId, score, at, visibleByDefault) {
+	const insert = LeaderboardEntry.encode({
+		id: 0,
+		boardId: board.key,
+		windowKey,
+		userId,
+		score,
+		achievedAt: at,
+		submittedAt: at,
+		visible: visibleByDefault,
+		hidden: false,
+		rank: null
+	});
+	delete insert.id;
+	const entries = sql.table(LEADERBOARD_ENTRIES_TABLE);
+	const improves = board.direction === "desc" ? sql`excluded.score > ${entries}.score` : sql`excluded.score < ${entries}.score`;
+	const guardNoOps = board.aggregation === "best" && !board.trackActivity;
+	return db.insertInto(LEADERBOARD_ENTRIES_TABLE).values(insert).onConflict((oc) => {
+		const updated = oc.columns([
+			"boardId",
+			"windowKey",
+			"userId"
+		]).doUpdateSet(() => {
+			const submittedAt = sql`excluded.submitted_at`;
+			if (board.aggregation === "latest") return {
+				submittedAt,
+				score: sql`excluded.score`,
+				achievedAt: sql`excluded.achieved_at`
+			};
+			if (board.aggregation === "sum") return {
+				submittedAt,
+				score: sql`${entries}.score + excluded.score`,
+				achievedAt: sql`excluded.achieved_at`
+			};
+			return {
+				submittedAt,
+				score: sql`CASE WHEN ${improves} THEN excluded.score ELSE ${entries}.score END`,
+				achievedAt: sql`CASE WHEN ${improves} THEN excluded.achieved_at ELSE ${entries}.achieved_at END`
+			};
+		});
+		return guardNoOps ? updated.where(improves) : updated;
+	});
+}
+function entryStore(db) {
+	return {
+		async submit(board, windowKey, userId, score, at, visibleByDefault) {
+			await submitQuery(db, board, windowKey, userId, score, at, visibleByDefault).execute();
+		},
+		async get(boardId, windowKey, userId) {
+			const row = await db.selectFrom(LEADERBOARD_ENTRIES_TABLE).selectAll().where("boardId", "=", boardId).where("windowKey", "=", windowKey).where("userId", "=", userId).executeTakeFirst();
+			return row ? LeaderboardEntry.parse(row) : void 0;
+		},
+		async setVisibility(boardId, windowKey, userId, visible) {
+			const result = await db.updateTable(LEADERBOARD_ENTRIES_TABLE).set({ visible: LeaderboardEntry.shape.visible.encode(visible) }).where("boardId", "=", boardId).where("windowKey", "=", windowKey).where("userId", "=", userId).executeTakeFirst();
+			return Number(result.numUpdatedRows) > 0;
+		},
+		async hide(boardId, windowKey, userId, hidden) {
+			const result = await db.updateTable(LEADERBOARD_ENTRIES_TABLE).set({ hidden: LeaderboardEntry.shape.hidden.encode(hidden) }).where("boardId", "=", boardId).where("windowKey", "=", windowKey).where("userId", "=", userId).executeTakeFirst();
+			return Number(result.numUpdatedRows) > 0;
+		},
+		async remove(boardId, windowKey, userId) {
+			const result = await db.deleteFrom(LEADERBOARD_ENTRIES_TABLE).where("boardId", "=", boardId).where("windowKey", "=", windowKey).where("userId", "=", userId).executeTakeFirst();
+			return Number(result.numDeletedRows) > 0;
+		},
+		async pruneWindowsBefore(boardId, cutoffWindow) {
+			const result = await db.deleteFrom(LEADERBOARD_ENTRIES_TABLE).where("boardId", "=", boardId).where("windowKey", "<", cutoffWindow).executeTakeFirst();
+			return Number(result.numDeletedRows);
+		}
+	};
+}
+//#endregion
+export { entryStore, submitQuery };

package/dist/error/errors.d.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+/**
+ * `@pithy-sh/leaderboard` throw sugar. The `leaderboard/*` codes live in core's closed `KitErrorPayload`
+ * union (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/media` and
+ * `@pithy-sh/turnstile`. Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface LeaderboardErrorArgs {
+    /** Override the public, safe-to-expose message. */
+    message?: string;
+    /** A remediation hint (CLI action line). */
+    action?: string;
+    /** Internal context for logs + audit. Never serialized to clients. */
+    detail?: string;
+    /**
+     * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+     * unlike `action` and `detail` — these cross the boundary with `message`.
+     */
+    params?: MessageParams;
+}
+export declare class LeaderboardBoardNotFoundError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LeaderboardEntryNotFoundError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LeaderboardScoreRejectedError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LeaderboardSubmitForbiddenError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LeaderboardBoardImmutableError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LeaderboardInvalidScheduleError extends PithyError {
+    constructor(args?: LeaderboardErrorArgs, options?: {
+        cause?: unknown;
+    });
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/error/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;;;GAKG;AAEH,uFAAuF;AACvF,UAAU,oBAAoB;IAC5B,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYzE;CACF;AAED,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYzE;CACF;AAED,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYzE;CACF;AAED,qBAAa,+BAAgC,SAAQ,UAAU;IAC7D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAczE;CACF;AAED,qBAAa,8BAA+B,SAAQ,UAAU;IAC5D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYzE;CACF;AAED,qBAAa,+BAAgC,SAAQ,UAAU;IAC7D,YAAY,IAAI,GAAE,oBAAyB,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAYzE;CACF"}

package/dist/error/errors.js

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/error/errors.ts
+var LeaderboardBoardNotFoundError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/board_not_found",
+			status: 404,
+			message: args.message ?? "That board does not exist.",
+			action: args.action ?? "Check the board key against the `boards` list in pithy.config.ts.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var LeaderboardEntryNotFoundError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/entry_not_found",
+			status: 404,
+			message: args.message ?? "You have no score on that board yet.",
+			action: args.action ?? "Submit a score first.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var LeaderboardScoreRejectedError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/score_rejected",
+			status: 400,
+			message: args.message ?? "That score is outside the board's allowed range.",
+			action: args.action ?? "Submit a score within the board's min and max.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var LeaderboardSubmitForbiddenError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/submit_forbidden",
+			status: 403,
+			message: args.message ?? "This session may not submit scores.",
+			action: args.action ?? "Submit from your trusted server with the board's submit scope, or set `serverAuthoritative: false` to let clients post directly.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var LeaderboardBoardImmutableError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/board_immutable",
+			status: 409,
+			message: args.message ?? "That board's definition cannot change.",
+			action: args.action ?? "Give the changed board a new key. The old board keeps its recorded scores.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+var LeaderboardInvalidScheduleError = class extends PithyError {
+	constructor(args = {}, options) {
+		super({
+			code: "leaderboard/invalid_schedule",
+			status: 500,
+			message: args.message ?? "That board's window schedule is invalid.",
+			action: args.action ?? "Fix the board's `window` CRON expression in pithy.config.ts.",
+			detail: args.detail,
+			params: args.params
+		}, options);
+	}
+};
+//#endregion
+export { LeaderboardBoardImmutableError, LeaderboardBoardNotFoundError, LeaderboardEntryNotFoundError, LeaderboardInvalidScheduleError, LeaderboardScoreRejectedError, LeaderboardSubmitForbiddenError };

package/dist/http/guard.d.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { MiddlewareHandler } from "hono";
+/**
+ * Route guards.
+ *
+ * These depend on the core `AuthContext` seam and nothing else — `@pithy-sh/auth` populates `c.var.auth`,
+ * and leaderboard never reaches into its internals (CLAUDE.md §HTTP). Without auth installed `c.var.auth`
+ * is null and every route below is denied, which is the correct failure: an entry with no stable player
+ * id cannot be keyed, upserted, or rate-limited, so an unauthenticated board is not a degraded board but
+ * an append log of unattributable scores.
+ */
+export declare function requireAuth(): MiddlewareHandler<PithyHonoEnv>;
+/**
+ * Require the board's submit scope while `serverAuthoritative` is on.
+ *
+ * Every vendor that offers server-authoritative writes ships it **off**; Pithy ships it **on**. The scope
+ * is the seam: mint it for your own trusted server's token and never for a player's, and a device cannot
+ * post a score it invented. Turning `serverAuthoritative` off removes this gate entirely — which is the
+ * vendor default, and is why it is not ours.
+ */
+export declare function requireSubmitScope(serverAuthoritative: boolean, scope: string): MiddlewareHandler<PithyHonoEnv>;
+/** Require the admin scope for moderation — hiding or removing another player's entry. */
+export declare function requireAdminScope(scope: string): MiddlewareHandler<PithyHonoEnv>;
+//# sourceMappingURL=guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/http/guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAG9C;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAU7D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,mBAAmB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAS/G;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAWhF"}

package/dist/http/guard.js

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardSubmitForbiddenError } from "../error/errors.js";
+import { ForbiddenError, UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/http/guard.ts
+/**
+* Route guards.
+*
+* These depend on the core `AuthContext` seam and nothing else — `@pithy-sh/auth` populates `c.var.auth`,
+* and leaderboard never reaches into its internals (CLAUDE.md §HTTP). Without auth installed `c.var.auth`
+* is null and every route below is denied, which is the correct failure: an entry with no stable player
+* id cannot be keyed, upserted, or rate-limited, so an unauthenticated board is not a degraded board but
+* an append log of unattributable scores.
+*/
+function requireAuth() {
+	return async (c, next) => {
+		if (!c.var.auth) throw new UnauthorizedError({
+			message: "Authentication required.",
+			action: "Sign in and retry with a valid session or bearer token."
+		});
+		await next();
+	};
+}
+/**
+* Require the board's submit scope while `serverAuthoritative` is on.
+*
+* Every vendor that offers server-authoritative writes ships it **off**; Pithy ships it **on**. The scope
+* is the seam: mint it for your own trusted server's token and never for a player's, and a device cannot
+* post a score it invented. Turning `serverAuthoritative` off removes this gate entirely — which is the
+* vendor default, and is why it is not ours.
+*/
+function requireSubmitScope(serverAuthoritative, scope) {
+	return async (c, next) => {
+		if (serverAuthoritative && !c.var.auth?.scopes.includes(scope)) throw new LeaderboardSubmitForbiddenError({ detail: `Submit requires the ${scope} scope; this session carries [${c.var.auth?.scopes.join(", ") ?? ""}].` });
+		await next();
+	};
+}
+/** Require the admin scope for moderation — hiding or removing another player's entry. */
+function requireAdminScope(scope) {
+	return async (c, next) => {
+		if (!c.var.auth?.scopes.includes(scope)) throw new ForbiddenError({
+			message: "This session may not moderate leaderboard entries.",
+			action: `Retry with a token carrying the ${scope} scope.`,
+			detail: `Moderation requires the ${scope} scope; this session carries [${c.var.auth?.scopes.join(", ") ?? ""}].`
+		});
+		await next();
+	};
+}
+//#endregion
+export { requireAdminScope, requireAuth, requireSubmitScope };

package/dist/http/handlers.d.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { LeaderboardConfig } from "../config/config";
+import type { LeaderboardDatabase } from "../data/tables";
+import { type RankedEntry } from "../rank/query";
+import type { HideBody, SegmentBody, SubmitScoreBody, VisibilityBody } from "./schemas";
+/**
+ * The leaderboard handlers — pure functions over injected deps. Nothing here touches a Hono `Context`;
+ * the routes unwrap the request and hand the pieces down, which is what makes every case below testable
+ * without a request at all. Nothing here parses, either: the route line declares each shape with
+ * `zValidator`, so a handler receives values that are already the type it names.
+ */
+export interface HandlerDeps {
+    config: LeaderboardConfig;
+    db: LeaderboardDatabase;
+    /** The authenticated player, from the core AuthContext seam. Never from the request body. */
+    userId: string;
+    now: () => Date;
+}
+export interface BoardPage {
+    board: string;
+    window: string;
+    entries: RankedEntry[];
+}
+export declare function submitScore(deps: HandlerDeps, boardKey: string, body: SubmitScoreBody): Promise<{
+    window: string;
+}>;
+export declare function readTop(deps: HandlerDeps, boardKey: string, query: {
+    window?: string;
+    limit: number;
+    offset: number;
+}): Promise<BoardPage>;
+export declare function readSegment(deps: HandlerDeps, boardKey: string, body: SegmentBody): Promise<BoardPage>;
+export interface OwnRank {
+    board: string;
+    window: string;
+    userId: string;
+    score: number;
+    rank: number | null;
+    tier: string | null;
+    visible: boolean;
+    /** True when `rank` came from the stored column and may lag the score beside it. */
+    rankStale: boolean;
+}
+export declare function readOwnRank(deps: HandlerDeps, boardKey: string, query: {
+    window?: string;
+}): Promise<OwnRank>;
+export declare function readAround(deps: HandlerDeps, boardKey: string, query: {
+    window?: string;
+    radius: number;
+}): Promise<BoardPage>;
+export declare function setOwnVisibility(deps: HandlerDeps, boardKey: string, query: {
+    window?: string;
+}, body: VisibilityBody): Promise<{
+    visible: boolean;
+}>;
+export declare function hideEntry(deps: HandlerDeps, boardKey: string, targetUserId: string, query: {
+    window?: string;
+}, body: HideBody): Promise<{
+    hidden: boolean;
+}>;
+export declare function removeEntry(deps: HandlerDeps, boardKey: string, targetUserId: string, query: {
+    window?: string;
+}): Promise<{
+    removed: boolean;
+}>;
+/** The board set, as configured — what a client needs to render a board picker. */
+export declare function listBoards(deps: HandlerDeps): {
+    boards: Array<{
+        key: string;
+        store: string;
+        direction: string;
+        aggregation: string;
+        window: string | null;
+        tiers: Array<{
+            key: string;
+            from: number;
+        }>;
+    }>;
+};
+//# sourceMappingURL=handlers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/http/handlers.ts"],"names":[],"mappings":"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"}