feat(engine): 169-class abstraction mode + blueprint generation pipeline (Phase 1, #68)

[amaster97]

Summary

Phase 1 of the Premium-A subplan (docs/premium_a_blueprint_subplan.md, task #68). Ships the offline preflop blueprint generation pipeline + asset format design, ahead of the Phase 1.5 overnight compute (27 cells = 9 depths x 3 ante configs).

Path taken

Hybrid Path B per the task brief's escape clause. The Rust engine continues to run the 1326-combo vector-form CFR; the pipeline post-aggregates each infoset's strategy into a 169-class strategy via uniform combo-weighted average within each class.

This is lossless within the engine's existing suit-variant approximation (the 169x169x3 equity table already integrates suit overlap). True Path B (169-vector inner loop) requires building an "effective" 169x169 leaf table that integrates blocker-respecting combo weights per class pair — a 1-2 day Rust refactor that does not fit the 4 hour Phase 1 budget. The asset schema is forward-compatible with that follow-up.

What this PR delivers

1. poker_solver/blueprint.py (965 LOC) — Blueprint + BlueprintConfig + Manifest dataclasses, gzipped JSON asset format, combo-weighted aggregation, label reconstruction, validator. Ships HandResolution enum (COMBO_1326 / CLASS_169) as the forward-compatible switch.
2. scripts/generate_preflop_blueprint.py (280 LOC) — CLI driver with single-cell + batch (--all-depths --all-antes) modes, idempotent resume, progress logging + ETA, --dry-run for pipeline validation.
3. tests/test_blueprint_pipeline.py (24 tests) — schema round-trip, aggregation correctness, label reconstruction, validator catches malformed data, manifest round-trip, filename canonicalization (3 ante configs), CLI dry-run smoke, idempotent resume.
4. docs/blueprint_generation.md — operator guide.
5. Asset format: preflop_169class_{depth}bb_{ante}.json.gz shards + manifest.json. Per-shard sha256 over uncompressed JSON (reproducible).

Smoke test result

100 iters at depth 40, no ante (on M4 Pro arm64):

Metric	Value
Wall time	18.3 s
Infosets	150
Strategy rows	25,350 (150 x ~169 classes)
Compressed size	672 KB
AA fold rate at root	0.0 (correct)
72o fold rate at root	0.9999 (correct)
Validator warnings	0

Phase 1.5 estimate (extrapolated from smoke)

• 25K iters ≈ 75-90 min per cell
• 27 cells single-threaded ≈ 34-40 h wall
• Parallelizable across two terminals ≈ 17-20 h wall
• Compressed total: ~30-60 MB (within 90 MB target)

Test plan

• pytest tests/test_blueprint_pipeline.py — 24 PASS
• pytest tests/test_preflop_rvr_diff.py — 4 PASS (existing engine, unchanged)
• pytest tests/test_kuhn_dcfr tests/test_leduc_dcfr tests/test_dcfr_diff — 16 PASS
• ruff check — clean
• ruff format --check — clean
• mypy poker_solver/blueprint.py — clean (0 errors; pre-existing 6 errors on cli.py/chained_tab.py are not from this PR)
• cargo clippy --lib --tests — clean (pre-existing 2 bench errors on main are not from this PR)
• Live end-to-end engine smoke (scripts/generate_preflop_blueprint.py --depth 40 --ante none --iterations 100) — PASS

NOT in this PR

• Phase 1.5 (the actual 27-cell overnight compute) — user runs on terminal
• True 169-vector engine inner loop (follow-up for per-iter speedup)
• Phase 2 loader API + Phase 4 postflop anchoring (separate PRs)

Risks

• R1 (wrapper-aggregation accuracy) — wrapper aggregation is lossless within the engine's 3-variant equity approximation; divergence against a true 169-vector engine at deep-cap depths should be measured before any cross-solver strict gate locks (Phase 7).
• R2 (Phase 1.5 wall-time estimate) — extrapolated from 100-iter smoke; may be ~10-20% high if DCFR discount cost amortizes per iter.
• R3 (label reconstruction) — mechanical-replay-based; if the engine adds new action paths the wrapper's fallback a{idx} labels preserve schema validity but lose readability.

References

• Subplan: docs/premium_a_blueprint_subplan.md
• Engine: crates/cfr_core/src/preflop_rvr.rs
• Equity table: assets/preflop_equity_169x169.npz
• Prerequisite: PR fix(engine): preflop State::initial honors config.initial_contributions (#67) #165 (cs-bug fix docs: surface pyenv x86_64 vs arm64 .so arch hazard for devs #67) — MERGED on origin/main (43ed53e)

Generated with Claude Code