@pithy-sh/leaderboard 0.1.0

package/src/config/config.ts

@@ -0,0 +1,261 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { assertValidSchedule } from "../window/schedule";
+import { BOARD_KEY_PATTERN } from "./boardKey";
+
+/**
+ * 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 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.",
+  );
+export type ScoreDirection = z.infer<typeof ScoreDirection>;
+
+export 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.",
+  );
+export type ScoreAggregation = z.infer<typeof ScoreAggregation>;
+
+export 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.",
+  );
+export type LeaderboardStore = z.infer<typeof LeaderboardStore>;
+
+export 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.");
+export type LeaderboardTier = z.infer<typeof LeaderboardTier>;
+
+export 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 !== undefined && max !== undefined && 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 !== undefined && retainDays !== undefined) {
+      // Both would need a union-or-intersection rule that the product ("keep N windows") and the
+      // compliance ("delete after N days") intents pull in opposite directions on. Forcing one keeps
+      // the meaning unambiguous.
+      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 !== undefined || retainDays !== undefined) && window === undefined) {
+      // An all-time board has one never-closing window; there is nothing for a window-based limit to
+      // prune, and age-based deletion of live entries is out of scope for v1.
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: [retainDays !== undefined ? "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 !== undefined) {
+      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 as Error).message}`,
+        });
+      }
+    }
+    if (tiers) {
+      // Worst-to-best in the board's direction: ascending thresholds on `desc`, descending on `asc`.
+      // An out-of-order tier is unreachable, and silently unreachable is worse than rejected.
+      for (let i = 1; i < tiers.length; i++) {
+        const previous = tiers[i - 1] as LeaderboardTier;
+        const current = tiers[i] as LeaderboardTier;
+        const improves = direction === "desc" ? current.from > previous.from : current.from < previous.from;
+        if (!improves) {
+          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.`,
+          });
+        }
+      }
+    }
+  });
+export type LeaderboardBoard = z.output<typeof LeaderboardBoard>;
+
+export 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.",
+  );
+export type LeaderboardRank = z.output<typeof LeaderboardRank>;
+
+export 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 as Error).message}`,
+        });
+      }
+    }
+  });
+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 function resolveBoard(config: LeaderboardConfig, key: string): LeaderboardBoard | undefined {
+  return config.boards.find((board) => board.key === key);
+}
+
+/** The rank refresh CRON, or undefined when rank is live and no refresh worker is needed. */
+export function materializeSchedule(config: LeaderboardConfig): string | undefined {
+  return typeof config.rank === "object" ? config.rank.materialize : undefined;
+}

