@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/LeaderboardRankStore.js

@@ -0,0 +1,18 @@
+// The rank store of the leaderboard service (game-server-leaderboards D1, DR §5): rankings, players, rate counters and
+// session presence, in the server's own Redis or in files under admin.dataDir. General purpose (D2).
+import path from "node:path";
+import { LEADERBOARD_DATA_FOLDER } from "./LeaderboardConstants.js";
+import { FileLeaderboardRankStore } from "./FileLeaderboardRankStore.js";
+import { RedisLeaderboardRankStore } from "./RedisLeaderboardRankStore.js";
+/**
+ * Opens the rank store on the same Redis client the admin store uses, or on files under admin.dataDir.
+ * @param dataDir The resolved admin data folder (used without Redis).
+ * @param redisClient The shared ioredis client, or null.
+ * @param isFolderPersistent The admin store's isPersistent (the file store's durability).
+ * @returns The store.
+ */
+export async function openLeaderboardRankStore(dataDir, redisClient, isFolderPersistent) {
+    if (redisClient != null)
+        return new RedisLeaderboardRankStore(redisClient);
+    return await FileLeaderboardRankStore.open(path.join(dataDir, LEADERBOARD_DATA_FOLDER), isFolderPersistent);
+}

package/lib/leaderboards/LeaderboardRules.d.ts

