Derive canonical material Key from the FEN

The Endgame key is now a canonical, colour-agnostic material signature derived
from the FEN instead of a hand-typed field: each side's pieces, strongest side
first by material value (e.g. "KQ v KR"). This fixes the seed ordering
inconsistency and guarantees the key always matches the position.

- Add Chesstrainer.Key.from_fen/1.
- Compute the key in the Endgame changeset; drop the manual input and its
  regex validation.
- Index endgames.key and derive keys in the seeds.
- Document the Key term and the decision (ADR 0003).

Closes #13
This commit is contained in:
2026-11-02 09:22:01 +01:00
parent cd2e7f0164
commit ca65207baa
12 changed files with 258 additions and 47 deletions
+29 -10
View File
@@ -6,23 +6,47 @@ defmodule Chesstrainer.EndgamesTest do
alias Chesstrainer.Themes
describe "create_endgame/1 FEN validation" do
test "accepts a standard valid FEN" do
test "accepts a standard valid FEN and derives its key" do
attrs = %{
fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1",
color: :white,
key: "KR v K",
result: :win,
rating: 1500
}
assert {:ok, %Endgame{}} = Endgames.create_endgame(attrs)
assert {:ok, %Endgame{} = endgame} = Endgames.create_endgame(attrs)
assert endgame.key == "KR v K"
end
test "derives the key from the strongest side, colour-agnostically" do
attrs = %{
fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 0",
color: :black,
result: :win,
rating: 1500
}
assert {:ok, endgame} = Endgames.create_endgame(attrs)
assert endgame.key == "KPPP v KPP"
end
test "ignores a supplied key and derives it from the FEN" do
attrs = %{
fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1",
color: :white,
key: "KQ v K",
result: :win,
rating: 1500
}
assert {:ok, endgame} = Endgames.create_endgame(attrs)
assert endgame.key == "KR v K"
end
test "normalizes fullmove 0 to 1 before inserting" do
attrs = %{
fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 0",
color: :black,
key: "KPPP v KPP",
result: :win,
rating: 1500
}
@@ -35,7 +59,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: " 8/8/3k4/8/8/3K1R2/8/8 w - - 0 1\t\n",
color: :white,
key: "KR v K",
result: :win,
rating: 1500
}
@@ -48,7 +71,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: "4k3/8/8/8/8/8/8/0K7 w - - 0 1",
color: :white,
key: "KQ v K",
result: :win,
rating: 1500
}
@@ -62,7 +84,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: "8/8/3k4/8/8/3K1R2/8/8",
color: :white,
key: "KQ v K",
result: :win,
rating: 1500
}
@@ -76,7 +97,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: "8/8/3k4/8/8/3K1R2/8/8 x - - 0 1",
color: :white,
key: "KQ v K",
result: :win,
rating: 1500
}
@@ -94,7 +114,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: "8/8/3k4/8/8/3K1R2/8/8 w - - 0 1",
color: :white,
key: "KR v K",
result: :win,
rating: 1500
}
@@ -110,7 +129,6 @@ defmodule Chesstrainer.EndgamesTest do
attrs = %{
fen: "6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1",
color: :black,
key: "KPPP v KPP",
result: :win,
rating: 1500
}
@@ -118,6 +136,7 @@ defmodule Chesstrainer.EndgamesTest do
assert {:ok, endgame} = Endgames.create_endgame(attrs, [lucena])
assert {:ok, updated} = Endgames.update_endgame(endgame, %{rating: 1600}, [philidor])
assert Enum.map(updated.themes, & &1.id) == [philidor.id]
assert updated.key == "KPPP v KPP"
end
end
end
+39
View File
@@ -0,0 +1,39 @@
defmodule Chesstrainer.KeyTest do
use ExUnit.Case, async: true
doctest Chesstrainer.Key
alias Chesstrainer.Key
describe "from_fen/1" do
test "derives a rook endgame" do
assert Key.from_fen("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1") == {:ok, "KR v K"}
end
test "is colour-agnostic" do
white_queen = "8/8/3k1r2/8/8/3K1Q2/8/8 w - - 0 1"
black_queen = "8/8/3k1q2/8/8/3K1R2/8/8 w - - 0 1"
assert Key.from_fen(white_queen) == {:ok, "KQ v KR"}
assert Key.from_fen(black_queen) == {:ok, "KQ v KR"}
end
test "puts the side with more material first" do
assert Key.from_fen("6k1/5p2/6p1/8/7p/8/6PP/6K1 b - - 0 1") == {:ok, "KPPP v KPP"}
end
test "orders equal-value sides deterministically" do
white_bishop = "8/8/3k1n2/8/8/3K1B2/8/8 w - - 0 1"
white_knight = "8/8/3k1b2/8/8/3K1N2/8/8 w - - 0 1"
assert Key.from_fen(white_bishop) == {:ok, "KB v KN"}
assert Key.from_fen(white_knight) == {:ok, "KB v KN"}
end
test "returns an error for malformed FENs" do
assert Key.from_fen("not a fen") == {:error, :invalid_fen}
assert Key.from_fen("8/8/8 w - - 0 1") == {:error, :invalid_fen}
assert Key.from_fen(nil) == {:error, :invalid_fen}
end
end
end