Files
owenrees e0b446bbfb Weight puzzle selection and stop repeats inside a session (#183)
Selection took a hard rating band (medium = user rating ± 100), removed
everything attempted in the last 30 days, and drew uniformly from what was
left. Because the bulk importer gives every endgame in a batch the same
rating, the band held either the whole library or — once a user's rating
drifted past it — only the endgames that user had already played. With
`fresh` empty, the fallback re-drew from the same band ignoring recency, so
recently played puzzles came straight back. An empty band used a
deterministic nearest-match, alternating between the same two puzzles.

Difficulty is now a bias rather than a filter: candidates are weighted by
`exp(-|rating - target| / spread)` and drawn with an exponential race, so
the whole library stays reachable and a thin region around the user's rating
can never empty the pool. `easy` and `hard` keep one-sided guards so the
labels stay honest. When every candidate is excluded, selection serves the
least recently attempted endgame instead of a random recent one.

Sessions now carry the ids they have served, which fixes the observed
in-session repeat (only the current puzzle used to be excluded), and guest
training gets the same treatment. The 30-day window is configurable as the
repeat window and is now named in GLOSSARY.md, distinct from the rating
window and from the tablebase cooldown.

Difficulty copy is qualitative, since the band numbers no longer describe
how selection works.
2026-11-17 14:28:24 +01:00

6.3 KiB

Chesstrainer

An endgame trainer: the user plays a stored endgame position against tablebase-optimal defence and is graded on every move.

Core model

Endgame: A stored chess position (FEN) plus metadata — side to move, result, rating, tags — that can be played as a puzzle. Avoid: Position, puzzle

Puzzle: A playable challenge derived from an endgame: play the winning (or drawing) side correctly against tablebase-optimal defence. Each endgame currently yields one puzzle. Avoid: Endgame (the stored record), exercise

Daily puzzle: The one endgame assigned to a UTC date and shared by every user; the assignment is persisted so it stays stable for that day. Avoid: Random puzzle, featured puzzle

Attempt: A recorded playthrough of a puzzle by a user, ending solved or failed; a per-user record, distinct from an endgame's global attempt and solve counts. Avoid: Run, game

Theme: A label describing an endgame's technique or goal, such as "mate in 2", "Lucena" or "opposition"; an endgame can carry several. Avoid: Tag, label, category, UI theme, colour mode

Interface

Colour mode: A user's display preference for the interface — system, light or dark — where system follows the operating system setting. It is a per-browser preference, independent of any user account. Avoid: Theme, colour scheme, display theme

Key: The canonical material signature of an endgame's starting position — which pieces each side has, written strongest side first and colour-agnostic (e.g. "KQ v KR"). Used to group and search endgames by material. Avoid: Material signature, hash

Public code: The short, stable identifier an endgame is played under in player-facing links, distinct from its database id and safe to share. Avoid: Slug, UUID, endgame id, token

Identity & access

User: A person who can sign in to the trainer, identified by a unique email address and a unique username. Avoid: Account, player

Role: A user's authority tier — member, moderator, admin or super_admin — deciding access to the admin area and the power to manage other users. Avoid: Permission, access level

Plan: A user's subscription tier — free or premium — independent of their role. Avoid: Tier, subscription, membership

Mailing list: Email addresses that opted in to occasional product updates, collected from the landing-page form or the registration checkbox; a subscriber need not have an account. Avoid: Newsletter, subscription (reserved for the premium plan)

Play

Winning side: The side that can force a win from the position; the side the user plays in win-type endgames.

Drawing side: In draw endgames, the side that must hold the draw; the side the user plays. Avoid: Defender

Optimal move: The tablebase's best move for the side to move (sharpest win / hardest defence).

Winning move: A move that keeps the win (the opponent is still lost). Passes. Avoid: Good move, accurate move

Losing move: A move that throws away the result (the position becomes drawn or lost). Fails the puzzle. Avoid: Blunder, mistake

Conversion: The decisive zeroing move — a promotion — that ends a conversion-type puzzle.

Cutoff: The terminal condition short of mate at which a puzzle counts as solved: promotion (still winning) for conversion puzzles, mate otherwise.

Session: One continuous spell of puzzle play, begun by choosing a difficulty, that carries a start time and a rating baseline for the timer and rating-gain monitor. Ephemeral — it lives only in the running LiveView, never persisted. Avoid: Run, game, attempt

Repeat window: The minimum interval before the same endgame may be served to the same user again. Selection skips endgames attempted inside the window; only when nothing else is available does the least recently attempted endgame come back. It is independent of the rating window, which decides whether a replay may move a rating. Avoid: Cooldown (reserved for tablebase rate-limiting), due date

Ratings

Rating: A user's estimated solving skill, or an endgame's estimated difficulty, on a scale that lets the two be compared. Avoid: Score, ELO, rank

Rating deviation: The uncertainty around a rating; it widens with inactivity and narrows with rated results, so a less certain rating moves further per result. Avoid: Error margin, variance

Rating window: The minimum interval before the same user replaying the same endgame can change either rating again. Avoid: Cooldown (reserved for tablebase rate-limiting)

Volatility: A measure of how erratic a competitor's recent results are, used by some rating systems; the trainer deliberately does not track it. Avoid: Variance, inconsistency

Difficulty: A choice — easy, medium or hard — that biases which puzzles are served relative to the current user's rating: medium centres on the user's rating, easy below it, hard above it. Candidates are weighted by how close their rating is to that centre, so a session draws mostly from near the target but the whole library stays reachable. The spread is a configured constant. It is a property of a session, not of an endgame — the same endgame is easy for one user and hard for another. Avoid: Level, rank, tier

Infrastructure

Tablebase: A database of precomputed optimal outcomes for every position with at most seven pieces. Positions with five or fewer pieces are answered from local Syzygy files; six and seven piece positions come from the lichess API. The trainer keeps only the outcome data it grades on — enough to tell a winning move from a losing one — and caches API answers only; local answers are cheap enough to refetch.

Probe: A single lookup of one position in the tablebase, returning its result and its legal moves. A probe is answered locally or by the API.

Position key: The identity of a tablebase position — board, side to move, castling and en-passant — excluding the move clocks. FENs that differ only in their clocks share a position key. Avoid: Full FEN

Cooldown: Rate-limit state entered after a 429 from the lichess API, during which the trainer blocks play for positions that need the API (six or seven pieces). Local positions are unaffected.

Cache sweep: The periodic halving of LFU cache frequencies (weekly) that lets rarely-used entries age out.