[jsgrrchg]

Summary

Raises the Klondike win rate in both draw modes without changing the solver's determinism or its FFI surface. The work started from a profile of Draw 3, which was well below published results, and ended up helping Draw 1 too.

	Draw 3	Draw 1
main (e7fc850), seed 1234, 192 games	65.62%	81.25%
This branch, best 500-game run	70.00% (P5 build)	82.00% seeded / 85.40% unseeded (P7 build)
Thoughtful-Klondike ceiling (Solvitaire)	81.945% ± 0.084%	≈ 90.4%

Six commits, each one self-contained and tested:

Commit	Change	Effect
5f36e39	P1 Real foundation-rollback pruning	+3 wins in both draws (seeded, 192 games)
c0adb90	P2 Stock macro moves ("advance k times and play")	Win rate flat, 5–13% less time
e9bc8a1	P4 Per-draw checkpoint node limits	Draw 3: the P2 time saving reinvested in nodes
8c94017	P5 Incremental Zobrist signature, cheaper move ordering	Identical results, 15–19% less time
5d1337e	Benchmark CSVs for the P5 build
c3e3c74	P7 Failed-bound cache in IDA*	Draw 1 up; time +42%, see open issues

How the problem was diagnosed

A temporary per-chunk trace (not committed) over 24 seeded Draw 3 games showed where the node budget went:

• 26–52% of first-chunk nodes were foundation → column moves, yet solutions averaged 0.17 undos. The FoundationRollback rule that should limit them never pruned anything (details under P1).
• 18–37% of nodes were pure stock advances in Draw 3, up to 56% in Draw 1. Each one re-branched the whole tableau for a state that only differed by stock_index.
• IDA re-expanded the full tree 5–84 times per chunk*, with the bound rising by one almost every iteration.
• About 5 of 25 Draw 3 losses were genuinely unwinnable deals (identical result in Strict mode); the rest were losses on probably-winnable deals.

Changes

P1 — Foundation rollbacks need a visible receiver (5f36e39)

FoundationRollback compared the tableau face-up count before and after returning a card from a foundation. The returned card itself always adds one face-up card, so the rule was a no-op and only MAX_UNDOS limited these moves.

FoundationRollbackNeedsReceiver replaces it and runs in can_prune_early, before apply(). A rollback is explored only when a visible card of rank − 1 and opposite color could then be placed on it: face-up in another column, or the current waste card. Aces never return. A stricter variant (the receiver must also lack any other destination) gave exactly the same results, so the simpler one was kept. Strict mode is unchanged.

Seeded paired runs (seed 1234, 192 games, same node budget):

	Before	After	Flips
Draw 3	126	129	9 won, 6 lost
Draw 1	156	159	4 won, 1 lost

P2 — Stock macro moves (c0adb90)

The stock is now modelled like Klondike-Solver and the K⁺ representation of Bjarnason et al. (2007): there are no pure advance nodes.

• StockDrawToColumn / StockDrawToFoundation { advances, increment, … } offer every waste card reachable in the current pass as one move.
• StockDrawRecycle recycles from any point of the pass.
• Plays of the current waste card and a recycle at the end of the stock stay primitive.
• A macro costs one search node but 1 + advances steps of depth, so MAX_DEPTH and the IDA* g cost keep primitive accounting.
• PRIORITY_DRAW_COST (15 per folded advance) explores nearer waste cards first.
• Paths are expanded back to primitives (expand_stock_macros) before leaving solve_with_stats. apply_move, progress_token and the UniFFI interface are unchanged. lib.rs maps the new variants defensively in case one ever escapes.
• find_candidate_moves now returns the macro view; find_primitive_moves is the derived primitive view used by tests as the UI legality oracle.

It was first gated to Draw 3 behind a flag, then enabled for Draw 1 after measuring, and the flag was removed.

500 games, unseeded	Win rate	Avg time
Draw 3, P1 only	68.60%	6.97 s
Draw 3, P1 + P2	68.20%	6.03 s
Draw 1, before P1 (6 Oct)	81.60%	7.94 s
Draw 1, P1 + P2	82.80%	7.54 s

P4 — Per-draw checkpoint node limits (e9bc8a1)

CHECKPOINT_BASE_LIMITS is split into CHECKPOINT_BASE_LIMITS_DRAW1 (unchanged) and CHECKPOINT_BASE_LIMITS_DRAW3, raised ~13% per bucket (8M → 9M nodes for 19+ hidden cards). This gives back the time P2 saved in Draw 3. CheckpointPolicy::for_draw replaces default_policy. The unused BoardEval::stock_inaccessible field, computed on the hot path and never read, is removed.

Draw 3, 500 games, unseeded: 69.80% at 6.94 s (P2 run: 68.20% at 6.03 s).

P5 — Incremental Zobrist signature and cheaper ordering (8c94017)

The node budget is fixed, so faster nodes mean more search in the same time.

• Zobrist hashing replaces FNV-1a. Keys are generated at compile time from a fixed-seed SplitMix64, so hashes are identical on every platform. Board mutations go through helpers (push_face_up, pop_face_up, reveal_top_if_hidden, set_foundation_rank, set_stock_index, take_waste_card) that XOR only the keys they touch. apply() debug-asserts that the incremental value equals a full recompute. compute_signature() remains for hand-edited boards.
• Move ordering: OrderingContext precomputes once per node which columns bury the next foundation card; the reveal bonus inspects only the source column; the safe-foundation test runs once per candidate.
• Reachable waste positions use a fixed buffer instead of a Vec per node.

