@pithy-sh/leaderboard 0.1.2 → 0.1.4

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

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import type { D1Database } from "@cloudflare/workers-types";
+/**
+ * The leaderboard rank refresh, as a cron-triggered Cloudflare Workflow.
+ *
+ * Why a Workflow rather than a plain `scheduled()` pass: a Worker invocation is wall-clock bounded, so
+ * an earlier design capped each run at ~64k entries and re-ranked from the top every tick — a board
+ * bigger than that never fully ranked. A Workflow step has unlimited wall-clock and does not burn CPU
+ * while awaiting D1 (all our work is D1 I/O), so a board of any size ranks across a series of bounded,
+ * individually-durable steps. Each step checkpoints the keyset cursor; a crash resumes from the last
+ * completed step instead of restarting. The 64k ceiling is gone.
+ *
+ * At-most-one at a time: a refresh takes a D1 advisory lock before it starts and releases it when done.
+ * If a cron fires again while a refresh is still running (a cron faster than the refresh takes), the
+ * second instance cannot take the lock and skips — so two passes never interleave their chunked writes
+ * into an incoherent rank set. A crashed instance's lock ages out (see `lock.ts`) so the next fire
+ * reclaims it.
+ *
+ * Why it does NOT require a dedicated worker: this is a Workflow class plus a `scheduled()` handler plus
+ * one cron trigger. `pithy add leaderboard` deploys it as its own small worker by default (the template
+ * in `wrangler.jsonc`), but the same three pieces can be merged into the adopter's app worker — the
+ * capability contributes the Workflow through its manifest. A cron trigger is the one hard requirement;
+ * a separate worker is not.
+ *
+ * Cost: on Workers Paid this stays inside the free allowances at any realistic cadence — a run is a
+ * handful of steps (one prune + a few per board), storage is zero (all state is D1), and idle/awaiting
+ * steps incur no CPU. Even firing every minute is well under the 500k-steps/month and 10M-requests/month
+ * included tiers.
+ */
+interface RankWorkerEnv {
+    DB: D1Database;
+    /** The resolved leaderboard config, as JSON. The board set is config; this worker needs the same one. */
+    LEADERBOARD_CONFIG: string;
+    /** Optional override for how long a held refresh lock stays valid before it is reclaimed (see lock.ts). */
+    LEADERBOARD_LOCK_STALE_MS?: string;
+    /** The Workflow binding — this worker's own class, used by `scheduled()` to start an instance. */
+    RANK_REFRESH: {
+        create(options?: {
+            id?: string;
+        }): Promise<unknown>;
+    };
+}
+export declare class RankRefreshWorkflow extends WorkflowEntrypoint<RankWorkerEnv, unknown> {
+    run(_event: WorkflowEvent<unknown>, step: WorkflowStep): Promise<void>;
+}
+declare const _default: {
+    /**
+     * Cron entry: start one rank-refresh Workflow instance per fire. Each instance re-ranks from the top;
+     * the checkpointing is within an instance (resume on crash), not across fires (a fire is a fresh full
+     * refresh). If a fire lands while a previous refresh is still running, the new instance takes no lock
+     * and exits immediately, so overlapping instances never write concurrently — see the lock acquisition
+     * in `run()` above.
+     */
+    scheduled(_controller: unknown, env: RankWorkerEnv): Promise<void>;
+};
+export default _default;
+//# sourceMappingURL=worker.entry.d.ts.map

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

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

