balatro-seed-search/TASK.md

35 KiB

Native CLI migration tasks

Each numbered task is one commit. A task is complete only when its checks pass and its checkbox is committed with the implementation. See AGENT.md for the non-negotiable commit and correctness rules.

Current engine inventory

Useful native code to retain:

  • src/{rng,seed,instance,state,derive,items,tables}.rs: deterministic seed and run derivation core.
  • src/filter.rs: serializable filter DSL and compiled operations.
  • src/search.rs: serial and optional Rayon range scanning.
  • src/inspect.rs: target-independent seed inspection and overview data.
  • examples/{verify,bench_throughput,smoke_anyof,smoke_filters}.rs and benches/throughput.rs: regression and performance references.

Known gaps to address:

  • Filter::compile cannot report bad joker/card/boss/tag/voucher names; unknown names are silently hashed and unknown edition/sticker/seal values degrade to sentinel values.
  • The public Searcher only scans fixed chunks and cannot stop after N matches, stream progress, or accept cancellation.
  • The engine models exact antes. Inclusive “before ante” behavior must be built deliberately with nested AnyOf clauses.

Tasks

  • 0. Record the migration contract and work plan. Add AGENT.md and this task list after inspecting the repository.

    • Checks: review paths and commands against the current tree; git diff --check.
    • Commit: docs: plan native CLI migration.
  • 1. Establish a native CLI binary and dependency boundary.

    • Add a balatro-seed-search binary in the Rust crate.
    • Add a maintained argument parser and error-reporting dependencies.
    • Introduce command skeletons for find-jokers, search, inspect, and list, with useful --help and version output.
    • Define shared run/search options: deck, stake, seed length, start rank, maximum seeds, maximum matches, threads, progress interval, and output format.
    • Checks: rustfmt --check on the new binary; cargo check --all-targets; CLI help smoke tests. (The imported engine is not globally rustfmt-clean; avoid mixing its mechanical reformat into this task.)
    • Commit: cli: scaffold native commands.
  • 2. Add validated, discoverable engine inputs.

    • Add canonical case-insensitive parsers for jokers, editions, stickers, tags, bosses, vouchers, cards, decks, stakes, and relevant standard-card fields.
    • Return structured errors for unknown names and suggest close canonical names.
    • Replace silent filter compilation fallbacks with a checked compile API; preserve an explicitly named unchecked/internal path only if benchmarks need it.
    • Power list from Rust tables so shell users can discover accepted values.
    • Validate ante, slot, pack, seed-length, score, rank, and count bounds.
    • Checks: parser/validation unit tests; cargo test --all-targets.
    • Commit: engine: validate search inputs.
  • 3. Implement the friendly joker-before-ante query.

    • Accept repeated --joker arguments and --before-ante Z (inclusive).
    • For each joker, compile exact-ante shop clauses for 1..=Z under AnyOf. Combine per-joker groups at the top level as strict AND for --mode all. Wrap the groups in a top-level AnyOf for --mode any.
    • Support optional edition/sticker and modeled shop-slot/reroll scope without obscuring the simple default.
    • Print copyable seed, rank, score, and query context.
    • Checks: filter-construction unit tests and end-to-end AND/OR tests using small deterministic ranges.
    • Commit: cli: add joker ante-range search.
  • 4. Make native searches parallel, bounded, and interruptible.

    • Add a native parallel feature and use Rayon by default.
    • Scan in bounded chunks, stream matches, stop at --max-matches or --max-seeds, and handle Ctrl-C cleanly.
    • Report scanned seeds, rate, elapsed time, and match count to stderr so stdout remains pipe-friendly.
    • Ensure thread count 1 and N return identical ordered results for the same bounded range.
    • Checks: serial/parallel equivalence, early-stop tests, release smoke search.
    • Commit: cli: add parallel cancellable search runner.
  • 5. Expose the complete filter DSL and output formats.

    • Implement search --filter PATH and search --filter - for JSON input.
    • Cover every current Clause variant, strict and partial scoring, deck/stake, rank/count bounds, and maximum matches.
    • Add human, JSON Lines, and quiet/seed-only output modes with stable schemas.
    • Add --print-filter to the friendly command so generated advanced filters are reproducible and editable.
    • Checks: one fixture per clause family; JSONL parsing test; stdin test.
    • Commit: cli: expose advanced filter searches.
  • 6. Move seed inspection into the native library.

    • Extract target-independent clause inspection and structured reports into a normal engine module.
    • Implement inspect SEED for a supplied filter and a useful run overview.
    • Keep all frontends on the same report rather than a second implementation.
    • Checks: inspection unit tests and CLI snapshot/shape tests.
    • Commit: engine: expose native seed inspection.
  • 7. Add configuration ergonomics and shell usability.

    • Support a documented config file or saved query format without changing explicit flag precedence.
    • Add shell completions and examples for common AND/OR joker searches.
    • Decide whether a lightweight interactive prompt/TUI adds value. If added, keep it a frontend over the same validated query and runner APIs; never make it the only interface.
    • Decision: JSON filter files are the saved-query format; run options remain explicit CLI flags, and no TUI is added because it would duplicate the complete scriptable interface without exposing additional engine behavior.
    • Checks: saved-query round-trip tests; completion generation smoke tests; interactive behavior tests if applicable.
    • Commit: cli: improve interactive and shell workflows.
  • 8. Document, benchmark, and package the native application.

    • Rewrite the README around native installation and practical examples.
    • Document exact meaning and limitations of shop slots, rerolls, sources, antes, decks, stakes, partial matches, and seed ranges.
    • Add representative release benchmarks and prevent obvious throughput regressions.
    • Provide reproducible release builds for the supported desktop platforms.
    • Checks: all documented commands smoke-tested; cargo test --release --all-targets; cargo clippy --all-targets -- -D warnings.
    • Commit: docs: prepare native CLI release.
  • 9. Remove superseded non-native applications.

    • First confirm the native commands cover all engine capabilities listed in the definition of done.
    • Remove superseded applications, platform-only scripts/dependencies, and stale architecture documentation.
    • Retain or rewrite valuable parity notes, canonical data provenance, and engine validation tools.
    • Simplify crate features and CI/build instructions for a native-only project.
    • Checks: no stale non-native references; clean release build; full tests and clippy; run the verifier on a documented sample size.
    • Commit: chore: remove superseded non-native applications.
  • 10. Final acceptance pass.

    • Build from a fresh checkout using only the documented native toolchain.
    • Demonstrate: one joker before ante Z, two jokers with AND, two jokers with OR, an advanced non-joker filter, JSONL output, bounded parallel search, and seed inspection.
    • Record any remaining engine parity limitations as issues/TODOs, not hidden claims.
    • Checks: full clean build/test/lint suite and acceptance command transcript.
    • Commit: test: complete native CLI acceptance pass.
  • 11. Make the repository a single root Rust package.

    • Move the engine crate to the repository root and keep only the supported CLI as a binary target.
    • Preserve verifier, smoke, probe, and throughput utilities as examples so a release publisher cannot mistake them for distributable applications.
    • Remove the superseded GitHub-specific release workflow and update all documented paths and commands.
    • Checks: cargo test --all-targets --locked; cargo clippy --all-targets --locked -- -D warnings; git diff --check.
    • Commit: refactor: flatten native Rust package.
  • 12. Adopt the rust_realease publishing contract.

    • Add package repository and cargo-binstall metadata matching the release archive layout.
    • Add rust-release.toml and Cross target configuration for the supported Linux and Windows targets.
    • Document release validation and run the publisher's dry-run checks.
    • Checks: full Rust quality gates; rust_realease . --dry-run; metadata and archive-name review.
    • Commit: build: configure rust_realease publishing.
  • 13. Credit the original author.

    • Add a short project description and prominently credit Julie (JupiterianSoul) for all original engine and application work.
    • Preserve the original MIT copyright notice and record the original author in Cargo package metadata.
    • Checks: compare attribution against Git history and LICENSE; cargo metadata --no-deps; git diff --check.
    • Commit: docs: credit original author.
  • 14. Add named-seed prefix searches.

    • Accept --seed-prefix TEXT and --named TEXT on friendly and advanced searches, normalize the prefix, and reject characters outside Balatro's seed alphabet.
    • Generate only fixed-length seeds formed by appending a base-35 suffix to the requested name, with suffix-relative start ranks and bounded ranges.
    • Keep serial and parallel results identical and document examples such as CHAD, SUPER, and CODEX.
    • Checks: prefix/range/validation unit tests; serial/parallel equivalence; CLI smoke search; cargo test --all-targets --locked; strict Clippy.
    • Commit: feat: add named seed searches.
  • 15. Evaluate search acceleration.

    • Benchmark existing single-thread and Rayon search throughput across representative filters and available worker counts.
    • Profile the hot path and evaluate portable or runtime-dispatched SIMD only if a vectorizable bottleneck can preserve bit-for-bit RNG behavior.
    • Implement and test an optimization only when benchmarks demonstrate a meaningful gain; otherwise document why SIMD is intentionally descoped.
    • Checks: deterministic serial/parallel parity; release benchmarks; full tests and strict Clippy.
    • Commit: perf: evaluate native search acceleration.
  • 16. Move to the canonical MadGobblins repository.

    • Change the Git origin to the new SSH repository and update Cargo, cargo-binstall documentation, and rust_realease fallback metadata to the matching public Gitea proxy URL.
    • Checks: inspect fetch/push remote URLs; cargo metadata --no-deps; rust_realease . --dry-run --stop-after metadata; git diff --check.
    • Commit: build: move canonical repository.

