[joshfactorial]

Closes #879 (close by hand on merge to develop).

MAJOR change, for v5.0.0. Config keys and their meaning are public API under docs-site/src/reference/versioning.md.

Change

• Both subcommands: the output name key is output_basename. "Prefix" reads as path-plus-prefix in samtools, bwa and STAR; this key is a file name only, joined to output_dir. output_prefix (gen-cancer-reads, and NEAT's name) is refused with `output_prefix` (renamed `output_basename` in v5.0.0).
• Path separators refused: a value containing / or \ is an error naming output_dir. Before, an absolute path silently replaced output_dir and sub/run failed with a bare I/O error.
• gen-reads: output_filename is refused with `output_filename` (removed in v5.0.0; use `output_basename`).
• gen-cancer-reads: its second names are removed, each refused with a message naming the replacement:
  • output_filename → output_basename;
  • coverage → total_coverage;
  • rng_seed_root → rng_seed.
• filter-reads: a read named with the pre-v3.0.0 prefix @RNEAT_generated_ is now an error, where it used to be read with a warning. The error names the prefix and gives the sed command that renames it. It must not fall through as an ordinary line: filter_fastq would then drop every read and still exit 0.
• Everything in the repo uses output_basename: Rust tests, templates, README, docs-site, scripts/delta, tools.
• New docs page: Upgrading from 4.x lists each removal, the shuffle default from Shuffle gen-reads FASTQ output by default (shuffle_fastq, #870) #875, and the commands to update configs. The 2.0.0 upgrade page no longer says filter-reads reads the old prefix.

The internal RunConfiguration field is renamed to match. That is not public API.

Evidence

• New tests in config_errors_exit_cleanly.rs: each removed gen-reads and gen-cancer-reads key, and a FASTQ with an RNEAT_generated_ read. Each requires exit 1, no panic, and the replacement named on stderr.

• Mutation checks, each confirmed applied and then restored with cmp:

  mutant	result
  output_filename back in gen-reads' accepted keys	the gen-reads test fails
  separator check disabled in gen-reads	output_basename_with_a_path_separator_is_refused fails
  separator check disabled in gen-cancer-reads	the same test fails
  coverage back in gen-cancer-reads' accepted keys	the cancer test fails
  RNEAT check disabled	the filter-reads test fails

• Unit test: the filter_lib test now requires the RetiredPrefix error.

• Rename tests: output_prefix is refused naming output_basename in both subcommands; sub/run, /abs/run and a\b are each refused in both.

• Must not fire: the whole existing suite now writes output_basename and passes.

• The workspace suite passes: 63 test binaries pass on the last run. Earlier in the branch invoked_name failed once at its copy-and-exec step and passed 3 of 3 on its own and on rerun. Clippy -D warnings and fmt pass.

Not verified

• The scripts/delta and tools edits were checked with bash -n only, not run. Each is a one-word key rename inside a heredoc or printf.
• Windows paths: the check rejects \\ on every platform, so a file name containing a literal backslash is refused on Linux too.
• Configs outside this repo break by design, and gen-cancer-reads configs now break too (output_prefix was its key since before 4.x). The upgrade page has a one-line sed for them.

🤖 Generated with Claude Code