feat(simd_avx2): add U8x32 — native AVX2 byte vector (round-3 keystone)

[AdaWorldAPI]

Summary

Round-3 W1 (foundation) — adds U8x32, the native AVX2 byte vector type that the round-2 audit fleet (agent #11) identified as the keystone gap. Without it, the 8 cosmetic-SIMD wrappers in hpc/byte_scan.rs, hpc/palette_codec.rs, and hpc/aabb.rs (#[target_feature(enable = "avx2")] decorating scalar bodies) couldn't be rewritten to use the polyfill — there was no type to call.

This PR ships the type + 26 methods + 18 regression tests. The consumer rewrites (cosmetic-SIMD sweep) ship in a follow-up fleet of PRs.

API surface

U8x32 mirrors simd_avx512::U8x64 at the natural AVX2 width (32 bytes = one __m256i):

use ndarray::simd::U8x32;

let v = U8x32::splat(0xAA);                 // 32 lanes
let mask = v.cmpeq_mask(other);             // → u32 (one bit per lane)
let blend = U8x32::mask_blend(mask_v, a, b); // MSB-driven select
let counts = lut.shuffle_bytes(idx);        // nibble popcount via LUT

Category	Methods
Constructors	splat, from_slice, from_array, to_array, copy_to_slice
Reductions	reduce_sum (wrap-add), reduce_min, reduce_max, sum_bytes_u64
Min/max	simd_min, simd_max
Compare → mask	cmpeq_mask → u32, cmpgt_mask → u32, movemask → u32
Saturating	saturating_add, saturating_sub
Avg	pairwise_avg (round-up, _mm256_avg_epu8)
Shifts	shr_epi16, shl_epi16 (16-bit lane shifts)
Shuffles	shuffle_bytes (within-lane), permute_bytes (cross-lane scalar fallback), unpack_lo_epi8, unpack_hi_epi8
Conditional	mask_blend (MSB-driven, NOT bitmask — distinct from U8x64::mask_blend)
LUT	nibble_popcount_lut
Operators	BitAnd, BitOr, BitXor, Add (wrap), Sub (wrap), Debug, Default

Design notes

Real __m256i storage, not scalar fallback. The existing simd_avx2::U8x64 uses scalar [u8; 64] because 64 bytes doesn't fit one ymm register — it's a polyfill-shape compatibility type. U8x32 is the real AVX2 byte vector; consumers wanting actual AVX2 SIMD speedup over scalar should iterate in 32-byte chunks via U8x32.

Soundness model matches the file's existing pattern: _mm256_* intrinsics are wrapped in unsafe { } inside safe pub fn, trusting AVX2 at compile time (project baseline is x86-64-v3 per the .cargo/config_ndarray_simd.toml template on the bevy side). The existing simd_avx2.rs:357 AVX2 popcount uses this same pattern.

permute_bytes cross-lane fallback is scalar. AVX2 has no native cross-lane byte permute (_mm256_permutexvar_epi8 is VBMI/AVX-512). Matches the shape of simd_avx512::U8x64::permute_bytes on AVX-512F-without-VBMI hosts (also scalar — landed in PR #142).

mask_blend differs from U8x64's: AVX-512 uses 64-bit bitmasks; AVX2's _mm256_blendv_epi8 is MSB-driven on a 32-byte mask vector. The signature reflects this (Self, Self, Self not u64, Self, Self).

Re-exports

U8x32 is re-exported from crate::simd::* on both AVX-512 and AVX2 build tiers — it's the natural AVX2 byte width and useful regardless of whether AVX-512's U8x64 is the consumer's preferred width.

Test plan

• 18 new tests in mod u8x32_tests covering all behavior (constructors, reductions, masks incl. unsigned high-byte cases > 127, saturating clamps, pairwise_avg round-up, nibble shifts, permute, blend, LUT)
• All 18 pass
• Total test count: 1786 → 1804, no regressions
• cargo clippy --features rayon -- -D warnings: clean
• cargo check --features rayon --lib: clean

What follows

The cosmetic-SIMD consumer-rewrite fleet — 12 Sonnet agents, each scoped to ONE function in hpc/byte_scan.rs / hpc/palette_codec.rs / hpc/aabb.rs, rewriting from #[target_feature]+scalar to crate::simd::U8x32::* calls. Will land as separate PRs after this one merges.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b538025f26

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve U8x64 blend argument order

U8x64::mask_blend(mask, a, b) and the scalar fallback select b when the mask bit is set, but this AVX2 implementation passes the operands to _mm256_blendv_epi8 in the opposite order, so set mask lanes return a. Any consumer porting code from the existing U8x64 API or feeding a comparison mask as a predicate will get the inverse result on every selected byte; call _mm256_blendv_epi8(a.0, b.0, mask.0) instead, or the new type will not mirror the documented API shape.

Useful? React with 👍 / 👎.