Weighted seed ranking plan

The weighted mode is deliberately opinionated and separate from the exact filter DSL. Its initial contract is:

  • score only modeled opportunities in antes 1..=8;
  • score each configured target once, at its highest-scoring legal occurrence;
  • use deterministic integer scores and stable ordering: score descending, then seed rank ascending;
  • default ante multipliers are 100%, 85%, 70%, 55%, 40%, 30%, 20%, 10% for antes 1 through 8;
  • accept non-negative numeric target weights plus the presets REQUIRED, FORBIDDEN, PRIORITY (100), PREFERRED (40), and BONUS (10);
  • REQUIRED is both a hard requirement and a 100-point preference, while FORBIDDEN rejects a seed immediately;
  • default threshold is 100, default retained result count is 50, and both remain configurable;
  • precompute a static maximum-remaining-score table from the query. Per-seed evaluation may stop after ante N when current + maximum_remaining[N] cannot reach the fixed threshold. Do not introduce a moving, result-dependent cutoff in the first version.

Legality is not synonymous with an ante number. The audited upstream rules include these categories, which must be encoded or surfaced as assumptions:

  • Ante 1 excludes Negative, Standard, Meteor, Buffoon, Handy, Garbage, Ethereal, Top-up, and Orbital tags.
  • Bosses unlock in stages: ten at ante 2, The Tooth and The Eye at ante 3, The Plant at ante 4, The Serpent at ante 5, and The Ox at ante 6. Finisher bosses are restricted to ante 8 in this search window.
  • Upgraded vouchers require the corresponding base voucher to have been activated earlier in the run.
  • Cavendish requires Gros Michel to have gone extinct. Stone Joker, Steel Joker, Glass Joker, Golden Ticket, and Lucky Cat require matching deck state.
  • Planet X, Ceres, and Eris require their poker hands to have been discovered.
  • Profile unlocks are distinct from run legality and need an explicit all_profile_unlocks policy rather than being guessed.

