@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/leaderboards/LeaderboardService.js

@@ -0,0 +1,1667 @@
+// The leaderboard service (game-server-leaderboards D4, DR §5): boards and seasons in the admin store, rankings and
+// players in the rank store, the submission pipeline, reads, activity, status and session presence. Created by
+// GameServer on every server, independent of the admin console. General purpose: nothing here knows any game (D2).
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { AdminConflictError } from "../admin/AdminStore.js";
+import { getLogger } from "../GameServerLogger.js";
+import { DEFAULT_LEADERBOARD_RULES, LEADERBOARD_DEFINITION_CACHE_MS, LEADERBOARD_DURATION_TOLERANCE_MS, LEADERBOARD_READ_CACHE_MS, LEADERBOARD_RULES_DOCUMENT_ID, LEADERBOARD_SESSION_WINDOW_MS, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_MINUTE, SUBMISSION_ID_PATTERN } from "./LeaderboardConstants.js";
+import { LeaderboardError } from "./LeaderboardError.js";
+import { ANONYMOUS_PLAYER_PREFIX, createAnonymousKey, defaultDisplayName, isPlayerKeyValid, MANUAL_PLAYER_PREFIX, parsePlayerKey, USER_PLAYER_PREFIX, userPlayerId } from "./LeaderboardIdentity.js";
+import { LeaderboardScheduler } from "./LeaderboardScheduler.js";
+import { checkMetadata, checkScore, cleanDisplayName, nextResetAt, rankKeyText, validateBoardDefinition, validateRules, variantKeyOf, variantValuesOf } from "./LeaderboardRules.js";
+/** Admin store collection of the boards. */
+const BOARDS_COLLECTION = "leaderboards";
+/** Admin store collection of the rules. */
+const SETTINGS_COLLECTION = "leaderboardSettings";
+/** Admin store stream of the activity (D21). */
+const ACTIVITY_STREAM = "leaderboardActivity";
+/** The format marker of a definitions file (D11). */
+const DEFINITIONS_FORMAT = "babylon-game-server-leaderboard-definitions";
+/** The format marker of an export file. */
+const EXPORT_FORMAT = "babylon-game-server-leaderboards";
+/** Retries of a season reset after a compare-and-set conflict. */
+const RESET_RETRY_LIMIT = 3;
+/** Records read per page of an activity scan. */
+const ACTIVITY_PAGE_SIZE = 500;
+/** Most records one activity read scans. */
+const ACTIVITY_SCAN_LIMIT = 5000;
+/** Longest gameMode and buildVersion. */
+const MAXIMUM_LABEL_TEXT_LENGTH = 64;
+/** Longest session name in a submission. */
+const MAXIMUM_SESSION_NAME_LENGTH = 128;
+/** Most players one search returns. */
+const PLAYER_SEARCH_LIMIT = 50;
+/** Rank shown on a removed entry (removed entries are not ranked). */
+const UNRANKED = 0;
+/** Most matches of an entry search. */
+const ENTRY_SEARCH_LIMIT = 50;
+/** Top-N read cache entries kept before the cache is emptied. */
+const READ_CACHE_CAPACITY = 1000;
+/** Who removes a hidden player's entries. */
+const SYSTEM_ACTOR = "system";
+/** Removal reason of a hidden player's entries (D18). */
+const PLAYER_HIDDEN_REASON = "playerHidden";
+/** Removal reason of an anonymous player's entry swept on start (leaderboard-signed-in-only D4). */
+const ANONYMOUS_PLAYER_REMOVAL_REASON = "anonymousPlayer";
+/** Who removes anonymous players' entries on start (leaderboard-signed-in-only D4). */
+const SERVER_REMOVER_NAME = "server";
+/** Outcomes that count as a personal best. */
+const PERSONAL_BEST_OUTCOMES = ["created", "improved", "replaced", "added"];
+/** Boards, seasons, rules, players, submissions, reads, activity, status and presence (D4). */
+export class LeaderboardService {
+    /** The options it was opened with. */
+    options;
+    /** The cached boards, or null. */
+    boardCache = null;
+    /** The cached rules, or null. */
+    rulesCache = null;
+    /** Cached top-N pages by `rankKeyText|offset|limit`. */
+    readCache = new Map();
+    /** The definitions-file problem found by the last start, or null. */
+    definitionsProblem = null;
+    /** The scheduler while started, or null. */
+    scheduler = null;
+    /**
+     * Creates the service; open() is the public way.
+     * @param options The options.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Opens the service (nothing runs until start()).
+     * @param options The stores, state, clock and scheduler settings.
+     * @returns The service.
+     */
+    static async open(options) {
+        return new LeaderboardService(options);
+    }
+    /** The admin store and rank store, for LeaderboardTransfer (T6). */
+    get stores() {
+        return { adminStore: this.options.adminStore, rankStore: this.options.rankStore };
+    }
+    /**
+     * Imports the definitions file, hides anonymous entries when only signed-in players may submit, starts listening for
+     * session presence and starts the scheduler.
+     */
+    async start() {
+        await this.importDefinitionsFile();
+        if (this.options.config.leaderboards.signedInPlayersOnly)
+            await this.hideAnonymousEntries();
+        this.options.state.onLeaderboardSessionPresence = (event) => this.recordPresence(event);
+        this.scheduler ??= new LeaderboardScheduler(this, this.options.adminStore, this.options.clock, this.options.processId, this.options.schedulerTickMs);
+        this.scheduler.start();
+    }
+    /** Stops the scheduler, stops listening for session presence and closes the rank store. */
+    async stop() {
+        await this.scheduler?.stop();
+        this.scheduler = null;
+        this.options.state.onLeaderboardSessionPresence = null;
+        await this.options.rankStore.close();
+    }
+    // ---- Boards and seasons -------------------------------------------------------------------------------------------
+    /**
+     * Lists every board document (cached for LEADERBOARD_DEFINITION_CACHE_MS), sorted by board id.
+     * @returns The documents.
+     */
+    async listBoardRecords() {
+        const boards = await this.cachedBoards();
+        return Array.from(boards.values()).sort((first, second) => first.id.localeCompare(second.id));
+    }
+    /**
+     * Reads one board document fresh from the admin store.
+     * @param boardId The board.
+     * @returns The document.
+     * @throws LeaderboardError 404 unknownBoard when it does not exist.
+     */
+    async getBoardRecord(boardId) {
+        const stored = await this.options.adminStore.getDocument(BOARDS_COLLECTION, boardId);
+        if (stored == null)
+            throw new LeaderboardError(404, "unknownBoard", "there is no leaderboard " + boardId);
+        return stored;
+    }
+    /**
+     * The public boards as game clients see them.
+     * @returns The boards, sorted by board id.
+     */
+    async listPublicBoards() {
+        const records = await this.listBoardRecords();
+        return records.filter((stored) => stored.value.definition.visibility === "public").map((stored) => toPublicBoardView(stored.value));
+    }
+    /**
+     * A board's console summary: definition, seasons, live entries of the current season and the last submission.
+     * @param stored The board document.
+     * @returns The summary.
+     */
+    async summarizeBoard(stored) {
+        const record = stored.value;
+        const variantKeys = await this.options.rankStore.listVariantKeys(record.definition.boardId, record.currentSeasonId);
+        let entryCount = 0;
+        for (const variantKey of variantKeys)
+            entryCount += await this.options.rankStore.count({ boardId: record.definition.boardId, seasonId: record.currentSeasonId, variantKey: variantKey });
+        return {
+            definition: record.definition,
+            revision: stored.revision,
+            currentSeasonId: record.currentSeasonId,
+            seasons: record.seasons,
+            nextResetAt: record.nextResetAt,
+            entryCount: entryCount,
+            lastSubmissionAt: await this.options.rankStore.readLastSubmissionAt(record.definition.boardId)
+        };
+    }
+    /**
+     * A board's detail view: its summary and every variant of one season with its top entry.
+     * @param boardId The board.
+     * @param seasonId The season, or null for the current one.
+     * @returns The detail view.
+     */
+    async describeBoard(boardId, seasonId) {
+        const stored = await this.getBoardRecord(boardId);
+        const resolvedSeasonId = resolveSeasonId(stored.value, seasonId);
+        const variants = [];
+        for (const variantKey of await this.options.rankStore.listVariantKeys(boardId, resolvedSeasonId)) {
+            const key = { boardId: boardId, seasonId: resolvedSeasonId, variantKey: variantKey };
+            const [topEntry] = await this.options.rankStore.readRange(key, 0, 1);
+            variants.push({ variantKey: variantKey, values: variantValuesOf(variantKey), entryCount: await this.options.rankStore.count(key), topEntry: (topEntry != null) ? toEntryView(topEntry) : null });
+        }
+        return { summary: await this.summarizeBoard(stored), seasonId: resolvedSeasonId, variants: variants };
+    }
+    /**
+     * Creates a board with season 1.
+     * @param definition The definition (any JSON; validated).
+     * @returns The new board's summary.
+     * @throws LeaderboardError 400 invalidRequest for an invalid definition; AdminConflictError when the id exists.
+     */
+    async createBoard(definition) {
+        const valid = requireValidDefinition(definition);
+        const stored = await this.options.adminStore.putDocument(BOARDS_COLLECTION, valid.boardId, this.newBoardRecord(valid), 0);
+        this.boardCache = null;
+        return await this.summarizeBoard(stored);
+    }
+    /**
+     * Updates a board's definition. Changing sortOrder, scoreFormat or keepPolicy while the current season has entries
+     * needs startNewSeason (D17); startNewSeason always starts the next season in the same write.
+     * @param boardId The board.
+     * @param definition The new definition (its boardId must match).
+     * @param revision The revision the editor read.
+     * @param startNewSeason True to start the next season.
+     * @returns The updated summary.
+     * @throws LeaderboardError 400 for an invalid definition, 409 for a ranking change that needs a new season;
+     *     AdminConflictError for a stale revision.
+     */
+    async updateBoard(boardId, definition, revision, startNewSeason) {
+        const valid = requireValidDefinition(definition);
+        if (valid.boardId !== boardId)
+            throw new LeaderboardError(400, "invalidRequest", "boardId cannot be changed; duplicate the board instead");
+        const stored = await this.getBoardRecord(boardId);
+        const current = stored.value.definition;
+        const changesRanking = valid.sortOrder !== current.sortOrder || valid.scoreFormat !== current.scoreFormat || valid.keepPolicy !== current.keepPolicy;
+        if (changesRanking && !startNewSeason && (await this.summarizeBoard(stored)).entryCount > 0) {
+            throw new LeaderboardError(409, "invalidRequest", "changing sortOrder, scoreFormat or keepPolicy needs a new season while the current season has entries; set startNewSeason");
+        }
+        const nowMs = this.options.clock.now();
+        const scheduleChanged = valid.resetSchedule !== current.resetSchedule;
+        const base = startNewSeason ? advanceSeason(stored.value, nowMs) : stored.value;
+        const updated = { ...base, definition: valid, nextResetAt: (scheduleChanged || startNewSeason) ? nextResetAt(valid.resetSchedule, nowMs) : base.nextResetAt };
+        const written = await this.options.adminStore.putDocument(BOARDS_COLLECTION, boardId, updated, revision);
+        this.boardCache = null;
+        return await this.summarizeBoard(written);
+    }
+    /**
+     * Creates a copy of a board's definition under a new id (no entries).
+     * @param boardId The source board.
+     * @param newBoardId The new id.
+     * @param displayName The new name.
+     * @returns The new board's summary.
+     */
+    async duplicateBoard(boardId, newBoardId, displayName) {
+        const stored = await this.getBoardRecord(boardId);
+        return await this.createBoard({ ...stored.value.definition, boardId: newBoardId, displayName: displayName });
+    }
+    /**
+     * Deletes a board and every ranking of every season (activity records stay, DR §15).
+     * @param boardId The board.
+     */
+    async deleteBoard(boardId) {
+        const stored = await this.getBoardRecord(boardId);
+        const seasonIds = stored.value.seasons.map((season) => season.seasonId);
+        await this.options.rankStore.deleteBoard(boardId, seasonIds);
+        await this.options.adminStore.deleteDocument(BOARDS_COLLECTION, boardId);
+        this.boardCache = null;
+        this.readCache.clear();
+    }
+    /**
+     * Ends the current season and starts the next (compare-and-set, retried on conflict). A scheduled reset that finds
+     * the board already reset by another writer returns without resetting again.
+     * @param boardId The board.
+     * @param trigger "admin" from the console, "schedule" from the scheduler.
+     * @returns The board's summary.
+     * @throws LeaderboardError 409 for a board that never resets.
+     */
+    async resetSeason(boardId, trigger) {
+        let lastConflict = null;
+        for (let attempt = 0; attempt <= RESET_RETRY_LIMIT; attempt++) {
+            const stored = await this.getBoardRecord(boardId);
+            if (stored.value.definition.resetSchedule === "never")
+                throw new LeaderboardError(409, "invalidRequest", "this board never resets; change its schedule first");
+            const nowMs = this.options.clock.now();
+            if (trigger === "schedule" && !isResetDue(stored.value, nowMs))
+                return await this.summarizeBoard(stored);
+            const advanced = { ...advanceSeason(stored.value, nowMs), nextResetAt: nextResetAt(stored.value.definition.resetSchedule, nowMs) };
+            try {
+                const written = await this.options.adminStore.putDocument(BOARDS_COLLECTION, boardId, advanced, stored.revision);
+                this.boardCache = null;
+                return await this.summarizeBoard(written);
+            }
+            catch (error) {
+                if (!(error instanceof AdminConflictError))
+                    throw error;
+                lastConflict = error;
+            }
+        }
+        throw lastConflict;
+    }
+    /**
+     * Deletes an archived season's rankings and drops it from the board's season list.
+     * @param boardId The board.
+     * @param seasonId The season.
+     * @returns How many entries were deleted.
+     * @throws LeaderboardError 409 for the current season, 404 for a season the board does not keep.
+     */
+    async deleteSeason(boardId, seasonId) {
+        const stored = await this.getBoardRecord(boardId);
+        if (seasonId === stored.value.currentSeasonId)
+            throw new LeaderboardError(409, "invalidRequest", "the current season cannot be deleted; reset the board first");
+        resolveSeasonId(stored.value, seasonId);
+        const deletedCount = await this.options.rankStore.deleteSeason(boardId, seasonId);
+        const seasons = stored.value.seasons.filter((season) => season.seasonId !== seasonId);
+        await this.options.adminStore.putDocument(BOARDS_COLLECTION, boardId, { ...stored.value, seasons: seasons }, stored.revision);
+        this.boardCache = null;
+        this.readCache.clear();
+        return deletedCount;
+    }
+    /**
+     * A board's seasons, oldest first.
+     * @param boardId The board.
+     * @param audience "public" hides hidden boards (404).
+     * @returns The seasons.
+     */
+    async listSeasons(boardId, audience) {
+        const record = await this.boardFor(boardId, audience);
+        return record.seasons;
+    }
+    // ---- Rules --------------------------------------------------------------------------------------------------------
+    /**
+     * The rules in force, the defaults and the stored revision (0 while the defaults apply).
+     * @returns The rules view.
+     */
+    async getRulesView() {
+        const nowMs = this.options.clock.now();
+        if (this.rulesCache != null && this.rulesCache.expiresAtMs > nowMs)
+            return this.rulesCache.view;
+        const stored = await this.options.adminStore.getDocument(SETTINGS_COLLECTION, LEADERBOARD_RULES_DOCUMENT_ID);
+        const view = {
+            rules: (stored != null) ? { ...DEFAULT_LEADERBOARD_RULES, ...stored.value } : { ...DEFAULT_LEADERBOARD_RULES },
+            defaults: { ...DEFAULT_LEADERBOARD_RULES },
+            revision: (stored != null) ? stored.revision : 0
+        };
+        this.rulesCache = { view: view, expiresAtMs: nowMs + LEADERBOARD_DEFINITION_CACHE_MS };
+        return view;
+    }
+    /**
+     * Saves new rules.
+     * @param rules The rules (any JSON; validated).
+     * @param revision The revision the editor read (0 while the defaults apply).
+     * @returns The new rules view.
+     * @throws LeaderboardError 400 for invalid rules; AdminConflictError for a stale revision.
+     */
+    async updateRules(rules, revision) {
+        const checked = validateRules(rules);
+        if (checked.rules == null)
+            throw new LeaderboardError(400, "invalidRequest", checked.problems.join("; "));
+        await this.options.adminStore.putDocument(SETTINGS_COLLECTION, LEADERBOARD_RULES_DOCUMENT_ID, checked.rules, revision);
+        this.rulesCache = null;
+        return await this.getRulesView();
+    }
+    // ---- Players and identity -----------------------------------------------------------------------------------------
+    /**
+     * Opens a player session (POST players): the auth user's player (created on first use), the player of a valid key,
+     * or a new anonymous player with its one-time key.
+     * @param caller The caller.
+     * @returns The player and, only for a new anonymous player, its key.
+     * @throws LeaderboardError 401 invalidPlayer for a wrong key, 429 rateLimited over identitiesPerHourPerAddress.
+     */
+    async openPlayerSession(caller) {
+        if (caller.userId != null || caller.playerKey != null) {
+            const player = await this.resolvePlayer(caller);
+            return { player: toPlayerView(player), playerKey: null };
+        }
+        const rules = (await this.getRulesView()).rules;
+        const nowMs = this.options.clock.now();
+        const isAllowed = await this.options.rankStore.consumeRate("identity-address:" + caller.clientAddress, rules.identitiesPerHourPerAddress, MILLISECONDS_PER_HOUR, nowMs);
+        if (!isAllowed)
+            throw new LeaderboardError(429, "rateLimited", "too many new players from this address; try again later");
+        const identity = createAnonymousKey();
+        const nowIso = new Date(nowMs).toISOString();
+        const record = { playerId: identity.playerId, kind: "anonymous", keyHash: identity.keyHash, displayName: defaultDisplayName(identity.playerId), hidden: false, createdAt: nowIso, lastSeenAt: nowIso };
+        await this.options.rankStore.putPlayer(record);
+        return { player: toPlayerView(record), playerKey: identity.playerKey };
+    }
+    /**
+     * Resolves the caller's player without creating an anonymous one: the auth user's player (its record is created on
+     * first use, D8) or the player of a valid key.
+     * @param caller The caller.
+     * @returns The player record.
+     * @throws LeaderboardError 401 invalidPlayer when there is no auth user and no valid key.
+     */
+    async resolvePlayer(caller) {
+        if (caller.userId != null)
+            return await this.userPlayer(caller.userId, caller.userDisplayName, caller.userAvatar);
+        const parsed = (caller.playerKey != null) ? parsePlayerKey(caller.playerKey) : null;
+        const record = (parsed != null) ? await this.options.rankStore.getPlayer(parsed.playerId) : null;
+        if (parsed == null || record == null || !isPlayerKeyValid(record, parsed.secret)) {
+            throw new LeaderboardError(401, "invalidPlayer", "the player key is missing or not valid");
+        }
+        return record;
+    }
+    /**
+     * The caller's own player (POST players/me).
+     * @param caller The caller.
+     * @returns The player.
+     * @throws LeaderboardError 401 invalidPlayer.
+     */
+    async getOwnPlayer(caller) {
+        return toPlayerView(await this.resolvePlayer(caller));
+    }
+    /**
+     * Erases the caller's own player and every entry of theirs (POST players/me/delete).
+     * @param caller The caller.
+     * @returns How many entries were deleted.
+     * @throws LeaderboardError 401 invalidPlayer.
+     */
+    async eraseOwnPlayer(caller) {
+        const player = await this.resolvePlayer(caller);
+        return await this.erasePlayer(player.playerId);
+    }
+    /**
+     * Gives a signed-in user their player at sign-in (D16): an existing player gets its name and avatar refreshed and
+     * nothing is merged; a new one is created and, when a valid anonymous key is sent, that anonymous player's history
+     * is merged into it (the anonymous player is erased by the merge).
+     * @param claim The user and the browser's anonymous key.
+     * @returns The player id and whether a merge happened.
+     */
+    async claimUserPlayer(claim) {
+        const playerId = userPlayerId(claim.userId);
+        const existing = await this.options.rankStore.getPlayer(playerId);
+        if (existing != null) {
+            await this.refreshUserProfile(existing, claim.displayName, claim.avatar);
+            return { playerId: playerId, merged: false };
+        }
+        const created = await this.userPlayer(claim.userId, claim.displayName, claim.avatar);
+        const anonymous = await this.anonymousPlayerOf(claim.anonymousPlayerKey);
+        if (anonymous == null)
+            return { playerId: created.playerId, merged: false };
+        await this.mergePlayers(anonymous.playerId, created.playerId);
+        return { playerId: created.playerId, merged: true };
+    }
+    /**
+     * Fills each entry's avatar from its player's record (only user: players can have one).
+     * @param entries The entries of one public read.
+     * @returns New entry objects with avatar set (null when the player has none).
+     */
+    async attachAvatars(entries) {
+        const avatarsByPlayer = new Map();
+        for (const entry of entries) {
+            if (!entry.playerId.startsWith(USER_PLAYER_PREFIX) || avatarsByPlayer.has(entry.playerId))
+                continue;
+            const record = await this.options.rankStore.getPlayer(entry.playerId);
+            avatarsByPlayer.set(entry.playerId, record?.avatar ?? null);
+        }
+        return entries.map((entry) => ({ ...entry, avatar: avatarsByPlayer.get(entry.playerId) ?? null }));
+    }
+    /**
+     * Consumes one public read of an address against readsPerMinutePerAddress (D19 read limit scope).
+     * @param clientAddress The caller's address.
+     * @throws LeaderboardError 429 rateLimited.
+     */
+    async consumeReadRate(clientAddress) {
+        const rules = (await this.getRulesView()).rules;
+        const isAllowed = await this.options.rankStore.consumeRate("read-address:" + clientAddress, rules.readsPerMinutePerAddress, MILLISECONDS_PER_MINUTE, this.options.clock.now());
+        if (!isAllowed)
+            throw new LeaderboardError(429, "rateLimited", "too many leaderboard reads; try again in a minute");
+    }
+    /**
+     * Renames the caller's own player (POST players/me/name) with the current rules' blocked words.
+     * @param caller The caller.
+     * @param displayName The new name (any JSON; cleaned).
+     * @returns The player.
+     * @throws LeaderboardError 403 nameManaged for a signed-in caller whose session owns the name, 400 nameInvalid or
+     *         nameBlocked, 401 invalidPlayer.
+     */
+    async renameOwnPlayer(caller, displayName) {
+        if (caller.isNameManaged)
+            throw new LeaderboardError(403, "nameManaged", "this player's name comes from their sign-in and cannot be changed here");
+        const player = await this.resolvePlayer(caller);
+        const cleanName = await this.requireCleanName(displayName);
+        const renamed = { ...player, displayName: cleanName, lastSeenAt: this.nowIso() };
+        await this.options.rankStore.putPlayer(renamed);
+        await this.options.rankStore.renamePlayerEntries(player.playerId, cleanName);
+        this.readCache.clear();
+        return toPlayerView(renamed);
+    }
+    // ---- Submissions and reads ----------------------------------------------------------------------------------------
+    /**
+     * Runs the submission pipeline (DR §10) in its binding order: request shape, score count, player, rate limits, trust,
+     * then per score board, variant, score, trust, metadata and write, each recorded in activity.
+     * @param caller The caller.
+     * @param request The envelope (a LeaderboardServerSubmissionRequest for source "server").
+     * @param source "public" from the public API, "server" from the admin route (server trust).
+     * @returns The per-score results.
+     * @throws LeaderboardError 400 invalidRequest or tooManyScores, 401 invalidPlayer, 403 signInRequired (a public
+     *     caller with no auth user id while leaderboards.signedInPlayersOnly is on), 429 rateLimited.
+     */
+    async submit(caller, request, source) {
+        requireValidEnvelope(request);
+        if (source === "public" && this.options.config.leaderboards.signedInPlayersOnly && caller.userId == null) {
+            throw new LeaderboardError(403, "signInRequired", "this server's leaderboards accept only signed-in players");
+        }
+        const rules = (await this.getRulesView()).rules;
+        if (request.scores.length > rules.maximumScoresPerSubmission) {
+            throw new LeaderboardError(400, "tooManyScores", "a submission may carry at most " + rules.maximumScoresPerSubmission + " scores");
+        }
+        const player = (source === "server") ? await this.serverPlayer(request) : await this.resolvePlayer(caller);
+        const nowMs = this.options.clock.now();
+        const context = { caller: caller, request: request, source: source, player: player, rules: rules, nowMs: nowMs, baseTrust: baseTrustOf(source, request) };
+        if (source === "public")
+            await this.consumeSubmissionRates(context);
+        const results = [];
+        for (const score of request.scores)
+            results.push(await this.submitScore(context, score));
+        await this.options.rankStore.putPlayer({ ...player, lastSeenAt: new Date(nowMs).toISOString() });
+        return { submissionId: request.submissionId, playerId: player.playerId, results: results };
+    }
+    /**
+     * Reads a page of one ranking (top-N reads are cached for LEADERBOARD_READ_CACHE_MS).
+     * @param boardId The board.
+     * @param variant The variant (null or {} without dimensions).
+     * @param seasonId The season, or null for the current one.
+     * @param offset Zero-based index of the first entry.
+     * @param limit Most entries.
+     * @param audience "public" hides hidden boards and checks variant values; "admin" also reads retired values.
+     * @returns The page.
+     */
+    async readEntries(boardId, variant, seasonId, offset, limit, audience) {
+        const key = await this.rankKeyFor(boardId, variant, seasonId, audience);
+        const cacheKey = rankKeyText(key) + "|" + offset + "|" + limit;
+        const nowMs = this.options.clock.now();
+        const cached = this.readCache.get(cacheKey);
+        if (cached != null && cached.expiresAtMs > nowMs)
+            return cached.page;
+        const entries = await this.options.rankStore.readRange(key, offset, limit);
+        const page = { ...pageHeader(key, await this.options.rankStore.count(key)), offset: offset, entries: entries.map(toEntryView) };
+        if (this.readCache.size >= READ_CACHE_CAPACITY)
+            this.readCache.clear();
+        this.readCache.set(cacheKey, { page: page, expiresAtMs: nowMs + LEADERBOARD_READ_CACHE_MS });
+        return page;
+    }
+    /**
+     * Finds entries of one ranking by name or player id (console search).
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @param text The text.
+     * @returns The matches as a page.
+     */
+    async searchEntries(boardId, variantKey, seasonId, text) {
+        await this.getBoardRecord(boardId);
+        const key = { boardId: boardId, seasonId: seasonId, variantKey: variantKey };
+        const entries = await this.options.rankStore.searchEntries(key, text, ENTRY_SEARCH_LIMIT);
+        return { ...pageHeader(key, await this.options.rankStore.count(key)), offset: 0, entries: entries.map(toEntryView) };
+    }
+    /**
+     * Reads the window around a player's entry.
+     * @param boardId The board.
+     * @param variant The variant.
+     * @param seasonId The season, or null for the current one.
+     * @param playerId The player.
+     * @param window Entries above and below.
+     * @returns The page with the player's rank (null without an entry).
+     */
+    async readAround(boardId, variant, seasonId, playerId, window) {
+        const key = await this.rankKeyFor(boardId, variant, seasonId, "public");
+        const entries = await this.options.rankStore.readAround(key, playerId, window);
+        const own = entries.find((entry) => entry.playerId === playerId);
+        const offset = (entries.length > 0) ? entries[0].rank - 1 : 0;
+        return { ...pageHeader(key, await this.options.rankStore.count(key)), offset: offset, entries: entries.map(toEntryView), playerRank: (own != null) ? own.rank : null };
+    }
+    /**
+     * Reads a player's entry in each of several rankings.
+     * @param playerId The player.
+     * @param targets The rankings.
+     * @returns One answer per target, in order.
+     */
+    async readTargets(playerId, targets) {
+        const answers = [];
+        for (const target of targets) {
+            const key = await this.rankKeyFor(target.boardId, target.variant, target.seasonId ?? null, "public");
+            const entry = await this.options.rankStore.readEntry(key, playerId);
+            answers.push({ boardId: key.boardId, variantKey: key.variantKey, seasonId: key.seasonId, total: await this.options.rankStore.count(key), entry: (entry != null) ? toEntryView(entry) : null });
+        }
+        return answers;
+    }
+    /**
+     * Reads the entries of named players in one ranking (friends lists).
+     * @param boardId The board.
+     * @param variant The variant.
+     * @param seasonId The season, or null for the current one.
+     * @param playerIds The players.
+     * @returns The entries they have, by rank.
+     */
+    async readPlayersEntries(boardId, variant, seasonId, playerIds) {
+        const key = await this.rankKeyFor(boardId, variant, seasonId, "public");
+        const entries = [];
+        for (const playerId of new Set(playerIds)) {
+            const entry = await this.options.rankStore.readEntry(key, playerId);
+            if (entry != null)
+                entries.push(toEntryView(entry));
+        }
+        return entries.sort((first, second) => first.rank - second.rank);
+    }
+    // ---- Moderation ---------------------------------------------------------------------------------------------------
+    /**
+     * The removed entries of one ranking, newest removal first.
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @returns The removed entries (rank 0: they are not ranked).
+     */
+    async readRemoved(boardId, variantKey, seasonId) {
+        const key = await this.adminRankKey(boardId, variantKey, seasonId);
+        const removed = await this.options.rankStore.readRemoved(key);
+        return removed.map(toRemovedEntryView);
+    }
+    /**
+     * Removes a live entry from its ranking (D18).
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @param playerId The player.
+     * @param reason Why (shown in the console).
+     * @param actorName Who removed it.
+     * @throws LeaderboardError 404 when the player has no live entry.
+     */
+    async removeEntry(boardId, variantKey, seasonId, playerId, reason, actorName) {
+        const key = await this.adminRankKey(boardId, variantKey, seasonId);
+        const wasRemoved = await this.options.rankStore.removeEntry(key, playerId, reason, actorName, this.nowIso());
+        if (!wasRemoved)
+            throw new LeaderboardError(404, "invalidRequest", "player " + playerId + " has no live entry in this ranking");
+        this.forgetCachedReads(key);
+    }
+    /**
+     * Puts a removed entry back into its ranking.
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @param playerId The player.
+     * @throws LeaderboardError 409 while the player has a live entry, 404 when nothing was removed.
+     */
+    async restoreEntry(boardId, variantKey, seasonId, playerId) {
+        const record = (await this.getBoardRecord(boardId)).value;
+        const key = { boardId: boardId, seasonId: resolveSeasonId(record, seasonId), variantKey: variantKey };
+        const restored = await this.options.rankStore.restoreEntry(key, playerId, record.definition.sortOrder);
+        if (restored === "liveEntryExists")
+            throw new LeaderboardError(409, "invalidRequest", "this player already has a live entry in this ranking; remove it first");
+        if (restored === "missing")
+            throw new LeaderboardError(404, "invalidRequest", "player " + playerId + " has no removed entry in this ranking");
+        this.forgetCachedReads(key);
+    }
+    /**
+     * Corrects a live entry's score (keep policy latest, a fresh achieved time).
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @param playerId The player.
+     * @param score The corrected score.
+     * @returns The corrected entry with its new rank.
+     * @throws LeaderboardError 400 for a score the board refuses, 404 without a live entry.
+     */
+    async correctEntry(boardId, variantKey, seasonId, playerId, score) {
+        const record = (await this.getBoardRecord(boardId)).value;
+        requireAcceptableScore(record.definition, score);
+        const key = { boardId: boardId, seasonId: resolveSeasonId(record, seasonId), variantKey: variantKey };
+        const current = await this.options.rankStore.readEntry(key, playerId);
+        if (current == null)
+            throw new LeaderboardError(404, "invalidRequest", "player " + playerId + " has no live entry in this ranking");
+        const nowMs = this.options.clock.now();
+        const nowIso = new Date(nowMs).toISOString();
+        const corrected = { ...withoutRank(current), score: score, submittedAt: nowIso, achievedAt: nowIso, achievedAtMs: nowMs, submissionCount: 1 };
+        return await this.writeAdminEntry(key, record, corrected);
+    }
+    /**
+     * Adds an entry by hand at server trust: for a new manual player when playerId is null, else for that player.
+     * @param boardId The board.
+     * @param variant The variant.
+     * @param playerId The player, or null to create a manual player.
+     * @param displayName The new manual player's name (cleaned).
+     * @param score The score.
+     * @returns The entry with its rank.
+     * @throws LeaderboardError 400 for a bad variant, score or name, 404 for an unknown player.
+     */
+    async addEntry(boardId, variant, playerId, displayName, score) {
+        const record = (await this.getBoardRecord(boardId)).value;
+        const variantKey = requireVariantKey(record.definition, variant);
+        requireAcceptableScore(record.definition, score);
+        const player = (playerId == null) ? await this.createManualPlayer(displayName) : await this.requirePlayer(playerId);
+        const nowMs = this.options.clock.now();
+        const nowIso = new Date(nowMs).toISOString();
+        const entry = {
+            playerId: player.playerId,
+            displayName: player.displayName,
+            score: score,
+            metadata: null,
+            trustLevel: "server",
+            sessionName: null,
+            gameMode: null,
+            buildVersion: null,
+            submittedAt: nowIso,
+            achievedAt: nowIso,
+            achievedAtMs: nowMs,
+            submissionCount: 1
+        };
+        return await this.writeAdminEntry({ boardId: boardId, seasonId: record.currentSeasonId, variantKey: variantKey }, record, entry);
+    }
+    // ---- Players ------------------------------------------------------------------------------------------------------
+    /**
+     * Renames a player and every entry of theirs.
+     * @param playerId The player.
+     * @param displayName The new name (cleaned with the blocked words).
+     * @returns The player.
+     * @throws LeaderboardError 400 nameInvalid or nameBlocked, 404 for an unknown player.
+     */
+    async renamePlayer(playerId, displayName) {
+        const cleanName = await this.requireCleanName(displayName);
+        const player = await this.requirePlayer(playerId);
+        const renamed = { ...player, displayName: cleanName };
+        await this.options.rankStore.putPlayer(renamed);
+        await this.options.rankStore.renamePlayerEntries(playerId, cleanName);
+        this.readCache.clear();
+        return toPlayerAdminView(renamed);
+    }
+    /**
+     * Hides a player (every live entry moves to removed with reason playerHidden, D18) or unhides them (those entries
+     * come back).
+     * @param playerId The player.
+     * @param hidden True to hide.
+     * @param actorName Who did it.
+     * @returns The player.
+     * @throws LeaderboardError 404 for an unknown player.
+     */
+    async hidePlayer(playerId, hidden, actorName) {
+        const player = await this.requirePlayer(playerId);
+        const updated = { ...player, hidden: hidden };
+        await this.options.rankStore.putPlayer(updated);
+        const nowIso = this.nowIso();
+        for (const key of await this.options.rankStore.listPlayerRankKeys(playerId)) {
+            if (hidden)
+                await this.options.rankStore.removeEntry(key, playerId, PLAYER_HIDDEN_REASON, actorName, nowIso);
+            else
+                await this.restoreHiddenEntry(key, playerId);
+        }
+        this.readCache.clear();
+        return toPlayerAdminView(updated);
+    }
+    /**
+     * Merges one player into another (DR §15): per ranking of the source, the target board's keep policy decides — best
+     * keeps the better, latest the later, sum adds — then the source is erased.
+     * @param sourcePlayerId The player merged away.
+     * @param targetPlayerId The player kept.
+     * @returns The target's detail.
+     * @throws LeaderboardError 400 for the same player, 404 for an unknown one.
+     */
+    async mergePlayers(sourcePlayerId, targetPlayerId) {
+        if (sourcePlayerId === targetPlayerId)
+            throw new LeaderboardError(400, "invalidRequest", "a player cannot be merged into itself");
+        await this.requirePlayer(sourcePlayerId);
+        const target = await this.requirePlayer(targetPlayerId);
+        const boards = await this.freshBoards();
+        for (const key of await this.options.rankStore.listPlayerRankKeys(sourcePlayerId)) {
+            const board = boards.get(key.boardId);
+            const sourceEntry = await this.options.rankStore.readEntry(key, sourcePlayerId);
+            if (board == null || sourceEntry == null)
+                continue;
+            await this.mergeEntry(key, board.value.definition, withoutRank(sourceEntry), target);
+        }
+        await this.erasePlayer(sourcePlayerId);
+        return await this.getPlayerDetail(targetPlayerId);
+    }
+    /**
+     * Erases a player: every entry, live and removed, and the player record.
+     * @param playerId The player.
+     * @returns How many entries were deleted.
+     * @throws LeaderboardError 404 for a player with neither a record nor entries.
+     */
+    async erasePlayer(playerId) {
+        const erasedCount = await this.options.rankStore.deletePlayerEntries(playerId);
+        const hadRecord = await this.options.rankStore.deletePlayer(playerId);
+        if (!hadRecord && erasedCount === 0)
+            throw new LeaderboardError(404, "invalidPlayer", "there is no player " + playerId);
+        this.readCache.clear();
+        return erasedCount;
+    }
+    /**
+     * A player and every entry of theirs across boards and seasons, live or removed.
+     * @param playerId The player.
+     * @returns The detail.
+     * @throws LeaderboardError 404 for an unknown player.
+     */
+    async getPlayerDetail(playerId) {
+        const player = await this.requirePlayer(playerId);
+        const boards = await this.cachedBoards();
+        const entries = [];
+        for (const key of await this.options.rankStore.listPlayerRankKeys(playerId)) {
+            const entry = await this.playerEntryView(key, playerId, boards.get(key.boardId)?.value ?? null);
+            if (entry != null)
+                entries.push(entry);
+        }
+        return { player: toPlayerAdminView(player), entries: entries };
+    }
+    /**
+     * Finds players by name or id.
+     * @param text The text ("" lists any).
+     * @returns Up to 50 players.
+     */
+    async searchPlayers(text) {
+        const players = await this.options.rankStore.searchPlayers(text, PLAYER_SEARCH_LIMIT);
+        return players.map(toPlayerAdminView);
+    }
+    // ---- Activity, status and presence --------------------------------------------------------------------------------
+    /**
+     * Reads activity newest first, filtered by kind and board, scanning at most ACTIVITY_SCAN_LIMIT records (it may
+     * return fewer than limit; the console pages with the oldest sequence shown).
+     * @param kind The kind, or null for all.
+     * @param boardId The board, or null for all.
+     * @param beforeSequence Only records older than this sequence, or null.
+     * @param limit Most records.
+     * @param includeAddresses True to keep client addresses (players.viewAddresses).
+     * @returns The records.
+     */
+    async readActivity(kind, boardId, beforeSequence, limit, includeAddresses) {
+        const matches = [];
+        let cursor = beforeSequence;
+        let scannedCount = 0;
+        while (matches.length < limit && scannedCount < ACTIVITY_SCAN_LIMIT) {
+            const page = await this.options.adminStore.readRecords(ACTIVITY_STREAM, { newestFirst: true, limit: ACTIVITY_PAGE_SIZE, beforeSequence: cursor ?? undefined });
+            for (const record of page) {
+                const isMatch = (kind == null || record.value.kind === kind) && (boardId == null || record.value.boardId === boardId);
+                if (isMatch && matches.length < limit)
+                    matches.push(toActivityView(record, includeAddresses));
+            }
+            scannedCount += page.length;
+            if (page.length < ACTIVITY_PAGE_SIZE)
+                break;
+            cursor = page[page.length - 1].sequence;
+        }
+        return matches;
+    }
+    /**
+     * The status view: storage, durability, the definitions problem, boards and fleet-wide per-minute counts (D20, D21).
+     * @returns The status.
+     */
+    async status() {
+        const nowMs = this.options.clock.now();
+        const records = await this.options.adminStore.readRecords(ACTIVITY_STREAM, { newestFirst: true, limit: ACTIVITY_SCAN_LIMIT });
+        const recent = records.filter((record) => Date.parse(record.at) >= nowMs - MILLISECONDS_PER_MINUTE);
+        const durability = await this.options.rankStore.measureDurability();
+        return {
+            storage: (this.options.rankStore.kind === "redis") ? "redis" : "files",
+            durability: durability.durability,
+            durabilityAdvice: durability.advice,
+            definitionsProblem: this.definitionsProblem,
+            boardCount: (await this.cachedBoards()).size,
+            acceptedPerMinute: recent.filter((record) => record.value.kind === "accepted").length,
+            refusedPerMinute: recent.filter((record) => record.value.kind === "refused").length
+        };
+    }
+    /**
+     * Records a session join for session-level trust (D10). Fire-and-forget: errors are logged at warn, never thrown.
+     * @param event The join or leave (leaves are ignored).
+     */
+    recordPresence(event) {
+        if (event.kind !== "joined")
+            return;
+        const subjects = ["address:" + event.clientAddress];
+        if (event.userId != null)
+            subjects.push("user:" + event.userId);
+        this.options.rankStore.recordSessionPresence(event.sessionName, subjects, this.options.clock.now(), LEADERBOARD_SESSION_WINDOW_MS).catch((error) => {
+            getLogger().warn("leaderboard session presence was not recorded", { sessionName: event.sessionName, error: errorText(error) });
+        });
+    }
+    // ---- Private helpers ----------------------------------------------------------------------------------------------
+    /**
+     * The board documents, cached for LEADERBOARD_DEFINITION_CACHE_MS.
+     * @returns Board id → document.
+     */
+    async cachedBoards() {
+        const nowMs = this.options.clock.now();
+        if (this.boardCache != null && this.boardCache.expiresAtMs > nowMs)
+            return this.boardCache.boards;
+        const documents = await this.options.adminStore.listDocuments(BOARDS_COLLECTION);
+        const boards = new Map(documents.map((stored) => [stored.id, stored]));
+        this.boardCache = { boards: boards, expiresAtMs: nowMs + LEADERBOARD_DEFINITION_CACHE_MS };
+        return boards;
+    }
+    /**
+     * A board for a read, from the cache: public reads see only public boards.
+     * @param boardId The board.
+     * @param audience "public" or "admin".
+     * @returns The board record.
+     * @throws LeaderboardError 404 unknownBoard.
+     */
+    async boardFor(boardId, audience) {
+        const stored = (await this.cachedBoards()).get(boardId);
+        const isVisible = stored != null && (audience === "admin" || stored.value.definition.visibility === "public");
+        if (stored == null || !isVisible)
+            throw new LeaderboardError(404, "unknownBoard", "there is no leaderboard " + boardId);
+        return stored.value;
+    }
+    /**
+     * The rank key of a read: the board, its variant key and the season.
+     * @param boardId The board.
+     * @param variant The variant.
+     * @param seasonId The season, or null for the current one.
+     * @param audience "public" checks variant values; "admin" also accepts values a board no longer allows (DR §15).
+     * @returns The rank key.
+     * @throws LeaderboardError 404 unknownBoard or for an unknown season, 400 variantNotAllowed.
+     */
+    async rankKeyFor(boardId, variant, seasonId, audience) {
+        const record = await this.boardFor(boardId, audience);
+        const variantKey = (audience === "admin") ? adminVariantKeyOf(record.definition, variant) : requireVariantKey(record.definition, variant);
+        return { boardId: boardId, seasonId: resolveSeasonId(record, seasonId), variantKey: variantKey };
+    }
+    /**
+     * A new board record with season 1 starting now.
+     * @param definition The valid definition.
+     * @returns The record.
+     */
+    newBoardRecord(definition) {
+        const nowMs = this.options.clock.now();
+        const nowIso = new Date(nowMs).toISOString();
+        return {
+            definition: definition,
+            currentSeasonId: 1,
+            seasons: [{ seasonId: 1, startedAt: nowIso, endedAt: null, isCurrent: true }],
+            nextResetAt: nextResetAt(definition.resetSchedule, nowMs),
+            createdAt: nowIso
+        };
+    }
+    /**
+     * Imports the definitions file (D11): creates each valid board that does not exist yet and records any problem.
+     */
+    async importDefinitionsFile() {
+        const definitionsFile = this.options.config.leaderboards.definitionsFile;
+        this.definitionsProblem = null;
+        if (definitionsFile == null)
+            return;
+        const filePath = path.resolve(definitionsFile);
+        const problems = [];
+        const definitions = await readDefinitions(filePath, problems);
+        for (const value of definitions) {
+            const checked = validateBoardDefinition(value);
+            if (checked.definition == null) {
+                problems.push(describeBoardValue(value) + ": " + checked.problems.join(", "));
+                continue;
+            }
+            await this.createBoardIfMissing(checked.definition);
+        }
+        this.boardCache = null;
+        if (problems.length === 0)
+            return;
+        this.definitionsProblem = problems.join("; ");
+        getLogger().error("leaderboard definitions file " + filePath + " has problems: " + this.definitionsProblem);
+    }
+    /**
+     * Moves every anonymous player's live entry, in every kept season of every board, to its ranking's removed list
+     * (leaderboard-signed-in-only D4). Entries stay restorable from the console and player records are untouched.
+     * Idempotent: a second run finds nothing left to move.
+     * @returns How many entries were moved.
+     */
+    async hideAnonymousEntries() {
+        const nowIso = this.nowIso();
+        let hiddenCount = 0;
+        for (const stored of await this.listBoardRecords()) {
+            const boardId = stored.value.definition.boardId;
+            for (const season of stored.value.seasons) {
+                for (const variantKey of await this.options.rankStore.listVariantKeys(boardId, season.seasonId)) {
+                    const key = { boardId: boardId, seasonId: season.seasonId, variantKey: variantKey };
+                    hiddenCount += await this.hideAnonymousEntriesOf(key, nowIso);
+                }
+            }
+        }
+        this.readCache.clear();
+        if (hiddenCount > 0)
+            getLogger().info("leaderboards: moved " + hiddenCount + " anonymous entries to the removed lists (signedInPlayersOnly)");
+        return hiddenCount;
+    }
+    /**
+     * Moves the anonymous players' live entries of one ranking to its removed list.
+     * @param key The ranking.
+     * @param nowIso The removal time (ISO).
+     * @returns How many entries were moved.
+     */
+    async hideAnonymousEntriesOf(key, nowIso) {
+        const entryCount = await this.options.rankStore.count(key);
+        const entries = await this.options.rankStore.readRange(key, 0, entryCount);
+        const anonymousEntries = entries.filter((entry) => entry.playerId.startsWith(ANONYMOUS_PLAYER_PREFIX));
+        let hiddenCount = 0;
+        for (const entry of anonymousEntries) {
+            const wasRemoved = await this.options.rankStore.removeEntry(key, entry.playerId, ANONYMOUS_PLAYER_REMOVAL_REASON, SERVER_REMOVER_NAME, nowIso);
+            if (wasRemoved)
+                hiddenCount += 1;
+        }
+        return hiddenCount;
+    }
+    /**
+     * Creates a board unless another process or the console already has it.
+     * @param definition The valid definition.
+     */
+    async createBoardIfMissing(definition) {
+        try {
+            await this.options.adminStore.putDocument(BOARDS_COLLECTION, definition.boardId, this.newBoardRecord(definition), 0);
+        }
+        catch (error) {
+            if (!(error instanceof AdminConflictError))
+                throw error;
+        }
+    }
+    /**
+     * The auth user's player record, created with the claim name (or a default) on first use; an existing record keeps
+     * its own name.
+     * @param userId The auth user id.
+     * @param userDisplayName The name claim, or null.
+     * @param userAvatar The avatar claim, or null (stored only when the record is created).
+     * @returns The record.
+     */
+    async userPlayer(userId, userDisplayName, userAvatar) {
+        const playerId = userPlayerId(userId);
+        const existing = await this.options.rankStore.getPlayer(playerId);
+        if (existing != null)
+            return existing;
+        const rules = (await this.getRulesView()).rules;
+        const nowIso = this.nowIso();
+        const displayName = cleanDisplayName(userDisplayName, rules.blockedWords).displayName ?? defaultDisplayName(playerId);
+        const record = { playerId: playerId, kind: "user", keyHash: null, displayName: displayName, avatar: userAvatar, hidden: false, createdAt: nowIso, lastSeenAt: nowIso };
+        await this.options.rankStore.putPlayer(record);
+        return record;
+    }
+    /**
+     * Refreshes an existing user player's name and avatar from a new sign-in (D16); its entries take the new name.
+     * @param record The stored player.
+     * @param displayName The sign-in's display name (cleaned; a refused name keeps the stored one).
+     * @param avatar The sign-in's avatar claim, or null.
+     */
+    async refreshUserProfile(record, displayName, avatar) {
+        const rules = (await this.getRulesView()).rules;
+        const cleanName = cleanDisplayName(displayName, rules.blockedWords).displayName ?? record.displayName;
+        const isNameChanged = cleanName !== record.displayName;
+        if (!isNameChanged && (record.avatar ?? null) === avatar)
+            return;
+        await this.options.rankStore.putPlayer({ ...record, displayName: cleanName, avatar: avatar, lastSeenAt: this.nowIso() });
+        if (isNameChanged)
+            await this.options.rankStore.renamePlayerEntries(record.playerId, cleanName);
+        this.readCache.clear();
+    }
+    /**
+     * The anonymous player a browser's key names, when the key is valid.
+     * @param playerKey The anonymous player key, or null.
+     * @returns The anonymous record, or null when the key is missing, malformed, unknown, not anonymous or not valid.
+     */
+    async anonymousPlayerOf(playerKey) {
+        if (playerKey == null)
+            return null;
+        const parsed = parsePlayerKey(playerKey);
+        if (parsed == null)
+            return null;
+        const record = await this.options.rankStore.getPlayer(parsed.playerId);
+        if (record == null || record.kind !== "anonymous" || !isPlayerKeyValid(record, parsed.secret))
+            return null;
+        return record;
+    }
+    /**
+     * The player of a server-trust submission: the named player, or one created when unknown and a name is given (DR §6):
+     * kind user for a user: id (discord-sign-in F1), else manual.
+     * @param request The server submission.
+     * @returns The record.
+     * @throws LeaderboardError 400 invalidPlayer for an unknown player without a name.
+     */
+    async serverPlayer(request) {
+        if (typeof request.playerId !== "string" || request.playerId === "")
+            throw new LeaderboardError(400, "invalidRequest", "playerId must be a player id");
+        const existing = await this.options.rankStore.getPlayer(request.playerId);
+        if (existing != null)
+            return existing;
+        if (request.displayName == null)
+            throw new LeaderboardError(400, "invalidPlayer", "there is no player " + request.playerId + "; give a displayName to create one");
+        const displayName = await this.requireCleanName(request.displayName);
+        const nowIso = this.nowIso();
+        const kind = request.playerId.startsWith(USER_PLAYER_PREFIX) ? "user" : "manual";
+        const record = { playerId: request.playerId, kind: kind, keyHash: null, displayName: displayName, hidden: false, createdAt: nowIso, lastSeenAt: nowIso };
+        await this.options.rankStore.putPlayer(record);
+        return record;
+    }
+    /**
+     * Cleans a display name with the current rules' blocked words.
+     * @param displayName The name (any JSON).
+     * @returns The clean name.
+     * @throws LeaderboardError 400 nameInvalid or nameBlocked.
+     */
+    async requireCleanName(displayName) {
+        const rules = (await this.getRulesView()).rules;
+        const cleaned = cleanDisplayName(displayName, rules.blockedWords);
+        if (cleaned.displayName == null) {
+            const sentence = (cleaned.refusal === "nameBlocked") ? "that name contains a blocked word" : "a name must be 1–24 characters without control characters";
+            throw new LeaderboardError(400, cleaned.refusal ?? "nameInvalid", sentence);
+        }
+        return cleaned.displayName;
+    }
+    /**
+     * Consumes the per-player and per-address submission limits; a refusal is recorded in activity and thrown.
+     * @param context The submission.
+     * @throws LeaderboardError 429 rateLimited.
+     */
+    async consumeSubmissionRates(context) {
+        const rankStore = this.options.rankStore;
+        const isPlayerAllowed = await rankStore.consumeRate("submit-player:" + context.player.playerId, context.rules.submissionsPerMinutePerPlayer, MILLISECONDS_PER_MINUTE, context.nowMs);
+        const isAddressAllowed = isPlayerAllowed && await rankStore.consumeRate("submit-address:" + context.caller.clientAddress, context.rules.submissionsPerMinutePerAddress, MILLISECONDS_PER_MINUTE, context.nowMs);
+        if (isAddressAllowed)
+            return;
+        await this.appendActivity(context, { boardId: null, variantKey: null, score: null, outcome: null, reason: "rateLimited", trustLevel: null, kind: "refused" });
+        throw new LeaderboardError(429, "rateLimited", "too many submissions; try again in a minute");
+    }
+    /**
+     * Checks and writes one score (DR §10 step 6), recording activity and the metric.
+     * @param context The submission.
+     * @param submission The score.
+     * @returns The score's result.
+     */
+    async submitScore(context, submission) {
+        const boardId = (submission != null && typeof submission.boardId === "string") ? submission.boardId : "";
+        const stored = (await this.cachedBoards()).get(boardId);
+        const isBoardOpen = stored != null && (context.source === "server" || stored.value.definition.visibility === "public");
+        if (stored == null || !isBoardOpen)
+            return await this.refuseScore(context, boardId, null, "unknownBoard");
+        const record = stored.value;
+        const variant = isVariantShape(submission.variant) ? variantKeyOf(record.definition, submission.variant) : { variantKey: null, problem: "variant must be an object" };
+        if (variant.variantKey == null)
+            return await this.refuseScore(context, boardId, null, "variantNotAllowed");
+        const scoreRefusal = checkScore(record.definition, submission.score, context.request.durationMs);
+        if (scoreRefusal != null)
+            return await this.refuseScore(context, boardId, variant.variantKey, scoreRefusal);
+        const trustLevel = await this.trustLevelOf(context, record.definition, submission.score);
+        if (!record.definition.acceptedTrustLevels.includes(trustLevel))
+            return await this.refuseScore(context, boardId, variant.variantKey, "trustLevelNotAccepted");
+        const metadata = checkMetadata(submission.metadata, context.rules.metadataMaximumBytes);
+        if (metadata.refusal != null)
+            return await this.refuseScore(context, boardId, variant.variantKey, metadata.refusal);
+        const key = { boardId: boardId, seasonId: record.currentSeasonId, variantKey: variant.variantKey };
+        if (context.player.hidden)
+            return await this.discardScore(context, key, submission.score, trustLevel);
+        const written = await this.options.rankStore.write({
+            key: key,
+            keepPolicy: record.definition.keepPolicy,
+            sortOrder: record.definition.sortOrder,
+            entry: this.incomingEntry(context, submission.score, metadata.metadata, trustLevel),
+            dedupeId: context.request.submissionId + "|" + boardId + "|" + variant.variantKey,
+            nowMs: context.nowMs
+        });
+        if (written.status === "overflow")
+            return await this.refuseScore(context, boardId, variant.variantKey, "scoreOutOfRange");
+        return await this.acceptScore(context, key, written, trustLevel);
+    }
+    /**
+     * The trust level of one score: server, session when presence passes for its duration (D10), else client.
+     * @param context The submission.
+     * @param definition The board.
+     * @param score The score (a time score must fit between the join and now).
+     * @returns The trust level.
+     */
+    async trustLevelOf(context, definition, score) {
+        if (context.baseTrust !== "session")
+            return context.baseTrust;
+        const sessionName = context.request.sessionName;
+        const runMs = (definition.scoreFormat === "timeMilliseconds") ? score : 0;
+        const latestJoinMs = context.nowMs - runMs + LEADERBOARD_DURATION_TOLERANCE_MS;
+        const subjects = ["address:" + context.caller.clientAddress];
+        if (context.caller.userId != null)
+            subjects.push("user:" + context.caller.userId);
+        for (const subject of subjects) {
+            const joinedAtMs = await this.options.rankStore.readSessionPresence(sessionName, subject, context.nowMs);
+            if (joinedAtMs != null && joinedAtMs <= latestJoinMs)
+                return "session";
+        }
+        return "client";
+    }
+    /**
+     * The incoming entry of a write: submissionCount 1, the service clock's times, the player's current name.
+     * @param context The submission.
+     * @param score The score.
+     * @param metadata The checked metadata.
+     * @param trustLevel The trust level.
+     * @returns The entry.
+     */
+    incomingEntry(context, score, metadata, trustLevel) {
+        const nowIso = new Date(context.nowMs).toISOString();
+        return {
+            playerId: context.player.playerId,
+            displayName: context.player.displayName,
+            score: score,
+            metadata: metadata,
+            trustLevel: trustLevel,
+            sessionName: context.request.sessionName,
+            gameMode: context.request.gameMode,
+            buildVersion: context.request.buildVersion,
+            submittedAt: nowIso,
+            achievedAt: nowIso,
+            achievedAtMs: context.nowMs,
+            submissionCount: 1
+        };
+    }
+    /**
+     * Records and returns an accepted or duplicate score.
+     * @param context The submission.
+     * @param key The ranking written.
+     * @param written The store's result.
+     * @param trustLevel The trust level.
+     * @returns The result.
+     */
+    async acceptScore(context, key, written, trustLevel) {
+        const status = (written.status === "duplicate") ? "duplicate" : "accepted";
+        const outcome = written.outcome;
+        const score = (written.entry != null) ? written.entry.score : null;
+        if (written.status === "written")
+            this.forgetCachedReads(key);
+        await this.appendActivity(context, { kind: status, boardId: key.boardId, variantKey: key.variantKey, score: score, outcome: outcome, reason: null, trustLevel: trustLevel });
+        this.options.state.metrics?.countLeaderboardScore?.(status, null);
+        return {
+            boardId: key.boardId,
+            variantKey: key.variantKey,
+            status: status,
+            outcome: outcome,
+            score: score,
+            previousScore: written.previousScore,
+            isPersonalBest: outcome != null && PERSONAL_BEST_OUTCOMES.includes(outcome),
+            rank: written.rank,
+            total: written.total,
+            seasonId: key.seasonId,
+            trustLevel: trustLevel,
+            refusal: null
+        };
+    }
+    /**
+     * Discards a hidden player's score (D18 shadow ban): accepted, outcome kept, no rank, nothing written.
+     * @param context The submission.
+     * @param key The ranking it would have gone to.
+     * @param score The score.
+     * @param trustLevel The trust level.
+     * @returns The result.
+     */
+    async discardScore(context, key, score, trustLevel) {
+        await this.appendActivity(context, { kind: "accepted", boardId: key.boardId, variantKey: key.variantKey, score: score, outcome: "kept", reason: null, trustLevel: trustLevel });
+        this.options.state.metrics?.countLeaderboardScore?.("accepted", null);
+        return { boardId: key.boardId, variantKey: key.variantKey, status: "accepted", outcome: "kept", score: score, previousScore: null, isPersonalBest: false, rank: null, total: null, seasonId: key.seasonId, trustLevel: trustLevel, refusal: null };
+    }
+    /**
+     * Records and returns a refused score.
+     * @param context The submission.
+     * @param boardId The board named.
+     * @param variantKey The variant key, or null when it was not valid.
+     * @param reason Why.
+     * @returns The result.
+     */
+    async refuseScore(context, boardId, variantKey, reason) {
+        await this.appendActivity(context, { kind: "refused", boardId: (boardId !== "") ? boardId : null, variantKey: variantKey, score: null, outcome: null, reason: reason, trustLevel: null });
+        this.options.state.metrics?.countLeaderboardScore?.("refused", reason);
+        return { boardId: boardId, variantKey: variantKey, status: "refused", outcome: null, score: null, previousScore: null, isPersonalBest: false, rank: null, total: null, seasonId: null, trustLevel: null, refusal: reason };
+    }
+    /**
+     * Appends one activity record (D21); a failing append is logged at warn and never fails the score.
+     * @param context The submission.
+     * @param fields The score's fields.
+     */
+    async appendActivity(context, fields) {
+        const record = {
+            ...fields,
+            playerId: context.player.playerId,
+            displayName: context.player.displayName,
+            gameMode: context.request.gameMode,
+            clientAddress: context.caller.clientAddress
+        };
+        try {
+            await this.options.adminStore.appendRecord(ACTIVITY_STREAM, record);
+        }
+        catch (error) {
+            getLogger().warn("leaderboard activity was not recorded", { error: errorText(error) });
+        }
+    }
+    /**
+     * Drops the cached pages of one ranking after a local write.
+     * @param key The ranking.
+     */
+    forgetCachedReads(key) {
+        const prefix = rankKeyText(key) + "|";
+        for (const cacheKey of this.readCache.keys()) {
+            if (cacheKey.startsWith(prefix))
+                this.readCache.delete(cacheKey);
+        }
+    }
+    /**
+     * The rank key of an admin moderation call (the board must exist; the season must be kept).
+     * @param boardId The board.
+     * @param variantKey The variant key.
+     * @param seasonId The season.
+     * @returns The rank key.
+     */
+    async adminRankKey(boardId, variantKey, seasonId) {
+        const record = (await this.getBoardRecord(boardId)).value;
+        return { boardId: boardId, seasonId: resolveSeasonId(record, seasonId), variantKey: variantKey };
+    }
+    /**
+     * Writes an admin entry with keep policy latest and no dedupe.
+     * @param key The ranking.
+     * @param record The board.
+     * @param entry The entry.
+     * @returns The entry's view with its rank.
+     */
+    async writeAdminEntry(key, record, entry) {
+        const written = await this.options.rankStore.write({ key: key, keepPolicy: "latest", sortOrder: record.definition.sortOrder, entry: entry, dedupeId: null, nowMs: this.options.clock.now() });
+        if (written.status === "overflow" || written.entry == null || written.rank == null)
+            throw new LeaderboardError(400, "scoreOutOfRange", "the score is outside the allowed range");
+        this.forgetCachedReads(key);
+        return toEntryView({ ...written.entry, rank: written.rank });
+    }
+    /**
+     * Restores a hidden player's entry in one ranking, if it was removed for playerHidden.
+     * @param key The ranking.
+     * @param playerId The player.
+     */
+    async restoreHiddenEntry(key, playerId) {
+        const removed = await this.options.rankStore.readRemoved(key);
+        const hiddenEntry = removed.find((item) => item.entry.playerId === playerId && item.reason === PLAYER_HIDDEN_REASON);
+        const board = (await this.freshBoards()).get(key.boardId);
+        if (hiddenEntry == null || board == null)
+            return;
+        await this.options.rankStore.restoreEntry(key, playerId, board.value.definition.sortOrder);
+    }
+    /**
+     * Merges one source entry into the target's entry of the same ranking by the board's keep policy.
+     * @param key The ranking.
+     * @param definition The board.
+     * @param sourceEntry The source player's live entry.
+     * @param target The target player.
+     */
+    async mergeEntry(key, definition, sourceEntry, target) {
+        const targetEntry = await this.options.rankStore.readEntry(key, target.playerId);
+        const isOlderLatest = definition.keepPolicy === "latest" && targetEntry != null && targetEntry.achievedAtMs >= sourceEntry.achievedAtMs;
+        if (isOlderLatest)
+            return;
+        const incoming = { ...sourceEntry, playerId: target.playerId, displayName: target.displayName, submissionCount: 1 };
+        const written = await this.options.rankStore.write({ key: key, keepPolicy: definition.keepPolicy, sortOrder: definition.sortOrder, entry: incoming, dedupeId: null, nowMs: this.options.clock.now() });
+        if (written.status === "overflow")
+            getLogger().warn("leaderboard merge left a sum unchanged: it would pass the score bound", { boardId: key.boardId, leaderboardPlayerId: target.playerId });
+        this.forgetCachedReads(key);
+    }
+    /**
+     * One entry of a player's detail: live with its rank, or removed with its reason.
+     * @param key The ranking.
+     * @param playerId The player.
+     * @param record The board, or null when it was deleted.
+     * @returns The entry view, or null when the player has no entry there.
+     */
+    async playerEntryView(key, playerId, record) {
+        const live = await this.options.rankStore.readEntry(key, playerId);
+        const removed = (live == null) ? (await this.options.rankStore.readRemoved(key)).find((item) => item.entry.playerId === playerId) : undefined;
+        if (live == null && removed == null)
+            return null;
+        return {
+            boardId: key.boardId,
+            boardName: (record != null) ? record.definition.displayName : key.boardId,
+            scoreFormat: (record != null) ? record.definition.scoreFormat : "integer",
+            seasonId: key.seasonId,
+            isCurrentSeason: record != null && record.currentSeasonId === key.seasonId,
+            variantKey: key.variantKey,
+            rank: (live != null) ? live.rank : null,
+            total: await this.options.rankStore.count(key),
+            score: (live != null) ? live.score : removed.entry.score,
+            removedReason: (removed != null) ? removed.reason : null
+        };
+    }
+    /**
+     * Reads a player record.
+     * @param playerId The player.
+     * @returns The record.
+     * @throws LeaderboardError 404 invalidPlayer when it does not exist.
+     */
+    async requirePlayer(playerId) {
+        const record = await this.options.rankStore.getPlayer(playerId);
+        if (record == null)
+            throw new LeaderboardError(404, "invalidPlayer", "there is no player " + playerId);
+        return record;
+    }
+    /**
+     * Creates a manual player (D8) with a cleaned name.
+     * @param displayName The name.
+     * @returns The record.
+     */
+    async createManualPlayer(displayName) {
+        const cleanName = await this.requireCleanName(displayName);
+        const nowIso = this.nowIso();
+        const record = { playerId: MANUAL_PLAYER_PREFIX + randomUUID(), kind: "manual", keyHash: null, displayName: cleanName, hidden: false, createdAt: nowIso, lastSeenAt: nowIso };
+        await this.options.rankStore.putPlayer(record);
+        return record;
+    }
+    /**
+     * The board documents read fresh (moderation must not act on a stale cache).
+     * @returns Board id → document.
+     */
+    async freshBoards() {
+        this.boardCache = null;
+        return await this.cachedBoards();
+    }
+    /**
+     * The service clock's time as ISO text.
+     * @returns ISO time.
+     */
+    nowIso() {
+        return new Date(this.options.clock.now()).toISOString();
+    }
+}
+/**
+ * Checks a submission envelope's shape (DR §10 step 1) and fills absent optional fields with null.
+ * @param request The envelope (any JSON).
+ * @throws LeaderboardError 400 invalidRequest naming the field.
+ */
+function requireValidEnvelope(request) {
+    if (request == null || typeof request !== "object")
+        throw invalidRequest("the submission must be an object");
+    if (typeof request.submissionId !== "string" || !SUBMISSION_ID_PATTERN.test(request.submissionId))
+        throw invalidRequest("submissionId must be 8–64 of A-Z, a-z, 0-9 and -");
+    if (!isOptionalText(request.gameMode, 0, MAXIMUM_LABEL_TEXT_LENGTH))
+        throw invalidRequest("gameMode must be null or text of at most " + MAXIMUM_LABEL_TEXT_LENGTH + " characters");
+    if (!isOptionalText(request.buildVersion, 0, MAXIMUM_LABEL_TEXT_LENGTH))
+        throw invalidRequest("buildVersion must be null or text of at most " + MAXIMUM_LABEL_TEXT_LENGTH + " characters");
+    if (!isOptionalText(request.sessionName, 1, MAXIMUM_SESSION_NAME_LENGTH))
+        throw invalidRequest("sessionName must be null or text of 1–" + MAXIMUM_SESSION_NAME_LENGTH + " characters");
+    const durationMs = request.durationMs;
+    const isDurationValid = durationMs == null || (typeof durationMs === "number" && Number.isSafeInteger(durationMs) && durationMs >= 0);
+    if (!isDurationValid)
+        throw invalidRequest("durationMs must be null or a whole number of milliseconds");
+    if (!Array.isArray(request.scores) || request.scores.length === 0)
+        throw invalidRequest("scores must be a list of at least one score");
+    request.gameMode ??= null;
+    request.buildVersion ??= null;
+    request.sessionName ??= null;
+    request.durationMs ??= null;
+}
+/**
+ * A 400 invalidRequest error.
+ * @param sentence What is wrong, naming the field.
+ * @returns The error to throw.
+ */
+function invalidRequest(sentence) {
+    return new LeaderboardError(400, "invalidRequest", sentence);
+}
+/**
+ * Whether a value is null/undefined or text within a length range.
+ * @param value The value.
+ * @param minimumLength Shortest text.
+ * @param maximumLength Longest text.
+ * @returns True when valid.
+ */
+function isOptionalText(value, minimumLength, maximumLength) {
+    if (value == null)
+        return true;
+    return typeof value === "string" && value.length >= minimumLength && value.length <= maximumLength;
+}
+/**
+ * Whether a submission's variant is null or an object of strings.
+ * @param variant The variant (any JSON).
+ * @returns True when it has the right shape.
+ */
+function isVariantShape(variant) {
+    if (variant == null)
+        return true;
+    if (typeof variant !== "object" || Array.isArray(variant))
+        return false;
+    return Object.values(variant).every((value) => typeof value === "string");
+}
+/**
+ * The trust level before the per-score presence check (DR §10 step 5).
+ * @param source The submission's source.
+ * @param request The envelope.
+ * @returns "server", "session" when presence may pass, else "client".
+ */
+function baseTrustOf(source, request) {
+    if (source === "server")
+        return "server";
+    return (request.sessionName != null) ? "session" : "client";
+}
+/**
+ * Validates a board definition or throws.
+ * @param definition The definition (any JSON).
+ * @returns The valid definition.
+ * @throws LeaderboardError 400 invalidRequest with the problems.
+ */
+function requireValidDefinition(definition) {
+    const checked = validateBoardDefinition(definition);
+    if (checked.definition == null)
+        throw new LeaderboardError(400, "invalidRequest", checked.problems.join("; "));
+    return checked.definition;
+}
+/**
+ * The variant key of a public read or throws.
+ * @param definition The board.
+ * @param variant The variant.
+ * @returns The variant key.
+ * @throws LeaderboardError 400 variantNotAllowed.
+ */
+function requireVariantKey(definition, variant) {
+    const checked = isVariantShape(variant) ? variantKeyOf(definition, variant) : { variantKey: null, problem: "variant must be an object of texts" };
+    if (checked.variantKey == null)
+        throw new LeaderboardError(400, "variantNotAllowed", checked.problem ?? "variant not allowed");
+    return checked.variantKey;
+}
+/**
+ * The variant key of an admin read: the declared dimensions in order, accepting values the board no longer allows.
+ * @param definition The board.
+ * @param variant The variant.
+ * @returns The variant key.
+ * @throws LeaderboardError 400 variantNotAllowed when a dimension is missing or a key is extra.
+ */
+function adminVariantKeyOf(definition, variant) {
+    const relaxed = {
+        ...definition,
+        dimensions: definition.dimensions.map((dimension) => {
+            const value = (variant != null) ? variant[dimension.name] : undefined;
+            const values = (typeof value === "string" && !dimension.values.includes(value)) ? [...dimension.values, value] : dimension.values;
+            return { ...dimension, values: values };
+        })
+    };
+    return requireVariantKey(relaxed, variant);
+}
+/**
+ * The season a read or delete names, or the current one.
+ * @param record The board.
+ * @param seasonId The season, or null for the current one.
+ * @returns The season id.
+ * @throws LeaderboardError 404 invalidRequest for a season the board does not keep.
+ */
+function resolveSeasonId(record, seasonId) {
+    if (seasonId == null)
+        return record.currentSeasonId;
+    const isKept = record.seasons.some((season) => season.seasonId === seasonId);
+    if (!isKept)
+        throw new LeaderboardError(404, "invalidRequest", "board " + record.definition.boardId + " has no season " + seasonId);
+    return seasonId;
+}
+/**
+ * A board record with its current season ended and the next one started.
+ * @param record The board.
+ * @param nowMs The reset time.
+ * @returns The new record (nextResetAt unchanged).
+ */
+function advanceSeason(record, nowMs) {
+    const nowIso = new Date(nowMs).toISOString();
+    const nextSeasonId = record.currentSeasonId + 1;
+    const ended = record.seasons.map((season) => (season.seasonId === record.currentSeasonId) ? { ...season, endedAt: nowIso, isCurrent: false } : season);
+    return { ...record, currentSeasonId: nextSeasonId, seasons: [...ended, { seasonId: nextSeasonId, startedAt: nowIso, endedAt: null, isCurrent: true }] };
+}
+/**
+ * Whether a board's scheduled reset is due.
+ * @param record The board.
+ * @param nowMs The time.
+ * @returns True when nextResetAt is set and not in the future.
+ */
+function isResetDue(record, nowMs) {
+    return record.nextResetAt != null && Date.parse(record.nextResetAt) <= nowMs;
+}
+/**
+ * The page fields of a ranking.
+ * @param key The ranking.
+ * @param total Its live entries.
+ * @returns boardId, seasonId, variantKey and total.
+ */
+function pageHeader(key, total) {
+    return { boardId: key.boardId, seasonId: key.seasonId, variantKey: key.variantKey, total: total };
+}
+/**
+ * The public view of a board.
+ * @param record The board.
+ * @returns The view.
+ */
+function toPublicBoardView(record) {
+    const definition = record.definition;
+    const currentSeason = record.seasons.find((season) => season.seasonId === record.currentSeasonId);
+    return {
+        boardId: definition.boardId,
+        displayName: definition.displayName,
+        description: definition.description,
+        sortOrder: definition.sortOrder,
+        scoreFormat: definition.scoreFormat,
+        keepPolicy: definition.keepPolicy,
+        dimensions: definition.dimensions,
+        currentSeasonId: record.currentSeasonId,
+        currentSeasonStartedAt: (currentSeason != null) ? currentSeason.startedAt : record.createdAt,
+        nextResetAt: record.nextResetAt
+    };
+}
+/**
+ * The view of a ranked entry.
+ * @param entry The entry.
+ * @returns The view.
+ */
+function toEntryView(entry) {
+    return { rank: entry.rank, playerId: entry.playerId, displayName: entry.displayName, score: entry.score, metadata: entry.metadata, trustLevel: entry.trustLevel, submittedAt: entry.submittedAt, achievedAt: entry.achievedAt };
+}
+/**
+ * The public view of a player.
+ * @param record The player.
+ * @returns The view.
+ */
+function toPlayerView(record) {
+    return { playerId: record.playerId, displayName: record.displayName, kind: record.kind, createdAt: record.createdAt };
+}
+/**
+ * The view of an activity record.
+ * @param record The stored record.
+ * @param includeAddresses True to keep the client address.
+ * @returns The view.
+ */
+function toActivityView(record, includeAddresses) {
+    return { ...record.value, sequence: record.sequence, at: record.at, clientAddress: includeAddresses ? record.value.clientAddress : "" };
+}
+/**
+ * The view of a removed entry.
+ * @param removed The removed entry.
+ * @returns The view (rank 0).
+ */
+function toRemovedEntryView(removed) {
+    return { entry: toEntryView({ ...removed.entry, rank: UNRANKED }), reason: removed.reason, removedBy: removed.removedBy, removedAt: removed.removedAt };
+}
+/**
+ * The console view of a player.
+ * @param record The player.
+ * @returns The view.
+ */
+function toPlayerAdminView(record) {
+    return { playerId: record.playerId, displayName: record.displayName, kind: record.kind, hidden: record.hidden, createdAt: record.createdAt, lastSeenAt: record.lastSeenAt };
+}
+/**
+ * A ranked entry without its rank.
+ * @param entry The ranked entry.
+ * @returns The stored entry.
+ */
+function withoutRank(entry) {
+    const stored = { ...entry };
+    delete stored.rank;
+    return stored;
+}
+/**
+ * Checks an admin score against the board or throws.
+ * @param definition The board.
+ * @param score The score.
+ * @throws LeaderboardError 400 with the refusal reason.
+ */
+function requireAcceptableScore(definition, score) {
+    const refusal = checkScore(definition, score, null);
+    if (refusal != null)
+        throw new LeaderboardError(400, refusal, "the score must be a whole number within the board's limits");
+}
+/**
+ * Reads the board definitions of a definitions file or an export file, adding a problem for anything unreadable.
+ * @param filePath The resolved file path.
+ * @param problems Receives the problems.
+ * @returns The definitions found (unvalidated).
+ */
+async function readDefinitions(filePath, problems) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        problems.push("cannot read " + filePath + " (" + errorText(error) + ")");
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        problems.push(filePath + " is not valid JSON");
+        return [];
+    }
+    const file = (typeof parsed === "object" && parsed != null) ? parsed : {};
+    if (file.format === DEFINITIONS_FORMAT && Array.isArray(file.boards))
+        return file.boards;
+    if (file.format === EXPORT_FORMAT && Array.isArray(file.boards))
+        return file.boards.map((board) => (typeof board === "object" && board != null) ? board.definition : board);
+    problems.push(filePath + " is not a leaderboard definitions file (format must be " + DEFINITIONS_FORMAT + ")");
+    return [];
+}
+/**
+ * A short label of a board value for a problem sentence.
+ * @param value The value.
+ * @returns "board <id>" or "a board".
+ */
+function describeBoardValue(value) {
+    const boardId = (typeof value === "object" && value != null) ? value.boardId : null;
+    return (typeof boardId === "string") ? "board " + boardId : "a board";
+}
+/**
+ * The message of an error.
+ * @param error Anything thrown.
+ * @returns Its message.
+ */
+function errorText(error) {
+    return (error instanceof Error) ? error.message : String(error);
+}