@pithy-sh/leaderboard 0.1.2 → 0.1.3

package/dist/board/registry.d.ts

@@ -0,0 +1,22 @@
+import type { LeaderboardBoard } from "../config/config";
+import { type LeaderboardDatabase } from "../data/tables";
+/**
+ * The board drift guard.
+ *
+ * `store`, `direction`, `aggregation`, and `window` are create-time and immutable on every vendor
+ * surveyed, and for good reason: each one is the lens through which stored scores are read, so changing
+ * one reinterprets data rather than reconfiguring behavior. Flip `direction` and last place becomes
+ * first. Switch `best` to `sum` and the number in the column stops meaning what it meant. Change `window`
+ * and new scores key into windows that do not line up with the stored ones. Move a board to a different
+ * `store` and its scores live in a different place entirely.
+ *
+ * Pithy cannot enforce that in the type system, because a board is config the adopter edits freely and
+ * redeploys. So the first entry on a board records those fields, and every later write checks against the
+ * record. The failure is loud and immediate instead of a silently corrupted board.
+ *
+ * This is the answer to the issue's open question: a board definition is *not* migratable. There is no
+ * `pithy migrate` story for a board, because there is no safe automatic reinterpretation of the scores
+ * already stored. Changing one of these fields means a new board key.
+ */
+export declare function assertBoardDefinition(db: LeaderboardDatabase, board: LeaderboardBoard, now: Date): Promise<void>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/board/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/board/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGpF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,IAAI,CAAC,CA+Df"}

package/dist/board/registry.js

@@ -0,0 +1,52 @@
+import { LeaderboardBoardImmutableError } from "../error/errors.js";
+import { LeaderboardBoardRecord } from "../data/boardRecord.js";
+import { LEADERBOARD_BOARDS_TABLE } from "../data/tables.js";
+//#region src/board/registry.ts
+/**
+* The board drift guard.
+*
+* `store`, `direction`, `aggregation`, and `window` are create-time and immutable on every vendor
+* surveyed, and for good reason: each one is the lens through which stored scores are read, so changing
+* one reinterprets data rather than reconfiguring behavior. Flip `direction` and last place becomes
+* first. Switch `best` to `sum` and the number in the column stops meaning what it meant. Change `window`
+* and new scores key into windows that do not line up with the stored ones. Move a board to a different
+* `store` and its scores live in a different place entirely.
+*
+* Pithy cannot enforce that in the type system, because a board is config the adopter edits freely and
+* redeploys. So the first entry on a board records those fields, and every later write checks against the
+* record. The failure is loud and immediate instead of a silently corrupted board.
+*
+* This is the answer to the issue's open question: a board definition is *not* migratable. There is no
+* `pithy migrate` story for a board, because there is no safe automatic reinterpretation of the scores
+* already stored. Changing one of these fields means a new board key.
+*/
+async function assertBoardDefinition(db, board, now) {
+	let recorded = await db.selectFrom(LEADERBOARD_BOARDS_TABLE).selectAll().where("boardKey", "=", board.key).executeTakeFirst();
+	if (!recorded) {
+		const row = LeaderboardBoardRecord.encode({
+			id: 0,
+			boardKey: board.key,
+			store: board.store,
+			direction: board.direction,
+			aggregation: board.aggregation,
+			window: board.window ?? null,
+			createdAt: now
+		});
+		delete row.id;
+		await db.insertInto(LEADERBOARD_BOARDS_TABLE).values(row).onConflict((oc) => oc.column("boardKey").doNothing()).execute();
+		recorded = await db.selectFrom(LEADERBOARD_BOARDS_TABLE).selectAll().where("boardKey", "=", board.key).executeTakeFirst();
+		if (!recorded) throw new LeaderboardBoardImmutableError({
+			message: "That board's definition could not be confirmed. Retry.",
+			detail: `Board "${board.key}" record vanished immediately after insert; a concurrent delete is the likely cause.`
+		});
+	}
+	const previous = LeaderboardBoardRecord.parse(recorded);
+	const drifted = [];
+	if (previous.store !== board.store) drifted.push(`store ${previous.store} → ${board.store}`);
+	if (previous.direction !== board.direction) drifted.push(`direction ${previous.direction} → ${board.direction}`);
+	if (previous.aggregation !== board.aggregation) drifted.push(`aggregation ${previous.aggregation} → ${board.aggregation}`);
+	if ((previous.window ?? null) !== (board.window ?? null)) drifted.push(`window ${previous.window ?? "all-time"} → ${board.window ?? "all-time"}`);
+	if (drifted.length > 0) throw new LeaderboardBoardImmutableError({ detail: `Board "${board.key}" changed after recording entries: ${drifted.join(", ")}.` });
+}
+//#endregion
+export { assertBoardDefinition };