The source of record for this audit is Immolate's instance.cl lock/unlock table and functions.cl state transitions. Those upstream comments warn that parts of the lock table were not updated for Balatro 1.0, so implementation must add versioned regression evidence rather than copying the table blindly.

  • 17. Record the weighted-ranking contract and implementation plan.

    • Audit the current engine and upstream legality/state rules, choose explicit initial scoring defaults, and split implementation into independently testable tasks without changing runtime behavior.
    • Checks: review every planned dependency and correctness gate against the current Rust modules; git diff --check.
    • Commit: docs: plan weighted seed ranking.
  • 18. Specify and parse the weighted-search configuration.

    • Add a versioned TOML/JSON schema for run settings, threshold, retained result count, ante multipliers, and weighted targets.
    • Represent target conditions with the same canonical names and source distinctions as the existing filter families: jokers, tags, bosses, vouchers, pack cards, Soul/Wraith results, and standard-card properties.
    • Define the preset grammar above, numeric bounds, duplicate-target behavior, and actionable validation errors. Reject antes outside 1..=8.
    • Checks: schema fixtures; preset/numeric round trips; invalid-name, invalid ante, overflow, and duplicate-policy tests.
    • Commit: feat: define weighted search configuration.
  • 19. Complete and version the legality model.

    • Move pure ante gates into reusable data rather than scattered conditionals, including the ante-1 tag exclusions and complete boss unlock schedule.
    • Model upgraded-voucher reachability through prior base-voucher activation.
    • Classify conditional items (Cavendish, deck-state jokers, discovered-hand planets) as modeled, explicitly assumed, or unsupported; fail validation when a query requires an unsupported path.
    • Add a profile policy, defaulting to all collection unlocks, separately from in-run legality.
    • Record upstream provenance, supported Balatro version, and known gaps in a focused weighted-search design document.
    • Checks: boundary test at every unlock ante; impossible-offer tests; voucher-chain tests; comparison fixtures against the chosen reference.
    • Commit: engine: model weighted search legality.
  • 20. Build a chronological ante observation engine.

    • Derive each seed once and walk antes 1 through 8 in order, exposing a compact observation per ante for shops/rerolls, tags, boss, voucher, packs, special resolutions, and standard cards.
    • Preserve state that affects later legality, especially voucher activation, rather than evaluating each weighted target in an isolated cloned run.
    • Define an explicit obtainability policy for purchases/opened packs; do not claim that every simultaneous offer can be acquired in one real run.
    • Share derivations across targets so adding weights does not repeat the same shop or pack simulation.
    • Checks: observation snapshots; deterministic replay; no duplicate RNG consumption; parity with existing inspection/filter results where scopes overlap.
    • Commit: engine: add chronological ante observations.
  • 21. Implement deterministic weighted scoring.

    • Compile target weights and ante percentages into checked fixed-point integer contributions with no platform-dependent floating-point ordering.
    • Give each target only its best legal occurrence, enforce REQUIRED after its last legal opportunity, and reject FORBIDDEN immediately.
    • Produce an explanation record containing each contribution, matched ante, source, hard-constraint result, and final total.
    • Keep the weighted scorer independent from output and parallel execution.
    • Checks: hand-calculated score fixtures; best-occurrence tests; hard-rule tests; tie and overflow tests; explanation totals equal reported totals.
    • Commit: engine: add weighted seed scoring.
  • 22. Evaluate safe static cutoff pruning.

    • Precompute, once per query, the maximum additional score reachable after each ante, accounting for target legality and custom ante multipliers.
    • Stop a seed only when the bound proves it cannot meet the fixed threshold; never prune from a heuristic estimate.
    • Benchmark pruning disabled versus enabled for low, medium, and high thresholds and for cheap versus pack-heavy targets.
    • Keep the bound only if it provides a meaningful speedup without making the common low-threshold case slower; otherwise retain it as a documented rejected optimization.
    • Checks: pruned/unpruned result equivalence over deterministic ranges; adversarial late-score tests; release benchmark report.
    • Commit: perf: evaluate weighted score pruning.
  • 23. Add bounded parallel ranking and stable aggregation.

    • Reuse the corrected Rayon partitioning and score seeds independently while preserving deterministic results for every thread count.
    • Drop scores below the threshold and maintain a bounded top-N heap per worker instead of storing every passing seed; merge heaps deterministically.
    • Sort final output by score descending and seed rank ascending, including named-seed prefix ranges and cancellation/progress behavior.
    • Checks: serial/parallel equality at 1/2/4 workers; heap versus exhaustive reference results; tie ordering; memory-bound test; Ctrl-C smoke test.
    • Commit: engine: rank weighted results in parallel.
  • 24. Expose the opinionated weighted CLI workflow.

    • Add a dedicated rank --config PATH command, with stdin support, rather than overloading exact search semantics.
    • Support human summary, JSONL, and seed-only output; include score and a machine-readable contribution breakdown in ranked formats.
    • Add rank-seed SEED --config PATH (or an equivalent inspect mode) so one seed's score can be explained without scanning a range.
    • Generate an example configuration showing numeric values and every preset, default ante weights, threshold, and top-N behavior.
    • Checks: CLI parsing; config/stdin tests; output schema tests; shell completion smoke tests; end-to-end ranked fixture.
    • Commit: cli: add weighted seed ranking.
  • 25. Benchmark and accept weighted search.

    • Measure one-thread and multi-thread throughput for joker-only, mixed, and pack-heavy weighted configurations, including pruning effectiveness.
    • Demonstrate all presets, custom numeric and ante weights, hard exclusions, required late-unlock items, named seeds, deterministic ordering, and score explanation.
    • Document the opinionated acquisition/profile assumptions and clearly list unsupported conditional paths; do not present offer scoring as a complete playthrough simulator.
    • Checks: release tests and strict Clippy; verifier sweep; acceptance transcript; clean rust_realease metadata dry run.
    • Commit: test: accept weighted seed ranking.
  • 26. Clean up the repository README.

    • Keep verified prerequisites, source build, one deterministic quick start, documentation navigation, attribution, license, and support in the README.
    • Move advanced searching, JSON filters, correctness, development, and release details into focused documentation pages without losing content.
    • Verify the canonical owner/project/default branch and do not add badges while no tracked CI pipeline generates or publishes them.
    • Checks: exercise the documented build and quick start from a clean export; check local links and Markdown structure; inspect all three public badge endpoints; git diff --check.
    • Commit: docs: streamline project README.
  • 27. Add randomized search starting ranks.

    • Add --random-start to friendly and advanced searches, mutually exclusive with an explicit --start-rank.
    • Choose one random logical rank per invocation, report it for reproducibility, and wrap at the end of ordinary, prefix, or named-substring spaces without visiting a seed twice.
    • Preserve bounded cancellation, stable within-chunk ordering, and identical serial/parallel results for a resolved starting rank.
    • Checks: CLI conflict test; deterministic injected-rank wrap tests; prefix and named-substring coverage; full tests and strict Clippy; release smoke searches.
    • Commit: feat: randomize search starting rank.
  • 28. Correct Balatro 1.0.1f Soul and pack derivation.

    • Model compound type/type/ante RNG nodes for Soul, Black Hole, and related special-card rolls instead of substituting the pack source.
    • Use the simple Joker4 node for legendary identity and force the first generated ante-1/2 shop pack to Buffoon, matching current Immolate rules.
    • Add ALEEB as a regression fixture proving Soul resolves to Canio.
    • Checks: focused derivation tests; full tests; strict Clippy; git diff --check.
    • Commit: fix: match current Soul and pack RNG.
  • 29. Add friendly legendary-joker search shortcuts.

    • Accept repeatable --legendary NAME targets in find-jokers, alone or alongside shop --joker targets under the existing all/any modes.
    • Generate Soul clauses through the inclusive ante limit using the modeled four ante-1 packs and six later-ante packs.
    • Validate against only the five legendary jokers and expose the option in help, completions, search documentation, and CLI regression tests.
    • Checks: generated-filter tests; ALEEB CLI smoke search; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: add legendary joker shortcuts.
  • 30. Complete website-backed Soul regression repair.

    • Snapshot exact public analyzer outcomes as offline fixtures, with source URLs and capture dates, so the test suite never depends on network access.
    • Cover repeated Souls in one ante, later-ante pack initialization, Arcana and Spectral Souls, and all five legendary jokers across published seeds.
    • Make search and inspection traverse the same pack/Soul sequence and report a later matching Soul instead of stopping at the first non-matching Soul.
    • Checks: website fixture integration tests; focused derivation, search, and inspection tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: fix: complete Soul regression coverage.
  • 31. Add a Jenkins CI pipeline.

    • Add a declarative pipeline with explicit checkout and worker-tool validation, using no unconfirmed installation-specific labels or paths.
    • Run the documented release tests, strict Clippy gate, engine verifier, and release build before archiving the validated native binary with a fingerprint.
    • Report Gitea checks without allowing a notification error to conceal the original build result; do not publish releases or use credentials.
    • Document worker requirements, local equivalents, the archived artifact, non-publication policy, and generic Gitea webhook setup.
    • Checks: all Jenkins shell commands locally; missing-tool and missing-output failures; Jenkins declarative syntax when a linter is available; archive scope and secret scan; git diff --check.
    • Commit: ci: add Jenkins pipeline.
  • 32. Add a guided JSON filter builder (superseded by task 34).

    • Add create-filter with interactive stdin or --input PATH answer streams, JSON stdout or --output PATH, and explicit --force replacement.
    • Prompt for every implemented clause family and all/any/score top-level matching while reusing canonical name and filter validation.
    • Keep prompts on stderr so generated JSON can pipe directly into search; update completions and focused filter documentation.
    • Checks: every-clause builder test; invalid-name retry and truncated-input tests; stdout pipe and protected-file CLI smoke tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: add guided filter builder.
  • 33. Add per-target joker and legendary ante ranges.

    • Accept inclusive NAME:MIN-MAX suffixes on repeatable --joker and --legendary, including omitted lower bounds and ante-8 open upper bounds.
    • Keep unsuffixed targets on the existing --before-ante behavior and allow every repeated target to carry an independent range.
    • Add native JSON shop_joker_in_range and soul_in_range clauses that compile to one logical any-of clause and work in search and inspection.
    • Checks: range parser/serde edge cases; CLI parsing and generated JSON; compiled-filter and known-seed search/inspection regression; full tests; strict Clippy; release build; git diff --check.
    • Commit: feat: add per-target ante ranges.
  • 34. Make create-filter refine normal CLI targets.

    • Replace the guided answer stream with the same joker/legendary target, range, ante, mode, edition, sticker, and slot flags as find-jokers.
    • Share one query argument model and filter generator so searching and JSON creation cannot drift; retain stdout/file output and overwrite protection.
    • Remove the superseded interactive builder and update completions and docs around the flag-based workflow.
    • Checks: exact requested CLI example; stdout and file JSON round trips; overwrite protection; full release tests; strict Clippy; release build; git diff --check.
    • Commit: fix: align filter creation with joker CLI.
  • 35. Improve bounded-search progress feedback.

    • Replace periodic counters with a terminal-aware progress bar showing the effective seed range, percentage, matches, compact rate, and ETA while retaining clean line-oriented output when standard error is redirected.
    • Accept case-insensitive K and M suffixes for --max-seeds and use compact k/s rate formatting above 1,000 seeds per second.
    • Checks: parser and progress-format unit tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: improve search progress feedback.
  • 36. Add complete seed-size search ranges.

    • Add --seed-size N as an alternative to manually pairing seed length and maximum count, deriving the complete exact-length range as 35^N.
    • Reject range and naming controls that would make the complete-range promise ambiguous, and retain the independent match limit for optional early exit.
    • Checks: CLI parsing and conflict tests; derived range test; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: add complete seed-size ranges.
  • 37. Polish the live search display.

    • Replace the basic block meter with a smooth fractional Unicode bar and a compact dashboard layout for progress, range, rate, ETA, and matches.
    • Add terminal-only color with NO_COLOR support while keeping redirected progress logs free of ANSI control sequences.
    • Checks: progress-format unit tests; redirected-output smoke test; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: polish live search display.
  • 38. Soften the progress color palette.

    • Use a neutral blue active state and muted green completion state without bold terminal styling, preserving NO_COLOR and ANSI-free log output.
    • Checks: full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: soften progress colors.
  • 39. Randomize complete seed-size searches.

    • Allow --random-start and reproducible --start-rank with --seed-size, wrapping once so the full exact-length space remains covered without duplicate candidates.
    • Retain and explicitly document random starts in named-seed candidate spaces.
    • Checks: CLI combination tests; deterministic seed-size and named-space wrap tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: randomize seed-size searches.
  • 40. Explain where matched conditions occur.

    • Add --explain to friendly and advanced searches, reusing native seed inspection to show each condition's first useful ante/shop/pack location.
    • Keep friendly any targets separate in analysis, add condition labels to inspection reports, and embed the same structured report in JSONL output.
    • Preserve seed-only output as a strict one-seed-per-line format and document the existing single-seed JSON inspection equivalent.
    • Checks: inspection and output-schema tests; human and JSONL smoke searches; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: explain matched condition locations.
  • 41. Add boxed pretty output.

    • Add --output pretty as a fourth output mode with padded Unicode match cards, bounded line wrapping, and an optional explanation section.
    • Support the same format for filtered seed inspection and ante overviews, while retaining compact human, JSONL, and seed-only contracts.
    • Checks: box shape/wrapping and CLI parsing tests; search and inspect smoke output; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: add boxed pretty output.
  • 42. Prevent false Soul and Black Hole pack draws.

    • Keep The Soul and Black Hole discoverable as spectral cards, but exclude them from the ordinary spectral fallback pool so they can only appear through their dedicated special-card rolls.
    • Add FMQNT regression coverage for the two ante-2 Jumbo Spectral Packs and prove legendary searches no longer report their former false matches.
    • Checks: focused derivation and public regression tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: fix: prevent false Soul pack draws.
  • 43. Bound spectral retry sentinel traversal.

    • Prevent a pathological spectral retry stream from trapping a worker inside one seed indefinitely and thereby delaying progress and Ctrl-C handling.
    • Preserve normal retry behavior, then use a deterministic unlocked spectral fallback only after the same safety bound used by ordinary pool resampling.
    • Add the reproducing seed 1116RBCP as a single-seed Soul regression.
    • Checks: reproducer test; bounded serial and parallel gud.json searches; full tests; strict Clippy; release build; git diff --check.
    • Commit: fix: bound spectral pack retries.
  • 44. Document deterministic spectral retry behavior.

    • Explain that Instance::random is a deterministic, stateful keyed stream rather than an operating-system or thread-local random source.
    • Document the spectral special-card rolls, ordinary retry sentinels, retry key sequence, safety bound, and deterministic fallback in code and the correctness guide.
    • Add independent-run coverage for the pathological retry seed.
    • Checks: focused determinism test; full tests; strict Clippy; release build; git diff --check.
    • Commit: docs: explain deterministic spectral retries.
  • 45. Finish worker teardown before reporting completion.

    • Drop the custom Rayon pool before rendering the final done state so the interface cannot claim completion while worker threads are still alive.
    • Make the progress display restore its terminal line during unwinding or an early return as well as on the normal path.
    • Checks: repeated redirected and pseudo-terminal completion stress; Ctrl-C smoke test; full tests; strict Clippy; release build; git diff --check.
    • Commit: fix: complete worker teardown before exit.
  • 46. Add a shop-reroll cutoff.

    • Add --max-rerolls 0..=7 to joker searches and filter creation, using two opening-shop cards plus two new cards for each permitted reroll.
    • Keep --slot as a mutually exclusive low-level draw-position option and document its mapping to opening-shop and reroll cards.
    • Expand reroll cutoffs into existing exact-slot clauses so saved filters, search, and inspection share one meaning without a new engine sentinel.
    • Checks: CLI conflicts and filter-shape tests; search/inspection equivalence; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: add shop reroll cutoff.
  • 47. Repair audited shop generation.

    • Correct rarity key ordering, post-1.0.1c joker pools, and shared hash and decimal rounding semantics; initialize starting deck vouchers consistently.
    • Describe shop positions as queue draws with conditional reroll locations. Preserve isolated-query semantics and document unmodeled purchase state.
    • Add external shop fixtures and false-Blueprint regressions; retain Soul and pack regressions. Checks: full tests, strict Clippy, release build, reference comparison, CLI smoke tests, and git diff --check.
    • Commit: fix: align shop generation with reference RNG and pools.
  • 48. Prepare patch release 0.1.1.

    • Bump package and lockfile versions and write release notes.
    • Checks: locked release build and version output, strict Clippy, release tests, publisher metadata inspection, and git diff --check.
    • Commit: release: prepare v0.1.1.
    • Publish the matching tag and configured Linux/Windows artifacts with the repository's rust_realease workflow after preparation passes.
  • 49. Search Buffoon packs for jokers.

    • Add repeatable --pack-joker NAME[:MIN-MAX] targets to find-jokers and create-filter, with the existing all/any and explanation behavior.
    • Keep shop-only modifiers scoped to --joker, and document the modeled per-ante pack limits and source distinction.
    • Checks: CLI/filter-shape and end-to-end tests; full tests; strict Clippy; release build; git diff --check.
    • Commit: cli: find jokers in booster packs.