feat(simd): cpu-* cargo features for compile-time SimdProfile pinning

Phase 3 T3.2: add 13 mutually-exclusive cargo features that pin
simd_profile() to a const at compile time, bypassing the runtime
LazyLock detection from T3.1. One feature per non-Scalar variant of
the SimdProfile enum.

Features (mapping to LLVM target-cpu codenames):
  cpu-gnr         → GraniteRapids    (graniterapids)
  cpu-spr         → SapphireRapids   (sapphirerapids)
  cpu-zen4        → Zen4Avx512       (znver4)
  cpu-cpl         → CooperLake       (cooperlake)
  cpu-tigerlake   → TigerLakeU       (tigerlake)
  cpu-icx         → IceLakeSp        (icelake-server)
  cpu-clx         → CascadeLake      (cascadelake)
  cpu-skx         → SkylakeX         (skylake-avx512)
  cpu-arrowlake   → ArrowLake        (arrowlake)
  cpu-haswell     → HaswellAvx2      (haswell)
  cpu-a76         → A76DotProd       (cortex-a76)
  cpu-a72         → A72Fast          (cortex-a72)
  cpu-a53         → A53Baseline      (cortex-a53)

Mutual exclusion (per integration-plan risk #1: "if a user sets
cpu-spr AND has runtime detection on Zen 4, the binary SIGILLs on
AMX instructions") is enforced via a const assert: each cpu-*
contributes 1 to _PIN_COUNT and the assert fires at compile time if
the sum exceeds one. Verified: enabling cpu-spr+cpu-zen4
simultaneously produces a build error citing the mutex.

Implementation: a const pinned_profile() -> Option<SimdProfile>
walks a cfg cascade and returns the active variant or None. The
simd_profile() function exists in two cfg-gated forms — a runtime
LazyLock variant compiled when no cpu-* feature is set, and a
const-foldable variant compiled when any is set. The LazyLock is
not linked into pinned binaries.

is_pinned() const helper exposes whether compile-time dispatch is
active, useful both for consumer-facing diagnostics and for gating
arch-detection tests that no longer apply when pinning overrides
hardware. Existing x86_target_lands_inside_x86_family /
aarch64_target_lands_inside_aarch64_family tests early-return when
pinned; two new tests (pinning_default_is_off, pinning_consistency)
verify the const + runtime paths agree.

Tests: 2077/2077 lib tests pass under both default and --features
cpu-spr configurations. cargo clippy --lib -- -D warnings clean in
both modes. Mutex compile_error verified by attempting
--features "cpu-spr,cpu-zen4" — fails as expected with the const
assert citation. The default (no feature) path is byte-identical to
the T3.1 runtime detection — no regression risk to the merged #181
work or to the e40f3a3 SimdProfile commit.

Author: claude

Cargo.toml

@@ -252,6 +252,36 @@ splat3d = ["std"]
 # quad-tree partition; the entropy coder + RDO loop land in later workers.
 codec = ["std"]
 
+# ── Phase 3 T3.2: compile-time SimdProfile pinning ───────────────────
+#
+# Each cpu-<codename> feature, when enabled, makes
+# `crate::simd::simd_profile()` fold to a const at compile time and
+# bypass the runtime LazyLock detection. Pair with the matching
+# `-Ctarget-cpu=<llvm-name>` in `.cargo/config.toml` (or `RUSTFLAGS`)
+# for full effect — the cargo feature picks the *dispatch* variant,
+# while `-Ctarget-cpu` picks the *codegen* variant. Both together
+# produce a binary that is specialised to one silicon family.
+#
+# Features are MUTUALLY EXCLUSIVE — enable at most one. A compile-time
+# assert in `src/hpc/simd_profile.rs` enforces this. Multiple
+# pinning features active = build error.
+#
+# Codename → SimdProfile variant mapping (see
+# `.claude/knowledge/td-simd-cpu-dispatch-matrix.md`):
+cpu-gnr = []          # GraniteRapids        — target-cpu=graniterapids
+cpu-spr = []          # SapphireRapids       — target-cpu=sapphirerapids
+cpu-zen4 = []         # Zen4Avx512           — target-cpu=znver4 (or znver5)
+cpu-cpl = []          # CooperLake           — target-cpu=cooperlake
+cpu-tigerlake = []    # TigerLakeU           — target-cpu=tigerlake
+cpu-icx = []          # IceLakeSp            — target-cpu=icelake-server
+cpu-clx = []          # CascadeLake          — target-cpu=cascadelake
+cpu-skx = []          # SkylakeX             — target-cpu=skylake-avx512
+cpu-arrowlake = []    # ArrowLake            — target-cpu=arrowlake
+cpu-haswell = []      # HaswellAvx2          — target-cpu=haswell (or znver3)
+cpu-a76 = []          # A76DotProd           — target-cpu=cortex-a76
+cpu-a72 = []          # A72Fast              — target-cpu=cortex-a72
+cpu-a53 = []          # A53Baseline          — target-cpu=cortex-a53
+
 # no_std polyfill for `static LazyLock` in `src/simd.rs` (sprint A12).
 # Pulls in `portable-atomic` with the `critical-section` impl plus the
 # `critical-section` runtime so we can build a once-cell-style cache for

src/hpc/simd_profile.rs

@@ -225,18 +225,200 @@ impl SimdProfile {
     }
 }
 
