feat(blueprint): postflop subgame wiring + range expansion (Phase 4, #68)

[amaster97]

Summary

Premium-A Phase 4 (issue #68) — thin Python glue layer that bridges the 169-class preflop blueprint (Phase 1, PR #167 / PR #171) to the postflop range-vs-range Nash solver. The existing chained orchestrator does NOT consume a pre-existing Blueprint asset (it runs its own Stage 1 preflop solve), so this PR adds a separate entry point operating directly on blueprint data — Phase 4 scope is independent of Phases 2 (loader) and 3 (interpolation).

New surface in poker_solver.blueprint_subgame (also re-exported from the top-level package):

• derive_continuation_ranges_from_blueprint: walks a preflop action sequence through the blueprint's history-keyed infosets, multiplying per-class action probabilities to produce per-class reach.
• expand_classes_to_range: 169-class -> 1326-combo expansion (uniform within class), with board-blocker filtering and per-combo weights threaded into a Range.
• solve_postflop_from_blueprint: full pipeline (lookup -> expand -> postflop solve) returning a BlueprintPostflopResult with per-stage wall times.

Scope hygiene

• No engine code modified. No Rust changes.
• No 169-class engine code modified.
• No chained orchestrator (chained.py) modified. Wider refactor (Phase 4 subplan §4 suggests replacing chained.py's Stage 1 with a blueprint lookup) is deferred — out of this phase's scope.
• Phase 4 scope is "verify postflop subgame solver consumes the blueprint as range prior; add wiring if missing". This adds the wiring as a separate entry point so chained.py's behavior stays intact for the Phase A test suite.

Test plan

• tests/test_blueprint_subgame_wiring.py — 15 cases, all passing locally:
  • Range expansion: uniform within class, weight-scaling across classes, board-blocker filtering, error paths.
  • Reach derivation: root reach == 1.0; polarized AA shove (10/90) propagates correct reach; missing-infoset raises clean error; class filtering; bad hero_player rejected.
  • End-to-end on Qs 7h 2d flop: blueprint -> 1326 expansion -> Rust vector-form CFR returns a simplex-valid strategy.
• ruff check clean on new files + __init__.py.
• Existing tests still collect (tests/test_blueprint_pipeline.py 24/24 pass; tests/test_chained_orchestrator.py collects 9 tests, no broken imports).

Wall-time sample

End-to-end blueprint lookup -> 1326 expansion -> postflop subgame solve on a 2-class fixture (AA + KK) on Qs 7h 2d, 30 iterations:

[Phase 4 wall-time] total=0.914s, lookup=0.000s, expand=0.000s, solve=0.914s

Lookup + expansion are pure Python, microsecond-scale. Solve cost dominates (Rust vector-form CFR, dominated by the 30-iter setting). Production iter counts (500-2000) would scale roughly linearly here.

What this unblocks

Phase 5 (top-level routing layer Solver.solve(spot)) can now route postflop spots through solve_postflop_from_blueprint once Phases 2 + 3 land the loader / interpolation. Phase 5 will likely also wrap or replace chained.py's Stage 1 to share the blueprint cache.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

🤖 Generated with Claude Code