package/src/data/boardRecord.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { LeaderboardStore, ScoreAggregation, ScoreDirection } from "../config/config";
+
+/**
+ * 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 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.");
+export type LeaderboardBoardRecord = z.output<typeof LeaderboardBoardRecord>;
+export type LeaderboardBoardRecordRow = z.input<typeof LeaderboardBoardRecord>;

package/src/data/entry.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+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 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`.");
+export type LeaderboardEntry = z.output<typeof LeaderboardEntry>;
+export type LeaderboardEntryRow = z.input<typeof LeaderboardEntry>;

package/src/data/lock.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+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 const LeaderboardLock = z
+  .object({
+    name: z.string().describe("The lock's identity — `rank-refresh` for the refresh pass. One row per name."),
+    holder: z.string().describe("A token unique to the instance currently holding the lock."),
+    acquiredAt: SQLiteDate.describe(
+      "When the current holder took the lock. A lock older than the stale horizon is treated as abandoned by a crashed instance and may be reclaimed.",
+    ),
+  })
+  .describe("One advisory lock in `pithy_leaderboard_locks`.");
+export type LeaderboardLock = z.output<typeof LeaderboardLock>;
+export type LeaderboardLockRow = z.input<typeof LeaderboardLock>;

package/src/data/tables.ts

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

package/src/entry/store.ts

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type SqlBool, sql } from "kysely";
+import type { LeaderboardBoard } from "../config/config";
+import { LeaderboardEntry } from "../data/entry";
+import { LEADERBOARD_ENTRIES_TABLE, type LeaderboardDatabase } from "../data/tables";
+
+/**
+ * Reads and writes over `pithy_leaderboard_entries`.
+ *
+ * Every write is one `INSERT … ON CONFLICT DO UPDATE` against the `(boardId, windowKey, userId)` unique
+ * index. Folding the aggregation into the conflict clause — rather than reading the row, deciding in JS,
+ * and writing it back — is what keeps a submission a single statement: D1 is single-threaded, so a
+ * read-then-write would both double the round trips and open a race where two submissions from the same
+ * player interleave and one silently wins.
+ *
+ * Round-trip rule (CLAUDE.md §Data layer): read with `LeaderboardEntry.parse` (decode), write with
+ * `LeaderboardEntry.encode` (encode). No raw `0/1` or epoch numbers below.
+ */
+export interface EntryStore {
+  /** Fold a submission into the player's entry for this window, per the board's aggregation. */
+  submit(
+    board: LeaderboardBoard,
+    windowKey: string,
+    userId: string,
+    score: number,
+    at: Date,
+    visibleByDefault: boolean,
+  ): Promise<void>;
+  /** The player's entry for this window, or undefined if they have never submitted. */
+  get(boardId: string, windowKey: string, userId: string): Promise<LeaderboardEntry | undefined>;
+  /** Set the player's own consent to appear. False if they have no entry. */
+  setVisibility(boardId: string, windowKey: string, userId: string, visible: boolean): Promise<boolean>;
+  /** Hide or unhide an entry as a moderator. False if they have no entry. */
+  hide(boardId: string, windowKey: string, userId: string, hidden: boolean): Promise<boolean>;
+  /** Delete an entry outright. False if they have no entry. */
+  remove(boardId: string, windowKey: string, userId: string): Promise<boolean>;
+  /** Delete entries on this board in windows chronologically before `cutoffWindow`. Returns rows deleted. */
+  pruneWindowsBefore(boardId: string, cutoffWindow: string): Promise<number>;
+}
+
+/**
+ * The submission upsert, as a compilable query.
+ *
+ * Exported so `writeAmplification.workers.test.ts` can compile the real statement and read D1's own
+ * `meta.rows_written` for it. The cost model in `scripts/costModel.ts` assumes a fixed number of rows
+ * written per submission, and that assumption is load-bearing for every figure in docs/costs.md — a test
+ * that measured a hand-written approximation of this SQL would only prove the approximation's cost.
+ */
+export function submitQuery(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  userId: string,
+  score: number,
+  at: Date,
+  visibleByDefault: boolean,
+) {
+  const insert = LeaderboardEntry.encode({
+    id: 0,
+    boardId: board.key,
+    windowKey,
+    userId,
+    score,
+    achievedAt: at,
+    submittedAt: at,
+    visible: visibleByDefault,
+    hidden: false,
+    rank: null,
+  }) as Record<string, unknown>;
+  // `id` is autoincrement — let SQLite assign it rather than inserting the placeholder above.
+  delete insert.id;
+
+  const entries = sql.table(LEADERBOARD_ENTRIES_TABLE);
+  const improves =
+    board.direction === "desc"
+      ? sql<SqlBool>`excluded.score > ${entries}.score`
+      : sql<SqlBool>`excluded.score < ${entries}.score`;
+
+  // On a `best` board with `trackActivity: false` (the default), a submission that does not beat the
+  // stored score should cost nothing. A `WHERE` on the conflict clause makes SQLite skip the row
+  // entirely — 0 rows written, versus 3 for a row it touches — which is the capability's biggest cost
+  // lever, since most submissions do not improve a player's best. `sum`/`latest` always change the
+  // score, so they always write and this guard never applies to them.
+  const guardNoOps = board.aggregation === "best" && !board.trackActivity;
+
+  const conflict = db
+    .insertInto(LEADERBOARD_ENTRIES_TABLE)
+    // biome-ignore lint/suspicious/noExplicitAny: the encoded row is the schema's `z.input` side; Kysely's insert type is derived from it.
+    .values(insert as any)
+    .onConflict((oc) => {
+      const updated = oc.columns(["boardId", "windowKey", "userId"]).doUpdateSet(() => {
+        // A submission advances submittedAt when it writes. With `trackActivity: false` a non-improving
+        // `best` submission is skipped by the guard below and never reaches here, so submittedAt tracks
+        // progress rather than activity. Neither the player's consent nor a moderator's hide is the
+        // submitter's to reset, so `visible` and `hidden` are absent from every branch.
+        const submittedAt = sql<number>`excluded.submitted_at`;
+        if (board.aggregation === "latest") {
+          return { submittedAt, score: sql<number>`excluded.score`, achievedAt: sql<number>`excluded.achieved_at` };
+        }
+        if (board.aggregation === "sum") {
+          return {
+            submittedAt,
+            score: sql<number>`${entries}.score + excluded.score`,
+            achievedAt: sql<number>`excluded.achieved_at`,
+          };
+        }
+        // `best`: take the new score only if it improves in the board's direction. On an equal score
+        // both branches keep the stored achievedAt, so a replay cannot cost a player the first-to-reach
+        // tiebreak they already earned.
+        return {
+          submittedAt,
+          score: sql<number>`CASE WHEN ${improves} THEN excluded.score ELSE ${entries}.score END`,
+          achievedAt: sql<number>`CASE WHEN ${improves} THEN excluded.achieved_at ELSE ${entries}.achieved_at END`,
+        };
+      });
+      return guardNoOps ? updated.where(improves) : updated;
+    });
+
+  return conflict;
+}
+
+export function entryStore(db: LeaderboardDatabase): EntryStore {
+  return {
+    async submit(board, windowKey, userId, score, at, visibleByDefault) {
+      await submitQuery(db, board, windowKey, userId, score, at, visibleByDefault).execute();
+    },
+
+    async get(boardId, windowKey, userId) {
+      const row = await db
+        .selectFrom(LEADERBOARD_ENTRIES_TABLE)
+        .selectAll()
+        .where("boardId", "=", boardId)
+        .where("windowKey", "=", windowKey)
+        .where("userId", "=", userId)
+        .executeTakeFirst();
+      return row ? LeaderboardEntry.parse(row) : undefined;
+    },
+
+    async setVisibility(boardId, windowKey, userId, visible) {
+      const result = await db
+        .updateTable(LEADERBOARD_ENTRIES_TABLE)
+        .set({ visible: LeaderboardEntry.shape.visible.encode(visible) })
+        .where("boardId", "=", boardId)
+        .where("windowKey", "=", windowKey)
+        .where("userId", "=", userId)
+        .executeTakeFirst();
+      return Number(result.numUpdatedRows) > 0;
+    },
+
+    async hide(boardId, windowKey, userId, hidden) {
+      const result = await db
+        .updateTable(LEADERBOARD_ENTRIES_TABLE)
+        .set({ hidden: LeaderboardEntry.shape.hidden.encode(hidden) })
+        .where("boardId", "=", boardId)
+        .where("windowKey", "=", windowKey)
+        .where("userId", "=", userId)
+        .executeTakeFirst();
+      return Number(result.numUpdatedRows) > 0;
+    },
+
+    async remove(boardId, windowKey, userId) {
+      const result = await db
+        .deleteFrom(LEADERBOARD_ENTRIES_TABLE)
+        .where("boardId", "=", boardId)
+        .where("windowKey", "=", windowKey)
+        .where("userId", "=", userId)
+        .executeTakeFirst();
+      return Number(result.numDeletedRows) > 0;
+    },
+
+    async pruneWindowsBefore(boardId, cutoffWindow) {
+      // Window keys are ISO instants, so `<` is chronological. `all` is never a windowed board's key, so
+      // an all-time window (which retention never targets) cannot be caught here.
+      const result = await db
+        .deleteFrom(LEADERBOARD_ENTRIES_TABLE)
+        .where("boardId", "=", boardId)
+        .where("windowKey", "<", cutoffWindow)
+        .executeTakeFirst();
+      return Number(result.numDeletedRows);
+    },
+  };
+}