package/dist/capability.d.ts

@@ -0,0 +1,43 @@
+import { type Capability } from "@pithy-sh/core/src/capability/capability";
+import { LeaderboardConfig, type LeaderboardConfigInput } from "./config/config";
+/**
+ * Where leaderboard's migrations sort in the app database. Unique per database; the registry composes
+ * keys like `0400_leaderboard_0001_entries`. Sits after media (300) and audit (250).
+ */
+export declare const LEADERBOARD_MIGRATION_ORDER = 400;
+export type LeaderboardOptions = LeaderboardConfigInput & {
+    /** Mount the routes somewhere other than `/leaderboard`. */
+    basePath?: string;
+};
+export interface LeaderboardCapability extends Capability {
+    leaderboardConfig: LeaderboardConfig;
+}
+/**
+ * The leaderboard capability: submit a score, read the standings, read your own rank — across windows.
+ *
+ * Fully optional. Config, migrations, routes, and bindings arrive only on `pithy add leaderboard`, and
+ * `pithy remove leaderboard` is the clean inverse.
+ *
+ * One store, always: D1. There is no engine flag, because Durable Objects do not fix what a leaderboard
+ * actually strains against. A DO bills rows exactly as D1 does, so a rank scan inside one costs the same;
+ * it adds request and duration billing D1 does not have; and each object is single-threaded with a soft
+ * 1,000 req/s ceiling and the same 10 GB cap, so it does not relieve hot-board serialization either.
+ * Scale is a cadence dial (`rank: { materialize }`), which is pure D1. A DO earns its place only when
+ * `live: true` ships — as a WebSocket push layer *over* D1, which is a latency play, not a store.
+ *
+ * `dependsOn` is deliberately empty. Auth is not a peer capability but a seam: the routes read
+ * `c.var.auth` through core's `AuthContext`, so without `@pithy-sh/auth` installed every route is denied
+ * rather than open. That is the right failure and it needs no dependency edge.
+ */
+export declare function leaderboard(options?: LeaderboardOptions): LeaderboardCapability;
+export declare function isLeaderboardCapability(capability: Capability): capability is LeaderboardCapability;
+/**
+ * Whether this configuration needs the rank worker deployed.
+ *
+ * Two things need it: materialized rank (the refresh), and configured retention (the prune). Retention
+ * now defaults to keep-all, so a windowed board only needs the worker if it actually sets `retain` or
+ * `retainDays` — a board that keeps everything has nothing to prune. A live, keep-all board set needs no
+ * worker at all.
+ */
+export declare function needsRankWorker(config: LeaderboardConfig): boolean;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAE7F,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAuB,MAAM,iBAAiB,CAAC;AAOtG;;;GAGG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG;IACxD,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACvD,iBAAiB,EAAE,iBAAiB,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAmC,GAAG,qBAAqB,CA8B/F;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,qBAAqB,CAEnG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAGlE"}

package/dist/capability.js