+// ────────────────────────────────────────────────────────────────────
+// Phase 3 T3.2 — compile-time pinning via `cpu-*` cargo features.
+//
+// When any `cpu-<codename>` feature is set, `PINNED_PROFILE` is `Some(_)`
+// and `simd_profile()` folds to the const at compile time — no LazyLock
+// initialisation, no branch, no atomics. Without any feature set,
+// behaviour matches the original runtime LazyLock detection.
+//
+// Mutual exclusion: at most ONE cpu-* feature may be enabled. The
+// `_PIN_COUNT` const assert below fires at compile time if more than
+// one is active, mirroring integration-plan risk #1 ("if a user sets
+// cpu-spr AND has runtime detection on Zen 4, the binary SIGILLs").
+// ────────────────────────────────────────────────────────────────────
+
+const _PIN_COUNT: u32 = 0
+    + cfg!(feature = "cpu-gnr") as u32
+    + cfg!(feature = "cpu-spr") as u32
+    + cfg!(feature = "cpu-zen4") as u32
+    + cfg!(feature = "cpu-cpl") as u32
+    + cfg!(feature = "cpu-tigerlake") as u32
+    + cfg!(feature = "cpu-icx") as u32
+    + cfg!(feature = "cpu-clx") as u32
+    + cfg!(feature = "cpu-skx") as u32
+    + cfg!(feature = "cpu-arrowlake") as u32
+    + cfg!(feature = "cpu-haswell") as u32
+    + cfg!(feature = "cpu-a76") as u32
+    + cfg!(feature = "cpu-a72") as u32
+    + cfg!(feature = "cpu-a53") as u32;
+
+const _: () = assert!(
+    _PIN_COUNT <= 1,
+    "cpu-* cargo features are mutually exclusive: enable at most one (cpu-gnr, cpu-spr, cpu-zen4, cpu-cpl, cpu-tigerlake, cpu-icx, cpu-clx, cpu-skx, cpu-arrowlake, cpu-haswell, cpu-a76, cpu-a72, cpu-a53)"
+);
+
+/// The compile-time pinned profile, or `None` when runtime detection is in
+/// effect. `Some(_)` exactly when one of the `cpu-*` cargo features is
+/// enabled; mutually exclusive features are enforced by the `_PIN_COUNT`
+/// const assert above.
+///
+/// Consumers wanting branch-free dispatch on pinned builds can match on
+/// this const directly — the optimiser folds `Some(SimdProfile::X)` into
+/// the call site and the `None`-arm runtime path is eliminated. Returned
+/// from a `const fn` so call sites in const contexts (e.g. `const` array
+/// initialisers for dispatch tables) work as well.
+pub const fn pinned_profile() -> Option<SimdProfile> {
+    #[cfg(feature = "cpu-gnr")]
+    {
+        return Some(SimdProfile::GraniteRapids);
+    }
+    #[cfg(feature = "cpu-spr")]
+    {
+        return Some(SimdProfile::SapphireRapids);
+    }
+    #[cfg(feature = "cpu-zen4")]
+    {
+        return Some(SimdProfile::Zen4Avx512);
+    }
+    #[cfg(feature = "cpu-cpl")]
+    {
+        return Some(SimdProfile::CooperLake);
+    }
+    #[cfg(feature = "cpu-tigerlake")]
+    {
+        return Some(SimdProfile::TigerLakeU);
+    }
+    #[cfg(feature = "cpu-icx")]
+    {
+        return Some(SimdProfile::IceLakeSp);
+    }
+    #[cfg(feature = "cpu-clx")]
+    {
+        return Some(SimdProfile::CascadeLake);
+    }
+    #[cfg(feature = "cpu-skx")]
+    {
+        return Some(SimdProfile::SkylakeX);
+    }
+    #[cfg(feature = "cpu-arrowlake")]
+    {
+        return Some(SimdProfile::ArrowLake);
+    }
+    #[cfg(feature = "cpu-haswell")]
+    {
+        return Some(SimdProfile::HaswellAvx2);
+    }
+    #[cfg(feature = "cpu-a76")]
+    {
+        return Some(SimdProfile::A76DotProd);
+    }
+    #[cfg(feature = "cpu-a72")]
+    {
+        return Some(SimdProfile::A72Fast);
+    }
+    #[cfg(feature = "cpu-a53")]
+    {
+        return Some(SimdProfile::A53Baseline);
+    }
+    #[allow(unreachable_code)]
+    None
+}
+
+/// `true` when a `cpu-*` cargo feature has pinned the profile at compile
+/// time, `false` when runtime detection is in use. Equivalent to
+/// `pinned_profile().is_some()` but spelled out for grep-ability.
+pub const fn is_pinned() -> bool {
+    pinned_profile().is_some()
+}
+
+// The LazyLock only exists when no cpu-* feature is set. With pinning,
+// linking the LazyLock would defeat the purpose — we want every code
+// path that touches `simd_profile()` to fold to a const.
+#[cfg(not(any(
+    feature = "cpu-gnr",
+    feature = "cpu-spr",
+    feature = "cpu-zen4",
+    feature = "cpu-cpl",
+    feature = "cpu-tigerlake",
+    feature = "cpu-icx",
+    feature = "cpu-clx",
+    feature = "cpu-skx",
+    feature = "cpu-arrowlake",
+    feature = "cpu-haswell",
+    feature = "cpu-a76",
+    feature = "cpu-a72",
+    feature = "cpu-a53",
+)))]
 static PROFILE: LazyLock<SimdProfile> = LazyLock::new(SimdProfile::detect);
 
