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
@@ -0,0 +1,8 @@
# Tablebase via the lichess API instead of self-hosting
The trainer grades moves against Syzygy tablebases, but self-hosting them is not
possible yet, so we query the lichess tablebase API (`tablebase.lichess.ovh`)
over HTTP and cache responses. This couples the core play loop to a remote
service with rate limits (mitigated by a cooldown and an LFU cache), but avoids
the multi-terabyte 7-piece dataset and hosting cost until local tablebases are
viable.
@@ -0,0 +1,8 @@
# Client-authoritative move legality; server grades via tablebase
Moves are validated by chess.js on the client (which also renders the board);
the server never applies moves and trusts the client's FEN, only grading the
move against the tablebase. We chose this over server-side validation with Chex
because Chex's move-legality logic is immature, and the app is single-user with
no auth, so client tampering is not a threat. Revisit once the Chex fork is
fixed.
+85
View File
@@ -0,0 +1,85 @@
# MVP: endgame trainer play loop
Goal: a user picks an endgame and plays it against tablebase-optimal defence,
with every move graded against the lichess tablebase, end-to-end.
## Definition of done
- On `/endgames/:id/play`, the seeded endgames (KR v K, KPPP v KPP) load and are
playable.
- The user plays `endgame.color`; a legal move is graded (optimal / winning /
losing) against the tablebase; the opponent auto-replies with optimal defence.
- A **losing move** fails the puzzle immediately; **checkmate or a winning
promotion** solves it.
- Draw endgames are playable: the user holds the draw (solves on chess.js
`isDraw()`), or fails on a losing move.
- Tablebase unavailability (429/network) blocks the session with a clear message.
- `times_attempted` / `times_solved` increment on finish.
## Decisions (see GLOSSARY.md, docs/adr/)
- Strict trainer; losing move fails. Optimal vs. winning-but-slower are two
feedback tiers; only losing moves fail.
- Client (chess.js) is authoritative for legality; server grades via tablebase
(ADR-0002). Tablebase via lichess API (ADR-0001).
- Server holds attempt state in `assigns`; the client is the only engine.
- Grading rule: a move passes iff its category ∈ {loss, syzygy-loss, maybe-loss}
(opponent still lost); `cursed-win`/`blessed-loss` normalise to draw.
- Cutoff: solve on checkmate or a winning promotion.
- LFU cache with weekly halving sweep.
## Work breakdown
### 0. Prerequisite bug fixes
- `Chesstrainer.Endgames.Tablebase.new/1`: return `{:ok, tablebase}` on a cache
hit (fix the `{:cache, _}` return + `@spec`); unwrap the tuple in
`Chesstrainer.Game.game_from_fen/2`.
- `Chesstrainer.Endgames.Tablebase.Parser`: normalise the full category
vocabulary to `:win | :draw | :loss | :unknown`
(`win/syzygy-win/maybe-win → :win`; `draw/cursed-win/blessed-loss → :draw`;
`loss/syzygy-loss/maybe-loss → :loss`).
- `assets/js/hooks/chessBoard.js`: add `promotion` (and `prev_fen`) to the
`endgame_move_played` payload for unambiguous UCI matching.
### 1. LFU cache rewrite
- `Chesstrainer.Cache`: store `{key, value, freq, last_access}`; on `put`, if
over `@max_size`, evict lowest frequency (LRU tie-break).
- `Chesstrainer.Cache.Evict`: replace timestamp-based eviction with frequency.
- Add a weekly sweep that halves every entry's frequency
(`Chesstrainer.Cache` `handle_info` timer, alongside the existing backup).
- `Chesstrainer.Cache.Persist`: the DETS tuple format changes; drop old backups
(tablebase data is re-fetchable).
### 2. Server attempt state + grading (`EndgameLive.Play`)
- `assigns`: `fen` (grading reference), `status` (`:playing | :solved | :failed
| :blocked`), `move_list`, `last_grade`.
- `handle_event("endgame_move_played", %{from, to, san, prev_fen, fen_after,
promotion})`:
1. grade the move against `prev_fen`'s tablebase (match UCI; pass/fail);
2. on fail → `status: :failed`, reveal the missed optimal move(s);
3. on pass → pick the opponent reply (`moves[0]`) from `fen_after`'s
tablebase, push it to the client, update `fen`;
4. detect solve (checkmate / winning promotion) and draw (for draw endgames).
- Block: when `Tablebase.new` returns `{:cooldown, _}` or `{:error, _}`,
set `status: :blocked` and surface a message.
### 3. Client hook (`assets/js/hooks/chessBoard.js`)
- Send `prev_fen` + `fen_after` + `promotion` on each move.
- Apply the opponent reply (from the server) via chess.js and animate it.
- Report draw/mate (chess.js `isDraw()` / `isCheckmate()`) for terminal
detection.
### 4. Feedback UI (`EndgameLive.Play` + components)
- Two-tier grade display (green "Best" vs. amber "Winning, but suboptimal"),
losing-move failure with the missed move, solved/failed banner, reset/retry.
### 5. Counters
- Increment `times_attempted` on start; `times_solved` on solve (via
`Chesstrainer.Endgames`).
## Out of scope (deferred)
- Auth / user accounts: #3
- Glicko rating for users and endgames (puzzle ELO): #4
- Draw via cursed-win 50-move defences; material-based cutoffs; per-endgame
`win_condition` field.