Files
chess-endgame-trainer/docs/adr/0005-tablebase-source-split.md
T
owenrees 3b527d21ed Update domain docs for local tablebase routing (#32)
Redefine Tablebase and Cooldown in GLOSSARY.md for the local<=5 / Lichess 6-7 / cache-only-API split, and add Probe and Position key terms. Add ADR-0005 recording the source split and its latency-vs-footprint trade-off, and mark ADR-0001 superseded.
2026-11-03 14:49:07 +01:00

1.6 KiB

Answer five-or-fewer-piece positions from local Syzygy, keep six and seven on Lichess, and cache only the API path

Status: accepted. Supersedes ADR-0001's "all lookups remote" assumption.

Relying entirely on the Lichess tablebase API put network latency and rate limits (and a cooldown on 429) in front of every lookup. Hosting everything is not viable either: the 3-4-5-piece Syzygy set is about 939 MB, six pieces about 150 GB, seven pieces about 18 TB, and eight or more pieces are outside every tablebase. We route by piece count instead: five or fewer are probed locally from Syzygy WDL+DTZ files, six and seven go to Lichess, and eight or more are rejected without a lookup. A local failure — missing or partial files, probe error — falls back to Lichess, so play only blocks when both sources are unavailable.

Only the Lichess path is cached. Local probes read from the OS page cache and are cheap, so an application cache would spend memory on answers we can regenerate. Cache entries are keyed by position rather than the full FEN: the result depends only on board, side to move, castling and en-passant, so clock-only differences are the same position, and the 50-move rule is already encoded in the WDL/DTZ values rather than the running halfmove clock.

The cost is a native build: the local prober is an MIT-licensed C library vendored behind a Rust NIF, so a release build needs the Rust toolchain, and each host points TABLEBASE_PATH at its own copy of the files. In exchange the common (≤5-piece) case is answered without the network or rate limits, while the enormous 6-7-piece sets stay off our infrastructure.