@@ -0,0 +1,73 @@
+import { LeaderboardConfig, materializeSchedule } from "./config/config.js";
+import { leaderboardTables } from "./data/tables.js";
+import { registerLeaderboardRoutes } from "./http/routes.js";
+import { leaderboard_0001_entries } from "./migrations/0001_entries.js";
+import { leaderboardExampleSeed } from "./seeds/example.js";
+import { PACKAGE_VERSION } from "./version.generated.js";
+import { defineCapability } from "@pithy-sh/core/src/capability/capability";
+//#region src/capability.ts
+/**
+* Where leaderboard's migrations sort in the app database. Unique per database; the registry composes
+* keys like `0400_leaderboard_0001_entries`. Sits after media (300) and audit (250).
+*/
+const LEADERBOARD_MIGRATION_ORDER = 400;
+/**
+* The leaderboard capability: submit a score, read the standings, read your own rank — across windows.
+*
+* Fully optional. Config, migrations, routes, and bindings arrive only on `pithy add leaderboard`, and
+* `pithy remove leaderboard` is the clean inverse.
+*
+* One store, always: D1. There is no engine flag, because Durable Objects do not fix what a leaderboard
+* actually strains against. A DO bills rows exactly as D1 does, so a rank scan inside one costs the same;
+* it adds request and duration billing D1 does not have; and each object is single-threaded with a soft
+* 1,000 req/s ceiling and the same 10 GB cap, so it does not relieve hot-board serialization either.
+* Scale is a cadence dial (`rank: { materialize }`), which is pure D1. A DO earns its place only when
+* `live: true` ships — as a WebSocket push layer *over* D1, which is a latency play, not a store.
+*
+* `dependsOn` is deliberately empty. Auth is not a peer capability but a seam: the routes read
+* `c.var.auth` through core's `AuthContext`, so without `@pithy-sh/auth` installed every route is denied
+* rather than open. That is the right failure and it needs no dependency edge.
+*/
+function leaderboard(options = { boards: [] }) {
+	const { basePath, ...configInput } = options;
+	const resolved = LeaderboardConfig.parse(configInput);
+	const migrations = { "0001_entries": leaderboard_0001_entries };
+	const capability = defineCapability({
+		name: "leaderboard",
+		version: PACKAGE_VERSION,
+		requiredBindings: [{
+			type: "d1",
+			name: "DB"
+		}],
+		config: LeaderboardConfig,
+		databases: { app: {
+			binding: "DB",
+			tables: leaderboardTables(),
+			migrationOrder: 400,
+			migrations
+		} },
+		routes: registerLeaderboardRoutes({
+			config: resolved,
+			basePath
+		}),
+		seeds: [leaderboardExampleSeed]
+	});
+	return Object.assign(capability, { leaderboardConfig: resolved });
+}
+function isLeaderboardCapability(capability) {
+	return capability.name === "leaderboard" && "leaderboardConfig" in capability;
+}
+/**
+* Whether this configuration needs the rank worker deployed.
+*
+* Two things need it: materialized rank (the refresh), and configured retention (the prune). Retention
+* now defaults to keep-all, so a windowed board only needs the worker if it actually sets `retain` or
+* `retainDays` — a board that keeps everything has nothing to prune. A live, keep-all board set needs no
+* worker at all.
+*/
+function needsRankWorker(config) {
+	if (materializeSchedule(config) !== void 0) return true;
+	return config.boards.some((board) => board.retain !== void 0 || board.retainDays !== void 0);
+}
+//#endregion
+export { LEADERBOARD_MIGRATION_ORDER, isLeaderboardCapability, leaderboard, needsRankWorker };