package/dist/rank/worker.entry.js

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { windowKeyAt } from "../window/schedule.js";
+import { LeaderboardConfig } from "../config/config.js";
+import { leaderboardDatabase } from "../data/tables.js";
+import { acquireRefreshLock, releaseRefreshLock } from "./lock.js";
+import { REFRESH_BATCH_CHUNKS, refreshWindowRanks } from "./materialize.js";
+import { leaderboardWorkflowRetry } from "./retryPolicy.js";
+import { pruneBoards } from "../retention/prune.js";
+import { materializedBoards } from "./worker.js";
+import { WorkflowEntrypoint } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+//#region src/rank/worker.entry.ts
+var RankRefreshWorkflow = class extends WorkflowEntrypoint {
+	async run(_event, step) {
+		const steps = classifiedSteps(step, leaderboardWorkflowRetry, NonRetryableError);
+		const config = LeaderboardConfig.parse(JSON.parse(this.env.LEADERBOARD_CONFIG));
+		const db = leaderboardDatabase(this.env.DB);
+		const staleMs = this.env.LEADERBOARD_LOCK_STALE_MS ? Number(this.env.LEADERBOARD_LOCK_STALE_MS) : void 0;
+		const ctx = await steps.do("refresh-context", async () => ({
+			holder: crypto.randomUUID(),
+			nowMs: Date.now()
+		}));
+		const now = new Date(ctx.nowMs);
+		if (!await acquireRefreshLock(db, ctx.holder, now, staleMs)) return;
+		try {
+			await steps.do("prune", () => pruneBoards(db, config.boards, now));
+			for (const board of materializedBoards(config)) {
+				const window = windowKeyAt(board.window, now);
+				let cursor = null;
+				let startRank = 0;
+				let batch = 0;
+				for (;;) {
+					const from = cursor ?? void 0;
+					const result = await steps.do(`refresh:${board.key}:${batch}`, () => refreshWindowRanks(db, board, window, {
+						maxChunks: REFRESH_BATCH_CHUNKS,
+						resumeAfter: from,
+						startRank
+					}));
+					if (result.complete) break;
+					cursor = result.cursor;
+					startRank = result.ranked;
+					batch += 1;
+					if (!cursor) break;
+				}
+			}
+		} finally {
+			await releaseRefreshLock(db, ctx.holder);
+		}
+	}
+};
+var worker_entry_default = { 
+/**
+* Cron entry: start one rank-refresh Workflow instance per fire. Each instance re-ranks from the top;
+* the checkpointing is within an instance (resume on crash), not across fires (a fire is a fresh full
+* refresh). If a fire lands while a previous refresh is still running, the new instance takes no lock
+* and exits immediately, so overlapping instances never write concurrently — see the lock acquisition
+* in `run()` above.
+*/
+async scheduled(_controller, env) {
+	await env.RANK_REFRESH.create();
+} };
+//#endregion
+export { RankRefreshWorkflow, worker_entry_default as default };

package/dist/rank/worker.js

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { windowKeyAt } from "../window/schedule.js";
+import { materializeSchedule } from "../config/config.js";
+import { leaderboardDatabase } from "../data/tables.js";
+import { refreshWindowRanks } from "./materialize.js";
+import { pruneBoards } from "../retention/prune.js";
+//#region src/rank/worker.ts
+/** The boards a refresh pass must rank: only materialized ones. Live boards compute rank per request. */
+function materializedBoards(config) {
+	return materializeSchedule(config) === void 0 ? [] : config.boards;
+}
+/**
+* **Every contributor here is degraded, and none of them is load-bearing (#371).**
+*
+* The sweep runs first so the refresh never spends a chunk ranking rows about to be deleted — an
+* efficiency, not a precondition. A board whose prune throws keeps its old rows a while longer and ranks
+* correctly regardless, so the sweep failing is no reason to leave every board's ranks stale. And boards
+* are independent of each other by construction: one board's entries, windows and ranks are its own, so a
+* board that will not rank has no claim on any other board's pass.
+*
+* So one sick board costs its own line. What it must never do is read as a board that ranked nobody.
+*/
+async function runRankPass(d1, config, now) {
+	const db = leaderboardDatabase(d1);
+	const pruned = await pruneBoards(db, config.boards, now);
+	const refreshed = [];
+	for (const board of materializedBoards(config)) {
+		const window = windowKeyAt(board.window, now);
+		let result;
+		try {
+			result = await refreshWindowRanks(db, board, window);
+		} catch {
+			refreshed.push({
+				state: "unavailable",
+				board: board.key,
+				window
+			});
+			continue;
+		}
+		refreshed.push({
+			state: "refreshed",
+			board: board.key,
+			window,
+			...result
+		});
+	}
+	return {
+		pruned,
+		refreshed
+	};
+}
+//#endregion
+export { materializedBoards, runRankPass };

package/dist/retention/prune.d.ts

