@pithy-sh/leaderboard 0.1.0

package/src/http/schemas.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { BOARD_KEY_PATTERN } from "../config/boardKey";
+import { MAX_SEGMENT_SIZE } from "../rank/segment";
+
+/**
+ * The HTTP boundary shapes. Everything a client can send is parsed through one of these before it
+ * reaches a handler — declared on the route line with `zValidator(target, Schema, validationHook)`, so
+ * reading a route tells you what it takes.
+ *
+ * Note what is absent from {@link SubmitScoreBody}: `userId`, `achievedAt`, and `rank`. The player comes
+ * from the AuthContext seam, the clock comes from the server, and the rank is derived — a client that
+ * could set any of them could score as someone else, backdate its way past the tiebreak, or simply
+ * declare itself first. Server-authoritative is not only about who may call submit; it is about which
+ * fields a caller may name at all.
+ */
+
+/** A player id is opaque to us — it comes from the adopter's auth provider — so it is bounded, not shaped. */
+const MAX_USER_ID_LENGTH = 256;
+
+export const BoardParam = z
+  .object({
+    board: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(BOARD_KEY_PATTERN, "A board key is lowercase, digits, and dashes — it is a URL path segment.")
+      .describe(
+        "Which board the route addresses. A shape check only: the same pattern config already enforces on every board key, so nothing that resolves today is rejected. Whether the key is *configured* stays the handler's 404.",
+      ),
+  })
+  .describe("The board a `/leaderboard/:board` route addresses.");
+export type BoardParam = z.infer<typeof BoardParam>;
+
+export const EntryParam = BoardParam.extend({
+  userId: z
+    .string()
+    .min(1)
+    .max(MAX_USER_ID_LENGTH)
+    .describe(
+      "The player whose entry a moderation route targets. Bounded in length, not in charset — player ids are minted by your auth provider, so we cap what reaches the store rather than guess its format.",
+    ),
+}).describe("The board and player a moderation route addresses.");
+export type EntryParam = z.infer<typeof EntryParam>;
+
+export const SubmitScoreBody = z
+  .object({
+    score: z
+      .number()
+      .finite()
+      .describe("The score to submit. Folded into the player's entry by the board's aggregation."),
+  })
+  .describe("A score submission. The player, the window, and the timestamp are all server-derived.");
+export type SubmitScoreBody = z.infer<typeof SubmitScoreBody>;
+
+export const WindowQuery = z
+  .object({
+    window: z
+      .string()
+      .optional()
+      .describe(
+        "Which window to read — the ISO key of a closed window, or omit for the one open now. Reading your own history is the point: these windows live in your D1 for as long as `retain` says, which no platform SDK offers.",
+      ),
+  })
+  .describe("Selects the window a read applies to.");
+export type WindowQuery = z.infer<typeof WindowQuery>;
+
+export const TopQuery = WindowQuery.extend({
+  limit: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20)
+    .describe("How many entries to return, capped at 100 — a page, not the whole board."),
+  offset: z.coerce.number().int().min(0).default(0).describe("How many entries to skip. Ranks number from here."),
+}).describe("A page of a board, best first.");
+export type TopQuery = z.infer<typeof TopQuery>;
+
+export const AroundQuery = WindowQuery.extend({
+  radius: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(25)
+    .default(5)
+    .describe("How many entries to return either side of the player."),
+}).describe("The slice of a board centered on the calling player.");
+export type AroundQuery = z.infer<typeof AroundQuery>;
+
+export const SegmentBody = z
+  .object({
+    userIds: z
+      .array(z.string().min(1))
+      .min(1)
+      .max(
+        MAX_SEGMENT_SIZE,
+        `A segment is capped at ${MAX_SEGMENT_SIZE} players: D1 allows 100 bound parameters per query and each member costs one.`,
+      )
+      .describe(
+        "The players to rank among — a friends list or any cohort. A collection dimension over the same store, not a second board.",
+      ),
+    limit: z.number().int().min(1).max(100).default(20).describe("How many entries to return."),
+    offset: z.number().int().min(0).default(0).describe("How many entries to skip."),
+    window: z.string().optional().describe("Which window to read; omit for the one open now."),
+  })
+  .describe("A friends or cohort view of a board.");
+export type SegmentBody = z.infer<typeof SegmentBody>;
+
+export const VisibilityBody = z
+  .object({
+    visible: z
+      .boolean()
+      .describe("Whether this player consents to appear on the board. Gates every read, including segments."),
+  })
+  .describe("A player's own consent to be shown. Theirs to set — a submission never resets it.");
+export type VisibilityBody = z.infer<typeof VisibilityBody>;
+
+export const HideBody = z
+  .object({
+    hidden: z.boolean().describe("Whether to hide this entry from every read. The score is kept, not deleted."),
+  })
+  .describe("A moderator's hide toggle. Separate from player consent so a player cannot undo it.");
+export type HideBody = z.infer<typeof HideBody>;

