balatro-seed-search/docs/correctness.md

4.7 KiB

Correctness and limitations

The engine ports Balatro and Immolate RNG constants, item tables, seed iteration, shops, packs, tags, vouchers, bosses, Soul, Wraith, editions, stickers, and standard cards. Tests cover deterministic behavior, pool validity, serial/parallel result ordering, filters, and the CLI.

The friendly find-jokers command searches modeled shop draws, --pack-joker searches Buffoon-pack contents, and --legendary searches Soul resolutions. Jokers produced by Wraith still require the relevant advanced JSON clause. The default any-slot shop search covers the first 16 modeled queue draws.

Shop reference contract

The shop targets the post-1.0.1c pools (1.0.1f reference), with Vampire in Uncommon and Stuntman in Rare. Rarity keys are rarity{ante}{source}, while identity and edition keys put the source before the ante. Hash arithmetic preserves the original operation order; stream state is rounded to 13 decimal places with ties to even, matching decimal formatting of the binary float.

tests/fixtures/shop_reference.json contains 1,024 externally generated card identities, from eight seeds over eight antes and sixteen draws each. The reference is TheSoul commit 780c1c2, configured as version 10106, Red Deck, White Stake, with unrestricted pools. tests/reference/shop_oracle.cpp documents how to reproduce the TSV output against that checkout without executing the Rust implementation. Only display spellings for Driver's License and Mail-In Rebate are normalized in the fixture. The regression covers positive Blueprint results and rejects the old false hit at seed 11111125, ante 2, queue card 4 (Castle).

Search and inspection apply Magic, Nebula, and Zodiac starting vouchers. However, each clause is an independent query: there is no chronological purchase, ownership, deck-enhancement, or unlock-state simulation. Conditional jokers remain in the unrestricted pools, and matching several clauses does not prove they are all obtainable along one gameplay route. This policy matches the fixture's explicit settings, not every online analyzer configuration.

Queue positions do not uniquely identify shop visits. Later visits and rerolls both consume the same ante queue. --max-rerolls is a first-visit cutoff with two cards per shop, not a budget for all visits; it rejects Zodiac Deck. Overstock purchases, tags, and other gameplay changes require a route-aware simulator. Edition voucher effects after purchases are not modeled either.

Shared RNG and pools also affect Buffoon/Wraith contents. Existing Soul and spectral-pack regression fixtures are checked alongside the shop fixtures; passing them is not a claim that every pack on every seed is externally proven.

The regression suite establishes deterministic self-consistency and published-pool sanity. It is not a complete external, bit-for-bit oracle for every Balatro version. Do not treat undocumented game-version behavior as verified parity, and verify important results in the relevant game version.

Deterministic RNG and spectral retries

The engine's random operation is deterministic despite its conventional name. It never reads operating-system entropy or thread-local random state. Each value comes from the run seed plus a named stream key, and repeated calls advance only that key's cached state. Independent instances given the same seed and the same ordered operations therefore produce identical results, including when seeds are evaluated on different Rayon workers.

Spectral packs first use the keyed soul_Spectral{ante} stream for the special The Soul and Black Hole checks. An ordinary spectral draw then selects from 18 slots: 16 cards and two retry sentinels. A sentinel or an already-selected card uses deterministic _resample2, _resample3, and later keys. Retry traversal is capped at 80 attempts, matching the safety budget used by other locked item pools. If that bound is exhausted, the engine picks the first unlocked ordinary spectral in table order. The fallback is deterministic; it exists to guarantee that one pathological seed cannot freeze progress or prevent Ctrl-C handling.

The retry cap is a safety policy, not evidence of full game parity. Seeds that reach it should be retained as explicit regressions and compared with the chosen external version before stronger parity claims are made.

The planned weighted-ranking mode has additional state and obtainability requirements. Its current design and unresolved legality work are tracked in TASK.md; those planned capabilities are not yet CLI features.

See the acceptance record for tested workflows and the search guide for user-facing semantics.