@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { LeaderboardBoard } from "../config/config";
+import type { LeaderboardDatabase } from "../data/tables";
+export declare function pruneBoard(db: LeaderboardDatabase, board: LeaderboardBoard, now: Date): Promise<number>;
+/**
+ * What a sweep over several boards deleted, and whether every board was swept (#371).
+ *
+ * The count sits behind the discriminant rather than beside a list of failures. A sweep that skipped a
+ * board deleted fewer rows than a sweep that did not, and `{ deleted: 4 }` cannot tell those apart —
+ * so `partial` spells the number differently, and a caller reaches it only by having been told the
+ * sweep was short.
+ */
+export type PruneOutcome = {
+    /** Every board with a retention limit was swept. */
+    state: "pruned";
+    /** Rows deleted across them all. */
+    deleted: number;
+} | {
+    /** Some boards were swept and at least one threw. */
+    state: "partial";
+    /** What the boards that were swept deleted — a total with a known hole in it. */
+    counted: {
+        deleted: number;
+    };
+    /** The key of every board whose prune threw. Non-empty, or this would be `pruned`. */
+    unpruned: string[];
+};
+/**
+ * Prune every board that configures a retention limit.
+ *
+ * **One board at a time (#371).** Retention is per board and boards are independent, so a board whose
+ * prune throws — a window key its config disagrees with, a D1 that stopped answering mid-sweep — used to
+ * discard every deletion the sweep had already made and take the rank pass down with it. It now costs its
+ * own entry and nothing else, and the boards it did not reach are named.
+ *
+ * **The guard takes no binding.** What a D1 write throws is throw-site context about somebody's database.
+ * The board key is this capability's own configuration and is the only thing anybody can act on.
+ */
+export declare function pruneBoards(db: LeaderboardDatabase, boards: readonly LeaderboardBoard[], now: Date): Promise<PruneOutcome>;
+//# sourceMappingURL=prune.d.ts.map

package/dist/retention/prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../src/retention/prune.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAwB1D,wBAAsB,UAAU,CAAC,EAAE,EAAE,mBAAmB,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB7G;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,oDAAoD;IACpD,KAAK,EAAE,QAAQ,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,qDAAqD;IACrD,KAAK,EAAE,SAAS,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/retention/prune.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { previousWindowKeys, windowKeyAt } from "../window/schedule.js";
+import { entryStore } from "../entry/store.js";
+//#region src/retention/prune.ts
+/**
+* Retention: how long closed windows live.
+*
+* This is the capability's plainest expression of principle 1. Nothing in the market offers unbounded
+* leaderboard history — PlayFab meters retained versions and tier-gates them (its own tutorial defaults
+* to keeping one), and Game Center holds an expired occurrence about 30 days and says outright it is not
+* an archival store. Here, closed windows sit in the adopter's own D1 for exactly as long as they choose,
+* in plain SQL they can join against their own tables. And the default is to keep **everything**: storage
+* is never the cost driver (docs/costs.md — 3 GB at 10M players against a 10 GB cap), so nothing is
+* deleted unless the adopter asks. Retention here is about data hygiene and compliance, not cost.
+*
+* Two ways to ask, mutually exclusive per board (validated in config):
+*
+*   - `retain: N`     — keep the newest N closed windows. A product limit ("browse the last 12 weeks").
+*   - `retainDays: N` — delete windows whose data is older than N days. A compliance limit.
+*
+* An all-time board never closes a window, so retention does not apply to it.
+*/
+const DAY_MS = 864e5;
+async function pruneBoard(db, board, now) {
+	if (board.window === void 0) return 0;
+	if (board.retain !== void 0) {
+		const closed = previousWindowKeys(board.window, now, board.retain);
+		const oldestKept = closed.length > 0 ? closed[closed.length - 1] : windowKeyAt(board.window, now);
+		return entryStore(db).pruneWindowsBefore(board.key, oldestKept);
+	}
+	if (board.retainDays !== void 0) {
+		const cutoff = windowKeyAt(board.window, /* @__PURE__ */ new Date(now.getTime() - board.retainDays * DAY_MS));
+		return entryStore(db).pruneWindowsBefore(board.key, cutoff);
+	}
+	return 0;
+}
+/**
+* Prune every board that configures a retention limit.
+*
+* **One board at a time (#371).** Retention is per board and boards are independent, so a board whose
+* prune throws — a window key its config disagrees with, a D1 that stopped answering mid-sweep — used to
+* discard every deletion the sweep had already made and take the rank pass down with it. It now costs its
+* own entry and nothing else, and the boards it did not reach are named.
+*
+* **The guard takes no binding.** What a D1 write throws is throw-site context about somebody's database.
+* The board key is this capability's own configuration and is the only thing anybody can act on.
+*/
+async function pruneBoards(db, boards, now) {
+	let deleted = 0;
+	const unpruned = [];
+	for (const board of boards) try {
+		deleted += await pruneBoard(db, board, now);
+	} catch {
+		unpruned.push(board.key);
+	}
+	return unpruned.length === 0 ? {
+		state: "pruned",
+		deleted
+	} : {
+		state: "partial",
+		counted: { deleted },
+		unpruned
+	};
+}
+//#endregion
+export { pruneBoard, pruneBoards };

