@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/leaderboards/LeaderboardService.d.ts

@@ -0,0 +1,669 @@
+import type { LeaderboardActivityView, LeaderboardAroundPage, LeaderboardBoardDefinition, LeaderboardBoardDetailView, LeaderboardBoardSummaryView, LeaderboardEntriesPage, LeaderboardEntryView, LeaderboardPlayerAdminView, LeaderboardPlayerDetailView, LeaderboardPlayerSession, LeaderboardPlayerView, LeaderboardPublicBoardView, LeaderboardRemovedEntryView, LeaderboardRules, LeaderboardRulesView, LeaderboardSeasonView, LeaderboardStatusView, LeaderboardSubmissionRequest, LeaderboardSubmissionResponse, LeaderboardTarget, LeaderboardTargetEntry } from "../admin/AdminApiTypes.js";
+import type { AdminClock } from "../admin/AdminClock.js";
+import type { PlayerSessionEvent } from "../admin/AdminRecords.js";
+import { type AdminStore, type StoredDocument } from "../admin/AdminStore.js";
+import type { GameServerConfig } from "../GameServerConfig.js";
+import type { GameServerStateValues } from "../GameServerState.js";
+import type { LeaderboardPlayerRecord, LeaderboardRankStore } from "./LeaderboardRankStore.js";
+/** Who is calling, after authentication. */
+export interface LeaderboardCaller {
+    /** The auth user id when the server's auth yielded one, else null. */
+    userId: string | null;
+    /** The display-name claim of an auth user (name or preferred_username), else null. */
+    userDisplayName: string | null;
+    /** The avatar claim of an auth user (string), else null. */
+    userAvatar: string | null;
+    /** True when the caller's session owns the name (claim name_managed: true), so renames are refused. */
+    isNameManaged: boolean;
+    /** The anonymous player key from the body, else null. */
+    playerKey: string | null;
+    /** The normalized client address. */
+    clientAddress: string;
+}
+/** What the Discord session exchange asks of the leaderboards (discord-sign-in D16). */
+export interface LeaderboardUserClaim {
+    /** The auth user id (discord:<id>). */
+    userId: string;
+    /** The display name from the sign-in. */
+    displayName: string;
+    /** The avatar claim, or null. */
+    avatar: string | null;
+    /** The browser's anonymous player key, or null when it has none. */
+    anonymousPlayerKey: string | null;
+}
+/** The outcome of a claim. */
+export interface LeaderboardUserClaimResult {
+    /** The user's player id (user:discord:<id>). */
+    playerId: string;
+    /** True when an anonymous history was moved onto the new player. */
+    merged: boolean;
+}
+/** Options of LeaderboardService.open. */
+export interface LeaderboardServiceOptions {
+    /** The resolved config. */
+    config: GameServerConfig;
+    /**
+     * The server state: the service reads only `metrics` and sets `onLeaderboardSessionPresence`. Tests pass a plain
+     * object `{ config, metrics: null, onLeaderboardSessionPresence: null }`.
+     */
+    state: GameServerStateValues;
+    /** The admin store (boards, rules, activity). */
+    adminStore: AdminStore;
+    /** The rank store (rankings, players, rates, presence). */
+    rankStore: LeaderboardRankStore;
+    /** The clock of every time the service writes and every timer (tests pass createManualClock()). */
+    clock: AdminClock;
+    /** This process's id for the scheduler lease (matchMaker.processId, read lazily). */
+    processId: () => string;
+    /** Milliseconds between scheduler ticks. */
+    schedulerTickMs: number;
+}
+/** A board as stored in the admin store collection "leaderboards" (document id = boardId). */
+export interface LeaderboardBoardRecord {
+    /** What an admin defined. */
+    definition: LeaderboardBoardDefinition;
+    /** The season new scores go to. */
+    currentSeasonId: number;
+    /** Every season still kept, oldest first. */
+    seasons: LeaderboardSeasonView[];
+    /** ISO time of the next scheduled reset, or null. */
+    nextResetAt: string | null;
+    /** ISO creation time. */
+    createdAt: string;
+}
+/** A server-trust submission (admin route `leaderboards/submit`, DR §6): the player is named, not resolved. */
+export type LeaderboardServerSubmissionRequest = LeaderboardSubmissionRequest & {
+    /** The player the scores belong to. */
+    playerId: string;
+    /** The name of a manual player created when playerId is unknown. */
+    displayName?: string;
+};
+/** Boards, seasons, rules, players, submissions, reads, activity, status and presence (D4). */
+export declare class LeaderboardService {
+    /** The options it was opened with. */
+    private readonly options;
+    /** The cached boards, or null. */
+    private boardCache;
+    /** The cached rules, or null. */
+    private rulesCache;
+    /** Cached top-N pages by `rankKeyText|offset|limit`. */
+    private readonly readCache;
+    /** The definitions-file problem found by the last start, or null. */
+    private definitionsProblem;
+    /** The scheduler while started, or null. */
+    private scheduler;
+    /**
+     * Creates the service; open() is the public way.
+     * @param options The options.
+     */
+    private constructor();
+    /**
+     * Opens the service (nothing runs until start()).
+     * @param options The stores, state, clock and scheduler settings.
+     * @returns The service.
+     */
+    static open(options: LeaderboardServiceOptions): Promise<LeaderboardService>;
+    /** The admin store and rank store, for LeaderboardTransfer (T6). */
+    get stores(): {
+        adminStore: AdminStore;
+        rankStore: LeaderboardRankStore;
+    };
+    /**
+     * Imports the definitions file, hides anonymous entries when only signed-in players may submit, starts listening for
+     * session presence and starts the scheduler.
+     */
+    start(): Promise<void>;
+    /** Stops the scheduler, stops listening for session presence and closes the rank store. */
+    stop(): Promise<void>;
+    /**
+     * Lists every board document (cached for LEADERBOARD_DEFINITION_CACHE_MS), sorted by board id.
+     * @returns The documents.
+     */
+    listBoardRecords(): Promise<StoredDocument<LeaderboardBoardRecord>[]>;
+    /**
+     * 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.
+     */
+    getBoardRecord(boardId: string): Promise<StoredDocument<LeaderboardBoardRecord>>;
+    /**
+     * The public boards as game clients see them.
+     * @returns The boards, sorted by board id.
+     */
+    listPublicBoards(): Promise<LeaderboardPublicBoardView[]>;
+    /**
+     * 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.
+     */
+    summarizeBoard(stored: StoredDocument<LeaderboardBoardRecord>): Promise<LeaderboardBoardSummaryView>;
+    /**
+     * 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.
+     */
+    describeBoard(boardId: string, seasonId: number | null): Promise<LeaderboardBoardDetailView>;
+    /**
+     * 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.
+     */
+    createBoard(definition: LeaderboardBoardDefinition): Promise<LeaderboardBoardSummaryView>;
+    /**
+     * 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.
+     */
+    updateBoard(boardId: string, definition: LeaderboardBoardDefinition, revision: number, startNewSeason: boolean): Promise<LeaderboardBoardSummaryView>;
+    /**
+     * 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.
+     */
+    duplicateBoard(boardId: string, newBoardId: string, displayName: string): Promise<LeaderboardBoardSummaryView>;
+    /**
+     * Deletes a board and every ranking of every season (activity records stay, DR §15).
+     * @param boardId The board.
+     */
+    deleteBoard(boardId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    resetSeason(boardId: string, trigger: "admin" | "schedule"): Promise<LeaderboardBoardSummaryView>;
+    /**
+     * 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.
+     */
+    deleteSeason(boardId: string, seasonId: number): Promise<number>;
+    /**
+     * A board's seasons, oldest first.
+     * @param boardId The board.
+     * @param audience "public" hides hidden boards (404).
+     * @returns The seasons.
+     */
+    listSeasons(boardId: string, audience: "public" | "admin"): Promise<LeaderboardSeasonView[]>;
+    /**
+     * The rules in force, the defaults and the stored revision (0 while the defaults apply).
+     * @returns The rules view.
+     */
+    getRulesView(): Promise<LeaderboardRulesView>;
+    /**
+     * 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.
+     */
+    updateRules(rules: LeaderboardRules, revision: number): Promise<LeaderboardRulesView>;
+    /**
+     * 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.
+     */
+    openPlayerSession(caller: LeaderboardCaller): Promise<LeaderboardPlayerSession>;
+    /**
+     * 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.
+     */
+    resolvePlayer(caller: LeaderboardCaller): Promise<LeaderboardPlayerRecord>;
+    /**
+     * The caller's own player (POST players/me).
+     * @param caller The caller.
+     * @returns The player.
+     * @throws LeaderboardError 401 invalidPlayer.
+     */
+    getOwnPlayer(caller: LeaderboardCaller): Promise<LeaderboardPlayerView>;
+    /**
+     * 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.
+     */
+    eraseOwnPlayer(caller: LeaderboardCaller): Promise<number>;
+    /**
+     * 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.
+     */
+    claimUserPlayer(claim: LeaderboardUserClaim): Promise<LeaderboardUserClaimResult>;
+    /**
+     * 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).
+     */
+    attachAvatars(entries: LeaderboardEntryView[]): Promise<LeaderboardEntryView[]>;
+    /**
+     * Consumes one public read of an address against readsPerMinutePerAddress (D19 read limit scope).
+     * @param clientAddress The caller's address.
+     * @throws LeaderboardError 429 rateLimited.
+     */
+    consumeReadRate(clientAddress: string): Promise<void>;
+    /**
+     * 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.
+     */
+    renameOwnPlayer(caller: LeaderboardCaller, displayName: unknown): Promise<LeaderboardPlayerView>;
+    /**
+     * 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.
+     */
+    submit(caller: LeaderboardCaller, request: LeaderboardSubmissionRequest, source: "public" | "server"): Promise<LeaderboardSubmissionResponse>;
+    /**
+     * 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.
+     */
+    readEntries(boardId: string, variant: Record<string, string> | null, seasonId: number | null, offset: number, limit: number, audience: "public" | "admin"): Promise<LeaderboardEntriesPage>;
+    /**
+     * 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.
+     */
+    searchEntries(boardId: string, variantKey: string, seasonId: number, text: string): Promise<LeaderboardEntriesPage>;
+    /**
+     * 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).
+     */
+    readAround(boardId: string, variant: Record<string, string> | null, seasonId: number | null, playerId: string, window: number): Promise<LeaderboardAroundPage>;
+    /**
+     * 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.
+     */
+    readTargets(playerId: string, targets: LeaderboardTarget[]): Promise<LeaderboardTargetEntry[]>;
+    /**
+     * 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.
+     */
+    readPlayersEntries(boardId: string, variant: Record<string, string> | null, seasonId: number | null, playerIds: string[]): Promise<LeaderboardEntryView[]>;
+    /**
+     * 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).
+     */
+    readRemoved(boardId: string, variantKey: string, seasonId: number): Promise<LeaderboardRemovedEntryView[]>;
+    /**
+     * 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.
+     */
+    removeEntry(boardId: string, variantKey: string, seasonId: number, playerId: string, reason: string, actorName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    restoreEntry(boardId: string, variantKey: string, seasonId: number, playerId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    correctEntry(boardId: string, variantKey: string, seasonId: number, playerId: string, score: number): Promise<LeaderboardEntryView>;
+    /**
+     * 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.
+     */
+    addEntry(boardId: string, variant: Record<string, string> | null, playerId: string | null, displayName: string, score: number): Promise<LeaderboardEntryView>;
+    /**
+     * 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.
+     */
+    renamePlayer(playerId: string, displayName: string): Promise<LeaderboardPlayerAdminView>;
+    /**
+     * 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.
+     */
+    hidePlayer(playerId: string, hidden: boolean, actorName: string): Promise<LeaderboardPlayerAdminView>;
+    /**
+     * 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.
+     */
+    mergePlayers(sourcePlayerId: string, targetPlayerId: string): Promise<LeaderboardPlayerDetailView>;
+    /**
+     * 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.
+     */
+    erasePlayer(playerId: string): Promise<number>;
+    /**
+     * 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.
+     */
+    getPlayerDetail(playerId: string): Promise<LeaderboardPlayerDetailView>;
+    /**
+     * Finds players by name or id.
+     * @param text The text ("" lists any).
+     * @returns Up to 50 players.
+     */
+    searchPlayers(text: string): Promise<LeaderboardPlayerAdminView[]>;
+    /**
+     * 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.
+     */
+    readActivity(kind: "accepted" | "duplicate" | "refused" | null, boardId: string | null, beforeSequence: number | null, limit: number, includeAddresses: boolean): Promise<LeaderboardActivityView[]>;
+    /**
+     * The status view: storage, durability, the definitions problem, boards and fleet-wide per-minute counts (D20, D21).
+     * @returns The status.
+     */
+    status(): Promise<LeaderboardStatusView>;
+    /**
+     * 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: PlayerSessionEvent): void;
+    /**
+     * The board documents, cached for LEADERBOARD_DEFINITION_CACHE_MS.
+     * @returns Board id → document.
+     */
+    private cachedBoards;
+    /**
+     * 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.
+     */
+    private boardFor;
+    /**
+     * 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.
+     */
+    private rankKeyFor;
+    /**
+     * A new board record with season 1 starting now.
+     * @param definition The valid definition.
+     * @returns The record.
+     */
+    private newBoardRecord;
+    /**
+     * Imports the definitions file (D11): creates each valid board that does not exist yet and records any problem.
+     */
+    private importDefinitionsFile;
+    /**
+     * 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.
+     */
+    private hideAnonymousEntries;
+    /**
+     * 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.
+     */
+    private hideAnonymousEntriesOf;
+    /**
+     * Creates a board unless another process or the console already has it.
+     * @param definition The valid definition.
+     */
+    private createBoardIfMissing;
+    /**
+     * 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.
+     */
+    private userPlayer;
+    /**
+     * 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.
+     */
+    private refreshUserProfile;
+    /**
+     * 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.
+     */
+    private anonymousPlayerOf;
+    /**
+     * 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.
+     */
+    private serverPlayer;
+    /**
+     * 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.
+     */
+    private requireCleanName;
+    /**
+     * 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.
+     */
+    private consumeSubmissionRates;
+    /**
+     * 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.
+     */
+    private submitScore;
+    /**
+     * 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.
+     */
+    private trustLevelOf;
+    /**
+     * 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.
+     */
+    private incomingEntry;
+    /**
+     * 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.
+     */
+    private acceptScore;
+    /**
+     * 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.
+     */
+    private discardScore;
+    /**
+     * 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.
+     */
+    private refuseScore;
+    /**
+     * 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.
+     */
+    private appendActivity;
+    /**
+     * Drops the cached pages of one ranking after a local write.
+     * @param key The ranking.
+     */
+    private forgetCachedReads;
+    /**
+     * 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.
+     */
+    private adminRankKey;
+    /**
+     * 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.
+     */
+    private writeAdminEntry;
+    /**
+     * Restores a hidden player's entry in one ranking, if it was removed for playerHidden.
+     * @param key The ranking.
+     * @param playerId The player.
+     */
+    private restoreHiddenEntry;
+    /**
+     * 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.
+     */
+    private mergeEntry;
+    /**
+     * 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.
+     */
+    private playerEntryView;
+    /**
+     * Reads a player record.
+     * @param playerId The player.
+     * @returns The record.
+     * @throws LeaderboardError 404 invalidPlayer when it does not exist.
+     */
+    private requirePlayer;
+    /**
+     * Creates a manual player (D8) with a cleaned name.
+     * @param displayName The name.
+     * @returns The record.
+     */
+    private createManualPlayer;
+    /**
+     * The board documents read fresh (moderation must not act on a stale cache).
+     * @returns Board id → document.
+     */
+    private freshBoards;
+    /**
+     * The service clock's time as ISO text.
+     * @returns ISO time.
+     */
+    private nowIso;
+}