Files

4.0 KiB

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.