gen-mut-model: refuse REF mismatches as NEAT2 did, with a bcftools fix in the error

[joshfactorial]

Behavior decisions from the #819 audit, as chosen by the maintainer. Builds on #823, which edits the same test; merge #823 first, and this PR's diff then shrinks to its own commit.

Versioning: a VCF with any REF mismatch used to build a model and is now refused, and the fitted rate changes for any VCF with edge SNPs. Simulated content is not public API under versioning.md, and this lands in v4.0.0, so no separate bump question arises.

What NEAT2 did (~/code/neat2/utilities/genMutModel.py)

• SNP REF ≠ reference: hard error, exit(1).
• SNP whose context has an N: skipped, and counted nowhere; SNP_COUNT += 1 runs only after every check (line 329).
• Indel REF: never checked.

What eidolon did

• Mismatched SNPs were warned about and skipped, but counted first: snp_count += 1 came before the edge and REF checks, so a skipped SNP still raised snp_freq and mutation_rate. Measured: one good SNP plus one mismatched gave rate 2/13114.
• Indel REFs were never checked.

Now (NEAT2's rule, with a better error)

• Any SNP or indel whose REF disagrees with the reference refuses the fit. NEAT2 exited at the first mismatch; eidolon scans the whole VCF first, so the error gives the SNP and indel counts and the first five positions (H1N1_HA:1000 REF G, reference T).
• The error says how to proceed deliberately: bcftools norm -f reference.fa --check-ref x in.vcf.gz -Oz -o checked.vcf.gz drops the mismatching records. Checked against bcftools 1.19: it kept the matching record and dropped the mismatched one (skipped: 1).
• A SNP at a contig edge has no context. It is left out and no longer counted, matching NEAT2, with a warning. An all-edge VCF still errors (NoUsableSnps).
• A BED that names no reference contig now fails with both contig lists and a chr1 vs 1 hint, instead of Trinuc counts are empty. Unknown error. This only fires when none of the BED's contigs is in the reference. A BED whose regions are all too short keeps the old path, where "check the names" would mislead.
• docs-site/src/models/mutation-model.md describes all of it.

An earlier revision of this PR dropped mismatches with a warning and refused only above 1%. Review replaced that with this rule: it removes an unmeasured constant, and the user drops records explicitly rather than a threshold deciding silently.

Evidence

• Known-answer tests, built from the H1N1 reference itself so every REF is exact:
  • 100 good SNPs give rate exactly 100/13114 (must-not-fire);
  • 100 good + 1 SNP with a wrong REF is refused, naming 1 SNP(s) and 0 indel(s), the position with both bases, and bcftools norm, and no model is written;
  • 100 good + 1 indel with a wrong REF is refused, naming H1N1_HA:80 REF ACG, reference ACA;
  • 100 good + 1 SNP at a contig edge builds with rate still 100/13114 (must-not-fire for the mismatch error);
  • two edge-only SNPs give NoUsableSnps { counted: 2, edge: 2 };
  • an unknown BED contig names chrZ_nonexistent and H1N1_HA.
• The indel-only test's fixture had wrong REFs (H1N1_HA POS 50 is C, 80–83 ACAA). The new check refused it, and the fixture is corrected.
• Mutations, each confirmed applied and caught by exactly the targeted test:
  • removing the mismatch error (warn-and-skip again) fails the SNP and indel refusal tests;
  • never checking indel REFs fails the indel test;
  • moving snp_count += 1 back before the checks fails the edge test;
  • removing the BED guard fails the BED test.
• Full workspace suite (1,100 tests), fmt --check and clippy -D warnings pass locally. model_parity's mutation-model baseline is unchanged.

Not verified

• Not run on a real VCF/reference pair, so how often real VCFs trip the refusal has not been measured.

Refs #819.

🤖 Generated with Claude Code