[coderdan]

Summary

Safety gates for the crate's unsafe SIMD code, and the code changes they prompted.

 .github/workflows/
+├── miri.yml        # x86_64 × {avx2, scalar}, default + strict models
+├── sanitizers.yml  # ASan on aarch64: the NEON path Miri can't run
+└── mutants.yml     # cargo-mutants gate, macOS (aarch64) + Ubuntu (x86_64)
+.cargo/mutants.toml # excludes that hold on every arch, timeouts
+scripts/mutants.sh  # per-arch excludes; CI and `mise run mutants` both call it

Miri runs on x86_64 only: it interprets the AVX2 intrinsics but stops at the NEON table lookup (vqtbx1q_u8). ASan covers the NEON path instead. Under cfg(miri) the property tests drop to 16 cases and the brute-force parity sweeps are ignored.

cargo-mutants mutates the PR's changed lines. It sweeps the whole crate instead when the mutants setup changes, or when a src/tests change yields no mutants on its own lines (a rename would otherwise pass without testing anything). cargo-mutants ignores #[cfg], so the per-arch dispatch functions get distinct names and each host excludes the arch it doesn't compile:

-fn encode_into / decode_into      (×3, cfg'd)
+fn encode_into_neon / _avx2 / _portable
+use encode_into_neon as encode_into;   // cfg'd alias; call sites unchanged

NEON decode kernel takes arrays, matching the AVX2 kernel, and is no longer unsafe fn:

-pub(crate) unsafe fn try_decode_block_x4(input: &[u8], out: &mut [u8])
+pub(crate) fn try_decode_block_x4(input: &[u8; 20], out: &mut [u8; 16])

Dispatch loops share one scalar block-and-tail loop instead of four copies:

 decode_into_neon / decode_into_avx2
   while let (Some(in_chunk), Some(out_chunk)) = …   // SIMD chunks
     on kernel error: decode_chunk_by_block   // exact error position
-  scalar block loop + tail                 (copy per path)
+  decode_blocks_from(input, out, in_off, out_off)
 decode_scalar
-  scalar block loop + tail
+  decode_blocks_from(input, out, 0, 0)

Encode is the same shape. Every NEON load and store has a // SAFETY: comment, and the two NEON lookup helpers, which had no preconditions, are safe fns.

Evidence

• Miri (local, x86_64 target): AVX2 and scalar suites pass, no UB. CI also runs the strict models (-Zmiri-tree-borrows -Zmiri-strict-provenance -Zmiri-symbolic-alignment-check).

• ASan, aarch64: full suite clean, locally and in CI.

• Mutants, aarch64 full sweep:
  Before: 6 missed, all in the NEON decode loop guards. decode() sizes out from input, so each guard's two halves were redundant and a broken one went unnoticed.
  After: 115 caught, 0 missed, 12 unviable. decode_into_stays_in_bounds_with_mismatched_buffers checks each bound on its own. The NEON kernel is mutation-tested for the first time (cargo-mutants skips unsafe fn).

• Also missed before, caught now: DecodeError's Display, and the x86 scalar fallback, which an AVX2 runner never reached.

• Excludes (.cargo/mutants.toml), each with its reason:

  • _portable: not compiled on any tested host.
  • The encode tail > 0 → >= 0 mutant: equivalent; no input can tell them apart.
  • The inverted is_x86_feature_detected!("avx2") check: same output on an AVX2 host, so no test can catch it. The Miri scalar job catches it, as a call to a function needing unavailable features.

• Benchmarks (M-series, AC power, main then this branch back to back; the unchanged base85 reference moved up to ±3.5% between runs):

  	16 B	64 B	256 B	1 KiB	1 MiB
  decode	+0.7%	+0.6%	−0.5%	+0.4%	−0.2%
  encode	+6.0%	+1.1%	+2.8%	+0.5%	−1.7%

  The comment that justified open slices claimed fixed arrays cost ~4×. That doesn't reproduce.

Merge Danger

Door: two-way

The public API is unchanged, and any commit can be reverted on its own.

Blast Radius: CI

The new gates can fail future PRs. To make them blocking, mark the two "Mutants gate" checks as required.

[github-actions]

Mutation testing — x86_64 (cargo-mutants, whole crate)

caught	missed	unviable	timeout
108	0	2	0

Every mutant was caught by a test.

[github-actions]

Mutation testing — aarch64 (cargo-mutants, whole crate)

caught	missed	unviable	timeout
115	0	12	0

Every mutant was caught by a test.