@pithy-sh/leaderboard 0.1.5 → 0.2.0

package/dist/rank/lock.d.ts

@@ -21,9 +21,50 @@ export declare const REFRESH_LOCK = "rank-refresh";
  * 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.
+ * with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that, within the bounds
+ * {@link requireLockStaleMs} enforces.
  */
 export declare const DEFAULT_LOCK_STALE_MS: number;
+/**
+ * The longest stale horizon this lock accepts — a day, and it is refused rather than clamped.
+ *
+ * The ceiling is not decoration on the finiteness check, for the reason `MAX_SECRETS_CACHE_TTL_SECONDS`
+ * records: `Infinity` is the loud spelling of *never reclaim*, and a number typed in the wrong unit is
+ * the quiet one. `3_600_000` is the default written in milliseconds, which is right; the same number
+ * typed as seconds-since-somebody-thought-it-was-seconds is `3_600_000_000` — forty-one days, during
+ * which a crashed instance's lock is never reclaimed, every cron fire stands down, and the ranks a
+ * board serves quietly stop moving. There is no error in that, and no line in the log; the boards just
+ * stop. A day is far past the ~5-minute worst case at the ~1M-player shard boundary and still short
+ * enough that a wedged lock is a today problem.
+ */
+export declare const MAX_LOCK_STALE_MS: number;
+/**
+ * Refuse a stale horizon that is not a duration — checked before anything is compared to it.
+ *
+ * `Number(env.LEADERBOARD_LOCK_STALE_MS)` is `NaN` for `"1h"`, `"3600 ms"` or a typo, and `Infinity`
+ * for `"1e999"`. Neither widens the horizon, and neither is caught by the `??` default one frame up,
+ * which answers `undefined` and nothing else. What each does instead is the whole reason this exists,
+ * and the two directions are different failures:
+ *
+ * - **Fails open — a negative or zero horizon.** `staleBefore` lands at or after `now`, so the takeover
+ *   `WHERE acquiredAt < staleBefore` is true of *every* row, fresh ones included. Each cron fire steals
+ *   the lock from the instance still holding it, both keep writing, and their chunked rank writes
+ *   interleave into the duplicate-and-gapped rank set the lock exists to prevent. At-most-one is gone,
+ *   silently, and every board reads as ranked.
+ * - **Fails obscurely — `NaN`, `Infinity`, or past the JS date range.** `new Date(now - NaN)` is an
+ *   Invalid Date, which `SQLiteDate`'s encode side refuses, so a `ZodError` — *"expected date, received
+ *   Date"* — leaves `acquireRefreshLock` outside any Workflow step and kills the run. It names nothing
+ *   an operator can act on, and it does it on every fire.
+ *
+ * There is no safe number to clamp a typo to, so it is named and refused, exactly as
+ * `@pithy-sh/email`'s `assertBatchSize` refuses `SCHEDULER_BATCH_SIZE` (#250) — this repository's own
+ * precedent, and the production bug that taught it. `core/internal`, because the number is ours to fix
+ * and the operator reading our logs is who can fix it (#521).
+ *
+ * It returns the value it checked so the env boundary reads as one expression: the coercion cannot be
+ * written without the check beside it, which is what `ci/environmentNumbers.test.ts` gates repo-wide.
+ */
+export declare function requireLockStaleMs(staleMs: number): number;
 /**
  * Try to take the refresh lock for `holder`, returning whether it was acquired.
  *

package/dist/rank/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/rank/lock.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEnF;;;;;;;;;;;GAWG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,IAAI,EACT,OAAO,GAAE,MAA8B,GACtC,OAAO,CAAC,OAAO,CAAC,CAuBlB;AAED,oGAAoG;AACpG,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/rank/lock.ts"],"names":[],"mappings":"AAKA,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEnF;;;;;;;;;;;GAWG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,QAAsB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS1D;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,IAAI,EACT,OAAO,GAAE,MAA8B,GACtC,OAAO,CAAC,OAAO,CAAC,CA4BlB;AAED,oGAAoG;AACpG,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F"}

package/dist/rank/lock.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 import { LeaderboardLock } from "../data/lock.js";
 import { LEADERBOARD_LOCKS_TABLE } from "../data/tables.js";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
 //#region src/rank/lock.ts
 /**
 * The rank-refresh advisory lock: at most one refresh runs at a time.
@@ -23,10 +24,58 @@ const REFRESH_LOCK = "rank-refresh";
 * 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.
+* with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that, within the bounds
+* {@link requireLockStaleMs} enforces.
 */
 const DEFAULT_LOCK_STALE_MS = 36e5;
 /**
+* The longest stale horizon this lock accepts — a day, and it is refused rather than clamped.
+*
+* The ceiling is not decoration on the finiteness check, for the reason `MAX_SECRETS_CACHE_TTL_SECONDS`
+* records: `Infinity` is the loud spelling of *never reclaim*, and a number typed in the wrong unit is
+* the quiet one. `3_600_000` is the default written in milliseconds, which is right; the same number
+* typed as seconds-since-somebody-thought-it-was-seconds is `3_600_000_000` — forty-one days, during
+* which a crashed instance's lock is never reclaimed, every cron fire stands down, and the ranks a
+* board serves quietly stop moving. There is no error in that, and no line in the log; the boards just
+* stop. A day is far past the ~5-minute worst case at the ~1M-player shard boundary and still short
+* enough that a wedged lock is a today problem.
+*/
+const MAX_LOCK_STALE_MS = 864e5;
+/**
+* Refuse a stale horizon that is not a duration — checked before anything is compared to it.
+*
+* `Number(env.LEADERBOARD_LOCK_STALE_MS)` is `NaN` for `"1h"`, `"3600 ms"` or a typo, and `Infinity`
+* for `"1e999"`. Neither widens the horizon, and neither is caught by the `??` default one frame up,
+* which answers `undefined` and nothing else. What each does instead is the whole reason this exists,
+* and the two directions are different failures:
+*
+* - **Fails open — a negative or zero horizon.** `staleBefore` lands at or after `now`, so the takeover
+*   `WHERE acquiredAt < staleBefore` is true of *every* row, fresh ones included. Each cron fire steals
+*   the lock from the instance still holding it, both keep writing, and their chunked rank writes
+*   interleave into the duplicate-and-gapped rank set the lock exists to prevent. At-most-one is gone,
+*   silently, and every board reads as ranked.
+* - **Fails obscurely — `NaN`, `Infinity`, or past the JS date range.** `new Date(now - NaN)` is an
+*   Invalid Date, which `SQLiteDate`'s encode side refuses, so a `ZodError` — *"expected date, received
+*   Date"* — leaves `acquireRefreshLock` outside any Workflow step and kills the run. It names nothing
+*   an operator can act on, and it does it on every fire.
+*
+* There is no safe number to clamp a typo to, so it is named and refused, exactly as
+* `@pithy-sh/email`'s `assertBatchSize` refuses `SCHEDULER_BATCH_SIZE` (#250) — this repository's own
+* precedent, and the production bug that taught it. `core/internal`, because the number is ours to fix
+* and the operator reading our logs is who can fix it (#521).
+*
+* It returns the value it checked so the env boundary reads as one expression: the coercion cannot be
+* written without the check beside it, which is what `ci/environmentNumbers.test.ts` gates repo-wide.
+*/
+function requireLockStaleMs(staleMs) {
+	if (!Number.isInteger(staleMs) || staleMs < 1 || staleMs > 864e5) throw new InternalError({
+		message: "The leaderboard rank refresh is misconfigured.",
+		action: `Set LEADERBOARD_LOCK_STALE_MS to a whole number of milliseconds from 1 to ${MAX_LOCK_STALE_MS}, or unset it for the default of ${DEFAULT_LOCK_STALE_MS}.`,
+		detail: `LEADERBOARD_LOCK_STALE_MS resolved to ${String(staleMs)}; a stale horizon must be a whole number of milliseconds from 1 to ${MAX_LOCK_STALE_MS}. At or below zero every cron fire steals a live holder's lock and two refreshes interleave their rank writes; above the range the horizon is not a date at all and the refresh cannot run.`
+	});
+	return staleMs;
+}
+/**
 * 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
@@ -36,7 +85,8 @@ const DEFAULT_LOCK_STALE_MS = 36e5;
 * to stand down.
 */
 async function acquireRefreshLock(db, holder, now, staleMs = DEFAULT_LOCK_STALE_MS) {
-	const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - staleMs));
+	const horizon = requireLockStaleMs(staleMs);
+	const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - horizon));
 	const row = LeaderboardLock.encode({
 		name: REFRESH_LOCK,
 		holder,
@@ -53,4 +103,4 @@ async function releaseRefreshLock(db, holder) {
 	await db.deleteFrom(LEADERBOARD_LOCKS_TABLE).where("name", "=", REFRESH_LOCK).where("holder", "=", holder).execute();
 }
 //#endregion
-export { DEFAULT_LOCK_STALE_MS, REFRESH_LOCK, acquireRefreshLock, releaseRefreshLock };
+export { DEFAULT_LOCK_STALE_MS, MAX_LOCK_STALE_MS, REFRESH_LOCK, acquireRefreshLock, releaseRefreshLock, requireLockStaleMs };

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

@@ -1 +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"}
+{"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,CAoEpF;CACF;;IAGC;;;;;;OAMG;IACG,SAAS,cAAc,OAAO,OAAO,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC"}

package/dist/rank/worker.entry.js

@@ -3,7 +3,7 @@
 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 { acquireRefreshLock, releaseRefreshLock, requireLockStaleMs } from "./lock.js";
 import { REFRESH_BATCH_CHUNKS, refreshWindowRanks } from "./materialize.js";
 import { leaderboardWorkflowRetry } from "./retryPolicy.js";
 import { pruneBoards } from "../retention/prune.js";
@@ -17,7 +17,7 @@ var RankRefreshWorkflow = class extends WorkflowEntrypoint {
 		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 staleMs = this.env.LEADERBOARD_LOCK_STALE_MS ? requireLockStaleMs(Number(this.env.LEADERBOARD_LOCK_STALE_MS)) : void 0;
 		const ctx = await steps.do("refresh-context", async () => ({
 			holder: crypto.randomUUID(),
 			nowMs: Date.now()

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** 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.5";
+export declare const PACKAGE_VERSION = "0.2.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** 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.5";
+const PACKAGE_VERSION = "0.2.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/leaderboard",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -38,11 +38,17 @@
   "dependencies": {
     "@cloudflare/workers-types": "^5.20260729.1",
     "@hono/zod-validator": "^0.9.0",
-    "@pithy-sh/core": "^0.2.0",
     "croner": "^10.0.1"
   },
+  "peerDependencies": {
+    "@pithy-sh/core": "^0.4.0",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.4.0"
+  },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/core": "workspace:*",
     "@pithy-sh/tsconfig": "workspace:*",
     "@types/node": "^22.15.0",
     "@vitest/coverage-v8": "^4.1.0",
@@ -54,10 +60,5 @@
     "vitest": "^4.1.0",
     "wrangler": "^4.115.0",
     "zod": "^4.4.0"
-  },
-  "peerDependencies": {
-    "hono": "^4.13.2",
-    "kysely": "^0.29.0",
-    "zod": "^4.4.0"
   }
 }

package/src/rank/lock.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
 import { LeaderboardLock } from "../data/lock";
 import { LEADERBOARD_LOCKS_TABLE, type LeaderboardDatabase } from "../data/tables";
 
@@ -26,10 +27,62 @@ export const REFRESH_LOCK = "rank-refresh";
  * 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.
+ * with `LEADERBOARD_LOCK_STALE_MS` if a deployment refreshes boards larger than that, within the bounds
+ * {@link requireLockStaleMs} enforces.
  */
 export const DEFAULT_LOCK_STALE_MS = 60 * 60 * 1000;
 
+/**
+ * The longest stale horizon this lock accepts — a day, and it is refused rather than clamped.
+ *
+ * The ceiling is not decoration on the finiteness check, for the reason `MAX_SECRETS_CACHE_TTL_SECONDS`
+ * records: `Infinity` is the loud spelling of *never reclaim*, and a number typed in the wrong unit is
+ * the quiet one. `3_600_000` is the default written in milliseconds, which is right; the same number
+ * typed as seconds-since-somebody-thought-it-was-seconds is `3_600_000_000` — forty-one days, during
+ * which a crashed instance's lock is never reclaimed, every cron fire stands down, and the ranks a
+ * board serves quietly stop moving. There is no error in that, and no line in the log; the boards just
+ * stop. A day is far past the ~5-minute worst case at the ~1M-player shard boundary and still short
+ * enough that a wedged lock is a today problem.
+ */
+export const MAX_LOCK_STALE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Refuse a stale horizon that is not a duration — checked before anything is compared to it.
+ *
+ * `Number(env.LEADERBOARD_LOCK_STALE_MS)` is `NaN` for `"1h"`, `"3600 ms"` or a typo, and `Infinity`
+ * for `"1e999"`. Neither widens the horizon, and neither is caught by the `??` default one frame up,
+ * which answers `undefined` and nothing else. What each does instead is the whole reason this exists,
+ * and the two directions are different failures:
+ *
+ * - **Fails open — a negative or zero horizon.** `staleBefore` lands at or after `now`, so the takeover
+ *   `WHERE acquiredAt < staleBefore` is true of *every* row, fresh ones included. Each cron fire steals
+ *   the lock from the instance still holding it, both keep writing, and their chunked rank writes
+ *   interleave into the duplicate-and-gapped rank set the lock exists to prevent. At-most-one is gone,
+ *   silently, and every board reads as ranked.
+ * - **Fails obscurely — `NaN`, `Infinity`, or past the JS date range.** `new Date(now - NaN)` is an
+ *   Invalid Date, which `SQLiteDate`'s encode side refuses, so a `ZodError` — *"expected date, received
+ *   Date"* — leaves `acquireRefreshLock` outside any Workflow step and kills the run. It names nothing
+ *   an operator can act on, and it does it on every fire.
+ *
+ * There is no safe number to clamp a typo to, so it is named and refused, exactly as
+ * `@pithy-sh/email`'s `assertBatchSize` refuses `SCHEDULER_BATCH_SIZE` (#250) — this repository's own
+ * precedent, and the production bug that taught it. `core/internal`, because the number is ours to fix
+ * and the operator reading our logs is who can fix it (#521).
+ *
+ * It returns the value it checked so the env boundary reads as one expression: the coercion cannot be
+ * written without the check beside it, which is what `ci/environmentNumbers.test.ts` gates repo-wide.
+ */
+export function requireLockStaleMs(staleMs: number): number {
+  if (!Number.isInteger(staleMs) || staleMs < 1 || staleMs > MAX_LOCK_STALE_MS) {
+    throw new InternalError({
+      message: "The leaderboard rank refresh is misconfigured.",
+      action: `Set LEADERBOARD_LOCK_STALE_MS to a whole number of milliseconds from 1 to ${MAX_LOCK_STALE_MS}, or unset it for the default of ${DEFAULT_LOCK_STALE_MS}.`,
+      detail: `LEADERBOARD_LOCK_STALE_MS resolved to ${String(staleMs)}; a stale horizon must be a whole number of milliseconds from 1 to ${MAX_LOCK_STALE_MS}. At or below zero every cron fire steals a live holder's lock and two refreshes interleave their rank writes; above the range the horizon is not a date at all and the refresh cannot run.`,
+    });
+  }
+  return staleMs;
+}
+
 /**
  * Try to take the refresh lock for `holder`, returning whether it was acquired.
  *
@@ -45,7 +98,12 @@ export async function acquireRefreshLock(
   now: Date,
   staleMs: number = DEFAULT_LOCK_STALE_MS,
 ): Promise<boolean> {
-  const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - staleMs));
+  // Before the upsert, and on the resolved value rather than on the caller's argument, so the check
+  // covers every route in: this worker's env var, an adopter who merged the Workflow into their own
+  // worker and passed a number of their own, and the default. The comparison two lines down is the only
+  // thing that reads this number, and it cannot be reached around.
+  const horizon = requireLockStaleMs(staleMs);
+  const staleBefore = LeaderboardLock.shape.acquiredAt.encode(new Date(now.getTime() - horizon));
   const row = LeaderboardLock.encode({ name: REFRESH_LOCK, holder, acquiredAt: now });
 
   await db

package/src/rank/worker.entry.ts

@@ -9,7 +9,7 @@ import { LeaderboardConfig } from "../config/config";
 import { leaderboardDatabase } from "../data/tables";
 import { pruneBoards } from "../retention/prune";
 import { windowKeyAt } from "../window/schedule";
-import { acquireRefreshLock, releaseRefreshLock } from "./lock";
+import { acquireRefreshLock, releaseRefreshLock, requireLockStaleMs } from "./lock";
 import { type Keyset, REFRESH_BATCH_CHUNKS, type RefreshResult, refreshWindowRanks } from "./materialize";
 import { leaderboardWorkflowRetry } from "./retryPolicy";
 import { materializedBoards } from "./worker";
@@ -62,7 +62,12 @@ export class RankRefreshWorkflow extends WorkflowEntrypoint<RankWorkerEnv, unkno
     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) : undefined;
+    // Checked here as well as inside `acquireRefreshLock`, and deliberately: this is where the string an
+    // operator typed becomes a number, so this is where the refusal can name the var. The coercion and the
+    // check are one expression because a bare `Number(env.…)` is what #521 keeps finding.
+    const staleMs = this.env.LEADERBOARD_LOCK_STALE_MS
+      ? requireLockStaleMs(Number(this.env.LEADERBOARD_LOCK_STALE_MS))
+      : undefined;
 
     // Mint this instance's identity and its clock ONCE, in a memoized step, and read them from the step's
     // return value. A replay does not re-run the step body, so it reuses the same holder token and the

package/src/rank/wrangler.jsonc

@@ -1,8 +1,17 @@
 {
-  // The leaderboard rank-refresh worker. This is a TEMPLATE, not a wrangler env-stanza file: `pithy add
-  // leaderboard` resolves it per environment — filling the `<...>` placeholders and the cron from the
-  // adopter's `rank: { materialize }` setting — and deploys each with its own config
-  // (`wrangler deploy --config <resolved>`). The adopter authors none of it.
+  // The leaderboard rank-refresh worker. This is a TEMPLATE, not a wrangler env-stanza file: the
+  // `<...>` placeholders and the cron are meant to be filled per environment from the adopter's
+  // `rank: { materialize }` setting, and each resolved config deployed with `wrangler deploy --config
+  // <resolved>`.
+  //
+  // **Nothing in the kit does that yet, and this file is not deployed by any command.**
+  // `cli/src/capabilities/hostRegistry.ts` leaves `@pithy-sh/leaderboard` out of `HOST_WORKERS`
+  // deliberately: the rank worker ships this template and a `RankRefreshWorkflow`, but no
+  // `resolveLeaderboardConfig` and no provisioner, so there is nothing to drive — and
+  // `hostRegistry.test.ts` pins that absence so it cannot become an oversight. Filling and deploying it
+  // is an adopter's own step today. This comment said otherwise for as long as the template has
+  // existed, which is the kind of claim that sends somebody looking for a command that was never
+  // written.
   //
   // It does NOT have to be its own worker. What the refresh actually needs is three things: the
   // `RankRefreshWorkflow` class, a `scheduled()` handler that starts an instance, and a cron trigger.
@@ -14,7 +23,12 @@
   // once capped the refresh at ~64k entries per run. A Workflow step has unlimited wall-clock and burns
   // no CPU while awaiting D1, so a board of any size ranks across bounded, individually-durable steps
   // that checkpoint a keyset cursor. See `worker.entry.ts`.
-  "name": "pithy-leaderboard-rank", // resolved per env → pithy-leaderboard-rank-staging / -production
+  // A placeholder, not the deployed name. When something does resolve this template it will compose
+  // `<project>-<env>-leaderboard` — `workflowHostName` in `core/src/workflow/naming.ts` is
+  // `<project>-<env>-<capability>`, so the project leads and the environment is second, never trailing
+  // and never `production`. Worker script names are account-scoped, which is what makes the project
+  // segment load-bearing: without it a second Pithy project's deploy overwrites this one's worker.
+  "name": "pithy-leaderboard-rank",
   "main": "./worker.entry.ts",
   // The compatibility date every Worker in this repository runs on. Stated once in the repository
   // root's `compatibility.ts` and copied here because JSONC cannot import it —
@@ -46,7 +60,9 @@
     "LEADERBOARD_CONFIG": "<filled-at-provision>",
     // Optional. How long a held refresh lock stays valid before a crashed instance's lock is reclaimed,
     // in ms. Defaults to one hour — raise it only if a deployment refreshes boards that take longer than
-    // that (well past the ~1M-player shard boundary). See `rank/lock.ts`.
+    // that (well past the ~1M-player shard boundary). A whole number of milliseconds from 1 to 86400000;
+    // anything else is refused by name on the first fire rather than quietly removing the lock. See
+    // `rank/lock.ts`.
     // "LEADERBOARD_LOCK_STALE_MS": "3600000",
     "ENVIRONMENT": "<filled-at-provision>"
   }

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 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.5";
+export const PACKAGE_VERSION = "0.2.0";