@@ -0,0 +1,122 @@
+import type { LeaderboardBoardDefinition, LeaderboardKeepPolicy, LeaderboardMetadata, LeaderboardRefusalReason, LeaderboardResetSchedule, LeaderboardRules, LeaderboardSortOrder, LeaderboardWriteOutcome } from "../admin/AdminApiTypes.js";
+import type { LeaderboardRankKey, StoredLeaderboardEntry } from "./LeaderboardRankStore.js";
+/**
+ * Validates a board definition (DR §10): every field present with its type, the id pattern, name and description
+ * lengths, enums, score limits, trust levels and dimensions.
+ * @param value The definition to check (any JSON).
+ * @returns The definition (null when there are problems) and one sentence per problem.
+ */
+export declare function validateBoardDefinition(value: unknown): {
+    definition: LeaderboardBoardDefinition | null;
+    problems: string[];
+};
+/**
+ * The canonical variant key of a submission's variant (D16): `name=value` pairs in declared order joined with `&`, or
+ * "all" for a board without dimensions.
+ * @param definition The board.
+ * @param variant The submission's variant (null or {} for a board without dimensions).
+ * @returns The key, or a problem sentence naming the bad key or value.
+ */
+export declare function variantKeyOf(definition: LeaderboardBoardDefinition, variant: Record<string, string> | null): {
+    variantKey: string | null;
+    problem: string | null;
+};
+/**
+ * The dimension values of a variant key (the inverse of variantKeyOf).
+ * @param variantKey The canonical key.
+ * @returns Name → value; {} for "all".
+ */
+export declare function variantValuesOf(variantKey: string): Record<string, string>;
+/**
+ * The value a ranking sorts ascending by (D13).
+ * @param sortOrder The board's sort order.
+ * @param score The score.
+ * @returns The score for lowerIsBetter, minus the score for higherIsBetter.
+ */
+export declare function sortValueOf(sortOrder: LeaderboardSortOrder, score: number): number;
+/**
+ * Orders two entries of one ranking (D13): sort value ascending, then the earlier achievedAtMs, then playerId.
+ * @param sortOrder The board's sort order.
+ * @param first One entry.
+ * @param second The other.
+ * @returns Negative when first ranks higher, positive when second does, 0 for the same player and time.
+ */
+export declare function compareRankedEntries(sortOrder: LeaderboardSortOrder, first: StoredLeaderboardEntry, second: StoredLeaderboardEntry): number;
+/**
+ * Applies a keep policy (D14) exactly as the Redis submit script does.
+ * @param keepPolicy The board's keep policy.
+ * @param sortOrder The board's sort order (for best).
+ * @param current The player's stored entry, or null.
+ * @param incoming The new entry (submissionCount 1, the submitted score).
+ * @returns The outcome and the entry to store (current itself when kept).
+ */
+export declare function applyKeepPolicy(keepPolicy: LeaderboardKeepPolicy, sortOrder: LeaderboardSortOrder, current: StoredLeaderboardEntry | null, incoming: StoredLeaderboardEntry): {
+    outcome: LeaderboardWriteOutcome;
+    stored: StoredLeaderboardEntry;
+};
+/**
+ * Checks one submitted score (D12), in order: integer, absolute bound, board limits, run duration.
+ * @param definition The board.
+ * @param score The submitted score (any JSON).
+ * @param durationMs The run's duration, or null.
+ * @returns The refusal, or null when the score is acceptable.
+ */
+export declare function checkScore(definition: LeaderboardBoardDefinition, score: unknown, durationMs: number | null): LeaderboardRefusalReason | null;
+/**
+ * Checks entry metadata: a plain object of JSON values, nested at most four levels, whose UTF-8 JSON fits the limit.
+ * @param metadata The submitted metadata (any JSON).
+ * @param maximumBytes The rules' metadataMaximumBytes.
+ * @returns The metadata (null when absent or refused) and the refusal, or null.
+ */
+export declare function checkMetadata(metadata: unknown, maximumBytes: number): {
+    metadata: LeaderboardMetadata | null;
+    refusal: LeaderboardRefusalReason | null;
+};
+/**
+ * Cleans a display name: trims, collapses whitespace runs to one space, refuses control characters, lengths outside
+ * 1–24 characters and names containing a blocked word (case-insensitive).
+ * @param value The name (any JSON).
+ * @param blockedWords The rules' blocked words.
+ * @returns The clean name, or null with the refusal.
+ */
+export declare function cleanDisplayName(value: unknown, blockedWords: readonly string[]): {
+    displayName: string | null;
+    refusal: "nameInvalid" | "nameBlocked" | null;
+};
+/**
+ * The next scheduled reset after a time (D17, UTC): daily the next 00:00, weekly the next Monday 00:00, monthly the 1st
+ * of next month 00:00.
+ * @param schedule The board's reset schedule.
+ * @param fromMs The time to count from, in epoch milliseconds.
+ * @returns ISO time, or null for "never" and "manual".
+ */
+export declare function nextResetAt(schedule: LeaderboardResetSchedule, fromMs: number): string | null;
+/**
+ * The string form of a rank key: `boardId/seasonId/variantKey` (the variant key is URI-encoded, so it has no `/`).
+ * @param key The rank key.
+ * @returns The text.
+ */
+export declare function rankKeyText(key: LeaderboardRankKey): string;
+/**
+ * Parses rankKeyText's output, splitting on the first two `/`.
+ * @param text The text.
+ * @returns The rank key.
+ */
+export declare function parseRankKeyText(text: string): LeaderboardRankKey;
+/**
+ * Validates console-edited rules (D19): every limit an integer in range, blocked words a list of short strings (kept
+ * trimmed and lower-case).
+ * @param value The rules (any JSON).
+ * @returns The rules (null when there are problems) and one sentence per problem.
+ */
+export declare function validateRules(value: unknown): {
+    rules: LeaderboardRules | null;
+    problems: string[];
+};
+/**
+ * The advice shown with a durability that is not "durable" (D20).
+ * @param durability The measured durability.
+ * @param storage Where the rankings live.
+ * @returns The advice sentence, or null.
+ */
+export declare function durabilityAdvice(durability: "durable" | "notDurable" | "unknown", storage: "redis" | "file"): string | null;

package/lib/leaderboards/LeaderboardRules.js