package/dist/seeds/example.d.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type SeedSet } from "@pithy-sh/core/src/seed/seed";
+/**
+ * A tiny demo board's worth of entries — the three canonical example users ({@link EXAMPLE_ADA} et al.)
+ * on an all-time board named `demo`. The `userId`s are the shared cast from `@pithy-sh/core`, so these
+ * scores belong to the same users `auth` seeds and `ledger`/`multiplayer` also reference: `pithy seed`
+ * fills a fresh backend with connected data, not isolated rows. Composed in only when the project turns
+ * on `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and `staging` — an example fixture
+ * never targets production, regardless of that setting.
+ */
+export declare const leaderboardExampleSeed: SeedSet;
+//# sourceMappingURL=example.d.ts.map

package/dist/seeds/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/seeds/example.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAcrF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,OA6CnC,CAAC"}

package/dist/seeds/example.js

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardEntry } from "../data/entry.js";
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables.js";
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed } from "@pithy-sh/core/src/seed/seed";
+//#region src/seeds/example.ts
+/**
+* Where the example set sorts among the whole project's seed registry. It runs after `auth` (100),
+* whose example seeds the users these entries belong to, so the owning identities exist first — the
+* order encodes that dependency, exactly like the migration registry. It need not line up with
+* {@link LEADERBOARD_MIGRATION_ORDER} (a different registry, composed separately by `pithy seed`).
+*/
+const LEADERBOARD_EXAMPLE_SEED_ORDER = 200;
+const now = () => /* @__PURE__ */ new Date();
+/**
+* A tiny demo board's worth of entries — the three canonical example users ({@link EXAMPLE_ADA} et al.)
+* on an all-time board named `demo`. The `userId`s are the shared cast from `@pithy-sh/core`, so these
+* scores belong to the same users `auth` seeds and `ledger`/`multiplayer` also reference: `pithy seed`
+* fills a fresh backend with connected data, not isolated rows. Composed in only when the project turns
+* on `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and `staging` — an example fixture
+* never targets production, regardless of that setting.
+*/
+const leaderboardExampleSeed = defineSeed({
+	name: "example",
+	order: LEADERBOARD_EXAMPLE_SEED_ORDER,
+	environments: ["dev", "staging"],
+	example: true,
+	d1: [d1SeedGroup("app", LEADERBOARD_ENTRIES_TABLE, LeaderboardEntry, [
+		{
+			id: 1,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_ADA.id,
+			score: 300,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		},
+		{
+			id: 2,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_GRACE.id,
+			score: 250,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		},
+		{
+			id: 3,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_ALAN.id,
+			score: 200,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		}
+	])]
+});
+//#endregion
+export { leaderboardExampleSeed };

