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.
This commit is contained in:
2026-11-03 14:49:07 +01:00
parent 8ba87d8efe
commit 3b527d21ed
3 changed files with 47 additions and 5 deletions
+18 -5
View File
@@ -63,13 +63,26 @@ promotion (still winning) for conversion puzzles, mate otherwise.
**Tablebase**:
A database of precomputed optimal outcomes for every position with at most
seven pieces, queried via the lichess API and cached. The trainer caches only
the outcome data it grades on — enough to tell a winning move from a losing
one — not every metric the tablebase reports, and refetches anything else.
seven pieces. Positions with five or fewer pieces are answered from local
Syzygy files; six and seven piece positions come from the lichess API. The
trainer keeps only the outcome data it grades on — enough to tell a winning
move from a losing one — and caches API answers only; local answers are cheap
enough to refetch.
**Probe**:
A single lookup of one position in the tablebase, returning its result and its
legal moves. A probe is answered locally or by the API.
**Position key**:
The identity of a tablebase position — board, side to move, castling and
en-passant — excluding the move clocks. FENs that differ only in their clocks
share a position key.
_Avoid_: Full FEN
**Cooldown**:
Rate-limit state entered after a 429 from the lichess tablebase API, during
which the trainer blocks play.
Rate-limit state entered after a 429 from the lichess API, during which the
trainer blocks play for positions that need the API (six or seven pieces).
Local positions are unaffected.
**Cache sweep**:
The periodic halving of LFU cache frequencies (weekly) that lets rarely-used
@@ -1,5 +1,8 @@
# Tablebase via the lichess API instead of self-hosting
_Superseded by ADR-0005: five-or-fewer-piece positions are now probed locally;
Lichess remains for six and seven pieces._
The trainer grades moves against Syzygy tablebases, but self-hosting them is not
possible yet, so we query the lichess tablebase API (`tablebase.lichess.ovh`)
over HTTP and cache responses. This couples the core play loop to a remote
+26
View File
@@ -0,0 +1,26 @@
# 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.