add initial ADR and glossary

This commit is contained in:
2026-11-01 21:18:07 +01:00
parent ca4878055d
commit 6f08cdd10f
4 changed files with 164 additions and 0 deletions
+63
View File
@@ -0,0 +1,63 @@
# 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
## 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.