package/dist/session/bookmark.d.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { D1Database } from "@cloudflare/workers-types";
+import { type LeaderboardDatabase } from "../data/tables";
+/**
+ * Read-your-own-writes across D1 read replication.
+ *
+ * D1 replicas "may be arbitrarily out of date" and Cloudflare publishes no staleness bound. On a
+ * leaderboard that lands exactly where a player notices: submit a score, read the board, and your own
+ * submission is missing. It reads as a lost write, not as replication lag, and it is the one
+ * inconsistency a ranking product cannot shrug off.
+ *
+ * The D1 Sessions API is the fix. Every query through a session is sequentially consistent with the
+ * session's bookmark, so threading a bookmark from a write to the player's next read guarantees they see
+ * themselves. The bookmark travels on {@link BOOKMARK_HEADER}: responses return the newest one, and a
+ * client echoes it back on the next request.
+ *
+ * The header is safe to expose and safe to ignore. It is an opaque replication watermark, not a
+ * credential — it carries no identity and grants nothing. A client that never echoes it is not broken,
+ * only unprotected against lag; a client that sends a stale or unparseable one is anchored no earlier
+ * than the write it names. Every route is authenticated regardless, so a bookmark cannot widen access.
+ */
+/** The header a bookmark travels on, in both directions. */
+export declare const BOOKMARK_HEADER = "x-pithy-d1-bookmark";
+/**
+ * Where a session with no bookmark starts.
+ *
+ * Writes anchor at the primary — a submission must land there, and the bookmark it returns is what makes
+ * the player's next read see it. Reads with no bookmark are unconstrained and may serve from any replica:
+ * that is the point of replication, and a reader who has not written has nothing of their own to miss.
+ */
+type SessionStart = "first-primary" | "first-unconstrained";
+export interface LeaderboardSession {
+    /** The Kysely database bound to this session. Every query through it is sequentially consistent. */
+    db: LeaderboardDatabase;
+    /** The newest bookmark across this session's queries, or null if it ran none. */
+    bookmark(): string | null;
+}
+/**
+ * Open a D1 session anchored at `bookmark` when the client sent one, or at `start` when it did not.
+ *
+ * An unparseable or expired bookmark is D1's to reject, not ours to pre-validate: it is opaque to us, and
+ * guessing at its shape here would just be a second place to get it wrong.
+ */
+export declare function leaderboardSession(d1: D1Database, bookmark: string | undefined, start: SessionStart): LeaderboardSession;
+/** The bookmark a client echoed back, or undefined. */
+export declare function readBookmark(headers: Headers): string | undefined;
+export {};
+//# sourceMappingURL=bookmark.d.ts.map

package/dist/session/bookmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookmark.d.ts","sourceRoot":"","sources":["../../src/session/bookmark.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,KAAK,mBAAmB,EAAuB,MAAM,gBAAgB,CAAC;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD;;;;;;GAMG;AACH,KAAK,YAAY,GAAG,eAAe,GAAG,qBAAqB,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,EAAE,EAAE,mBAAmB,CAAC;IACxB,iFAAiF;IACjF,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,YAAY,GAClB,kBAAkB,CAQpB;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEjE"}

package/dist/session/bookmark.js

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { leaderboardDatabase } from "../data/tables.js";
+//#region src/session/bookmark.ts
+/**
+* Read-your-own-writes across D1 read replication.
+*
+* D1 replicas "may be arbitrarily out of date" and Cloudflare publishes no staleness bound. On a
+* leaderboard that lands exactly where a player notices: submit a score, read the board, and your own
+* submission is missing. It reads as a lost write, not as replication lag, and it is the one
+* inconsistency a ranking product cannot shrug off.
+*
+* The D1 Sessions API is the fix. Every query through a session is sequentially consistent with the
+* session's bookmark, so threading a bookmark from a write to the player's next read guarantees they see
+* themselves. The bookmark travels on {@link BOOKMARK_HEADER}: responses return the newest one, and a
+* client echoes it back on the next request.
+*
+* The header is safe to expose and safe to ignore. It is an opaque replication watermark, not a
+* credential — it carries no identity and grants nothing. A client that never echoes it is not broken,
+* only unprotected against lag; a client that sends a stale or unparseable one is anchored no earlier
+* than the write it names. Every route is authenticated regardless, so a bookmark cannot widen access.
+*/
+/** The header a bookmark travels on, in both directions. */
+const BOOKMARK_HEADER = "x-pithy-d1-bookmark";
+/**
+* Open a D1 session anchored at `bookmark` when the client sent one, or at `start` when it did not.
+*
+* An unparseable or expired bookmark is D1's to reject, not ours to pre-validate: it is opaque to us, and
+* guessing at its shape here would just be a second place to get it wrong.
+*/
+function leaderboardSession(d1, bookmark, start) {
+	const session = d1.withSession(bookmark ?? start);
+	return {
+		db: leaderboardDatabase(session),
+		bookmark: () => session.getBookmark()
+	};
+}
+/** The bookmark a client echoed back, or undefined. */
+function readBookmark(headers) {
+	return headers.get("x-pithy-d1-bookmark")?.trim() || void 0;
+}
+//#endregion
+export { BOOKMARK_HEADER, leaderboardSession, readBookmark };