@@ -0,0 +1,472 @@
+// Pure rules of the leaderboard service (game-server-leaderboards DR §10): board and rules validation, variant keys,
+// ranking order, keep policies, score, metadata and name checks, reset schedules and durability advice. Synchronous and
+// free of side effects. General purpose: nothing here knows any game (D2).
+import { BOARD_ID_PATTERN, DIMENSION_NAME_PATTERN, LEADERBOARD_ALL_VARIANT_KEY, LEADERBOARD_DURATION_TOLERANCE_MS, LEADERBOARD_MAX_BODY_BYTES, LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE, LEADERBOARD_MAXIMUM_DIMENSION_VALUES, LEADERBOARD_MAXIMUM_DIMENSIONS, LEADERBOARD_MAXIMUM_NAME_LENGTH, LEADERBOARD_MAXIMUM_VALUE_LENGTH } from "./LeaderboardConstants.js";
+/** Sort orders a board may use. */
+const SORT_ORDERS = ["higherIsBetter", "lowerIsBetter"];
+/** Score formats a board may use. */
+const SCORE_FORMATS = ["integer", "timeMilliseconds", "points"];
+/** Keep policies a board may use. */
+const KEEP_POLICIES = ["best", "latest", "sum"];
+/** Trust levels a board may accept. */
+const TRUST_LEVELS = ["client", "session", "server"];
+/** Visibilities a board may have. */
+const VISIBILITIES = ["public", "hidden"];
+/** Reset schedules a board may have. */
+const RESET_SCHEDULES = ["never", "manual", "daily", "weekly", "monthly"];
+/** Longest board display name. */
+const MAXIMUM_BOARD_NAME_LENGTH = 80;
+/** Longest board description. */
+const MAXIMUM_DESCRIPTION_LENGTH = 500;
+/** Longest dimension label. */
+const MAXIMUM_LABEL_LENGTH = 40;
+/** Deepest metadata nesting (the top-level object is level 1). */
+const MAXIMUM_METADATA_DEPTH = 4;
+/** Largest value of a per-minute or per-hour rules limit. */
+const MAXIMUM_RATE_LIMIT = 1000000;
+/** Most scores one submission may carry, whatever the rules say. */
+const MAXIMUM_SCORES_PER_SUBMISSION = 100;
+/** Most blocked words. */
+const MAXIMUM_BLOCKED_WORDS = 1000;
+/** Longest blocked word. */
+const MAXIMUM_BLOCKED_WORD_LENGTH = 64;
+/** getUTCDay() of Monday. */
+const MONDAY = 1;
+/** Days in a week. */
+const DAYS_PER_WEEK = 7;
+/** C0 and C1 control characters (and DEL), refused in display names. */
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+/** Runs of whitespace, collapsed to one space in display names. */
+const WHITESPACE_RUNS = /\s+/g;
+/** Fields of a board definition, each required. */
+const DEFINITION_FIELDS = ["boardId", "displayName", "description", "sortOrder", "scoreFormat", "keepPolicy", "minimumScore", "maximumScore", "acceptedTrustLevels", "visibility", "resetSchedule", "dimensions"];
+/** Integer fields of the rules with their smallest and largest values. */
+const RULE_LIMITS = [
+    { field: "submissionsPerMinutePerPlayer", minimum: 1, maximum: MAXIMUM_RATE_LIMIT },
+    { field: "submissionsPerMinutePerAddress", minimum: 1, maximum: MAXIMUM_RATE_LIMIT },
+    { field: "readsPerMinutePerAddress", minimum: 1, maximum: MAXIMUM_RATE_LIMIT },
+    { field: "identitiesPerHourPerAddress", minimum: 1, maximum: MAXIMUM_RATE_LIMIT },
+    { field: "maximumScoresPerSubmission", minimum: 1, maximum: MAXIMUM_SCORES_PER_SUBMISSION },
+    { field: "metadataMaximumBytes", minimum: 0, maximum: LEADERBOARD_MAX_BODY_BYTES }
+];
+/**
+ * Validates a board definition (DR §10): every field present with its type, the id pattern, name and description
+ * lengths, enums, score limits, trust levels and dimensions.
+ * @param value The definition to check (any JSON).
+ * @returns The definition (null when there are problems) and one sentence per problem.
+ */
+export function validateBoardDefinition(value) {
+    if (!isPlainObject(value))
+        return { definition: null, problems: ["a board definition must be an object"] };
+    const missing = DEFINITION_FIELDS.filter((field) => !(field in value));
+    if (missing.length > 0)
+        return { definition: null, problems: missing.map((field) => field + " is missing") };
+    const problems = [
+        ...identityProblems(value),
+        ...enumProblems(value),
+        ...scoreLimitProblems(value.minimumScore, value.maximumScore),
+        ...trustLevelProblems(value.acceptedTrustLevels),
+        ...dimensionListProblems(value.dimensions)
+    ];
+    if (problems.length > 0)
+        return { definition: null, problems: problems };
+    const definition = {
+        boardId: value.boardId,
+        displayName: value.displayName.trim(),
+        description: value.description,
+        sortOrder: value.sortOrder,
+        scoreFormat: value.scoreFormat,
+        keepPolicy: value.keepPolicy,
+        minimumScore: value.minimumScore,
+        maximumScore: value.maximumScore,
+        acceptedTrustLevels: [...value.acceptedTrustLevels],
+        visibility: value.visibility,
+        resetSchedule: value.resetSchedule,
+        dimensions: value.dimensions.map((dimension) => ({ name: dimension.name, label: dimension.label, values: [...dimension.values] }))
+    };
+    return { definition: definition, problems: [] };
+}
+/**
+ * The canonical variant key of a submission's variant (D16): `name=value` pairs in declared order joined with `&`, or
+ * "all" for a board without dimensions.
+ * @param definition The board.
+ * @param variant The submission's variant (null or {} for a board without dimensions).
+ * @returns The key, or a problem sentence naming the bad key or value.
+ */
+export function variantKeyOf(definition, variant) {
+    const values = (variant != null) ? variant : {};
+    if (!isPlainObject(values))
+        return { variantKey: null, problem: "variant must be an object" };
+    const declaredNames = new Set(definition.dimensions.map((dimension) => dimension.name));
+    const extraName = Object.keys(values).find((name) => !declaredNames.has(name));
+    if (extraName != null)
+        return { variantKey: null, problem: "variant key " + extraName + " is not a dimension of " + definition.boardId };
+    if (definition.dimensions.length === 0)
+        return { variantKey: LEADERBOARD_ALL_VARIANT_KEY, problem: null };
+    for (const dimension of definition.dimensions) {
+        const dimensionValue = values[dimension.name];
+        if (dimensionValue == null)
+            return { variantKey: null, problem: "variant must name " + dimension.name };
+        if (typeof dimensionValue !== "string" || !dimension.values.includes(dimensionValue)) {
+            return { variantKey: null, problem: "variant value " + String(dimensionValue) + " is not allowed for " + dimension.name };
+        }
+    }
+    const pairs = definition.dimensions.map((dimension) => encodeURIComponent(dimension.name) + "=" + encodeURIComponent(values[dimension.name]));
+    return { variantKey: pairs.join("&"), problem: null };
+}
+/**
+ * The dimension values of a variant key (the inverse of variantKeyOf).
+ * @param variantKey The canonical key.
+ * @returns Name → value; {} for "all".
+ */
+export function variantValuesOf(variantKey) {
+    const values = {};
+    if (variantKey === LEADERBOARD_ALL_VARIANT_KEY || variantKey === "")
+        return values;
+    for (const pair of variantKey.split("&")) {
+        const separatorIndex = pair.indexOf("=");
+        if (separatorIndex < 0)
+            continue;
+        values[decodeURIComponent(pair.slice(0, separatorIndex))] = decodeURIComponent(pair.slice(separatorIndex + 1));
+    }
+    return values;
+}
+/**
+ * The value a ranking sorts ascending by (D13).
+ * @param sortOrder The board's sort order.
+ * @param score The score.
+ * @returns The score for lowerIsBetter, minus the score for higherIsBetter.
+ */
+export function sortValueOf(sortOrder, score) {
+    return (sortOrder === "higherIsBetter") ? -score : score;
+}
+/**
+ * Orders two entries of one ranking (D13): sort value ascending, then the earlier achievedAtMs, then playerId.
+ * @param sortOrder The board's sort order.
+ * @param first One entry.
+ * @param second The other.
+ * @returns Negative when first ranks higher, positive when second does, 0 for the same player and time.
+ */
+export function compareRankedEntries(sortOrder, first, second) {
+    const sortDifference = sortValueOf(sortOrder, first.score) - sortValueOf(sortOrder, second.score);
+    if (sortDifference !== 0)
+        return sortDifference;
+    const timeDifference = first.achievedAtMs - second.achievedAtMs;
+    if (timeDifference !== 0)
+        return timeDifference;
+    return first.playerId.localeCompare(second.playerId, "en");
+}
+/**
+ * Applies a keep policy (D14) exactly as the Redis submit script does.
+ * @param keepPolicy The board's keep policy.
+ * @param sortOrder The board's sort order (for best).
+ * @param current The player's stored entry, or null.
+ * @param incoming The new entry (submissionCount 1, the submitted score).
+ * @returns The outcome and the entry to store (current itself when kept).
+ */
+export function applyKeepPolicy(keepPolicy, sortOrder, current, incoming) {
+    if (current == null)
+        return { outcome: "created", stored: incoming };
+    const nextCount = current.submissionCount + 1;
+    if (keepPolicy === "sum")
+        return { outcome: "added", stored: { ...incoming, score: current.score + incoming.score, submissionCount: nextCount } };
+    if (keepPolicy === "latest")
+        return { outcome: "replaced", stored: { ...incoming, submissionCount: nextCount } };
+    const isBetter = (sortOrder === "lowerIsBetter") ? incoming.score < current.score : incoming.score > current.score;
+    if (!isBetter)
+        return { outcome: "kept", stored: current };
+    return { outcome: "improved", stored: { ...incoming, submissionCount: nextCount } };
+}
+/**
+ * Checks one submitted score (D12), in order: integer, absolute bound, board limits, run duration.
+ * @param definition The board.
+ * @param score The submitted score (any JSON).
+ * @param durationMs The run's duration, or null.
+ * @returns The refusal, or null when the score is acceptable.
+ */
+export function checkScore(definition, score, durationMs) {
+    if (typeof score !== "number" || !Number.isSafeInteger(score))
+        return "scoreNotInteger";
+    if (Math.abs(score) > LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE)
+        return "scoreOutOfRange";
+    if (definition.minimumScore != null && score < definition.minimumScore)
+        return "scoreOutOfRange";
+    if (definition.maximumScore != null && score > definition.maximumScore)
+        return "scoreOutOfRange";
+    const isTimeBoard = definition.scoreFormat === "timeMilliseconds";
+    if (isTimeBoard && durationMs != null && score > durationMs + LEADERBOARD_DURATION_TOLERANCE_MS)
+        return "implausibleDuration";
+    return null;
+}
+/**
+ * Checks entry metadata: a plain object of JSON values, nested at most four levels, whose UTF-8 JSON fits the limit.
+ * @param metadata The submitted metadata (any JSON).
+ * @param maximumBytes The rules' metadataMaximumBytes.
+ * @returns The metadata (null when absent or refused) and the refusal, or null.
+ */
+export function checkMetadata(metadata, maximumBytes) {
+    if (metadata == null)
+        return { metadata: null, refusal: null };
+    if (!isPlainObject(metadata) || !isJsonValue(metadata, 1))
+        return { metadata: null, refusal: "metadataTooLarge" };
+    const byteLength = new TextEncoder().encode(JSON.stringify(metadata)).length;
+    if (byteLength > maximumBytes)
+        return { metadata: null, refusal: "metadataTooLarge" };
+    return { metadata: metadata, refusal: null };
+}
+/**
+ * Cleans a display name: trims, collapses whitespace runs to one space, refuses control characters, lengths outside
+ * 1–24 characters and names containing a blocked word (case-insensitive).
+ * @param value The name (any JSON).
+ * @param blockedWords The rules' blocked words.
+ * @returns The clean name, or null with the refusal.
+ */
+export function cleanDisplayName(value, blockedWords) {
+    if (typeof value !== "string")
+        return { displayName: null, refusal: "nameInvalid" };
+    const collapsed = value.replace(WHITESPACE_RUNS, " ").trim();
+    if (CONTROL_CHARACTERS.test(collapsed))
+        return { displayName: null, refusal: "nameInvalid" };
+    const characterCount = Array.from(collapsed).length;
+    if (characterCount < 1 || characterCount > LEADERBOARD_MAXIMUM_NAME_LENGTH)
+        return { displayName: null, refusal: "nameInvalid" };
+    const lowerName = collapsed.toLowerCase();
+    const isBlocked = blockedWords.some((word) => word.length > 0 && lowerName.includes(word.toLowerCase()));
+    if (isBlocked)
+        return { displayName: null, refusal: "nameBlocked" };
+    return { displayName: collapsed, refusal: null };
+}
+/**
+ * The next scheduled reset after a time (D17, UTC): daily the next 00:00, weekly the next Monday 00:00, monthly the 1st
+ * of next month 00:00.
+ * @param schedule The board's reset schedule.
+ * @param fromMs The time to count from, in epoch milliseconds.
+ * @returns ISO time, or null for "never" and "manual".
+ */
+export function nextResetAt(schedule, fromMs) {
+    const from = new Date(fromMs);
+    const year = from.getUTCFullYear();
+    const month = from.getUTCMonth();
+    const day = from.getUTCDate();
+    if (schedule === "daily")
+        return new Date(Date.UTC(year, month, day + 1)).toISOString();
+    if (schedule === "monthly")
+        return new Date(Date.UTC(year, month + 1, 1)).toISOString();
+    if (schedule !== "weekly")
+        return null;
+    const daysUntilMonday = ((MONDAY - from.getUTCDay() + DAYS_PER_WEEK) % DAYS_PER_WEEK) || DAYS_PER_WEEK;
+    return new Date(Date.UTC(year, month, day + daysUntilMonday)).toISOString();
+}
+/**
+ * The string form of a rank key: `boardId/seasonId/variantKey` (the variant key is URI-encoded, so it has no `/`).
+ * @param key The rank key.
+ * @returns The text.
+ */
+export function rankKeyText(key) {
+    return key.boardId + "/" + key.seasonId + "/" + key.variantKey;
+}
+/**
+ * Parses rankKeyText's output, splitting on the first two `/`.
+ * @param text The text.
+ * @returns The rank key.
+ */
+export function parseRankKeyText(text) {
+    const firstSlash = text.indexOf("/");
+    const secondSlash = text.indexOf("/", firstSlash + 1);
+    return { boardId: text.slice(0, firstSlash), seasonId: Number(text.slice(firstSlash + 1, secondSlash)), variantKey: text.slice(secondSlash + 1) };
+}
+/**
+ * Validates console-edited rules (D19): every limit an integer in range, blocked words a list of short strings (kept
+ * trimmed and lower-case).
+ * @param value The rules (any JSON).
+ * @returns The rules (null when there are problems) and one sentence per problem.
+ */
+export function validateRules(value) {
+    if (!isPlainObject(value))
+        return { rules: null, problems: ["rules must be an object"] };
+    const problems = [];
+    for (const limit of RULE_LIMITS) {
+        const limitValue = value[limit.field];
+        const isValid = typeof limitValue === "number" && Number.isSafeInteger(limitValue) && limitValue >= limit.minimum && limitValue <= limit.maximum;
+        if (!isValid)
+            problems.push(limit.field + " must be an integer from " + limit.minimum + " to " + limit.maximum);
+    }
+    const blockedWords = value.blockedWords;
+    const areWordsValid = Array.isArray(blockedWords) && blockedWords.length <= MAXIMUM_BLOCKED_WORDS
+        && blockedWords.every((word) => typeof word === "string" && word.trim().length > 0 && word.length <= MAXIMUM_BLOCKED_WORD_LENGTH);
+    if (!areWordsValid)
+        problems.push("blockedWords must be a list of at most " + MAXIMUM_BLOCKED_WORDS + " words of 1–" + MAXIMUM_BLOCKED_WORD_LENGTH + " characters");
+    if (problems.length > 0)
+        return { rules: null, problems: problems };
+    const rules = {
+        submissionsPerMinutePerPlayer: value.submissionsPerMinutePerPlayer,
+        submissionsPerMinutePerAddress: value.submissionsPerMinutePerAddress,
+        readsPerMinutePerAddress: value.readsPerMinutePerAddress,
+        identitiesPerHourPerAddress: value.identitiesPerHourPerAddress,
+        maximumScoresPerSubmission: value.maximumScoresPerSubmission,
+        metadataMaximumBytes: value.metadataMaximumBytes,
+        blockedWords: blockedWords.map((word) => word.trim().toLowerCase())
+    };
+    return { rules: rules, problems: [] };
+}
+/**
+ * The advice shown with a durability that is not "durable" (D20).
+ * @param durability The measured durability.
+ * @param storage Where the rankings live.
+ * @returns The advice sentence, or null.
+ */
+export function durabilityAdvice(durability, storage) {
+    if (durability === "notDurable" && storage === "file") {
+        return "Leaderboards are kept in files on this machine's own disk and are lost when it is replaced or redeployed. Set GAME_SERVER_REDIS_URL (on Colyseus Cloud, REDIS_URI) to a Redis with persistence, or mount a volume at GAME_SERVER_ADMIN_DATA_DIR, and export a backup now.";
+    }
+    if (durability === "notDurable" && storage === "redis") {
+        return "This Redis keeps no snapshot or append-only file, so a restart loses every leaderboard. Turn on appendonly (or RDB saves), or point GAME_SERVER_REDIS_URL at a managed Redis with persistence.";
+    }
+    if (durability === "unknown" && storage === "redis") {
+        return "This Redis does not say whether it persists data (INFO or CONFIG is restricted). Check your Redis host keeps snapshots, and export backups from the console.";
+    }
+    return null;
+}
+/**
+ * Whether a value is a plain object (not null, not an array).
+ * @param value Any value.
+ * @returns True for a plain object.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value != null && !Array.isArray(value);
+}
+/**
+ * Whether a value is JSON (strings, finite numbers, booleans, null, arrays, objects) nested within the metadata limit.
+ * @param value Any value.
+ * @param depth The nesting level of this value (the top-level object is 1).
+ * @returns True when it is JSON within the depth.
+ */
+function isJsonValue(value, depth) {
+    if (value == null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || depth > MAXIMUM_METADATA_DEPTH)
+        return false;
+    const children = Array.isArray(value) ? value : Object.values(value);
+    return children.every((child) => isJsonValue(child, depth + 1));
+}
+/**
+ * Problems of the board id, display name and description.
+ * @param value The definition.
+ * @returns The problems.
+ */
+function identityProblems(value) {
+    const problems = [];
+    if (typeof value.boardId !== "string" || !BOARD_ID_PATTERN.test(value.boardId)) {
+        problems.push("boardId must be 1–64 of a-z, 0-9 and -, starting with a letter or digit");
+    }
+    const nameLength = (typeof value.displayName === "string") ? value.displayName.trim().length : 0;
+    if (nameLength < 1 || nameLength > MAXIMUM_BOARD_NAME_LENGTH)
+        problems.push("displayName must be 1–" + MAXIMUM_BOARD_NAME_LENGTH + " characters");
+    if (typeof value.description !== "string" || value.description.length > MAXIMUM_DESCRIPTION_LENGTH) {
+        problems.push("description must be text of at most " + MAXIMUM_DESCRIPTION_LENGTH + " characters");
+    }
+    return problems;
+}
+/**
+ * Problems of the enum fields.
+ * @param value The definition.
+ * @returns The problems.
+ */
+function enumProblems(value) {
+    const enumFields = [
+        { field: "sortOrder", allowed: SORT_ORDERS },
+        { field: "scoreFormat", allowed: SCORE_FORMATS },
+        { field: "keepPolicy", allowed: KEEP_POLICIES },
+        { field: "visibility", allowed: VISIBILITIES },
+        { field: "resetSchedule", allowed: RESET_SCHEDULES }
+    ];
+    return enumFields
+        .filter((enumField) => !enumField.allowed.includes(value[enumField.field]))
+        .map((enumField) => enumField.field + " must be one of " + enumField.allowed.join(", "));
+}
+/**
+ * Problems of the score limits: null or integers within the absolute bound, minimum ≤ maximum.
+ * @param minimum The minimumScore.
+ * @param maximum The maximumScore.
+ * @returns The problems.
+ */
+function scoreLimitProblems(minimum, maximum) {
+    const problems = [];
+    if (!isScoreLimit(minimum))
+        problems.push("minimumScore must be null or an integer within ±" + LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE);
+    if (!isScoreLimit(maximum))
+        problems.push("maximumScore must be null or an integer within ±" + LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE);
+    if (problems.length === 0 && minimum != null && maximum != null && minimum > maximum) {
+        problems.push("minimumScore must not be greater than maximumScore");
+    }
+    return problems;
+}
+/**
+ * Whether a score limit is null or an integer within the absolute bound.
+ * @param value The limit.
+ * @returns True when valid.
+ */
+function isScoreLimit(value) {
+    if (value === null)
+        return true;
+    return typeof value === "number" && Number.isSafeInteger(value) && Math.abs(value) <= LEADERBOARD_MAXIMUM_ABSOLUTE_SCORE;
+}
+/**
+ * Problems of the accepted trust levels: a non-empty list of known levels without duplicates.
+ * @param value The acceptedTrustLevels.
+ * @returns The problems.
+ */
+function trustLevelProblems(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return ["acceptedTrustLevels must list at least one trust level"];
+    const areKnown = value.every((level) => typeof level === "string" && TRUST_LEVELS.includes(level));
+    if (!areKnown)
+        return ["acceptedTrustLevels may hold only " + TRUST_LEVELS.join(", ")];
+    if (new Set(value).size !== value.length)
+        return ["acceptedTrustLevels must not repeat a level"];
+    return [];
+}
+/**
+ * Problems of the dimension list: at most four, unique names, each dimension valid.
+ * @param value The dimensions.
+ * @returns The problems.
+ */
+function dimensionListProblems(value) {
+    if (!Array.isArray(value))
+        return ["dimensions must be a list"];
+    if (value.length > LEADERBOARD_MAXIMUM_DIMENSIONS)
+        return ["a board may declare at most " + LEADERBOARD_MAXIMUM_DIMENSIONS + " dimensions"];
+    const problems = value.flatMap((dimension, index) => dimensionProblems(dimension, index));
+    const names = value.map((dimension) => isPlainObject(dimension) ? dimension.name : null);
+    if (problems.length === 0 && new Set(names).size !== names.length)
+        problems.push("dimension names must be unique");
+    return problems;
+}
+/**
+ * Problems of one dimension: name pattern, label length, 1–100 unique values of 1–64 characters.
+ * @param dimension The dimension.
+ * @param index Its position (for the sentence).
+ * @returns The problems.
+ */
+function dimensionProblems(dimension, index) {
+    const label = "dimension " + (index + 1);
+    if (!isPlainObject(dimension))
+        return [label + " must be an object"];
+    const problems = [];
+    if (typeof dimension.name !== "string" || !DIMENSION_NAME_PATTERN.test(dimension.name)) {
+        problems.push(label + " name must be 1–32 of letters, digits, _ and -, starting with a letter");
+    }
+    const labelLength = (typeof dimension.label === "string") ? dimension.label.trim().length : 0;
+    if (labelLength < 1 || labelLength > MAXIMUM_LABEL_LENGTH)
+        problems.push(label + " label must be 1–" + MAXIMUM_LABEL_LENGTH + " characters");
+    const values = dimension.values;
+    const areValuesValid = Array.isArray(values) && values.length >= 1 && values.length <= LEADERBOARD_MAXIMUM_DIMENSION_VALUES
+        && values.every((entry) => typeof entry === "string" && entry.length >= 1 && entry.length <= LEADERBOARD_MAXIMUM_VALUE_LENGTH)
+        && new Set(values).size === values.length;
+    if (!areValuesValid) {
+        problems.push(label + " values must be 1–" + LEADERBOARD_MAXIMUM_DIMENSION_VALUES + " unique texts of 1–" + LEADERBOARD_MAXIMUM_VALUE_LENGTH + " characters");
+    }
+    return problems;
+}

