Add chess.chesstb: pure-Python prober for chesstb endgame tablebases

[noobpwnftw]

Add chess.chesstb: pure-Python prober for chesstb endgame tablebases

What this adds

A new module, chess.chesstb, that probes the chesstb endgame
tablebase format directly from chess.Board positions — in the same spirit as
the existing chess.syzygy and chess.gaviota modules.

chesstb ships four table types per material:

Table	Extension	Answer
WDL	.lzw	50-move-rule-aware win/draw/loss with cursed/blessed classes
DTZ	.lzdtz	distance-to-zeroing (plies to the next capture, promotion or pawn move)
DTM	.lzdtm	unbounded distance-to-mate
DTM50	.lzdtm50	one pack giving both the unbounded DTM and the exact 50MR DTM at any halfmove clock

The DTM50 pack carries the unbounded DTM in its flat layer, which makes the
standalone DTM table redundant wherever a pack ships. Both are read, with the
pack preferred: material shipping only .lzdtm still answers probe_dtm.

Files are looked up in the wdl/, dtz/, dtm/ and dtm50/ subdirectories of
each search directory, and in the directory itself, so a flat dump of table
files is also probeable.

API

import chess, chess.chesstb

with chess.chesstb.open_tablebase("/path/to/chesstb") as tb:
    board = chess.Board("8/8/8/5k2/8/8/1Q6/K7 w - - 0 1")
    tb.probe_wdl(board)        # 2  (+2 win .. -2 loss, like syzygy)
    tb.probe_dtz(board)        # 19 (signed distance-to-zeroing)
    tb.probe_dtm(board)        # 19 (signed distance-to-mate, ignoring 50MR)
    tb.probe_dtm50(board)      # (2, 19): rule-true (wdl, plies) at the board's clock

get_wdl / get_dtz / get_dtm are non-raising variants returning a default
(None) when no table is available. probe(board, rule50=0) returns the full
structured result — every metric at once, off a single walk.

probe_dtz measures what syzygy's does, but the two are not interchangeable.
Syzygy bases its cursed band off 100 — n > 100 is a cursed win whose zeroing
move is n or n - 100 plies away — so a DTZ magnitude carries the WDL class
along with the count. A chesstb DTZ is a plain distance in every class, the
class being WDL's alone, so substituting one for the other silently changes
what the number means.

Why pure Python

chess.syzygy is pure Python; this follows suit. The module depends only on
python-chess and the standard library:

• LZMA (DTZ / DTM / DTM50 blocks) via stdlib lzma with FORMAT_RAW (the
  C++ side uses the LZMA SDK with props appended at each block tail).
• LZ4 (WDL blocks) via a small bundled pure-Python LZ4-block decoder
  (~40 lines) supporting the optional LZ4 dictionary. No new dependency.

The position index (symmetry canonicalization, king/pawn slice managers, the
binomial piece-group ranking, the radix-composed board index and the
index-permutation layout) and the probe orchestration (dropped-frame one-ply
minimax reconstruction for shrunk files, the en-passant overlay, and the DTM50
halfmove-clock layer selection) are faithful re-implementations of the C++
src/probe library. Square numbering already matches python-chess exactly
(a1=0 … h8=63), so boards are consumed directly.

DTZ and DTM are byte-for-byte twins on disk — as src/probe/dtm_file.cpp says
of its own traits — so they share one reader here, with the magic and the value
decode as the whole of what separates them.

Design notes

• Mapped, not read. Tables are memory-mapped and decoded a block at a time,
  with one shared LRU holding decoded blocks across every open table against a
  single budget (open_tablebase(..., block_cache_bytes=...)).
• One transport seam. _TableFile._open_source is the only place the
  transport is decided, and the four file classes are named as class attributes
  on Tablebase, so serving tables from something other than a mapping is four
  subclasses and a _find. Nothing above that seam asks for a span wider than
  one block.
• Thread-safe. Probes register as readers so close() can wait for them
  before unmapping; table opens are double-checked under a per-kind lock, and
  block decoding is guarded per (color, block) rather than per table.

Validation

Every value is validated bit-for-bit against the reference C++ prober
(tests/probe_fen) by enumerating positions and comparing WDL, DTZ, DTM and
DTM50 in lockstep:

• All 145 shipped ≤5-man materials, ~72k positions at halfmove clock 0 —
  0 mismatches.
• Layered DTM50 at halfmove clocks 1, 30, 40, 80, 98, 99 across all
  materials (exercising the CONST/SINGLE/DOUBLE/MULTI changepoint state machine,
  the draw-end hint, and recover_mate_at_hmc) — 0 mismatches.
• Dropped-frame reconstruction: both the symmetric-mirror path (e.g. KRKR)
  and the asymmetric one-ply-minimax derive (109 of 145 materials ship a dropped
  frame) — 0 mismatches.
• En-passant overlay and color-mirrored material (stronger side is
  Black) — verified against the oracle.
• The pure-Python LZ4 decoder is cross-checked block-for-block against the
  reference lz4 C library on every shipped WDL table.

The standalone DTM reader was validated the same way, over random positions and
short playouts across the seven fixture materials (which reach en-passant
squares, mates, stalemates and every capture/promotion sub-material), against
probe_fen pointed at the same directories — 0 mismatches in each shape the
table can take on disk:

Table shape	how produced	positions
frames intact	chesstb --builddtm	22,851
dropped frame	shrink	22,851
loss-only (wins derive at probe time)	transcribe --loss-only	3,453
loss-only and dropped, over shrunk wdl/+dtz/	both	14,187
all four kinds present (pack preferred)	—	8,640

Tests

ChesstbTestCase in test.py, against table sets for seven materials
(KBK … KRKR) committed under data/chesstb/, shrink-processed as they would
ship.

The logic is proven on the C++ side and by the sweeps above, so these tests
target what is specific to this port rather than re-proving the format: the
four-kind wiring and directory search, the shared DTZ/DTM reader and its value
decodes, rejection of malformed files (and release of the mapping a failed open
had taken), the changepoint decoder at a live clock, the block-cache budget,
the mmap lifecycle, the transport seam, and probing concurrently from several
threads.