package/dist/version.generated.d.ts

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/** This package's npm name — the join key against a release feed. */
+export declare const PACKAGE_NAME = "@pithy-sh/leaderboard";
+/** This package's version, stamped from its own package.json at generation time. */
+export declare const PACKAGE_VERSION = "0.1.4";
+//# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAEpD,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/version.generated.js

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/version.generated.ts
+/** This package's npm name — the join key against a release feed. */
+const PACKAGE_NAME = "@pithy-sh/leaderboard";
+/** This package's version, stamped from its own package.json at generation time. */
+const PACKAGE_VERSION = "0.1.4";
+//#endregion
+export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/window/schedule.d.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * Window keys. A board's `window` is a CRON expression; the window a score falls into is keyed by the
+ * instant that CRON last fired at or before the score. Omitting the schedule means one all-time window.
+ *
+ * CRON — rather than a fixed `daily|weekly|monthly|all-time` enum — is what lets a board align to the
+ * calendar. Apple caps leaderboard recurrence at 30 days and expresses it as a fixed duration, so a
+ * calendar month (28/29/30/31 days) is not expressible there and a calendar year is impossible; Google
+ * Play Games Services ships daily/weekly/all-time and no monthly at all. `0 0 1 * *` and `0 0 1 1 *`
+ * cost us nothing extra because `rank: { materialize: <cron> }` already needs a parser.
+ *
+ * Every derivation is UTC-anchored. The host's local timezone must never move a window boundary, or the
+ * same submission would key differently on two Workers.
+ */
+/** The window key for a board with no schedule: one window, open forever. */
+export declare const ALL_TIME_WINDOW = "all";
+/**
+ * Validate a board's schedule at config time, so a typo fails at assembly rather than on the first
+ * submission. An expression that parses but never fires (`0 0 30 2 *` — February 30) is rejected too:
+ * it would strand every score with no window to key it to.
+ */
+export declare function assertValidSchedule(schedule: string): void;
+/** The key of the window `at` falls into: the ISO instant the board's CRON last fired at or before it. */
+export declare function windowKeyAt(schedule: string | undefined, at: Date): string;
+/**
+ * The keys of the `count` windows closed behind the one `at` falls into, newest first. Retention prunes
+ * everything older than the last of these.
+ */
+export declare function previousWindowKeys(schedule: string | undefined, at: Date, count: number): string[];
+//# sourceMappingURL=schedule.d.ts.map

package/dist/window/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/window/schedule.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,eAAe,QAAQ,CAAC;AAuDrC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ1D;AAED,0GAA0G;AAC1G,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAS1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAYlG"}

