v2 arm: gate simd_avx2's own test modules off v2; document the realizations

A per-test sweep of all 2541 lib tests under qemu -cpu Nehalem found 28
SIGILLs, all in simd_avx2's tests, u8x32_tests and f16_precision_tests,
which call AVX2 intrinsics directly. No library path faulted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011BMJnDBAfzcuQh5HeT39Rh

Author: claude

.claude/plans/simd-sse-v2-tier-v1.md

@@ -30,16 +30,27 @@ goes through `crate::simd`, so the switch is confined to `simd.rs`.
 
 ## Work items
 
-- [ ] P0 TESTS FIRST: `v2-qemu` parity arm (`--config .cargo/config-v2.toml`,
+- [x] P0 TESTS FIRST: `v2-qemu` parity arm (`--config .cargo/config-v2.toml`,
       run under `qemu-x86_64-static -cpu Nehalem`) in `scripts/masking-parity.sh`
       and a `realization/v2` row in `simd-matrix.yaml`, with an objdump witness
       (no AVX instruction at all: no `%ymm`, no VEX `v`-prefixed op). Expect it
       to fail before the arm exists.
-- [ ] P1 `.cargo/config-v2.toml`; `simd.rs` routing; `cpu_guard` floor gated off
+- [x] P1 `.cargo/config-v2.toml`; `simd.rs` routing; `cpu_guard` floor gated off
       the v2 arm.
-- [ ] P2 close the API gap: compile v2, list every missing item, add each to
+- [x] P2 close the API gap: compile v2, list every missing item, add each to
       `simd_scalar.rs` (types `U8x32`, `F32Mask16`, `F64Mask8` and the x86-only
       methods). Safe Rust only.
-- [ ] P3 gates: lib tests on v2 under qemu Nehalem; parity on every arm; clippy
+- [x] P3 gates: lib tests on v2 under qemu Nehalem; parity on every arm; clippy
       v2/v3/v4/avx/baseline; codegen witness avx2/avx512 unchanged.
-- [ ] P4 docs: CLAUDE.md realization list, blackboard, `simd.rs` dispatch comment.
+- [x] P4 docs: CLAUDE.md realization list, blackboard, `simd.rs` dispatch comment.
+
+## Outcome (2026-10-10)
+
+- Per-test sweep: all 2541 v2 lib tests, each run as its own process under
+  `qemu-x86_64-static -cpu Nehalem`. 28 faulted with SIGILL, every one in
+  `simd_avx2`'s own test modules (`tests`, `u8x32_tests`,
+  `f16_precision_tests`), which call AVX2 intrinsics directly. No library
+  path faulted. Those three modules are now gated off the v2 arm.
+- Open: `crate::simd_avx2` stays public on v2 builds and has no startup
+  check there, so a direct caller faults with SIGILL. Documented in the
+  `simd.rs` module doc; the safe path is the `crate::simd` re-exports.

src/simd.rs

@@ -4,6 +4,26 @@
 //! AVX-512 → AVX2 → Scalar. Consumer writes `crate::simd::F32x16`. Period.
 //!
 //! When `std::simd` stabilizes: swap this file. Zero consumer changes.
+//!
+//! The `Tier` above is runtime detection. The SIMD *types* are chosen at
+//! compile time, one realization per build, from the target features:
+//!
+//! * x86_64 `avx512f`: `simd_avx512.rs`.
+//! * x86_64 `avx2`, no `avx512f`: `simd_avx2.rs`. This arm is also what a
+//!   baseline x86-64 build compiles, and `cpu_guard` refuses to start such a
+//!   build on a CPU without AVX2.
+//! * x86_64 `avx`, no `avx2`: `simd_avx.rs` (`.cargo/config-avx.toml`).
+//! * x86_64 `sse4.2`, no `avx` (x86-64-v2, `.cargo/config-v2.toml`):
+//!   `simd_scalar.rs`. The AVX2/AVX-512 types wrap 256/512-bit registers, so
+//!   this arm uses plain arrays that LLVM compiles to SSE.
+//! * aarch64: NEON; wasm32 with `simd128`: `simd_wasm.rs`; any other target:
+//!   `simd_scalar.rs`. The `nightly-simd` feature replaces all of these with
+//!   `core::simd` for validation only.
+//!
+//! The module `crate::simd_avx2` stays public on every x86_64 build,
+//! including v2. Calling it directly on a CPU without AVX2 faults with
+//! SIGILL, and on the v2 arm no startup check catches it. Use the types
+//! re-exported from `crate::simd`.
 
 #[cfg(feature = "std")]
 use std::sync::LazyLock;

src/simd_avx2.rs

@@ -3248,7 +3248,9 @@ impl Default for U8x32 {
 // U8x32 tests
 // ═══════════════════════════════════════════════════════════════════
 
-#[cfg(all(test, target_arch = "x86_64"))]
+// Off the x86-64-v2 arm: these call AVX2 intrinsics directly, and a v2 build
+// (SSE4.2, no AVX) routes `crate::simd` to the scalar realization instead.
+#[cfg(all(test, target_arch = "x86_64", not(all(target_feature = "sse4.2", not(target_feature = "avx")))))]
 mod u8x32_tests {
     use super::U8x32;
 
@@ -3446,7 +3448,9 @@ pub type i32x8 = I32x8;
 #[allow(non_camel_case_types)]
 pub type i64x4 = I64x4;
 
-#[cfg(test)]
+// Off the x86-64-v2 arm: these call AVX2 intrinsics directly, and a v2 build
+// (SSE4.2, no AVX) routes `crate::simd` to the scalar realization instead.
+#[cfg(all(test, not(all(target_feature = "sse4.2", not(target_feature = "avx")))))]
 mod tests {
     use super::*;
 
@@ -4001,7 +4005,9 @@ impl F16Scaler {
     }
 }
 
-#[cfg(test)]
+// Off the x86-64-v2 arm: these call AVX2 intrinsics directly, and a v2 build
+// (SSE4.2, no AVX) routes `crate::simd` to the scalar realization instead.
+#[cfg(all(test, not(all(target_feature = "sse4.2", not(target_feature = "avx")))))]
 mod f16_precision_tests {
     use super::*;