Search decisions are unchanged: with seed 777, 24 games per draw produced identical moves, undos, checkpoints and outcomes, with 19% less time in Draw 3 and 15% less in Draw 1.

500 games, unseeded (5d1337e)	Win rate	Avg time	Stalled avg	Won avg
Draw 3	70.00%	5.70 s	7.21 s	5.05 s
Draw 1	81.20%	6.62 s	8.18 s	6.26 s

These two CSVs carry no header comment; their build is inferred from run order and timing.

P7 — Failed-bound cache in IDA* (c3e3c74)

The transposition table stores TtEntry { budget, fail_h }. When the search below a state returns a finite NextBound, the state, and every node of a compressed safe-foundation chain inside it at its own depth, records fail_h = next_bound − depth. tt_verdict returns:

• Explore: not seen, or seen with less budget and no blocking cached bound.
• Skip: the existing budget check.
• Bounded(f): skip the subtree while depth + fail_h exceeds the bound, and report f upward so the bound progression is unchanged.

NextBound(i64::MAX) is never cached because dead ends may depend on the path (cycle checks). The primitive reference search in solver_optimizations_tests.rs mirrors the cache, so the chain-compression equivalence test also validates fail_h.

Draw 1, 500 games	Win rate	Avg time	Stalled avg
P5 build, unseeded	81.20%	6.62 s	8.18 s
P7 build, seeded 1234	82.00%	9.48 s	12.92 s
P7 build, unseeded	85.40%	9.38 s	12.61 s

Draw 3 has not been measured with P7 yet.

Open issues before merging

• P7 raises wall-clock time by ~42% in Draw 1 at the same node budget. Likely cause: children skipped through Bounded are still generated, applied and looked up in the table, but only expanded nodes are charged against the budget. Options: charge Bounded skips as nodes, or lower the node limits until time is back at the P5 level and re-measure. The win-rate gain (81.2% → 82.0–85.4%) is within noise of a 500-game run, so it is not yet clear that P7 pays for its cost.
• Measure Draw 3 with P7, seeded, against the P5 run.
• Most results above are unseeded. From now on all comparisons should use --seed 1234 and be paired game by game.

Compatibility

• Determinism: every change depends only on the board and node counters, never on the clock.
• FFI: solver_core.udl is untouched. Returned paths contain only primitive moves.
• Signatures: hash values changed with Zobrist. They are internal to the search and are not persisted.
• Memory: transposition-table entries grow from one i64 to two. With TT_MAX_ENTRIES = 5_000_000 that is up to ~40 MB more in the worst case; consider lowering it on iOS.
• SolitaireSolver uses its own fork of solver-core-rs with a streaming API (solve_start / solve_next / solve_cancel) that this repository does not have. None of these changes are ported there yet. When porting P2, solve_next_chunk must expand stock macros per chunk, from the chunk's start board, before returning moves.

Rejected

• P3, checkpoint candidates with backtracking. Keeping the top three progress candidates and falling back when the adopted one dies cheaply would recover losses where the checkpoint was a dead end. SolitaireSolver animates each checkpoint as soon as solve_next returns it, so a checkpoint cannot be withdrawn, and a validate-before-deliver variant adds latency and complexity to streaming.

Testing

• cargo fmt --check, cargo test (111 lib + 21 integration tests) and cargo clippy with no new warnings on touched files, at every commit.
• New tests cover: rollback pruning with and without a receiver; macro generation, legality and exact equivalence with primitive steps; macro expansion and replay; depth accounting for folded advances; per-draw node limits; incremental signature sync for every mutation helper; and failed-bound skipping and re-exploration.
• The slow ignored smoke tests were not run as part of this branch.

Follow-ups

• Resolve the P7 time cost, then reinvest the P5 saving into the node limits (+15% Draw 1, +19% Draw 3).
• Write the seed into the configuration section of the TUI CSV so seeded runs are self-describing.
• Update the README win-rate figures once Draw 3 with P7 is measured.
• Remaining ideas: dead-end detection by relaxation (Bjarnason et al. prove 8.56% of deals unwinnable in linear time), transposition entries that dominate across undo counts, canonical column order in the signature, and tuning PRIORITY_DRAW_COST.

References

• C. Blake, I. P. Gent, The Winnability of Klondike Solitaire and Many Other Patience Games (Solvitaire), arXiv 1906.12314 / JAIR 2024. Draw 3: 81.945% ± 0.084%. Draw 1, Table 8: 904,226 winnable of 10⁶.
• R. Bjarnason, P. Tadepalli, A. Fern, Searching Solitaire in Real Time, ICGA Journal 30(3), 2007. Draw 3 thoughtful: 72.3% under 4 s, 78.3% under 16 s, 82.2% unbounded (2007 hardware).
• X. Yan, P. Diaconis, P. Rusmevichientong, B. Van Roy, Solitaire: Man Versus Machine, NIPS 2004. 70.2% with five nested rollouts at 1 h 45 min per game.