-/// Get the resolved silicon profile, detected once at first access.
+/// Get the resolved silicon profile.
+///
+/// **Default (no `cpu-*` feature):** detected once at first access via
+/// `LazyLock`; subsequent calls are a single pointer deref to a `Copy`
+/// enum — no atomics, no branching.
+///
+/// **Pinned (one `cpu-*` feature set):** returns the pinned const
+/// directly. The compiler folds this call into the matching variant at
+/// every call site; the LazyLock is not linked into the binary.
 ///
-/// All subsequent calls are a single pointer deref to a `Copy` enum —
-/// no atomics, no branching. Pair with `*Dispatch` static tables to make
-/// per-call dispatch a single indirect call after monomorphisation.
+/// Pair with `*Dispatch` static tables to make per-call dispatch a single
+/// indirect call after monomorphisation (runtime path) or to fold to a
+/// direct call (pinned path).
+#[cfg(not(any(
+    feature = "cpu-gnr",
+    feature = "cpu-spr",
+    feature = "cpu-zen4",
+    feature = "cpu-cpl",
+    feature = "cpu-tigerlake",
+    feature = "cpu-icx",
+    feature = "cpu-clx",
+    feature = "cpu-skx",
+    feature = "cpu-arrowlake",
+    feature = "cpu-haswell",
+    feature = "cpu-a76",
+    feature = "cpu-a72",
+    feature = "cpu-a53",
+)))]
 #[inline(always)]
 pub fn simd_profile() -> SimdProfile {
     *PROFILE
 }
 
