Files
chess-endgame-trainer/GLOSSARY.md
T
owenrees ca65207baa Derive canonical material Key from the FEN
The Endgame key is now a canonical, colour-agnostic material signature derived
from the FEN instead of a hand-typed field: each side's pieces, strongest side
first by material value (e.g. "KQ v KR"). This fixes the seed ordering
inconsistency and guarantees the key always matches the position.

- Add Chesstrainer.Key.from_fen/1.
- Compute the key in the Endgame changeset; drop the manual input and its
  regex validation.
- Index endgames.key and derive keys in the seeds.
- Document the Key term and the decision (ADR 0003).

Closes #13
2026-11-02 09:22:01 +01:00

2.2 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. Avoid: Endgame (the stored record), exercise

Attempt: One playthrough of a puzzle by a user, ending solved or failed. Avoid: Run, session, 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

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

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.

Infrastructure

Tablebase: A database of precomputed optimal outcomes for every position with at most seven pieces, queried via the lichess API and cached.

Cooldown: Rate-limit state entered after a 429 from the lichess tablebase API, during which the trainer blocks play.

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