From 515196857f6c7ebd4dabe00440908ba6f81cceed Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 3 Nov 2026 12:51:08 +0100 Subject: [PATCH] Route tablebase lookups through a piece-count backend seam (#27) Add a Backend behaviour, a Lichess implementation, and a Router that picks a backend by piece count: five or fewer to the local slot, six or seven to the remote slot, and eight or more short-circuited as not covered with no network call. Both slots point at Lichess for now; the local Syzygy backend replaces the local slot when it lands. Map :not_covered to the existing 'not covered by the tablebase' message. --- lib/chesstrainer/endgames/tablebase.ex | 5 ++- .../endgames/tablebase/backend.ex | 17 ++++++++ .../endgames/tablebase/backend/lichess.ex | 12 ++++++ lib/chesstrainer/endgames/tablebase/router.ex | 42 +++++++++++++++++++ .../live/endgame_live/play.ex | 4 ++ .../endgames/tablebase/router_test.exs | 40 ++++++++++++++++++ test/chesstrainer/endgames/tablebase_test.exs | 7 ++++ .../live/endgame_live/play_test.exs | 25 +++++++++++ 8 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 lib/chesstrainer/endgames/tablebase/backend.ex create mode 100644 lib/chesstrainer/endgames/tablebase/backend/lichess.ex create mode 100644 lib/chesstrainer/endgames/tablebase/router.ex create mode 100644 test/chesstrainer/endgames/tablebase/router_test.exs diff --git a/lib/chesstrainer/endgames/tablebase.ex b/lib/chesstrainer/endgames/tablebase.ex index e055cec..9d2bacd 100644 --- a/lib/chesstrainer/endgames/tablebase.ex +++ b/lib/chesstrainer/endgames/tablebase.ex @@ -2,6 +2,9 @@ defmodule Chesstrainer.Endgames.Tablebase do @moduledoc """ All endgame tablebase related functions. + Lookups are routed by piece count through `Tablebase.Router`, which picks the + backend that can answer the position. + The cached value carries only what the trainer reads: `category`, `checkmate`, and `moves`. Cursed-win/blessed-loss are normalised to `:draw` at parse time, and distance fields (`dtm`/`dtc`/`dtw`) are not kept because the @@ -51,7 +54,7 @@ defmodule Chesstrainer.Endgames.Tablebase do {:ok, tablebase} _ -> - case Tablebase.Parser.from_fen(fen) do + case Tablebase.Router.probe(fen) do {:error, reason} -> {:error, reason} diff --git a/lib/chesstrainer/endgames/tablebase/backend.ex b/lib/chesstrainer/endgames/tablebase/backend.ex new file mode 100644 index 0000000..dae3df5 --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/backend.ex @@ -0,0 +1,17 @@ +defmodule Chesstrainer.Endgames.Tablebase.Backend do + @moduledoc """ + A backend answers a tablebase probe for one position. + + The router chooses a backend by piece count, so the play flow never depends on + which one answered. Every backend returns the same shape. + """ + + alias Chesstrainer.Endgames.Tablebase + + @type result :: + {:ok, Tablebase.t()} + | {:cooldown, non_neg_integer()} + | {:error, term()} + + @callback probe(String.t()) :: result() +end diff --git a/lib/chesstrainer/endgames/tablebase/backend/lichess.ex b/lib/chesstrainer/endgames/tablebase/backend/lichess.ex new file mode 100644 index 0000000..a58379b --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/backend/lichess.ex @@ -0,0 +1,12 @@ +defmodule Chesstrainer.Endgames.Tablebase.Backend.Lichess do + @moduledoc """ + The Lichess tablebase API backend (covers up to seven pieces). + """ + + @behaviour Chesstrainer.Endgames.Tablebase.Backend + + alias Chesstrainer.Endgames.Tablebase.Parser + + @impl true + def probe(fen), do: Parser.from_fen(fen) +end diff --git a/lib/chesstrainer/endgames/tablebase/router.ex b/lib/chesstrainer/endgames/tablebase/router.ex new file mode 100644 index 0000000..014699d --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/router.ex @@ -0,0 +1,42 @@ +defmodule Chesstrainer.Endgames.Tablebase.Router do + @moduledoc """ + Chooses a tablebase backend by piece count. + + Positions with five or fewer pieces go to the local slot; six or seven go to + the remote slot. The local slot currently points at Lichess until the local + Syzygy backend lands, so this ships without changing today's behaviour. + + Positions with eight or more pieces are beyond every tablebase and are + rejected without a network call. + """ + + alias Chesstrainer.Endgames.Tablebase + alias Chesstrainer.Endgames.Tablebase.Backend.Lichess + alias Chesstrainer.FEN + + @max_local_pieces 5 + @max_pieces 7 + + # The local Syzygy backend will replace Lichess here once it exists. + @local_backend Lichess + @remote_backend Lichess + + @spec backend(String.t()) :: {:ok, module()} | {:error, :not_covered | :invalid_endgame} + def backend(fen) do + case FEN.piece_count(fen) do + count when is_integer(count) and count <= @max_local_pieces -> {:ok, @local_backend} + count when is_integer(count) and count <= @max_pieces -> {:ok, @remote_backend} + count when is_integer(count) -> {:error, :not_covered} + _ -> {:error, :invalid_endgame} + end + end + + @spec probe(String.t()) :: + {:ok, Tablebase.t()} | {:cooldown, non_neg_integer()} | {:error, term()} + def probe(fen) do + case backend(fen) do + {:ok, backend} -> backend.probe(fen) + {:error, reason} -> {:error, reason} + end + end +end diff --git a/lib/chesstrainer_web/live/endgame_live/play.ex b/lib/chesstrainer_web/live/endgame_live/play.ex index f733e25..a5e094b 100644 --- a/lib/chesstrainer_web/live/endgame_live/play.ex +++ b/lib/chesstrainer_web/live/endgame_live/play.ex @@ -572,6 +572,10 @@ defmodule ChesstrainerWeb.EndgameLive.Play do "This position is not covered by the tablebase." end + defp blocked_reason({:error, :not_covered}) do + "This position is not covered by the tablebase." + end + defp blocked_reason({:error, reason}) do "The tablebase is unavailable (#{inspect(reason)})." end diff --git a/test/chesstrainer/endgames/tablebase/router_test.exs b/test/chesstrainer/endgames/tablebase/router_test.exs new file mode 100644 index 0000000..bdfb638 --- /dev/null +++ b/test/chesstrainer/endgames/tablebase/router_test.exs @@ -0,0 +1,40 @@ +defmodule Chesstrainer.Endgames.Tablebase.RouterTest do + use ExUnit.Case, async: true + + alias Chesstrainer.Endgames.Tablebase.Backend.Lichess + alias Chesstrainer.Endgames.Tablebase.Router + + @three "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1" + @six "8/8/5p2/1P1K1k2/8/2r5/8/7R w - - 0 0" + @seven "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1" + @ten "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1" + + describe "backend/1" do + test "routes five or fewer pieces to the local slot" do + assert Router.backend(@three) == {:ok, Lichess} + end + + test "routes six and seven pieces to the remote slot" do + assert Router.backend(@six) == {:ok, Lichess} + assert Router.backend(@seven) == {:ok, Lichess} + end + + test "marks eight or more pieces as not covered" do + assert Router.backend(@ten) == {:error, :not_covered} + end + + test "marks a malformed FEN as invalid" do + assert Router.backend("not a fen") == {:error, :invalid_endgame} + end + end + + describe "probe/1" do + test "rejects a position with more than seven pieces without a network call" do + assert Router.probe(@ten) == {:error, :not_covered} + end + + test "rejects a malformed FEN" do + assert Router.probe("not a fen") == {:error, :invalid_endgame} + end + end +end diff --git a/test/chesstrainer/endgames/tablebase_test.exs b/test/chesstrainer/endgames/tablebase_test.exs index 4ccaf0b..d7dffbf 100644 --- a/test/chesstrainer/endgames/tablebase_test.exs +++ b/test/chesstrainer/endgames/tablebase_test.exs @@ -150,5 +150,12 @@ defmodule Chesstrainer.Endgames.TablebaseTest do assert {:ok, ^tablebase} = Tablebase.new(fen) 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) + + assert Tablebase.new(fen) == {:error, :not_covered} + end end end diff --git a/test/chesstrainer_web/live/endgame_live/play_test.exs b/test/chesstrainer_web/live/endgame_live/play_test.exs index 4b4f134..2698f8d 100644 --- a/test/chesstrainer_web/live/endgame_live/play_test.exs +++ b/test/chesstrainer_web/live/endgame_live/play_test.exs @@ -57,6 +57,21 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do }) end + # >7-piece positions short-circuit to "not covered" before any backend, but + # the changeset now rejects them, so insert one directly to exercise the path. + defp insert_out_of_range_endgame do + fen = "3k4/2n2B2/1KP5/2B2p2/5b1p/7P/8/8 b - - 0 1" + {:ok, key} = Chesstrainer.Key.from_fen(fen) + + Chesstrainer.Repo.insert!(%Chesstrainer.Endgames.Endgame{ + fen: fen, + color: :black, + key: key, + result: :win, + rating: 1500 + }) + end + # Plays one optimal move, applies the opponent's reply, then a losing move, # leaving a three-ply failed attempt to review. defp seeded_attempt(conn) do @@ -170,6 +185,16 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do play_move(view, endgame, "d1", "d7", "Qd7+") assert render(view) =~ "cannot be graded" end + + test "blocks an out-of-range endgame as not covered", %{conn: conn} do + endgame = insert_out_of_range_endgame() + + {:ok, view, _html} = live(conn, ~p"/endgames/#{endgame}/play") + + html = render(view) + assert html =~ "Tablebase unavailable" + assert html =~ "not covered by the tablebase" + end end describe "chess_fen_invalid" do