package/dist/config/boardKey.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The board-key pattern, in the one module that has no reason to import anything (#430).
+ *
+ * Both `config/config.ts` and `http/schemas.ts` constrain a board key with this regex, and the schema
+ * used to take it from the config module. That module validates a board's cron window through
+ * `window/schedule.ts`, which imports `croner` — so a request schema, which a management client compiles
+ * in a browser to build a call, was dragging a cron parser in to spell one regex. `croner` runs in a
+ * browser perfectly well, and that is exactly why widening the allowlist would have been the wrong fix:
+ * the rule is what a browser build may reach, not what it can survive.
+ *
+ * A board key is a URL path segment (`/leaderboard/<key>/top`), so it is kebab-case and lowercase.
+ */
+export declare const BOARD_KEY_PATTERN: RegExp;
+//# sourceMappingURL=boardKey.d.ts.map

package/dist/config/boardKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boardKey.d.ts","sourceRoot":"","sources":["../../src/config/boardKey.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,QAAyB,CAAC"}

package/dist/config/boardKey.js

@@ -0,0 +1,16 @@
+//#region src/config/boardKey.ts
+/**
+* The board-key pattern, in the one module that has no reason to import anything (#430).
+*
+* Both `config/config.ts` and `http/schemas.ts` constrain a board key with this regex, and the schema
+* used to take it from the config module. That module validates a board's cron window through
+* `window/schedule.ts`, which imports `croner` — so a request schema, which a management client compiles
+* in a browser to build a call, was dragging a cron parser in to spell one regex. `croner` runs in a
+* browser perfectly well, and that is exactly why widening the allowlist would have been the wrong fix:
+* the rule is what a browser build may reach, not what it can survive.
+*
+* A board key is a URL path segment (`/leaderboard/<key>/top`), so it is kebab-case and lowercase.
+*/
+const BOARD_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+//#endregion
+export { BOARD_KEY_PATTERN };

package/dist/config/config.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/**
+ * The leaderboard capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field
+ * is `.describe()`d: the descriptions feed the self-documenting CLI, so a non-expert can pick the right
+ * board shape and the right `rank` mode from the CLI's questions alone (CLAUDE.md §Config).
+ *
+ * A board definition is the unit of config. There is no boards table to administer and no dashboard to
+ * click through — the board set is code, reviewed and deployed like the rest of the app. What the
+ * database records is only what config cannot: the entries, and a fingerprint of each board's immutable
+ * fields so a later edit cannot silently reinterpret scores already stored (see `data/boardRecord`).
+ */
+export declare const ScoreDirection: z.ZodEnum<{
+    asc: "asc";
+    desc: "desc";
+}>;
+export type ScoreDirection = z.infer<typeof ScoreDirection>;
+export declare const ScoreAggregation: z.ZodEnum<{
+    best: "best";
+    latest: "latest";
+    sum: "sum";
+}>;
+export type ScoreAggregation = z.infer<typeof ScoreAggregation>;
+export declare const LeaderboardStore: z.ZodLiteral<"d1">;
+export type LeaderboardStore = z.infer<typeof LeaderboardStore>;
+export declare const LeaderboardTier: z.ZodObject<{
+    key: z.ZodString;
+    from: z.ZodNumber;
+}, z.core.$strip>;
+export type LeaderboardTier = z.infer<typeof LeaderboardTier>;
+export declare const LeaderboardBoard: z.ZodObject<{
+    key: z.ZodString;
+    store: z.ZodDefault<z.ZodLiteral<"d1">>;
+    direction: z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>;
+    aggregation: z.ZodDefault<z.ZodEnum<{
+        best: "best";
+        latest: "latest";
+        sum: "sum";
+    }>>;
+    window: z.ZodOptional<z.ZodString>;
+    retain: z.ZodOptional<z.ZodNumber>;
+    retainDays: z.ZodOptional<z.ZodNumber>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    tiers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        from: z.ZodNumber;
+    }, z.core.$strip>>>;
+    trackActivity: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LeaderboardBoard = z.output<typeof LeaderboardBoard>;
+export declare const LeaderboardRank: z.ZodUnion<readonly [z.ZodLiteral<"live">, z.ZodObject<{
+    materialize: z.ZodString;
+}, z.core.$strip>]>;
+export type LeaderboardRank = z.output<typeof LeaderboardRank>;
+export declare const LeaderboardConfig: z.ZodObject<{
+    boards: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        store: z.ZodDefault<z.ZodLiteral<"d1">>;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+        aggregation: z.ZodDefault<z.ZodEnum<{
+            best: "best";
+            latest: "latest";
+            sum: "sum";
+        }>>;
+        window: z.ZodOptional<z.ZodString>;
+        retain: z.ZodOptional<z.ZodNumber>;
+        retainDays: z.ZodOptional<z.ZodNumber>;
+        min: z.ZodOptional<z.ZodNumber>;
+        max: z.ZodOptional<z.ZodNumber>;
+        tiers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            from: z.ZodNumber;
+        }, z.core.$strip>>>;
+        trackActivity: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    rank: z.ZodPrefault<z.ZodUnion<readonly [z.ZodLiteral<"live">, z.ZodObject<{
+        materialize: z.ZodString;
+    }, z.core.$strip>]>>;
+    serverAuthoritative: z.ZodDefault<z.ZodBoolean>;
+    submitScope: z.ZodDefault<z.ZodString>;
+    adminScope: z.ZodDefault<z.ZodString>;
+    visibleByDefault: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LeaderboardConfig = z.output<typeof LeaderboardConfig>;
+export type LeaderboardConfigInput = z.input<typeof LeaderboardConfig>;
+/** The board with this key, or undefined. Board keys come from config, so an unknown key is a 404. */
+export declare function resolveBoard(config: LeaderboardConfig, key: string): LeaderboardBoard | undefined;
+/** The rank refresh CRON, or undefined when rank is live and no refresh worker is needed. */
+export declare function materializeSchedule(config: LeaderboardConfig): string | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/config/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AAEH,eAAO,MAAM,cAAc;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,gBAAgB;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB,oBAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;iBAYmD,CAAC;AAChF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;iBAkHzB,CAAC;AACL,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,eAAO,MAAM,eAAe;;mBAiBzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyD1B,CAAC;AACL,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACnE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEvE,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEjG;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAEjF"}

package/dist/config/config.js

@@ -0,0 +1,121 @@
+import { assertValidSchedule } from "../window/schedule.js";
+import { BOARD_KEY_PATTERN } from "./boardKey.js";
+import { z } from "zod";
+//#region src/config/config.ts
+/**
+* The leaderboard capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field
+* is `.describe()`d: the descriptions feed the self-documenting CLI, so a non-expert can pick the right
+* board shape and the right `rank` mode from the CLI's questions alone (CLAUDE.md §Config).
+*
+* A board definition is the unit of config. There is no boards table to administer and no dashboard to
+* click through — the board set is code, reviewed and deployed like the rest of the app. What the
+* database records is only what config cannot: the entries, and a fingerprint of each board's immutable
+* fields so a later edit cannot silently reinterpret scores already stored (see `data/boardRecord`).
+*/
+const ScoreDirection = z.enum(["asc", "desc"]).describe("Which way a score sorts: `desc` = highest wins (points, distance), `asc` = lowest wins (lap time, strokes). Immutable after the board records its first entry — every vendor surveyed treats it that way, and flipping it would silently reinterpret every stored score.");
+const ScoreAggregation = z.enum([
+	"best",
+	"latest",
+	"sum"
+]).describe("How repeat submissions combine into one entry: `best` keeps the best score in the board's direction, `latest` overwrites, `sum` accumulates. Orthogonal to direction — only `best` reads it.");
+const LeaderboardStore = z.literal("d1").describe("Which backing store ranks this board. Today the only value is `d1`: exact ranking on your own D1, the store this whole capability is built on. It is a per-board discriminant on purpose — the issue settled `Store: D1, always` against a Durable-Object *engine* flag (a DO fixes neither cost nor throughput), but a future column-oriented store is a different axis: an Analytics-Engine-shaped board would be far cheaper at scale yet *approximate* (it samples on read and write), so it can only ever back a separate, opt-in `approximate` board type — never replace exact `d1` ranking. This field is the seam that would let such a board live beside a `d1` one, chosen per board. It is immutable once a board records entries: there is no safe automatic migration of scores between stores.");
+const LeaderboardTier = z.object({
+	key: z.string().min(1).describe("The tier's name as returned to clients — `gold`, `diamond`, whatever your game calls it."),
+	from: z.number().describe("The score at which this tier begins, inclusive. Read in the board's direction: on a `desc` board a score at or above `from` qualifies; on an `asc` board a score at or below it does.")
+}).describe("One tier threshold — a named band of scores, classified on read.");
+const LeaderboardBoard = z.object({
+	key: z.string().regex(BOARD_KEY_PATTERN, "A board key is lowercase, digits, and dashes — it is a URL path segment.").describe("The board's stable id, unique across the app. It is a URL path segment and an entry key."),
+	store: LeaderboardStore.default("d1").describe("Which backing store ranks this board. Only `d1` today."),
+	direction: ScoreDirection.describe("Which way this board's scores sort. Required — there is no safe default."),
+	aggregation: ScoreAggregation.default("best").describe("How this board folds repeat submissions from the same player in the same window."),
+	window: z.string().optional().describe("A UTC CRON expression marking where each window opens; omit for one all-time board. `0 0 * * *` is daily, `0 0 * * 1` weekly, `0 0 1 * *` a calendar month, `0 0 1 1 *` a calendar year. CRON rather than a fixed enum is what makes calendar months and years expressible at all — Apple caps recurrence at 30 fixed days and Google offers no monthly."),
+	retain: z.number().int().min(0).optional().describe("How many closed windows to keep before the retention sweep deletes the rest — a *product* limit (\"users can browse the last 12 weeks\"). Omit to keep every window forever, which is the default: storage is never the cost driver here (see docs/costs.md), so nothing is deleted unless you ask. Ignored on an all-time board, which never closes a window. Set this OR `retainDays`, not both."),
+	retainDays: z.number().int().min(1).optional().describe("Delete windows whose data is older than this many days — a *compliance* limit (\"nothing older than 90 days\"), independent of window cadence. Omit to keep everything (the default). Ignored on an all-time board, whose single window has no age. Set this OR `retain`, not both."),
+	min: z.number().optional().describe("The lowest score this board will accept. Server-side bounds are the anti-cheat baseline: a client that posts outside them is rejected, not ranked."),
+	max: z.number().optional().describe("The highest score this board will accept."),
+	tiers: z.array(LeaderboardTier).optional().describe("Named score bands, listed worst to best. Classified on read from the score already stored — a tier costs nothing on write and no second board."),
+	trackActivity: z.boolean().default(false).describe("Whether every submission is written, or only ones that change the ranked score. Default `false`: on a `best` board a submission that fails to beat the stored score writes *nothing* — zero rows billed — because the guard skips it. That is the single biggest cost lever this capability has, since submission writes dominate the bill and most submissions do not improve a player's best (see docs/costs.md). The cost is that `submittedAt` then advances only on an improving submission, so it stops being a record of *activity* and becomes a record of *progress*. Set `true` to write on every submission and keep `submittedAt` a true last-seen timestamp — at full write cost. Ignored on `sum` and `latest` boards, where every submission changes the score and therefore always writes.")
+}).describe("One board definition — the unit of leaderboard config.").check((ctx) => {
+	const { min, max, window, tiers, direction, retain, retainDays } = ctx.value;
+	if (min !== void 0 && max !== void 0 && min > max) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["min"],
+		message: `Board "${ctx.value.key}" sets min ${min} above max ${max}, so every score would be rejected.`
+	});
+	if (retain !== void 0 && retainDays !== void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["retainDays"],
+		message: `Board "${ctx.value.key}" sets both retain and retainDays. Set one: retain for a window-count limit, retainDays for an age limit.`
+	});
+	if ((retain !== void 0 || retainDays !== void 0) && window === void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: [retainDays !== void 0 ? "retainDays" : "retain"],
+		message: `Board "${ctx.value.key}" is all-time (no window), so retention does not apply. Remove retain/retainDays or give the board a window.`
+	});
+	if (window !== void 0) try {
+		assertValidSchedule(window);
+	} catch (error) {
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			path: ["window"],
+			message: `Board "${ctx.value.key}" has an invalid window schedule: ${error.message}`
+		});
+	}
+	if (tiers) for (let i = 1; i < tiers.length; i++) {
+		const previous = tiers[i - 1];
+		const current = tiers[i];
+		if (!(direction === "desc" ? current.from > previous.from : current.from < previous.from)) ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			path: [
+				"tiers",
+				i,
+				"from"
+			],
+			message: `Board "${ctx.value.key}" lists tier "${current.key}" after "${previous.key}", but its threshold does not improve on a ${direction} board. List tiers worst to best.`
+		});
+	}
+});
+const LeaderboardRank = z.union([z.literal("live").describe("Rank is counted at read time. Always correct, no moving parts, and $0 under ~10k players."), z.object({ materialize: z.string().describe("A UTC CRON expression for the rank refresh pass. `0 * * * *` is hourly. Faster means fresher ranks and a bigger bill; the cadence is a dial, not a switch.") }).describe("Rank is stored on the entry and refreshed on a schedule, making my-rank a single point read.")]).describe("How rank is computed. `live` counts better entries per request — correct and free for small boards, and quadratic as they grow. `{ materialize }` trades rank staleness for cost and is the documented path past ~100k players; a player's own score stays live either way. See docs/costs.md before choosing.");
+const LeaderboardConfig = z.object({
+	boards: z.array(LeaderboardBoard).min(1, "A leaderboard capability with no boards does nothing — configure at least one.").describe("Every board this app ranks. The board set is config, not database rows."),
+	rank: LeaderboardRank.prefault("live").describe("How rank is computed across every board."),
+	serverAuthoritative: z.boolean().default(true).describe("Require the submit scope to post a score. On by default, inverting the vendor norm — every platform that offers server-authoritative writes ships it off. Leave it on and submit from your trusted server; turn it off only if you accept that a player's device can post any score it likes."),
+	submitScope: z.string().min(1).default("leaderboard:submit").describe("The AuthContext scope a session must carry to submit a score while `serverAuthoritative` is on. Mint it for your server's own token, never for a player's."),
+	adminScope: z.string().min(1).default("leaderboard:admin").describe("The AuthContext scope required to hide or remove another player's entry."),
+	visibleByDefault: z.boolean().default(true).describe("Whether a new entry appears on the board before the player says otherwise. Set false to make the board opt-in, so a player only shows up once they consent.")
+}).describe("Configuration for the leaderboard capability — the board set, how rank is computed, and who may write.").check((ctx) => {
+	const keys = ctx.value.boards.map((b) => b.key);
+	const duplicates = [...new Set(keys.filter((key, i) => keys.indexOf(key) !== i))];
+	if (duplicates.length > 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["boards"],
+		message: `Duplicate board keys: ${duplicates.join(", ")}. Two boards sharing a key would merge their entries.`
+	});
+	const rank = ctx.value.rank;
+	if (typeof rank === "object") try {
+		assertValidSchedule(rank.materialize);
+	} catch (error) {
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			path: ["rank", "materialize"],
+			message: `Invalid materialize schedule: ${error.message}`
+		});
+	}
+});
+/** The board with this key, or undefined. Board keys come from config, so an unknown key is a 404. */
+function resolveBoard(config, key) {
+	return config.boards.find((board) => board.key === key);
+}
+/** The rank refresh CRON, or undefined when rank is live and no refresh worker is needed. */
+function materializeSchedule(config) {
+	return typeof config.rank === "object" ? config.rank.materialize : void 0;
+}
+//#endregion
+export { LeaderboardBoard, LeaderboardConfig, LeaderboardRank, LeaderboardStore, LeaderboardTier, ScoreAggregation, ScoreDirection, materializeSchedule, resolveBoard };

