Files
chess-endgame-trainer/docs/adr/0004-tablebase-cache-shape-and-scaling.md
T
owenrees a5bb1cb670 Scale the tablebase cache to ~100k entries (#24)
* Slim the cached tablebase value to the fields the trainer reads (#20)

* Sample for LFU eviction instead of scanning the cache (#21)

* Make cache size configurable and back up daily off-peak (#22)

* Document the cache design in the glossary and an ADR (#23)

* Address cache-scaling code review findings
2026-11-02 23:02:01 +01:00

1.9 KiB

Cache only the graded tablebase outcome, at ~100k entries with sampled eviction and daily best-effort backups

The cached value keeps only what the trainer reads: the position's category, checkmate flag and moves (each with category, dtz, san and uci), plus dtm/dtc as a small, deliberate hedge for a future "mate in N" or distance-to-conversion feature. The rest of the API response — dtw, precise DTZ, per-move terminal and variant flags, material flags — is dropped: it is never read, and slimming each entry from ~10 KB to ~4 KB keeps the working set in memory. Cursed-win and blessed-loss are normalised to a draw at parse time, so the variant and dtw fields mean nothing here. The cost is that a richer trainer would need a cache shape (and DETS format) change and a refill; dtm/dtc keep the most likely such feature cheap.

The cache holds 100k entries by default and is configurable. At ~4 KB per entry that is roughly 400 MB of BEAM memory per node — accepted because the cache is a warm, per-node optimization rather than the source of truth, and the cap is configurable for smaller deployments. That is large enough that the recurring working set rarely evicts, and at capacity eviction samples ~64 entries and drops the least-frequently-used of those rather than scanning the whole table for the exact victim: a cache that re-fetches on a miss only needs a cold entry, and the O(n) scan per put was what stopped the cache scaling past ~100k. The weekly frequency-halving sweep stays, because it is time-based aging rather than victim selection. The cache is warm state — the API is the source of truth — so a daily backup at 03:00 UTC, written off the cache process to a temporary file and atomically renamed, is the right durability level: a crash can lose up to a day of cache, costing rate-limited re-fetches rather than data, and a torn write can never replace a good backup.