Derive only-move, underpromotion and 50-move motif themes (#195)

Motifs describe the kind of problem, independent of the material family. One
local tablebase probe returns the root WDL, the DTZ and every legal move with
its own WDL, so each motif is proved without a search or a remote lookup.

- only move: more than one legal move and exactly one preserves the
  50-move-aware result, for wins and draws.
- underpromotion: a preserving underpromotion exists while no preserving queen
  promotion does.
- 50-move draw: cursed/blessed WDL, or a win whose DTZ exceeds the remaining
  halfmove budget.

Motif links are recorded as derived and refreshed as a whole, scoped to the
motif themes, so material, curated and community links survive. Loss endgames
are skipped because only-move is undefined there.

Stalemate is deferred: a stored endgame cannot itself be terminal, so it can
only describe a line and needs a definition before it becomes a predicate.

Release helpers run the derivation without starting the web application, so
`bin/chesstrainer eval` works on the server.

Closes #188
This commit is contained in:
2026-11-17 22:37:37 +01:00
committed by GitHub
parent e6f08e0ca6
commit 2759b34296
6 changed files with 493 additions and 0 deletions
@@ -80,6 +80,38 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
end
end
@doc """
Probes the local tablebase and returns the raw root outcome and move list.
Unlike `probe_result_local/1`, this keeps the per-move tuples and the raw WDL
atom, including `:cursed_win` and `:blessed_loss`, which the motif derivation
needs. It never falls back to the remote backend or consults the cache.
Returns `{:error, :unsupported}` when the local files cannot answer the
position, including a partial tablebase set where Fathom reports `:failed`.
"""
@spec probe_local_detail(String.t()) ::
{:ok, %{wdl: atom(), dtz: integer(), moves: [tuple()]}}
| {:error, :not_configured | :terminal | :unsupported}
def probe_local_detail(fen) do
with {:ok, largest} <- Local.check(),
pieces when is_integer(pieces) <- FEN.piece_count(fen),
true <- pieces <= largest || {:error, :unsupported},
{:ok, {root, moves}} <- Nif.probe(fen) do
case root do
:failed -> {:error, :unsupported}
:checkmate -> {:error, :terminal}
:stalemate -> {:error, :terminal}
{wdl, _from, _to, _promotes, _ep, dtz} -> {:ok, %{wdl: wdl, dtz: dtz, moves: moves}}
end
else
{:error, :not_configured} = error -> error
{:error, :unsupported} = error -> error
{:error, _reason} -> {:error, :unsupported}
nil -> {:error, :unsupported}
end
end
defp fallback(fen) do
(Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen)
end