package/dist/data/boardRecord.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * The recorded definition of a board that has started taking entries — the row in
+ * `pithy_leaderboard_boards`.
+ *
+ * Boards are config, not database rows, so this table holds no board *settings*. It holds only the three
+ * fields that may never change once a score exists, so that changing one in `pithy.config.ts` fails loudly
+ * instead of silently reinterpreting stored data:
+ *
+ *   - `direction` — flipping it turns every leader into a laggard.
+ *   - `aggregation` — switching `best` to `sum` makes existing rows mean something they never meant.
+ *   - `window` — a new schedule keys new scores into windows that do not line up with the stored ones.
+ *
+ * Every vendor surveyed treats these as create-time and immutable. Pithy cannot enforce that in the type
+ * system because the board set is config the adopter edits freely, so it enforces it here, on first write
+ * of each window, against what was actually recorded.
+ */
+export declare const LeaderboardBoardRecord: z.ZodObject<{
+    id: z.ZodNumber;
+    boardKey: z.ZodString;
+    store: z.ZodLiteral<"d1">;
+    direction: z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>;
+    aggregation: z.ZodEnum<{
+        best: "best";
+        latest: "latest";
+        sum: "sum";
+    }>;
+    window: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+}, z.core.$strip>;
+export type LeaderboardBoardRecord = z.output<typeof LeaderboardBoardRecord>;
+export type LeaderboardBoardRecordRow = z.input<typeof LeaderboardBoardRecord>;
+//# sourceMappingURL=boardRecord.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boardRecord.d.ts","sourceRoot":"","sources":["../../src/data/boardRecord.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;iBAaiE,CAAC;AACrG,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC7E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/data/boardRecord.js

