@pithy-sh/leaderboard 0.1.0

package/src/retention/prune.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LeaderboardBoard } from "../config/config";
+import type { LeaderboardDatabase } from "../data/tables";
+import { entryStore } from "../entry/store";
+import { previousWindowKeys, windowKeyAt } from "../window/schedule";
+
+/**
+ * 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 = 24 * 60 * 60 * 1000;
+
+export async function pruneBoard(db: LeaderboardDatabase, board: LeaderboardBoard, now: Date): Promise<number> {
+  if (board.window === undefined) return 0;
+
+  if (board.retain !== undefined) {
+    // Keep the open window plus the newest `retain` closed ones. The kept set is a contiguous newest
+    // suffix, so "delete everything not kept" is exactly "delete everything older than the oldest kept
+    // window" — a cutoff delete with two bound parameters, rather than a `NOT IN` list that would blow
+    // D1's 100-bound-parameter cap once `retain` reaches ~98 (a daily board keeping a year is retain 365).
+    const closed = previousWindowKeys(board.window, now, board.retain);
+    const oldestKept = closed.length > 0 ? (closed[closed.length - 1] as string) : windowKeyAt(board.window, now);
+    return entryStore(db).pruneWindowsBefore(board.key, oldestKept);
+  }
+
+  if (board.retainDays !== undefined) {
+    // Keep the window that was open `retainDays` ago and everything newer: that window is the oldest one
+    // whose tail is still within the retention horizon. Its key is the cutoff — delete windows before it.
+    // Window keys are ISO instants, so a lexicographic `<` is a chronological one.
+    const cutoff = windowKeyAt(board.window, new Date(now.getTime() - board.retainDays * DAY_MS));
+    return entryStore(db).pruneWindowsBefore(board.key, cutoff);
+  }
+
+  // Neither limit set: keep everything. The default.
+  return 0;
+}
+
+/**
+ * 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 async function pruneBoards(
+  db: LeaderboardDatabase,
+  boards: readonly LeaderboardBoard[],
+  now: Date,
+): Promise<PruneOutcome> {
+  let deleted = 0;
+  const unpruned: string[] = [];
+  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 };
+}

package/src/seeds/example.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { LeaderboardEntry } from "../data/entry";
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables";
+
+/**
+ * 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 = () => 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.
+ */
+export const leaderboardExampleSeed: SeedSet = 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,
+      },
+    ]),
+  ],
+});

package/src/session/bookmark.ts

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database, D1DatabaseSession } from "@cloudflare/workers-types";
+import { type LeaderboardDatabase, 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 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 function leaderboardSession(
+  d1: D1Database,
+  bookmark: string | undefined,
+  start: SessionStart,
+): LeaderboardSession {
+  const session: D1DatabaseSession = d1.withSession(bookmark ?? start);
+  return {
+    // kysely-d1 drives the database through `prepare` alone, which a session provides — so a session
+    // stands in for the binding without the dialect knowing the difference.
+    db: leaderboardDatabase(session as unknown as D1Database),
+    bookmark: () => session.getBookmark(),
+  };
+}
+
+/** The bookmark a client echoed back, or undefined. */
+export function readBookmark(headers: Headers): string | undefined {
+  return headers.get(BOOKMARK_HEADER)?.trim() || undefined;
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/leaderboard knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/leaderboard";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";

package/src/window/schedule.ts

@@ -0,0 +1,120 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Cron } from "croner";
+import { LeaderboardInvalidScheduleError } from "../error/errors";
+
+/**
+ * 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 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 = 60_000;
+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] as number;
+
+function compile(schedule: string): Cron {
+  try {
+    // `timezone: "UTC"` is the anchor: without it croner resolves against the host zone and a board
+    // boundary would drift by the deployment's offset.
+    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: Cron, at: Date): Date | null {
+  const target = at.getTime();
+  for (const lookback of LOOKBACK_LADDER_MS) {
+    let candidate: Date | null = null;
+    let cursor: Date | null = 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.
+ */
+export function assertValidSchedule(schedule: string): void {
+  const cron = compile(schedule);
+  if (!cron.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. */
+export function windowKeyAt(schedule: string | undefined, at: Date): string {
+  if (schedule === undefined) return ALL_TIME_WINDOW;
+  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.
+ */
+export function previousWindowKeys(schedule: string | undefined, at: Date, count: number): string[] {
+  if (schedule === undefined || count <= 0) return [];
+  const cron = compile(schedule);
+  const keys: string[] = [];
+  let cursor = lastFireAtOrBefore(cron, at);
+  for (let i = 0; i < count; i++) {
+    if (!cursor) break;
+    // Step one millisecond behind this window's start to land inside the window before it.
+    cursor = lastFireAtOrBefore(cron, new Date(cursor.getTime() - 1));
+    if (cursor) keys.push(cursor.toISOString());
+  }
+  return keys;
+}