package/dist/window/schedule.js

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { LeaderboardInvalidScheduleError } from "../error/errors.js";
+import { Cron } from "croner";
+//#region src/window/schedule.ts
+/**
+* Window keys. A board's `window` is a CRON expression; the window a score falls into is keyed by the
+* instant that CRON last fired at or before the score. Omitting the schedule means one all-time window.
+*
+* CRON — rather than a fixed `daily|weekly|monthly|all-time` enum — is what lets a board align to the
+* calendar. Apple caps leaderboard recurrence at 30 days and expresses it as a fixed duration, so a
+* calendar month (28/29/30/31 days) is not expressible there and a calendar year is impossible; Google
+* Play Games Services ships daily/weekly/all-time and no monthly at all. `0 0 1 * *` and `0 0 1 1 *`
+* cost us nothing extra because `rank: { materialize: <cron> }` already needs a parser.
+*
+* Every derivation is UTC-anchored. The host's local timezone must never move a window boundary, or the
+* same submission would key differently on two Workers.
+*/
+/** The window key for a board with no schedule: one window, open forever. */
+const ALL_TIME_WINDOW = "all";
+/**
+* Lookback rungs for {@link lastFireAtOrBefore}, smallest first.
+*
+* croner can only walk *forward* (`nextRun`); its `previousRun` reports a live job's last execution, not
+* a historical period start, so finding the window a past instant falls into means searching back. The
+* ladder keeps that search cheap for every cadence: a rung is tried only if the finer one found no fire,
+* so a per-minute board settles on the first rung after one step and a yearly board reaches the last rung
+* having walked one. That bounds the forward walk to roughly one period per rung instead of letting a
+* frequent board enumerate a year of fires. The final rung spans four years: `0 0 29 2 *` — a leap-day
+* board — only fires when February has 29 days.
+*/
+const MINUTE_MS = 6e4;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+const LOOKBACK_LADDER_MS = [
+	MINUTE_MS,
+	HOUR_MS,
+	DAY_MS,
+	8 * DAY_MS,
+	40 * DAY_MS,
+	400 * DAY_MS,
+	1500 * DAY_MS
+];
+/** How far ahead {@link assertValidSchedule} looks for a fire before calling an expression dead. */
+const NEVER_FIRES_HORIZON = LOOKBACK_LADDER_MS[LOOKBACK_LADDER_MS.length - 1];
+function compile(schedule) {
+	try {
+		return new Cron(schedule, { timezone: "UTC" });
+	} catch (cause) {
+		throw new LeaderboardInvalidScheduleError({ detail: `Board schedule ${JSON.stringify(schedule)} is not a valid CRON expression.` }, { cause });
+	}
+}
+/**
+* The latest fire at or before `at`, or null if the ladder's deepest rung found none.
+*
+* An instant exactly on a boundary belongs to the window it opens, not the one it closes — hence
+* `<= target` rather than `<`. Off by one here and a score landing precisely on the boundary files into
+* the window that just closed.
+*/
+function lastFireAtOrBefore(cron, at) {
+	const target = at.getTime();
+	for (const lookback of LOOKBACK_LADDER_MS) {
+		let candidate = null;
+		let cursor = cron.nextRun(new Date(target - lookback));
+		while (cursor && cursor.getTime() <= target) {
+			candidate = cursor;
+			cursor = cron.nextRun(cursor);
+		}
+		if (candidate) return candidate;
+	}
+	return null;
+}
+/**
+* Validate a board's schedule at config time, so a typo fails at assembly rather than on the first
+* submission. An expression that parses but never fires (`0 0 30 2 *` — February 30) is rejected too:
+* it would strand every score with no window to key it to.
+*/
+function assertValidSchedule(schedule) {
+	if (!compile(schedule).nextRun(new Date(Date.now() - NEVER_FIRES_HORIZON))) throw new LeaderboardInvalidScheduleError({
+		message: "That board's window schedule never fires.",
+		detail: `Board schedule ${JSON.stringify(schedule)} parses but never fires, so no window could ever open.`
+	});
+}
+/** The key of the window `at` falls into: the ISO instant the board's CRON last fired at or before it. */
+function windowKeyAt(schedule, at) {
+	if (schedule === void 0) return "all";
+	const start = lastFireAtOrBefore(compile(schedule), at);
+	if (!start) throw new LeaderboardInvalidScheduleError({ detail: `Board schedule ${JSON.stringify(schedule)} has no fire at or before ${at.toISOString()}.` });
+	return start.toISOString();
+}
+/**
+* The keys of the `count` windows closed behind the one `at` falls into, newest first. Retention prunes
+* everything older than the last of these.
+*/
+function previousWindowKeys(schedule, at, count) {
+	if (schedule === void 0 || count <= 0) return [];
+	const cron = compile(schedule);
+	const keys = [];
+	let cursor = lastFireAtOrBefore(cron, at);
+	for (let i = 0; i < count; i++) {
+		if (!cursor) break;
+		cursor = lastFireAtOrBefore(cron, /* @__PURE__ */ new Date(cursor.getTime() - 1));
+		if (cursor) keys.push(cursor.toISOString());
+	}
+	return keys;
+}
+//#endregion
+export { ALL_TIME_WINDOW, assertValidSchedule, previousWindowKeys, windowKeyAt };