Chess Policy Pipeline

Chess Policy Pipeline (self-play → CNN → zero-dep Rust inference)

Overview

End-to-end recipe for a small policy network that biases move ordering in an alpha-beta chess search. Validated on my-engine (Rust + chess crate). The hard part is NOT the math — it is the silent layout/IO mismatches between Python (training) and Rust (inference). This skill records every one of those traps.

When to Use

• Training a from*64+to (4096-class) move-prior for a chess engine.
• Generating self-play / teacher datasets via UCI.
• Adding policy guidance to a Rust alpha-beta searcher.
• Measuring whether a policy change actually improves playing strength.
• NOT for: full evaluation networks (NNUE), MCTS value nets, or non-chess games.

Pipeline

1. Self-play data — drive the engine over UCI (dataset_gen.py). Record per-ply {fen, bestmove_uci, score_cp, ...} as JSONL. Keep only decisive/active positions (drop games that hit the ply cap; truncate to first ~40 plies).
2. Teacher labels — CAUTION — make_teacher.py queries Stockfish (public/stockfish) per FEN at depth 8–10, replaces bestmove_uci. This is a FOREIGN-engine teacher. Because the policy only guides MOVE ORDERING (not the final move), a foreign engine's idea of "good move" does NOT transfer — it mismatches my-engine's own eval and gives no ordering benefit. Empirical result: 40-game match at 300ms showed BEFORE(self-play) 10 / AFTER(Stockfish-teacher) 9, Elo Δ +8.7, CI [-102, +121] → NO gain. Use SELF-DISTILLATION instead: label each FEN with my-engine's OWN bestmove at a deeper search (depth 8–10 of itself). That aligns the policy with the engine's own evaluation, so ordering guidance actually helps. This is the correct labeling strategy.
3. Augment — 8× D4 board symmetries (rot90/180/270 + flips). Transform board AND the move; DROP castling/ep on non-identity transforms and KEEP only variants where the transformed move is board.is_legal (python-chess). This removes illegal-label noise.
4. Train — tiny CNN 13ch→16→16 conv3x3(pad1)→FC1024→64→4096. 80/20 split. train_policy.py (system python, see Gotchas).
5. Export — export_weights.py writes policy.bin (float32, exact order below).
6. GOLDEN TEST (mandatory) — policy_golden_test.py: numpy re-impl of predict() reads policy.bin, compares to policy.onnx via onnxruntime. Max |Δlogit| ~5e-5 and identical top-1 ⇒ Rust matches training. NEVER skip — proves the model actually runs.
7. Evaluate — match.py plays engine-vs-engine N games, swapped colors, fixed movetime. Reports W/D/L + Elo diff with 95% CI. Compare before/after policy.

Critical Gotchas (silent bugs)

• ⚠️ Timeout sentinel poisoning the transposition table — the single worst silent strength-killer. If alpha_beta/quiesce set stopped=true and return 0 on timeout, then EVERY caller must check stopped immediately after each recursive call, and the tt.store(...) at the end MUST be guarded by if !stopped. Otherwise the sentinel 0 is treated as a real score, gets written into the TT, and (since the TT is usually only cleared on ucinewgame) persists for the whole game. Because iterative deepening always gets interrupted mid-iteration, every move poisons the TT — and the faster/deeper the search, the more nodes get poisoned. Symptom: the engine searches several plies deeper yet loses badly (measured here: NMP+PVS reached depth 12 vs 7 but scored −107 Elo). No crash, no error — only mysterious weakness that gets worse the more you optimize. Always verify: root discards incomplete iterations AND interior nodes never store aborted scores.
• ⚠️⚠️ chess 3.2.0 null_move() does NOT update the Zobrist hash — TT key collision that makes null-move pruning actively harmful. Two defects compound: (1) impl Hash for Board returns the raw internal self.hash field, which omits en-passant (only get_hash() XORs the EP term in); (2) null_move() flips side_to_move but never XORs the SIDE_TO_MOVE term → the null-moved position gets the exact same TT key as the original, while its score is sign-flipped under negamax. NMP therefore writes sign-inverted scores under the real position's key, and every later probe reads a catastrophically wrong eval. Only the NMP branch calls null_move(), so a no-NMP baseline is unaffected — the symptom is "the engine gets weaker the moment I enable NMP". Fix — always build your own key, never trust the crate's Hash:

  fn board_key(board: &Board) -> u64 {
      let mut h = DefaultHasher::new();
      board.get_hash().hash(&mut h);                        // includes en-passant
      (board.side_to_move() == Color::White).hash(&mut h);   // null_move() forgets this
      h.finish()
  }
  

  Measured impact: the same search feature set went from −107.5 Elo to +470.4 Elo (21W/3D/0L over 24 games) from this 4-line fix — a ~577 Elo swing. General rule: with any third-party board library, assume its incremental hash may omit side-to-move / en-passant / castling rights, especially for "non-normal move" APIs.