package/lib/leaderboards/LeaderboardScheduler.d.ts

@@ -0,0 +1,43 @@
+import type { AdminClock } from "../admin/AdminClock.js";
+import type { AdminStore } from "../admin/AdminStore.js";
+import type { LeaderboardService } from "./LeaderboardService.js";
+/** Scheduled season resets and activity trimming, run on the lease holder (D17). */
+export declare class LeaderboardScheduler {
+    /** The service whose boards are reset. */
+    private readonly service;
+    /** The admin store (lease and activity). */
+    private readonly adminStore;
+    /** The service clock (timers and "now"). */
+    private readonly clock;
+    /** This process's id, read lazily (matchMaker.processId). */
+    private readonly processId;
+    /** Milliseconds between ticks. */
+    private readonly tickMs;
+    /** The interval handle while started, or null. */
+    private intervalHandle;
+    /** The tick in progress, or null; a tick that comes due meanwhile is skipped. */
+    private runningTick;
+    /**
+     * Creates the scheduler (nothing runs until start()).
+     * @param service The leaderboard service.
+     * @param adminStore The admin store.
+     * @param clock The service clock.
+     * @param processId This process's id.
+     * @param tickMs Milliseconds between ticks.
+     */
+    constructor(service: LeaderboardService, adminStore: AdminStore, clock: AdminClock, processId: () => string, tickMs: number);
+    /** Starts ticking every tickMs (a second call does nothing). */
+    start(): void;
+    /** Stops ticking and waits for a tick in progress. */
+    stop(): Promise<void>;
+    /**
+     * One tick: when this process holds the lease, resets every due board and trims the activity stream. Never throws;
+     * failures are logged at warn.
+     * @returns Resolves when the tick is done (the running tick when one is in progress).
+     */
+    tick(): Promise<void>;
+    /** The work of one tick. */
+    private runOnce;
+    /** Resets every board whose nextResetAt has come; a failing board is logged and the others still run. */
+    private resetDueBoards;
+}