From 3fadd4397c45d4b3ec9677477cf1049c1fbe3c20 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 3 Nov 2026 13:09:45 +0100 Subject: [PATCH] Key the tablebase cache by position instead of full FEN (#28) Add FEN.position_key/1 (board, side, castling and en-passant; clocks dropped) and have Tablebase.new/1 key cache reads and writes on it, so transpositions and clock-only differences share an entry. The Lichess category is a position property, so dropping the clocks is safe. Update the cache docs and tests, and give the play fixture's after_first/after_losing distinct positions since they previously differed only by the halfmove clock. --- lib/chesstrainer/endgames/tablebase.ex | 7 ++-- lib/chesstrainer/endgames/tablebase/cache.ex | 11 ++++--- lib/chesstrainer/fen.ex | 26 +++++++++++++++ test/chesstrainer/endgames/tablebase_test.exs | 20 ++++++++++-- test/chesstrainer/fen_test.exs | 32 +++++++++++++++++++ .../live/endgame_live/play_test.exs | 14 +++++--- 6 files changed, 96 insertions(+), 14 deletions(-) diff --git a/lib/chesstrainer/endgames/tablebase.ex b/lib/chesstrainer/endgames/tablebase.ex index 9d2bacd..d810f0d 100644 --- a/lib/chesstrainer/endgames/tablebase.ex +++ b/lib/chesstrainer/endgames/tablebase.ex @@ -12,6 +12,7 @@ defmodule Chesstrainer.Endgames.Tablebase do """ alias Chesstrainer.Endgames.Tablebase + alias Chesstrainer.FEN @type result :: :win | :draw | :loss | :unknown @@ -49,7 +50,9 @@ defmodule Chesstrainer.Endgames.Tablebase do | {:error, :invalid_endgame} | {:error, term()} def new(fen) do - case Tablebase.Cache.get(fen) do + key = FEN.position_key(fen) + + case Tablebase.Cache.get(key) do {:ok, tablebase} -> {:ok, tablebase} @@ -65,7 +68,7 @@ defmodule Chesstrainer.Endgames.Tablebase do {:error, :invalid_endgame} {:ok, tablebase} -> - Tablebase.Cache.put(fen, tablebase) + Tablebase.Cache.put(key, tablebase) {:ok, tablebase} end end diff --git a/lib/chesstrainer/endgames/tablebase/cache.ex b/lib/chesstrainer/endgames/tablebase/cache.ex index 8214ad3..e033ada 100644 --- a/lib/chesstrainer/endgames/tablebase/cache.ex +++ b/lib/chesstrainer/endgames/tablebase/cache.ex @@ -1,17 +1,20 @@ defmodule Chesstrainer.Endgames.Tablebase.Cache do @moduledoc """ - A cache of tablebases by FEN. + A cache of tablebases keyed by position. + + The key is a FEN's position fields (see `Chesstrainer.FEN.position_key/1`), so + transpositions and clock-only differences share an entry. """ alias Chesstrainer.Cache @table :tablebase - def put(fen, tablebase), do: Cache.put(@table, fen, tablebase) + def put(key, tablebase), do: Cache.put(@table, key, tablebase) - def get(fen), do: Cache.get(@table, fen) + def get(key), do: Cache.get(@table, key) - def delete(fen), do: Cache.delete(@table, fen) + def delete(key), do: Cache.delete(@table, key) def show, do: Cache.show(@table) def size, do: Cache.size(@table) end diff --git a/lib/chesstrainer/fen.ex b/lib/chesstrainer/fen.ex index 26e503d..2aa0f8e 100644 --- a/lib/chesstrainer/fen.ex +++ b/lib/chesstrainer/fen.ex @@ -40,6 +40,32 @@ defmodule Chesstrainer.FEN do end end + @doc """ + Returns the position key for a FEN: the board, side to move, castling and + en-passant fields, with the halfmove and fullmove clocks dropped. + + A tablebase answer depends only on the position, so two FENs that differ only + in their clocks resolve to the same position key and share a cache entry. + + ## Examples + + iex> Chesstrainer.FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") + "8/8/3k4/8/8/3K1R2/8/8 w - -" + + iex> Chesstrainer.FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 w - - 37 99") + "8/8/3k4/8/8/3K1R2/8/8 w - -" + """ + @spec position_key(String.t()) :: String.t() + def position_key(fen) when is_binary(fen) do + case String.split(fen) do + [board, active, castling, en_passant | _] -> + Enum.join([board, active, castling, en_passant], " ") + + _ -> + String.trim(fen) + end + end + @doc """ Counts the pieces on the board, or returns `nil` if the board field is not a well-formed FEN board. diff --git a/test/chesstrainer/endgames/tablebase_test.exs b/test/chesstrainer/endgames/tablebase_test.exs index d7dffbf..1bb8ffd 100644 --- a/test/chesstrainer/endgames/tablebase_test.exs +++ b/test/chesstrainer/endgames/tablebase_test.exs @@ -4,6 +4,7 @@ defmodule Chesstrainer.Endgames.TablebaseTest do alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache alias Chesstrainer.Endgames.Tablebase.Parser + alias Chesstrainer.FEN alias Chesstrainer.Ratelimiters describe "normalize_category/1" do @@ -144,16 +145,29 @@ defmodule Chesstrainer.Endgames.TablebaseTest do test "returns {:ok, tablebase} on a cache hit" do fen = "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" tablebase = %Tablebase{category: :win, moves: []} + key = FEN.position_key(fen) - TablebaseCache.put(fen, tablebase) - on_exit(fn -> TablebaseCache.delete(fen) end) + TablebaseCache.put(key, tablebase) + on_exit(fn -> TablebaseCache.delete(key) end) assert {:ok, ^tablebase} = Tablebase.new(fen) end + test "shares a cache entry for FENs that differ only in the clocks" do + fen = "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + other_clock = "8/8/3k4/8/8/3K1R2/8/8 w - - 7 42" + tablebase = %Tablebase{category: :win, moves: []} + key = FEN.position_key(fen) + + TablebaseCache.put(key, tablebase) + on_exit(fn -> TablebaseCache.delete(key) end) + + assert {:ok, ^tablebase} = Tablebase.new(other_clock) + end + test "returns {:error, :not_covered} for a position with more than seven pieces" do fen = "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1" - TablebaseCache.delete(fen) + TablebaseCache.delete(FEN.position_key(fen)) assert Tablebase.new(fen) == {:error, :not_covered} end diff --git a/test/chesstrainer/fen_test.exs b/test/chesstrainer/fen_test.exs index 4bca2c3..620613e 100644 --- a/test/chesstrainer/fen_test.exs +++ b/test/chesstrainer/fen_test.exs @@ -60,6 +60,38 @@ defmodule Chesstrainer.FENTest do end end + describe "position_key/1" do + test "drops the halfmove and fullmove clocks" do + assert FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") == + "8/8/3k4/8/8/3K1R2/8/8 w - -" + end + + test "shares a key for FENs that differ only in the clocks" do + a = "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + b = "8/8/3k4/8/8/3K1R2/8/8 w - - 37 99" + + assert FEN.position_key(a) == FEN.position_key(b) + end + + test "keeps board, side to move, castling and en-passant distinct" do + base = "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + + refute FEN.position_key(base) == FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 b - - 0 1") + refute FEN.position_key(base) == FEN.position_key("8/8/3k4/8/8/3K1R3/8/8 w - - 0 1") + refute FEN.position_key(base) == FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 w K - 0 1") + refute FEN.position_key(base) == FEN.position_key("8/8/3k4/8/8/3K1R2/8/8 w - e3 0 1") + end + + test "trims surrounding whitespace" do + assert FEN.position_key(" 8/8/3k4/8/8/3K1R2/8/8 w - - 0 1\n") == + "8/8/3k4/8/8/3K1R2/8/8 w - -" + end + + test "passes through a non-FEN string" do + assert FEN.position_key("not a fen") == "not a fen" + end + end + describe "piece_count/1" do test "counts kings and pieces, ignoring empty squares and slashes" do assert FEN.piece_count("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") == 3 diff --git a/test/chesstrainer_web/live/endgame_live/play_test.exs b/test/chesstrainer_web/live/endgame_live/play_test.exs index 2698f8d..ec32b4e 100644 --- a/test/chesstrainer_web/live/endgame_live/play_test.exs +++ b/test/chesstrainer_web/live/endgame_live/play_test.exs @@ -7,6 +7,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do alias Chesstrainer.Endgames alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache + alias Chesstrainer.FEN alias Chesstrainer.Ratelimiters defp assert_init_board(view, expected_fen, expected_orientation, expected_player_color) do @@ -27,8 +28,9 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do moves: Keyword.get(opts, :moves, []) } - TablebaseCache.put(fen, tablebase) - on_exit(fn -> TablebaseCache.delete(fen) end) + key = FEN.position_key(fen) + TablebaseCache.put(key, tablebase) + on_exit(fn -> TablebaseCache.delete(key) end) end defp grading_moves do @@ -77,9 +79,11 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do defp seeded_attempt(conn) do endgame = endgame_fixture() + # The tablebase cache is keyed by position (clocks ignored), so these must + # differ by more than the move clocks to stay distinct cache entries. after_first = "8/8/8/8/8/8/8/8 b - - 0 1" after_reply = "8/8/8/8/8/8/8/8 w - - 0 1" - after_losing = "8/8/8/8/8/8/8/8 b - - 1 1" + after_losing = "8/8/8/8/8/8/8/7K b - - 1 1" reply = %Tablebase.Move{uci: "e8e7", san: "Ke7", category: :loss, dtz: -3} losing_reply = %Tablebase.Move{uci: "e8e7", san: "Ke7", category: :draw, dtz: 0} @@ -174,7 +178,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do describe "tablebase availability" do test "blocks the attempt when the tablebase is cooling down", %{conn: conn} do endgame = endgame_fixture() - TablebaseCache.delete(endgame.fen) + TablebaseCache.delete(FEN.position_key(endgame.fen)) Ratelimiters.lichess_add_cooldown() on_exit(fn -> Ratelimiters.lichess_reset_cooldown() end) @@ -735,7 +739,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do test "degrades gracefully and reuses played-position snapshots", %{conn: conn} do {view, fens} = seeded_attempt(conn) - TablebaseCache.delete(fens.after_losing) + TablebaseCache.delete(FEN.position_key(fens.after_losing)) Ratelimiters.lichess_add_cooldown() on_exit(fn -> Ratelimiters.lichess_reset_cooldown() end)