• ⚠️⚠️ PST orientation must be verified numerically, not by eye. Piece-square tables are almost always written visually (row 0 = rank 8 = Black's back rank), but chess's Square::to_index() = rank*8 + file with Rank::First(rank 1) = 0, i.e. a1 = 0. So White needs 63 - idx and Black uses idx — getting it backwards flips the whole table vertically for both colors. This engine had exactly that bug: White pawn on e2 scored +50 and on e7 −20 (rewarding not advancing pawns); White king on e1 −50, on castled g1 −40, but on g8 (deep in enemy camp) +30 (actively marching the king into the opponent's position mid-game). Pawn + king are the two heaviest PST terms, so the engine's entire positional sense was inverted. Test: print pst_val for pawn e2/e4/e7 and king e1/g1/g8 before trusting it — a promoting pawn must outscore a home pawn, and a castled king must outscore an advanced one. Note 63 - idx is a 180° rotation, equivalent to a vertical flip only because these tables are left-right symmetric — verify that before relying on it.
• my-engine prints UCI info to STDERR (eprintln!), bestmove to STDOUT. When scraping engine output, read info from stderr, bestmove from stdout.
• Python env split: torch 2.2.2 is in /usr/bin/python3 (3.9) which lacked chess → python3 -m pip install --user chess. The managed venv has chess+onnxruntime but NO torch. Train with system py3.9; golden-test with venv py3.13.
• match.py MUST run under /usr/bin/python3 (it needs chess; the managed py3.13 at ~/.workbuddy/binaries/python/... does NOT have it). Running it under the managed python dies instantly with ModuleNotFoundError: No module named 'chess'. If launched as a background job with output piped, this failure is completely silent — no result JSON is ever written and the job just vanishes. Always redirect background runs to a log file (> /tmp/x.log 2>&1) and check the log, never a bare pipe. (make_self_teacher.py needs no chess, so managed py3.13 is fine there.)
• Background jobs die when the agent turn ends — and nohup ... & does NOT save them. Backgrounding inside a foreground shell call gets killed when that call returns (symptom: empty log, no traceback, no result JSON). The only reliable way is the Bash tool's own run_in_background: true mechanism, plus a log redirect (> /tmp/x.log 2>&1). Verify liveness with pgrep -fl match.py — ps and top are sandbox-blocked here.
• Long timed matches vs CPU-heavy training: a sleep 120-style poll can be killed (exit 137); poll with short sleeps instead. If a torch training run must overlap a timed match, renice +19 -p <pid> the trainer so the engines keep CPU priority — otherwise both engines search shallower and the measured Elo gap is compressed.
• Label encoding: from*64+to (0..4095). Promotion is NOT encoded (move-gen handles it). Never try to predict promotion as a class.
• Tensor layout (must match Rust policy.rs exactly): (13,8,8), channels P N B R Q K p n b r q k (0..11) + stm plane (12, =1 when Black to move). row0 = rank8.
• policy.bin byte order: c1w(16*13*9) c1b(16) c2w(16*16*9) c2b(16) f1w(64*1024) f1b(64) f2w(4096*64) f2b(4096), each C-order .ravel(), float32 little-endian. Total = 1,344,192 bytes (336,048 params). Mismatch ⇒ Rust load returns None silently.
• The golden test does NOT cover the Rust FEN→tensor path. policy_golden_test.py builds the input with its own Python fen_to_flat and feeds it to both the Python replica and ONNX — so it proves the weights + layer math, never the real policy.rs encoder. A mismatch between policy.rs::predict and train_policy.py::fen_to_tensor would pass the golden test while the live engine feeds the net garbage. Verify by hand. Audited 2026-08-12 and currently consistent: channels P N B R Q K p n b r q k (0..11); board row0 = rank8 (Rust uses rank_i = 7 - rank.to_index()); plane 12 = 1 iff Black to move; labels from*64+to with a1 = 0 (uci_to_label == pack_move). Note the tensor is rank-flipped (row0=rank8) while labels are not (a1=0) — a deliberate asymmetry that is fine because both sides apply it identically; don't "fix" one alone.
• Policy only biases move ORDERING, not the final move — so at shallow depth top-1 move may be identical with/without policy. Measure strength with full matches, not "first move changed".
• Disable policy for ablation: UCI setoption name Policy value false, or run the binary from a dir without policy.bin.
• Never overwrite committed policy.pt/policy.onnx with a toy smoke-test model — train into a temp --data subset then git checkout to restore if you abort.
• UCI harness "engine hang" is almost always a PYTHON bug, not the engine. Two classic traps when driving my-engine over subprocess: (a) blocking proc.stdout.readline() with a "deadline" checked only AFTER the line returns — if the engine is ever slow it blocks FOREVER (the deadline is never reached). (b) never draining stderr during a search — the engine writes info lines to stderr; once the OS 64KB pipe fills, the engine blocks on its own eprintln! → true deadlock that looks exactly like an engine infinite loop. Robust pattern: run a background thread that continuously reads (and discards) stderr; read bestmove via a dedicated reader thread + threading.Event with a real wall-clock timeout; on timeout, proc.kill() + relaunch and skip the position. Verified: the engine (with 50M node cap + qsearch + depth fix) terminates on every position; all prior "hangs" were this harness bug. See make_self_teacher.py.
• go movetime N without explicit depth was being capped at depth 6 in parse_go (default depth=6, loop stopped there, wasting the rest of the time budget). Fix: when movetime>0 && !has_depth, set eff_depth=64 so iterative deepening uses the full budget.
• quiescence + null-move + PVS + check-extension are the highest-ROI search upgrades. NMP must guard: depth>=3, not-in-check, and skip when the side to move has only K/pawns (zugzwang). PVS: first child full window, rest null window (-alpha-1,-alpha) + re-search on fail-high. Check extension: at the qsearch frontier when in_check, depth=1 (cap ply<48 to avoid runaway). These took startpos from depth 7 → 11 in the same 1s budget.
• An invalid FEN is silently swallowed → your whole test is fake. parse_position does Board::from_str(fen).unwrap_or_default(), so an illegal FEN makes the engine search the start position while still happily printing a bestmove (e2e4/b1c3). Two hand-written probe FENs (k7/8/8/8/8/8/8/K6Q w, 7k/8/8/8/8/8/8/K6Q w) were illegal — the black king was in check with White to move (h1–a8 diagonal / h-file) — and chess 3.2.0 correctly rejected them; only the two engines printing identical output exposed it. Rule: pre-validate every hand-written FEN with chess.Board(fen).is_valid() (python-chess) before feeding it to the engine.
• chess 3.2.0 Board keeps NO move history and NO halfmove clock → an engine built on it is blind to repetition and the 50-move rule unless the UCI layer rebuilds both. Symptoms: it repeats moves away a won game, and never steers into a saving repetition when lost. Fix: parse_position returns (Board, Vec<u64> position keys, u32 halfmove); clear the key list and zero the clock on every irreversible move (capture / pawn move); parse FEN field 4 yourself (the crate drops it). Pass both into search(). Measured on the KQ-vs-K probe: before → cp 99987 (a mate that lies beyond the 50-move boundary, i.e. pure illusion); after → cp 0. Three implementation details that are easy to get wrong: (a) the draw test must run before the check-extension / qsearch transition, or repetitions at the search frontier are invisible; (b) track the ancestor path with self.path.truncate(ply) at node entry instead of paired push/pop — alpha_beta has ~5 return sites and one missing pop makes the path grow without bound. Invariant: on entering a node at ply p, path holds exactly p ancestors; deeper leftovers from a sibling subtree get truncated automatically; (c) disable repetition/50-move scoring inside null-move subtrees (a null_ply counter) — a null move is not a real move, so a "repetition" there is meaningless and injects fake draw scores into NMP cutoffs.
• Aspiration windows: parameterize root_search(alpha, beta) and search [prev-δ, prev+δ] (δ=30, ×3 on fail, full window above ~1200). If you do this you MUST also fix the root TT store — the old code wrote flag=0 (exact) unconditionally, which is a real bug once the root can fail low/high.

Quick Reference

Common Mistakes

• Reading engine info from stdout (gets null scores) — use stderr.
• Augmenting without legality filter (teaches illegal moves).
• Skipping the golden test (deploys a silently-wrong model).
• Judging policy by single-game ply count instead of a matched Elo.

测量方法论（血泪教训，改引擎前必读）

固定深度节点数什么时候能当棋力代理，什么时候不能

实证：LMP+futility 固定深度 9 节点 −60%、WAC 3/4 不变、同时间偶尔 +1 层， 看起来是大胜；96 局实测 Elo −69.7，CI [−134.4, −9.4]，LOS 1.2%，显著变弱，已回滚。 凡是改变搜索走法集合的改动，只能用对局验证。

对局评测框架必须具备的三件事

否则测出来的 Elo 主要是运气（star/match.py 已全部实现）：

1. 开局分散 + 成对对局：不要所有对局都从初始局面开跑——固定 movetime 下引擎差异只来自 时间抖动，等于拿噪声当样本多样性。内置 30 条均衡开局，相邻两局同一开局交换先后手。
2. 并行：--concurrency N。movetime 是每步固定思考时间而非挂钟制，并行不会让谁少想； 8 核跑 4 路安全，吞吐 ~4×。每槽位要有独立的一对引擎实例+工作目录。
3. CI 不能用胜率二项近似（等于假设没有和棋）：对每局得分(1/0.5/0)算样本方差， SE = std/sqrt(n)，并输出 LOS。 效果：同样 ~16 分钟，分辨率从 ±147 Elo（24 局同开局）提升到 ±62 Elo（96 局）。

24 局的 CI 宽达 ±150 Elo —— 这个量级下测出的"+0 Elo"含义是"测不出来"，不是"没效果"。 小改动要么加大局数，要么用等价改写类的节点基准佐证。

已被实测否决的改动（别再重复实现）

• 渴望窗口 (aspiration windows)：PVS + TT 已吃掉收益，失败高低位重搜是净开销。
• SEE 排序降级（SEE<0 的吃子排到安静走法之后）：节点 +14%（open 局面 +57%）。 SEE 只是静态近似，靠后续战术获利的"亏损"吃子被排到最末，一旦它才是最佳着就要在最贵的位置全窗重搜。
• LMP + 前向 futility：见上，−69.7 Elo。

已被实测接受并保留的搜索杠杆（完整 Elo 归因链，逐项隔离）

逐级对比（policy-off 纯搜索、24/96 局 movetime300、交换先后手、CI 报告）：

• qsearch（基线）→ keyfix（TT/key 修复，含 chess 3.2.0 null_move Zobrist 缺陷修复）：+470.4 Elo（零败，决定性）
• → pstfix（PST 上下颠倒修复）：+231.9 Elo（零败，显著）
• → evalv2（tapered 评估+兵形+双象+车线）：+137.0 Elo（勉强显著）
• → rep（重复局面+50步规则检测，正确性缺陷非调参）：保留（24局 +0 实为测不出，SEE 节点−5%/+1层为硬证据）
• → ttage（置换表老化 age 字段）：+10.9 Elo（LOS 64%，不显著但修真实缺陷，保留）
• → histmalus（反证历史：安静走法截断时给先前安静走法 −depth² 惩罚）：+25.4 Elo，96局 CI[−38,+90] LOS 78%（安全类重排序，节点−3%、bestmove 不变，接受）
• 否决：LMP+前向futility（−69.7 Elo）、SEE排序降级（+14%节点）、渴望窗口（无收益）。 准则：改变"哪些走法被搜"的改动只能对局验证；走法排序/TT/静态过滤类可用节点基准佐证。

history malus（反证历史）实现要点

• 在 alpha_beta 循环起点声明 quiets:[u16;64] + nquiet；未截断的安静走法（按 board.piece_on(mv.get_dest()).is_none() 判）在 if alpha>=beta 之后追加记录。
• beta 截断且截断走法是安静走法时，对 quiets[..nquiet] 施加 self.history[qm] = self.history[qm].saturating_sub(depth*depth)。
• 注意：记录必须在截断判断之后（截断走法本身不该被惩罚）；history 数组同时被 policy 注入与 malus 修改，二者在内部节点叠加，不冲突。
• 这是安全类改动：固定深度节点↓ + bestmove 不变即方向正确信号，但仍需对局确认 Elo 方向。

Rust / 沙箱小坑

• gen 是 Rust 2024 保留字，置换表老化的代号字段要命名为 age（或 r#gen）。
• 置换表 store() 的替换策略必须带老化：只判「空槽 or depth >= 已有 depth」会导致 深条目占死槽位（连 key 都不比），后续不同局面的浅条目永远写不进去，一整局命中率持续下降。 正确判据：空槽 or 同 key or 代号不同(陈旧) or depth >= 已有。
• 后台跑长任务不要用 nohup ... &：父 shell 退出后进程被杀（日志只剩表头）。用工具自带的后台执行。
• 本沙箱 ps 不可用（operation not permitted），用 pgrep -fl 查进程。