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}.rsandbenches/throughput.rs: regression and performance references.
Known gaps to address:
Filter::compilecannot 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
Searcheronly 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
AnyOfclauses.
Tasks
-
0. Record the migration contract and work plan. Add
AGENT.mdand 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.
- Checks: review paths and commands against the current tree;
-
1. Establish a native CLI binary and dependency boundary.
- Add a
balatro-seed-searchbinary in the Rust crate. - Add a maintained argument parser and error-reporting dependencies.
- Introduce command skeletons for
find-jokers,search,inspect, andlist, with useful--helpand 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 --checkon 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.
- Add a
-
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
listfrom 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
--jokerarguments and--before-ante Z(inclusive). - For each joker, compile exact-ante shop clauses for
1..=ZunderAnyOf. Combine per-joker groups at the top level as strict AND for--mode all. Wrap the groups in a top-levelAnyOffor--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.
- Accept repeated
-
4. Make native searches parallel, bounded, and interruptible.
- Add a native
parallelfeature and use Rayon by default. - Scan in bounded chunks, stream matches, stop at
--max-matchesor--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.
- Add a native
-
5. Expose the complete filter DSL and output formats.
- Implement
search --filter PATHandsearch --filter -for JSON input. - Cover every current
Clausevariant, 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-filterto 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.
- Implement
-
6. Move seed inspection into the native library.
- Extract target-independent clause inspection and structured reports into a normal engine module.
- Implement
inspect SEEDfor 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.tomland 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.
- Add a short project description and prominently credit Julie
(
-
14. Add named-seed prefix searches.
- Accept
--seed-prefix TEXTand--named TEXTon 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, andCODEX. - 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.
- Accept
-
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_realeasefallback 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.
- Change the Git origin to the new SSH repository and update Cargo,
cargo-binstall documentation, and
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), andBONUS(10); REQUIREDis both a hard requirement and a 100-point preference, whileFORBIDDENrejects a seed immediately;- default threshold is
100, default retained result count is50, 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_unlockspolicy 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
REQUIREDafter its last legal opportunity, and rejectFORBIDDENimmediately. - 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 PATHcommand, with stdin support, rather than overloading exactsearchsemantics. - 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.
- Add a dedicated
-
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_realeasemetadata 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-startto 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.
- Add
-
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
Joker4node for legendary identity and force the first generated ante-1/2 shop pack to Buffoon, matching current Immolate rules. - Add
ALEEBas 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 NAMEtargets infind-jokers, alone or alongside shop--jokertargets 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;
ALEEBCLI smoke search; full tests; strict Clippy; release build;git diff --check. - Commit:
cli: add legendary joker shortcuts.
- Accept repeatable
-
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-filterwith interactive stdin or--input PATHanswer streams, JSON stdout or--output PATH, and explicit--forcereplacement. - 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.
- Add
-
33. Add per-target joker and legendary ante ranges.
- Accept inclusive
NAME:MIN-MAXsuffixes on repeatable--jokerand--legendary, including omitted lower bounds and ante-8 open upper bounds. - Keep unsuffixed targets on the existing
--before-antebehavior and allow every repeated target to carry an independent range. - Add native JSON
shop_joker_in_rangeandsoul_in_rangeclauses 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.
- Accept inclusive
-
34. Make
create-filterrefine 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.
- Replace the guided answer stream with the same joker/legendary target,
range, ante, mode, edition, sticker, and slot flags as
-
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
KandMsuffixes for--max-seedsand use compactk/srate 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 Nas an alternative to manually pairing seed length and maximum count, deriving the complete exact-length range as35^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.
- Add
-
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_COLORsupport 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_COLORand ANSI-free log output. - Checks: full tests; strict Clippy; release build;
git diff --check. - Commit:
cli: soften progress colors.
- Use a neutral blue active state and muted green completion state without
bold terminal styling, preserving
-
39. Randomize complete seed-size searches.
- Allow
--random-startand reproducible--start-rankwith--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.
- Allow
-
40. Explain where matched conditions occur.
- Add
--explainto friendly and advanced searches, reusing native seed inspection to show each condition's first useful ante/shop/pack location. - Keep friendly
anytargets 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.
- Add
-
41. Add boxed pretty output.
- Add
--output prettyas 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.
- Add
-
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
FMQNTregression 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
1116RBCPas a single-seed Soul regression. - Checks: reproducer test; bounded serial and parallel
gud.jsonsearches; full tests; strict Clippy; release build;git diff --check. - Commit:
fix: bound spectral pack retries.
-
44. Document deterministic spectral retry behavior.
- Explain that
Instance::randomis 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.
- Explain that
-
45. Finish worker teardown before reporting completion.
- Drop the custom Rayon pool before rendering the final
donestate 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.
- Drop the custom Rayon pool before rendering the final
-
46. Add a shop-reroll cutoff.
- Add
--max-rerolls 0..=7to joker searches and filter creation, using two opening-shop cards plus two new cards for each permitted reroll. - Keep
--slotas 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.
- Add
-
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_realeaseworkflow after preparation passes.
-
49. Search Buffoon packs for jokers.
- Add repeatable
--pack-joker NAME[:MIN-MAX]targets tofind-jokersandcreate-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.
- Add repeatable