+/// Get the resolved silicon profile (pinned variant).
+///
+/// A `cpu-*` cargo feature is active: this returns the pinned constant
+/// directly, foldable at every call site. The runtime LazyLock is not
+/// linked into the binary. See the documentation on the runtime variant
+/// for the call-site contract.
+#[cfg(any(
+    feature = "cpu-gnr",
+    feature = "cpu-spr",
+    feature = "cpu-zen4",
+    feature = "cpu-cpl",
+    feature = "cpu-tigerlake",
+    feature = "cpu-icx",
+    feature = "cpu-clx",
+    feature = "cpu-skx",
+    feature = "cpu-arrowlake",
+    feature = "cpu-haswell",
+    feature = "cpu-a76",
+    feature = "cpu-a72",
+    feature = "cpu-a53",
+))]
+#[inline(always)]
+pub const fn simd_profile() -> SimdProfile {
+    // SAFETY of the unwrap: the cfg gate above guarantees at least one
+    // cpu-* feature is set, and `pinned_profile()` returns Some(_) under
+    // any of those gates. Const-evaluable since the inner cfg cascade is
+    // resolved at compile time.
+    match pinned_profile() {
+        Some(p) => p,
+        None => SimdProfile::Scalar, // unreachable; const fn can't panic cleanly
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -273,6 +455,11 @@ mod tests {
 
     #[test]
     fn x86_target_lands_inside_x86_family() {
+        // Pinning overrides hardware detection — the test only describes
+        // the default (runtime-detection) path.
+        if is_pinned() {
+            return;
+        }
         #[cfg(target_arch = "x86_64")]
         {
             let p = simd_profile();
@@ -290,13 +477,54 @@ mod tests {
 
     #[test]
     fn aarch64_target_lands_inside_aarch64_family() {
+        if is_pinned() {
+            return;
+        }
         #[cfg(target_arch = "aarch64")]
         {
             let p = simd_profile();
             assert!(p.is_aarch64(), "aarch64 silicon resolved as {:?}", p);
         }
     }
 
+    #[test]
+    fn pinning_default_is_off() {
+        // The default build (no cpu-* feature) must NOT be pinned, so
+        // downstream consumers don't get surprised by compile-time
+        // dispatch they didn't opt into.
+        #[cfg(not(any(
+            feature = "cpu-gnr",
+            feature = "cpu-spr",
+            feature = "cpu-zen4",
+            feature = "cpu-cpl",
+            feature = "cpu-tigerlake",
+            feature = "cpu-icx",
+            feature = "cpu-clx",
+            feature = "cpu-skx",
+            feature = "cpu-arrowlake",
+            feature = "cpu-haswell",
+            feature = "cpu-a76",
+            feature = "cpu-a72",
+            feature = "cpu-a53",
+        )))]
+        {
+            assert!(!is_pinned());
+            assert_eq!(pinned_profile(), None);
+        }
+    }
+
+    #[test]
+    fn pinning_consistency() {
+        // When pinning is in effect, simd_profile() must equal the
+        // pinned const — hardware detection is bypassed entirely.
+        if let Some(pinned) = pinned_profile() {
+            assert!(is_pinned());
+            assert_eq!(simd_profile(), pinned);
+        } else {
+            assert!(!is_pinned());
+        }
+    }
+
     #[test]
     fn has_avx512_is_subset_of_is_x86() {
         for &p in &[