@@ -0,0 +1,31 @@
+import { LeaderboardStore, ScoreAggregation, ScoreDirection } from "../config/config.js";
+import { z } from "zod";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/boardRecord.ts
+/**
+* The recorded definition of a board that has started taking entries — the row in
+* `pithy_leaderboard_boards`.
+*
+* Boards are config, not database rows, so this table holds no board *settings*. It holds only the three
+* fields that may never change once a score exists, so that changing one in `pithy.config.ts` fails loudly
+* instead of silently reinterpreting stored data:
+*
+*   - `direction` — flipping it turns every leader into a laggard.
+*   - `aggregation` — switching `best` to `sum` makes existing rows mean something they never meant.
+*   - `window` — a new schedule keys new scores into windows that do not line up with the stored ones.
+*
+* Every vendor surveyed treats these as create-time and immutable. Pithy cannot enforce that in the type
+* system because the board set is config the adopter edits freely, so it enforces it here, on first write
+* of each window, against what was actually recorded.
+*/
+const LeaderboardBoardRecord = z.object({
+	id: z.number().int().describe("Autoincrement primary key."),
+	boardKey: z.string().describe("The board key this definition belongs to. Unique — one record per board."),
+	store: LeaderboardStore.describe("The backing store recorded when this board took its first entry."),
+	direction: ScoreDirection.describe("The direction recorded when this board took its first entry."),
+	aggregation: ScoreAggregation.describe("The aggregation recorded when this board took its first entry."),
+	window: z.string().nullish().describe("The window CRON recorded when this board took its first entry; null on an all-time board."),
+	createdAt: SQLiteDate.describe("When this board first recorded an entry.")
+}).describe("The immutable fields of a board that has started recording entries — the drift guard.");
+//#endregion
+export { LeaderboardBoardRecord };