package/src/index.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add leaderboard` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, and the read shapes an app renders. Every
+ * other module is imported by deep path (`@pithy-sh/leaderboard/src/...`); this is the documented
+ * contract, not a barrel over the package.
+ */
+
+export {
+  isLeaderboardCapability,
+  LEADERBOARD_MIGRATION_ORDER,
+  type LeaderboardCapability,
+  type LeaderboardOptions,
+  leaderboard,
+  needsRankWorker,
+} from "./capability";
+export {
+  LeaderboardBoard,
+  LeaderboardConfig,
+  type LeaderboardConfigInput,
+  LeaderboardRank,
+  LeaderboardStore,
+  LeaderboardTier,
+  materializeSchedule,
+  resolveBoard,
+  ScoreAggregation,
+  ScoreDirection,
+} from "./config/config";
+export { LeaderboardEntry } from "./data/entry";
+export type { OwnRank } from "./http/handlers";
+export type { RankedEntry } from "./rank/query";
+export { MAX_SEGMENT_SIZE } from "./rank/segment";
+export { classifyTier } from "./rank/tiers";
+export { BOOKMARK_HEADER } from "./session/bookmark";
+export { ALL_TIME_WINDOW, previousWindowKeys, windowKeyAt } from "./window/schedule";

package/src/migrations/0001_entries.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The leaderboard tables: player entries, and the board drift guard.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+ */
+export const leaderboard_0001_entries: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyLeaderboardEntries")
+      // Plain INTEGER PRIMARY KEY (a rowid alias), deliberately NOT autoincrement. It still auto-assigns
+      // ascending ids; autoincrement would only add a never-reuse-a-deleted-id guarantee we do not need
+      // (the id is internal, never exposed) and would cost an extra `sqlite_sequence` row write on every
+      // insert — and even on a guarded no-op upsert, since SQLite reserves the sequence value before it
+      // detects the conflict. Dropping it makes a non-improving submission truly free.
+      .addColumn("id", "integer", (c) => c.primaryKey())
+      .addColumn("boardId", "text", (c) => c.notNull())
+      .addColumn("windowKey", "text", (c) => c.notNull())
+      .addColumn("userId", "text", (c) => c.notNull())
+      .addColumn("score", "real", (c) => c.notNull())
+      .addColumn("achievedAt", "integer", (c) => c.notNull())
+      .addColumn("submittedAt", "integer", (c) => c.notNull())
+      .addColumn("visible", "integer", (c) => c.notNull().defaultTo(1))
+      .addColumn("hidden", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("rank", "integer")
+      .execute();
+
+    // One entry per player per window: the key the upsert-on-improve conflict target needs, and the
+    // reason a window carries aggregation state rather than being a filter over an append log.
+    await db.schema
+      .createIndex("pithyLeaderboardEntriesPlayerIdx")
+      .on("pithyLeaderboardEntries")
+      .columns(["boardId", "windowKey", "userId"])
+      .unique()
+      .execute();
+
+    // The ranking index. The ranking keys come LAST, after the equality-matched board and window:
+    // SQLite uses a multi-column index only on a left-prefix subset, so a score-first index would sit
+    // unused behind `board_id = ? AND window_key = ?`. The sort directions are deliberately mixed
+    // (score DESC, achievedAt ASC on a `desc` board) because the tiebreak is earliest-achieved-wins;
+    // that defeats SQLite's row-value comparison shortcut, so the rank predicate is spelled out as
+    // `score > ? OR (score = ? AND achieved_at < ?) OR (...)` instead. `rank/plan.workers.test.ts`
+    // reads EXPLAIN QUERY PLAN to prove this index is actually chosen rather than assuming it.
+    await db.schema
+      .createIndex("pithyLeaderboardEntriesRankIdx")
+      .on("pithyLeaderboardEntries")
+      .columns(["boardId", "windowKey", "score", "achievedAt"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyLeaderboardBoards")
+      // Plain INTEGER PRIMARY KEY, not autoincrement — same reasoning as the entries table.
+      .addColumn("id", "integer", (c) => c.primaryKey())
+      .addColumn("boardKey", "text", (c) => c.notNull().unique())
+      .addColumn("store", "text", (c) => c.notNull().defaultTo("d1"))
+      .addColumn("direction", "text", (c) => c.notNull())
+      .addColumn("aggregation", "text", (c) => c.notNull())
+      .addColumn("window", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // A single-row advisory lock so at most one rank-refresh Workflow instance runs at a time. Without
+    // it, a cron that fires again before a refresh finishes would run two passes concurrently, and their
+    // chunked writes would interleave into an incoherent rank set (duplicate/gapped numbers) until the
+    // next fire. `name` is the lock's identity ("rank-refresh"); `holder` is the acquiring instance's
+    // token; `acquiredAt` lets a stale lock from a crashed instance be reclaimed.
+    await db.schema
+      .createTable("pithyLeaderboardLocks")
+      .addColumn("name", "text", (c) => c.primaryKey())
+      .addColumn("holder", "text", (c) => c.notNull())
+      .addColumn("acquiredAt", "integer", (c) => c.notNull())
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropTable("pithyLeaderboardLocks").execute();
+    await db.schema.dropTable("pithyLeaderboardBoards").execute();
+    await db.schema.dropIndex("pithyLeaderboardEntriesRankIdx").execute();
+    await db.schema.dropIndex("pithyLeaderboardEntriesPlayerIdx").execute();
+    await db.schema.dropTable("pithyLeaderboardEntries").execute();
+  },
+};

package/src/rank/lock.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { LeaderboardLock } from "../data/lock";
+import { LEADERBOARD_LOCKS_TABLE, type LeaderboardDatabase } from "../data/tables";
+
+/**
+ * The rank-refresh advisory lock: at most one refresh runs at a time.
+ *
+ * Why it exists: the materialize refresh writes ranks in chunks, not atomically. If a cron fired again
+ * before a refresh finished, two passes would run concurrently and their chunked writes would interleave
+ * into an incoherent rank set — duplicate or gapped rank numbers — until the next fire corrected it. The
+ * lock serializes them: a second instance that cannot acquire it simply skips, and the pass it would have
+ * done is redundant anyway (the holder is already producing fresh ranks).
+ *
+ * The lock lives in D1, not in DO or KV, because the refresh already has the `DB` binding and D1's
+ * single-threaded execution makes the acquire genuinely atomic — the whole point.
+ */
+
+/** The one lock name the refresh uses. A single-row lock; there is no per-board locking. */
+export const REFRESH_LOCK = "rank-refresh";
+
+/**
+ * How long a held lock stays valid before it is treated as abandoned by a crashed instance.
+ *
+ * A refresh that finishes releases the lock immediately, so this only matters when an instance dies
+ * mid-pass. It must be comfortably longer than any real refresh so a slow-but-alive instance is never
+ * stolen from; one hour is far past the ~5-minute worst case at the ~1M-player shard boundary. Override
+ * with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that.
+ */
+export const DEFAULT_LOCK_STALE_MS = 60 * 60 * 1000;
+
+/**
+ * Try to take the refresh lock for `holder`, returning whether it was acquired.
+ *
+ * Atomic on D1's single thread: the upsert either inserts the row (no holder yet) or, on conflict, takes
+ * it over only if the current holder's lock is older than `staleMs` — a fresh lock is left untouched.
+ * A concurrent second caller therefore either finds no row and loses the insert race, or finds a fresh
+ * lock and is refused by the `WHERE`. Either way it reads back a `holder` that is not its own and knows
+ * to stand down.
+ */
+export async function acquireRefreshLock(
+  db: LeaderboardDatabase,
+  holder: string,
+  now: Date,
+  staleMs: number = DEFAULT_LOCK_STALE_MS,
+): Promise<boolean> {
+  const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - staleMs));
+  const row = LeaderboardLock.encode({ name: REFRESH_LOCK, holder, acquiredAt: now });
+
+  await db
+    .insertInto(LEADERBOARD_LOCKS_TABLE)
+    // biome-ignore lint/suspicious/noExplicitAny: the encoded row is the schema's `z.input` side.
+    .values(row as any)
+    .onConflict((oc) =>
+      oc
+        .column("name")
+        .doUpdateSet({ holder, acquiredAt: LeaderboardLock.shape.acquiredAt.encode(now) })
+        // Take over only an abandoned lock; a live holder's row is left as-is.
+        .where("pithyLeaderboardLocks.acquiredAt", "<", staleBefore),
+    )
+    .execute();
+
+  const current = await db
+    .selectFrom(LEADERBOARD_LOCKS_TABLE)
+    .select("holder")
+    .where("name", "=", REFRESH_LOCK)
+    .executeTakeFirst();
+  return current?.holder === holder;
+}
+
+/** Release the lock if `holder` still holds it. A no-op if it was already reclaimed or released. */
+export async function releaseRefreshLock(db: LeaderboardDatabase, holder: string): Promise<void> {
+  await db.deleteFrom(LEADERBOARD_LOCKS_TABLE).where("name", "=", REFRESH_LOCK).where("holder", "=", holder).execute();
+}

package/src/rank/materialize.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { boundParameterBudget, chunkRowsByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { sql } from "kysely";
+import type { LeaderboardBoard } from "../config/config";
+import { LEADERBOARD_ENTRIES_TABLE, type LeaderboardDatabase } from "../data/tables";
+
+/**
+ * The rank refresh pass — what `rank: { materialize }` buys and what it costs.
+ *
+ * A full-table rank rewrite is the obvious implementation and the wrong one. D1 executes one query at a
+ * time per database and caps a query at 30 seconds; a single `UPDATE` over a large board would hold the
+ * only thread for its whole duration and risk the documented `overloaded` error for every live
+ * submission behind it. So the pass is chunked: many small, bounded statements the runtime can
+ * interleave with real traffic.
+ *
+ * A chunk is a **pacing** unit: how much of the board one keyset step walks, kept well inside D1's
+ * 30-second per-query limit. It is no longer also the width of a statement — the bulk update sizes
+ * itself against D1's bound-parameter cap through core's arithmetic, so a chunk of any size is written
+ * in as many statements as it takes. That separation is the fix for #250: `chunkSize` was unvalidated,
+ * and `chunkSize: 40` bound 120 and broke the pass with no warning that a limit was even involved.
+ *
+ * Chunks walk the board by keyset, not by `OFFSET`: an offset page makes SQLite count past every row it
+ * skips, so an offset walk is quadratic in billed rows — the very cost `materialize` exists to avoid.
+ *
+ * Cloudflare documents no rank-materialization pattern. All of this is adopter-built, which is exactly
+ * why it lives in the package instead of in every adopter's repo.
+ */
+
+/**
+ * What one ranked row costs the bulk update: `WHEN id`, `THEN rank`, and the id again in the `IN` list.
+ *
+ * The cap itself is not restated here. It was, and a second copy of a platform limit is how a limit goes
+ * stale in one place and not the other — `MAX_BOUND_PARAMETERS` lives in `@pithy-sh/core`, once.
+ */
+export const RANK_PARAMETERS_PER_ROW = 3;
+
+/**
+ * Rows per chunk by default: as many as one update statement can carry, from core's budget.
+ *
+ * Derived rather than written out, so it moves if the platform does. Any other size works — the update
+ * chunks itself — and this is simply the size at which a chunk is exactly one statement.
+ */
+export const RANK_CHUNK_SIZE = Math.floor(boundParameterBudget(0) / RANK_PARAMETERS_PER_ROW);
+
+/**
+ * Chunks a refresh ranks before it checkpoints its cursor. `2000 * 33` is ~66k entries per Workflow step.
+ *
+ * The batch cap is stated here rather than in `worker.entry.ts`, which is the module that passes it as
+ * `maxChunks`. That module imports `cloudflare:workers`, so anything it exports is unreachable from a
+ * plain Node process, and a constant that reads as ordinary is exactly how #172 and #180 happened twice:
+ * a Node-side caller imports the number, gets workerd behind it, and the failure surfaces as
+ * `Could not load pithy.config.ts` — naming the config rather than the import. A pure value belongs in a
+ * pure module. `configEntrypoints.test.ts` is what holds that.
+ */
+export const REFRESH_BATCH_CHUNKS = 2000;
+
+/** The last entry a chunk ranked — where the next chunk (or the next batch's step) resumes. */
+export interface Keyset {
+  score: number;
+  achievedAt: number;
+  userId: string;
+}
+
+/**
+ * Narrow a selected `achievedAt` to its stored epoch.
+ *
+ * The column's decode-side input is a union (`number | string | Date`) so the codec stays
+ * encode-compatible, but a chunk selects raw columns rather than parsing whole rows — D1 always hands
+ * back the stored integer. This keeps the keyset arithmetic honest without paying to parse every row.
+ */
+function toEpoch(value: number | string | Date): number {
+  return value instanceof Date ? value.getTime() : Number(value);
+}
+
+export interface RefreshResult {
+  /** The cumulative number of entries ranked, including any `startRank` carried in from a prior batch. */
+  ranked: number;
+  /** How many chunks ran in this call. */
+  chunks: number;
+  /** True when the board is fully ranked; false when `maxChunks` stopped this batch mid-board. */
+  complete: boolean;
+  /**
+   * Where the next batch resumes, or null when the board is complete. Passing this back as `resumeAfter`
+   * (with `startRank` set to `ranked`) continues the pass exactly where it left off — the seam that makes
+   * a board rankable across many bounded steps of a Workflow, rather than one unbounded invocation.
+   */
+  cursor: Keyset | null;
+}
+
+export interface RefreshOptions {
+  /**
+   * Rows per keyset step. Defaults to {@link RANK_CHUNK_SIZE}; lower it to be gentler on a hot database.
+   *
+   * It carries no bound-parameter ceiling — the update chunks itself — so the only thing refused is a
+   * value that is not a count. A `chunkSize` of 0 used to report a board complete having ranked nobody.
+   */
+  chunkSize?: number;
+  /** Stop cleanly once this many chunks have run, whether or not the board is finished. Default: no cap. */
+  maxChunks?: number;
+  /** Resume the keyset walk after this entry — the `cursor` a prior batch returned. */
+  resumeAfter?: Keyset;
+  /** The rank already assigned before this batch, so numbering continues rather than restarting at 1. */
+  startRank?: number;
+}
+
+/**
+ * Recompute the stored rank for one board and window, best first.
+ *
+ * Ranks are positions in the total ordering, so a chunk needs no counting — the first chunk's first row
+ * is rank 1 and every chunk continues the count. The pass is **resumable**: with no `maxChunks` it ranks
+ * the whole board; with a `maxChunks` batch cap it ranks that many chunks, returns a `cursor`, and the
+ * caller feeds the cursor (and `startRank: ranked`) back to continue. That is what lets a board of any
+ * size be ranked across a series of bounded, individually-durable Workflow steps — there is no longer a
+ * per-invocation ceiling on how many entries a board can have.
+ */
+export async function refreshWindowRanks(
+  db: LeaderboardDatabase,
+  board: LeaderboardBoard,
+  windowKey: string,
+  options: RefreshOptions = {},
+): Promise<RefreshResult> {
+  const chunkSize = options.chunkSize ?? RANK_CHUNK_SIZE;
+  if (!Number.isInteger(chunkSize) || chunkSize < 1) {
+    throw new ValidationError({
+      message: "The rank refresh was asked for an impossible chunk size.",
+      action: "Pass a whole number of one or more, or omit chunkSize for the default.",
+      detail: `refreshWindowRanks received chunkSize=${chunkSize}; it must be a positive integer.`,
+    });
+  }
+  const maxChunks = options.maxChunks ?? Number.POSITIVE_INFINITY;
+  const descending = board.direction === "desc";
+
+  let after: Keyset | undefined = options.resumeAfter;
+  let ranked = options.startRank ?? 0;
+  let chunks = 0;
+
+  while (chunks < maxChunks) {
+    let query = db
+      .selectFrom(LEADERBOARD_ENTRIES_TABLE)
+      .select(["id", "score", "achievedAt", "userId"])
+      .where("boardId", "=", board.key)
+      .where("windowKey", "=", windowKey)
+      .where("visible", "=", 1)
+      .where("hidden", "=", 0);
+
+    if (after) {
+      // Keyset resume: strictly worse than the last row ranked, in the board's total ordering. Spelled
+      // out as an OR-of-ANDs for the same reason as the rank predicate — the sort directions are mixed.
+      const scoreWorse = descending ? sql`score < ${after.score}` : sql`score > ${after.score}`;
+      query = query.where(
+        sql<boolean>`(
+          ${scoreWorse}
+          OR (score = ${after.score} AND achieved_at > ${after.achievedAt})
+          OR (score = ${after.score} AND achieved_at = ${after.achievedAt} AND user_id > ${after.userId})
+        )`,
+      );
+    }
+
+    const rows = await query
+      .orderBy("score", descending ? "desc" : "asc")
+      .orderBy("achievedAt", "asc")
+      .orderBy("userId", "asc")
+      .limit(chunkSize)
+      .execute();
+
+    if (rows.length === 0) return { ranked, chunks, complete: true, cursor: null };
+
+    // One bulk UPDATE per statement's worth of rows: `SET rank = CASE id WHEN ? THEN ? … END WHERE id
+    // IN (…)`. Row-at-a-time updates would be correct too, and would cost one round trip each on a
+    // single-threaded database. How many rows fit is core's arithmetic, not a number written out here,
+    // so a chunk larger than one statement is simply written as several.
+    let written = 0;
+    for (const group of chunkRowsByBoundParameters(rows, RANK_PARAMETERS_PER_ROW)) {
+      const base = ranked + written;
+      let cases = sql``;
+      group.forEach((row, index) => {
+        cases = sql`${cases} WHEN ${row.id} THEN ${base + index + 1}`;
+      });
+      await db
+        .updateTable(LEADERBOARD_ENTRIES_TABLE)
+        .set({ rank: sql<number>`CASE id ${cases} END` })
+        .where(
+          "id",
+          "in",
+          group.map((row) => row.id),
+        )
+        .execute();
+      written += group.length;
+    }
+
+    ranked += rows.length;
+    chunks += 1;
+    const last = rows[rows.length - 1];
+    if (!last) break;
+    after = { score: last.score, achievedAt: toEpoch(last.achievedAt), userId: last.userId };
+
+    // A short chunk means the board ran out, so there is nothing left to resume into.
+    if (rows.length < chunkSize) return { ranked, chunks, complete: true, cursor: null };
+  }
+
+  // The batch cap stopped us mid-board: hand back the cursor so the next step resumes here.
+  return { ranked, chunks, complete: false, cursor: after ?? null };
+}