package/dist/data/entry.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/**
+ * One player's state on one board in one window — the row in `pithy_leaderboard_entries`.
+ *
+ * `z.output` is the app shape (Dates, booleans); `z.input` is the SQLite row (ms-epoch, 0|1). All
+ * JS↔SQLite conversion runs through the core codecs — no raw `0/1`, epoch, or `new Date()` in query code.
+ *
+ * The entry is keyed `(boardId, windowKey, userId)`: each window carries its own aggregation state rather
+ * than being a query-time filter over an append log. That is what makes `best` and `sum` expressible per
+ * window at all, and what keeps a read O(one row) instead of O(a player's whole history).
+ *
+ * `id` is an autoincrement integer, not a UUID: an entry id is never handed to a client or embedded in a
+ * URL — every route addresses an entry by its natural key — so there is nothing to enumerate.
+ */
+export declare const LeaderboardEntry: z.ZodObject<{
+    id: z.ZodNumber;
+    boardId: z.ZodString;
+    windowKey: z.ZodString;
+    userId: z.ZodString;
+    score: z.ZodNumber;
+    achievedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    submittedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+    visible: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+    hidden: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+    rank: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export type LeaderboardEntry = z.output<typeof LeaderboardEntry>;
+export type LeaderboardEntryRow = z.input<typeof LeaderboardEntry>;
+//# sourceMappingURL=entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/data/entry.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAqCyE,CAAC;AACvG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/data/entry.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+//#region src/data/entry.ts
+/**
+* One player's state on one board in one window — the row in `pithy_leaderboard_entries`.
+*
+* `z.output` is the app shape (Dates, booleans); `z.input` is the SQLite row (ms-epoch, 0|1). All
+* JS↔SQLite conversion runs through the core codecs — no raw `0/1`, epoch, or `new Date()` in query code.
+*
+* The entry is keyed `(boardId, windowKey, userId)`: each window carries its own aggregation state rather
+* than being a query-time filter over an append log. That is what makes `best` and `sum` expressible per
+* window at all, and what keeps a read O(one row) instead of O(a player's whole history).
+*
+* `id` is an autoincrement integer, not a UUID: an entry id is never handed to a client or embedded in a
+* URL — every route addresses an entry by its natural key — so there is nothing to enumerate.
+*/
+const LeaderboardEntry = z.object({
+	id: z.number().int().describe("Autoincrement primary key. Internal only; entries are addressed by natural key."),
+	boardId: z.string().describe("The board key this entry ranks on, from `boards` in pithy.config.ts."),
+	windowKey: z.string().describe("The window this entry belongs to: the ISO instant the board's CRON last fired at or before the score, or `all` on an all-time board."),
+	userId: z.string().describe("The authenticated player, from the core AuthContext seam. Never read from the request body — that would let any caller score as anyone."),
+	score: z.number().describe("The player's current score for this window, already folded by the board's aggregation."),
+	achievedAt: SQLiteDate.describe("When the current score was first reached. The primary tiebreak: on equal scores the player who got there first ranks higher."),
+	submittedAt: SQLiteDate.describe("When this entry was last written. Distinct from achievedAt — a submission that fails to improve a `best` board still touches this."),
+	visible: SQLiteBoolean.describe("Whether the player consents to appear. Gates every read, including friends and segment queries."),
+	hidden: SQLiteBoolean.describe("Whether an admin has hidden this entry. Distinct from `visible` so a moderator action cannot be undone by the player toggling their own consent."),
+	rank: z.number().int().nullish().describe("The materialized rank, refreshed by the rank worker. Null while rank is live, and null on a fresh entry until the next refresh pass reaches it.")
+}).describe("One player's entry on one board in one window — the row in `pithy_leaderboard_entries`.");
+//#endregion
+export { LeaderboardEntry };

package/dist/data/lock.d.ts

@@ -0,0 +1,18 @@
+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"}