fuel-cpu-backend 0.23.0

// SPDX-License-Identifier: MIT OR Apache-2.0
//! Unary-elementwise chassis — one shape/loop pass shared by every
//! per-(op, dtype) unary kernel (Relu / Neg / Sqr / … / GeluTanh,
//! across f32 / f64 / bf16 / f16).
//!
//! ## Design
//!
//! The chassis splits into three layers so per-op authors write the
//! math once and get four dtype impls for free:
//!
//! 1. [`UnaryOp<T>`] — what the chassis function consumes. One
//!    `apply(T) -> T` method.
//! 2. [`UnaryOpCore`] — what op authors implement. Two methods
//!    (`f32` + `f64`) carrying the per-precision math. Op markers
//!    are zero-sized structs implementing this trait.
//! 3. Four blanket impls — every `O: UnaryOpCore` automatically
//!    gets `UnaryOp<f32>`, `UnaryOp<f64>`, `UnaryOp<bf16>` (via
//!    f32 round-trip), and `UnaryOp<f16>` (via f32 round-trip).
//!
//! The half-float round-trip preserves the pre-refactor behavior
//! bit-for-bit: every existing `unary_kernel!(*_bf16, ..., |x|
//! half::bf16::from_f32(<f32 op>(x.to_f32())))` invocation becomes
//! a single `<UnaryOpCore>::f32` definition that flows through the
//! blanket bf16 impl.
//!
//! Adding a new op is "implement two methods on a new marker."
//! Adding a new dtype to the family is "add one more blanket impl
//! in this file." Adding a new dtype to a single op is impossible
//! by design — the blanket impls cover every op uniformly.

use bytemuck::Pod;

use crate::byte_storage::CpuStorageBytes;
use fuel_ir::{Error, Result};

// =============================================================================
// Traits
// =============================================================================

/// Per-(op, dtype) unary operation. The chassis function
/// [`unary`] consumes one of these implementations to walk a
/// byte-shaped tensor elementwise.
///
/// Implementations are auto-derived from [`UnaryOpCore`] via four
/// blanket impls — don't implement this directly.
pub trait UnaryOp<T: Copy> {
    fn apply(x: T) -> T;
}

/// What op authors actually implement. Two methods carry the f32
/// and f64 math respectively; the blanket [`UnaryOp`] impls in this
/// module derive the four dtype-specific implementations (f32 / f64
/// direct, bf16 / f16 via f32 round-trip).
///
/// Splitting `f32` and `f64` lets ops that want extra f64 precision
/// (e.g. higher-precision constants) opt in without forcing every
/// op to be generic over a numeric trait we'd have to define.
pub trait UnaryOpCore {
    fn f32(x: f32) -> f32;
    fn f64(x: f64) -> f64;

    /// Narrow-float lowering. THE DEFAULT PROMOTES, COMPUTES AND ROUNDS BACK,
    /// which is correct for every op that COMPUTES its result -- rounding a
    /// computed narrow value is what KISS-OPS-6.16-0003 licenses.
    ///
    /// ⚠️ OPS THAT **SELECT** MUST OVERRIDE THIS AND RETURN SOURCE BITS.
    /// IEEE 754-2019 §5.5.1 makes `negate`/`abs`/`copySign` SIGN-BIT
    /// operations, not arithmetic: they neither signal on a signalling NaN nor
    /// quiet it. Routing them through f32 does quiet it -- measured, bf16
    /// `0x7F81` (signalling) comes back `0x7FC1` (quiet), because the quiet bit
    /// is set on the WIDENING convert, before the op runs at all.
    ///
    /// The split is the same one KISS #355 and #363 draw: COMPUTE may quiet
    /// (IEEE default exception handling), SELECT may not.
    fn bf16(x: half::bf16) -> half::bf16 {
        half::bf16::from_f32(Self::f32(x.to_f32()))
    }

    /// See [`UnaryOpCore::bf16`].
    fn f16(x: half::f16) -> half::f16 {
        half::f16::from_f32(Self::f32(x.to_f32()))
    }
}

// Blanket impls.

impl<O: UnaryOpCore> UnaryOp<f32> for O {
    fn apply(x: f32) -> f32 {
        <O as UnaryOpCore>::f32(x)
    }
}

impl<O: UnaryOpCore> UnaryOp<f64> for O {
    fn apply(x: f64) -> f64 {
        <O as UnaryOpCore>::f64(x)
    }
}

impl<O: UnaryOpCore> UnaryOp<half::bf16> for O {
    fn apply(x: half::bf16) -> half::bf16 {
        <O as UnaryOpCore>::bf16(x)
    }
}

impl<O: UnaryOpCore> UnaryOp<half::f16> for O {
    fn apply(x: half::f16) -> half::f16 {
        <O as UnaryOpCore>::f16(x)
    }
}

// =============================================================================
// Chassis function
// =============================================================================

/// Elementwise `out[i] = U::apply(input[i])`. Validates byte
/// lengths match (input and output must hold the same element
/// count of type `T`), then walks the typed views.
///
/// `name` appears in size-mismatch error messages so the
/// diagnostic points at the entry the caller invoked.
pub fn unary<T, U>(name: &str, input: &CpuStorageBytes, output: &mut CpuStorageBytes) -> Result<()>
where
    T: Copy + Pod,
    U: UnaryOp<T>,
{
    let in_bytes = input.len_bytes();
    let out_bytes = output.len_bytes();
    if in_bytes != out_bytes {
        return Err(Error::Msg(format!(
            "{name}: input bytes={in_bytes} != output bytes={out_bytes}",
        ))
        .bt());
    }
    let in_view: &[T] = input.as_slice()?;
    let out_view: &mut [T] = output.as_slice_mut()?;
    for (i, slot) in out_view.iter_mut().enumerate() {
        *slot = U::apply(in_view[i]);
    }
    Ok(())
}

// =============================================================================
// Op markers
// =============================================================================
//
// Each op is a zero-sized struct implementing `UnaryOpCore`. The
// four `UnaryOp<T>` impls fall out of the blanket impls above.
// Pre-refactor `unary_kernel!(*_bf16, ..., |x| half::bf16::from_f32(f32_op(x.to_f32())))`
// invocations all collapse onto the bf16 blanket impl.

/// ReLU: `select(x < 0, 0, x)` — the `x<0 ? 0 : x` form, NOT `max(x, 0)`.
/// Per KISS-OPS-6.15-0002 (and torch parity) `relu` is both **NaN-propagating**
/// (`x < 0` is false for NaN → the NaN input is returned unchanged, sign +
/// payload intact) and **`-0.0`-preserving** (`-0.0 < 0` is false → `-0.0`
/// passes through, where `max(x, 0)` would normalize it to `+0.0`). Pinned
/// 2026-07-08 (NaN) + 2026-07-14 (`-0.0`, `docs/architecture/10-decisions-log.md`).
pub struct Relu;
impl UnaryOpCore for Relu {
    fn f32(x: f32) -> f32 {
        if x < 0.0 { 0.0 } else { x }
    }
    fn f64(x: f64) -> f64 {
        if x < 0.0 { 0.0 } else { x }
    }

    // ⚠️ NARROW OVERRIDE -- Relu SELECTS: on the `else` branch the result IS the
    // input, so it must be the input's BITS. The default promotes through f32,
    // and `bf16::to_f32` QUIETS a signalling NaN before the predicate runs.
    // Measured: 0x7F81 (signalling) came back 0x7FC1 (quiet); the branch taken
    // was ELSE (observed, with a -2.5 control proving the probe distinguishes
    // the branches), so a SOURCE value was quieted on its way through.
    //
    // `-0.0` behaviour is UNCHANGED and deliberately so: `-0.0 < 0.0` is false
    // in narrow exactly as in f32, so `-0.0` passes through. That contract is
    // pinned twice in the decisions log (2026-07-08 NaN, 2026-07-14 -0.0) and
    // this override preserves it rather than relying on the round-trip to.
    fn bf16(x: half::bf16) -> half::bf16 {
        if x < half::bf16::ZERO {
            half::bf16::ZERO
        } else {
            x
        }
    }

    /// See [`Relu::bf16`].
    fn f16(x: half::f16) -> half::f16 {
        if x < half::f16::ZERO {
            half::f16::ZERO
        } else {
            x
        }
    }
}

/// Negation: `-x`.
pub struct Neg;
impl UnaryOpCore for Neg {
    fn f32(x: f32) -> f32 {
        -x
    }
    fn f64(x: f64) -> f64 {
        -x
    }

    // ⚠️ NARROW OVERRIDE -- do NOT delete to "simplify". The default promotes
    // through f32, and `bf16::to_f32` QUIETS a signalling NaN (half 2.7.1
    // `convert.rs`, `i | 0x0040`), before this op runs at all. IEEE 754-2019
    // §5.5.1 classes negate/abs/copySign as SIGN-BIT operations that neither
    // signal nor quiet, so promoting here violates the standard directly --
    // not KISS #355 by analogy. Measured: bf16 0x7F81 (signalling) came back
    // 0x7FC1 (quiet) through the default path.
    //
    // `half`'s own `impl Neg for bf16` is exactly `Self(self.0 ^ 0x8000)`, so
    // delegating to `-x` is the bit operation, not a promotion.
    fn bf16(x: half::bf16) -> half::bf16 {
        -x
    }

    /// See [`Neg::bf16`].
    fn f16(x: half::f16) -> half::f16 {
        -x
    }
}

/// Square: `x * x`.
pub struct Sqr;
impl UnaryOpCore for Sqr {
    fn f32(x: f32) -> f32 {
        x * x
    }
    fn f64(x: f64) -> f64 {
        x * x
    }
}

/// Square root. Negative inputs yield NaN per IEEE-754.
pub struct Sqrt;
impl UnaryOpCore for Sqrt {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.sqrt())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.sqrt())
    }
}

/// Reciprocal: `1 / x`. Zero input yields IEEE-754 inf/NaN.
pub struct Recip;
impl UnaryOpCore for Recip {
    fn f32(x: f32) -> f32 {
        1.0 / x
    }
    fn f64(x: f64) -> f64 {
        1.0 / x
    }
}

/// Absolute value: `|x|`.
pub struct Abs;
impl UnaryOpCore for Abs {
    fn f32(x: f32) -> f32 {
        x.abs()
    }
    fn f64(x: f64) -> f64 {
        x.abs()
    }

    // ⚠️ NARROW OVERRIDE -- do NOT delete to "simplify". The default promotes
    // through f32, and `bf16::to_f32` QUIETS a signalling NaN (half 2.7.1
    // `convert.rs`, `i | 0x0040`), before this op runs at all. IEEE 754-2019
    // §5.5.1 classes negate/abs/copySign as SIGN-BIT operations that neither
    // signal nor quiet, so promoting here violates the standard directly --
    // not KISS #355 by analogy. Measured: bf16 0x7F81 (signalling) came back
    // 0x7FC1 (quiet) through the default path.
    //
    // ⚠️ WRITTEN OUT because `half` HAS NO `abs` on `bf16`/`f16` -- measured,
    // zero occurrences, with `fn signum` (1 hit) as the control proving the
    // query would have found one. Clearing the sign bit is the whole operation.
    fn bf16(x: half::bf16) -> half::bf16 {
        half::bf16::from_bits(x.to_bits() & 0x7FFF)
    }

    /// See [`Abs::bf16`].
    fn f16(x: half::f16) -> half::f16 {
        half::f16::from_bits(x.to_bits() & 0x7FFF)
    }
}

/// A COMPUTED float result that is NaN must be a QUIET NaN (IEEE 754 default
/// exception handling; KISS-OPS-6.16-0010: an op whose decomposition contains
/// arithmetic delivers a quiet NaN on a signalling operand). Hardware arithmetic
/// does this by itself; a `libm` call does not have to. Measured: on Apple's
/// `logf`, `log(sNaN)` returns the signalling NaN `7F800001` UNCHANGED, while
/// `expf`/`sinf` (and every x86 libm tried) return `7FC00000`. Setting the quiet
/// bit of a NaN result is idempotent, keeps the payload, and never touches a
/// non-NaN, so it is applied to every direct `libm` transcendental below.
#[inline]
pub(crate) fn quiet_f32(r: f32) -> f32 {
    if r.is_nan() {
        f32::from_bits(r.to_bits() | 0x0040_0000)
    } else {
        r
    }
}

/// [`quiet_f32`] for `f64` (the quiet bit is bit 51).
#[inline]
pub(crate) fn quiet_f64(r: f64) -> f64 {
    if r.is_nan() {
        f64::from_bits(r.to_bits() | 0x0008_0000_0000_0000)
    } else {
        r
    }
}

/// Hyperbolic tangent.
pub struct Tanh;
impl UnaryOpCore for Tanh {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.tanh())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.tanh())
    }
}

/// Exponential: `e^x`.
pub struct Exp;
impl UnaryOpCore for Exp {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.exp())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.exp())
    }
}

/// Natural log. Negative inputs yield NaN per IEEE-754.
pub struct Log;
impl UnaryOpCore for Log {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.ln())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.ln())
    }
}

/// Sine.
pub struct Sin;
impl UnaryOpCore for Sin {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.sin())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.sin())
    }
}

/// Cosine.
pub struct Cos;
impl UnaryOpCore for Cos {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.cos())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.cos())
    }
}

/// Logistic sigmoid: `1 / (1 + exp(-x))`.
pub struct Sigmoid;
impl UnaryOpCore for Sigmoid {
    fn f32(x: f32) -> f32 {
        1.0 / (1.0 + (-x).exp())
    }
    fn f64(x: f64) -> f64 {
        1.0 / (1.0 + (-x).exp())
    }
}

/// SiLU / Swish: `x * sigmoid(x)`.
pub struct Silu;
impl UnaryOpCore for Silu {
    fn f32(x: f32) -> f32 {
        x / (1.0 + (-x).exp())
    }
    fn f64(x: f64) -> f64 {
        x / (1.0 + (-x).exp())
    }
}

/// Heaviside step: `1 where x > 0, else 0`.
pub struct Step;
impl UnaryOpCore for Step {
    fn f32(x: f32) -> f32 {
        if x > 0.0 { 1.0 } else { 0.0 }
    }
    fn f64(x: f64) -> f64 {
        if x > 0.0 { 1.0 } else { 0.0 }
    }
}

/// Floor: `⌊x⌋`.
pub struct Floor;
impl UnaryOpCore for Floor {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.floor())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.floor())
    }
}

/// Ceiling: `⌈x⌉`.
pub struct Ceil;
impl UnaryOpCore for Ceil {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.ceil())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.ceil())
    }
}

/// Round-half-to-even (banker's rounding, IEEE-754 roundeven).
pub struct Round;
impl UnaryOpCore for Round {
    fn f32(x: f32) -> f32 {
        quiet_f32(x.round_ties_even())
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(x.round_ties_even())
    }
}

/// Sign: `-1 / 0 / 1`. `sign(0) = 0` by subgradient convention.
pub struct Sign;
impl UnaryOpCore for Sign {
    fn f32(x: f32) -> f32 {
        if x > 0.0 {
            1.0
        } else if x < 0.0 {
            -1.0
        } else {
            0.0
        }
    }
    fn f64(x: f64) -> f64 {
        if x > 0.0 {
            1.0
        } else if x < 0.0 {
            -1.0
        } else {
            0.0
        }
    }
}

/// Gauss error function (`erf` via libm).
pub struct Erf;
impl UnaryOpCore for Erf {
    fn f32(x: f32) -> f32 {
        quiet_f32(libm::erff(x))
    }
    fn f64(x: f64) -> f64 {
        quiet_f64(libm::erf(x))
    }
}

/// GELU (exact erf form): `0.5 * x * (1 + erf(x/√2))`.
pub struct GeluErf;
impl UnaryOpCore for GeluErf {
    fn f32(x: f32) -> f32 {
        0.5 * x * (1.0 + libm::erff(x * std::f32::consts::FRAC_1_SQRT_2))
    }
    fn f64(x: f64) -> f64 {
        0.5 * x * (1.0 + libm::erf(x * std::f64::consts::FRAC_1_SQRT_2))
    }
}

/// Reciprocal square root: `1 / sqrt(x)`.
pub struct Rsqrt;
impl UnaryOpCore for Rsqrt {
    fn f32(x: f32) -> f32 {
        1.0 / x.sqrt()
    }
    fn f64(x: f64) -> f64 {
        1.0 / x.sqrt()
    }
}

/// GELU (tanh approximation): `0.5 * x * (1 + tanh(√(2/π) * (x + 0.044715 * x³)))`.
/// Matches `Op::GeluTanh`'s tanh-approximation semantics in fuel-graph.
/// f32 uses a 7-digit constant for √(2/π); f64 uses a 16-digit
/// constant — both match the pre-chassis `gelu_*` functions
/// bit-for-bit. bf16 / f16 route through the f32 path via the
/// blanket impl.
pub struct GeluTanh;
impl UnaryOpCore for GeluTanh {
    fn f32(x: f32) -> f32 {
        const COEFF: f32 = 0.797_884_6;
        let inner = COEFF * (x + 0.044_715 * x * x * x);
        0.5 * x * (1.0 + inner.tanh())
    }
    fn f64(x: f64) -> f64 {
        const COEFF: f64 = 0.797_884_560_802_865_4;
        let inner = COEFF * (x + 0.044_715 * x * x * x);
        0.5 * x * (1.0 + inner.tanh())
    }
}

// =============================================================================
// Structural tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    /// The REST of the direct-libm unary ops (`erf`, `floor`, `ceil`,
    /// `round_even`, `sqrt`) also return a quiet NaN for a signalling operand,
    /// and so do the compositions over them. Same caveat as the sibling test:
    /// x86 passes without the helper; the macOS CI leg is the instrument that
    /// can see a libm that passes a signalling NaN through.
    #[test]
    fn remaining_libm_ops_return_a_quiet_nan_for_a_signalling_operand() {
        let snan32 = f32::from_bits(0x7F80_0001);
        let snan64 = f64::from_bits(0x7FF0_0000_0000_0001);
        assert!(snan32.is_nan() && snan32.to_bits() & 0x0040_0000 == 0);
        assert!(snan64.is_nan() && snan64.to_bits() & 0x0008_0000_0000_0000 == 0);
        let q32 = |r: f32| r.is_nan() && r.to_bits() & 0x0040_0000 != 0;
        let q64 = |r: f64| r.is_nan() && r.to_bits() & 0x0008_0000_0000_0000 != 0;
        assert!(q32(<Erf as UnaryOpCore>::f32(snan32)), "erf f32");
        assert!(q32(<Floor as UnaryOpCore>::f32(snan32)), "floor f32");
        assert!(q32(<Ceil as UnaryOpCore>::f32(snan32)), "ceil f32");
        assert!(q32(<Round as UnaryOpCore>::f32(snan32)), "round f32");
        assert!(q32(<Sqrt as UnaryOpCore>::f32(snan32)), "sqrt f32");
        assert!(q32(<Rsqrt as UnaryOpCore>::f32(snan32)), "rsqrt f32");
        assert!(q32(<Sigmoid as UnaryOpCore>::f32(snan32)), "sigmoid f32");
        assert!(q32(<Silu as UnaryOpCore>::f32(snan32)), "silu f32");
        assert!(q32(<GeluErf as UnaryOpCore>::f32(snan32)), "gelu_erf f32");
        assert!(q32(<GeluTanh as UnaryOpCore>::f32(snan32)), "gelu_tanh f32");
        assert!(q64(<Erf as UnaryOpCore>::f64(snan64)), "erf f64");
        assert!(q64(<Floor as UnaryOpCore>::f64(snan64)), "floor f64");
        assert!(q64(<Ceil as UnaryOpCore>::f64(snan64)), "ceil f64");
        assert!(q64(<Round as UnaryOpCore>::f64(snan64)), "round f64");
        assert!(q64(<Sqrt as UnaryOpCore>::f64(snan64)), "sqrt f64");
        assert!(q64(<Rsqrt as UnaryOpCore>::f64(snan64)), "rsqrt f64");
        assert!(q64(<Sigmoid as UnaryOpCore>::f64(snan64)), "sigmoid f64");
        assert!(q64(<Silu as UnaryOpCore>::f64(snan64)), "silu f64");
        assert!(q64(<GeluErf as UnaryOpCore>::f64(snan64)), "gelu_erf f64");
        assert!(q64(<GeluTanh as UnaryOpCore>::f64(snan64)), "gelu_tanh f64");
    }

    /// A libm transcendental returns a QUIET NaN for a signalling operand. Apple's
    /// `logf` does not (it returns `7F800001` unchanged), which the KISS NaN
    /// vectors caught on the macOS CI leg; `quiet_f32`/`quiet_f64` close it. On
    /// x86 libm this passes WITHOUT the helper, so the assertion states the
    /// contract and macOS CI is where it earns its keep. CONTROL: the input
    /// really is signalling (quiet bit clear), so a fixture that was never
    /// signalling cannot make this pass vacuously.
    #[test]
    fn transcendentals_return_a_quiet_nan_for_a_signalling_operand() {
        let snan32 = f32::from_bits(0x7F80_0001);
        let snan64 = f64::from_bits(0x7FF0_0000_0000_0001);
        assert!(
            snan32.is_nan() && snan32.to_bits() & 0x0040_0000 == 0,
            "f32 fixture must be signalling"
        );
        assert!(
            snan64.is_nan() && snan64.to_bits() & 0x0008_0000_0000_0000 == 0,
            "f64 fixture must be signalling"
        );
        fn q32(r: f32) -> bool {
            r.is_nan() && r.to_bits() & 0x0040_0000 != 0
        }
        fn q64(r: f64) -> bool {
            r.is_nan() && r.to_bits() & 0x0008_0000_0000_0000 != 0
        }
        assert!(q32(<Exp as UnaryOpCore>::f32(snan32)), "exp f32");
        assert!(q32(<Log as UnaryOpCore>::f32(snan32)), "log f32");
        assert!(q32(<Sin as UnaryOpCore>::f32(snan32)), "sin f32");
        assert!(q32(<Cos as UnaryOpCore>::f32(snan32)), "cos f32");
        assert!(q32(<Tanh as UnaryOpCore>::f32(snan32)), "tanh f32");
        assert!(q64(<Exp as UnaryOpCore>::f64(snan64)), "exp f64");
        assert!(q64(<Log as UnaryOpCore>::f64(snan64)), "log f64");
        assert!(q64(<Sin as UnaryOpCore>::f64(snan64)), "sin f64");
        assert!(q64(<Cos as UnaryOpCore>::f64(snan64)), "cos f64");
        assert!(q64(<Tanh as UnaryOpCore>::f64(snan64)), "tanh f64");
        // The helper changes nothing else: finite values and infinities pass through.
        assert_eq!(quiet_f32(1.5), 1.5);
        assert_eq!(quiet_f32(f32::INFINITY), f32::INFINITY);
        assert_eq!(quiet_f64(-2.5), -2.5);
        // A quiet NaN keeps its payload.
        assert_eq!(
            quiet_f32(f32::from_bits(0x7FC0_1234)).to_bits(),
            0x7FC0_1234
        );
    }

    /// KISS #355: SIGN-BIT and SELECT ops must not QUIET a signalling NaN.
    ///
    /// The default narrow lowering promotes through f32, and `bf16::to_f32`
    /// quiets deliberately (`half` 2.7.1 `convert.rs`, `i | 0x0040`) BEFORE the
    /// op runs. IEEE 754-2019 §5.5.1 classes negate/abs/copySign as sign-bit
    /// operations that neither signal nor quiet; `Relu` selects its input on the
    /// `else` branch, so its result is a SOURCE value too.
    ///
    /// ⚠️ THE POSITIVE CONTROL IS LOAD-BEARING. "Still signalling" only means
    /// something if the promoting path demonstrably quiets in this same build --
    /// otherwise a fixture that was never signalling, or a `half` version that
    /// stopped quieting, would make every assertion below pass vacuously.
    #[test]
    fn sign_bit_and_select_ops_preserve_a_signalling_nan_in_narrow() {
        const QUIET: u16 = 0x0040;
        let s = half::bf16::from_bits(0x7F81); // exp all ones, mantissa set, quiet CLEAR
        assert!(s.is_nan(), "fixture is not a NaN");
        assert_eq!(s.to_bits() & QUIET, 0, "fixture must be SIGNALLING");

        // CONTROL: the DEFAULT (promoting) lowering must quiet. `Sqrt` computes,
        // so it legitimately keeps the default path.
        let promoted = <Sqrt as UnaryOpCore>::bf16(s);
        assert_ne!(
            promoted.to_bits() & QUIET,
            0,
            "control failed: the promoting path did NOT quiet, so 'still signalling'              below proves nothing -- check the fixture and half's convert"
        );

        for (name, got) in [
            ("Neg", <Neg as UnaryOpCore>::bf16(s)),
            ("Abs", <Abs as UnaryOpCore>::bf16(s)),
            ("Relu", <Relu as UnaryOpCore>::bf16(s)),
        ] {
            assert!(got.is_nan(), "{name} lost NaN-ness entirely");
            assert_eq!(
                got.to_bits() & QUIET,
                0,
                "{name} QUIETED a signalling NaN (0x{:04X} -> 0x{:04X}); it is a                  sign-bit/select op and must return SOURCE bits, not round an f32                  result. See KISS #355 and IEEE 754-2019 §5.5.1.",
                s.to_bits(),
                got.to_bits()
            );
        }
    }

    /// The narrow overrides must not change any ORDINARY value -- otherwise the
    /// NaN fix would be bought with a numeric regression nothing else asserts.
    #[test]
    fn narrow_overrides_agree_with_the_promoting_path_on_non_nan_values() {
        // ±inf (0x7F80/0xFF80) included: neither finite nor NaN, so the
        // exactness argument -- worded about FINITE values -- does not cover
        // them. Both conversion legs take their non-NaN path for an infinity
        // and round-trip it exactly, so these must agree.
        for bits in [
            0x3F80u16, 0xC020, 0x0000, 0x8000, 0x7F7F, 0xFF7F, 0x7F80, 0xFF80,
        ] {
            let x = half::bf16::from_bits(bits);
            assert_eq!(
                <Neg as UnaryOpCore>::bf16(x).to_bits(),
                half::bf16::from_f32(-x.to_f32()).to_bits(),
                "Neg diverged from the promoting path on 0x{bits:04X}"
            );
            assert_eq!(
                <Abs as UnaryOpCore>::bf16(x).to_bits(),
                half::bf16::from_f32(x.to_f32().abs()).to_bits(),
                "Abs diverged from the promoting path on 0x{bits:04X}"
            );
            assert_eq!(
                <Relu as UnaryOpCore>::bf16(x).to_bits(),
                half::bf16::from_f32(if x.to_f32() < 0.0 { 0.0 } else { x.to_f32() }).to_bits(),
                "Relu diverged from the promoting path on 0x{bits:04X}"
            );
        }
        // -0.0 explicitly: the contract pinned twice in the decisions log.
        let nz = half::bf16::from_f32(-0.0);
        assert_eq!(
            <Relu as UnaryOpCore>::bf16(nz).to_bits(),
            nz.to_bits(),
            "Relu must PRESERVE -0.0 (pinned 2026-07-14), not normalise it to +0.0"
        );
    }

    #[test]
    fn unary_op_neg_f32_negates() {
        assert_eq!(<Neg as UnaryOp<f32>>::apply(2.5), -2.5);
        assert_eq!(<Neg as UnaryOp<f32>>::apply(-3.0), 3.0);
        assert_eq!(<Neg as UnaryOp<f32>>::apply(0.0), 0.0);
    }

    #[test]
    fn unary_op_relu_f32_clamps_negative_to_zero() {
        assert_eq!(<Relu as UnaryOp<f32>>::apply(2.5), 2.5);
        assert_eq!(<Relu as UnaryOp<f32>>::apply(-3.0), 0.0);
        assert_eq!(<Relu as UnaryOp<f32>>::apply(0.0), 0.0);
    }

    #[test]
    fn unary_op_bf16_blanket_routes_through_f32() {
        // Sqr: a value too large to represent precisely in bf16
        // after squaring should round-trip through f32 first. The
        // pre-chassis kernel did the same; bytes must match.
        let x = half::bf16::from_f32(1.5);
        let got = <Sqr as UnaryOp<half::bf16>>::apply(x).to_f32();
        let expect = half::bf16::from_f32(1.5 * 1.5).to_f32();
        assert_eq!(got, expect);
    }

    #[test]
    fn unary_op_gelu_tanh_f32_at_zero_is_zero() {
        assert!(<GeluTanh as UnaryOp<f32>>::apply(0.0).abs() < 1e-6);
    }

    #[test]
    fn unary_op_gelu_tanh_f32_at_one() {
        // gelu_tanh(1) ≈ 0.8412 (tanh approx) per the existing
        // `gelu_at_known_points` test.
        let got = <GeluTanh as UnaryOp<f32>>::apply(1.0);
        assert!((got - 0.841_192).abs() < 1e-3, "got {got}");
    }

    #[test]
    fn unary_op_sign_f32_handles_zero_as_zero() {
        assert_eq!(<Sign as UnaryOp<f32>>::apply(0.0), 0.0);
        assert_eq!(<Sign as UnaryOp<f32>>::apply(5.0), 1.0);
        assert_eq!(<Sign as UnaryOp<f32>>::apply(-5.0), -1.0);
    }

    #[test]
    fn unary_chassis_size_mismatch_errors() {
        let input = CpuStorageBytes::from_slice(&[1.0_f32, 2.0]);
        let mut output = CpuStorageBytes::from_zero_bytes(4); // 1 f32, not 2
        let r = unary::<f32, Neg>("test", &input, &mut output);
        assert!(r.is_err());
    }

    #[test]
    fn unary_chassis_walks_all_elements() {
        let input = CpuStorageBytes::from_slice(&[1.0_f32, -2.0, 3.0, -4.0]);
        let mut output = CpuStorageBytes::from_zero_bytes(input.len_bytes());
        unary::<f32, Neg>("test", &input, &mut output).expect("unary neg_f32");
        let r: &[f32] = output.as_slice().unwrap();
        assert_eq!(r, &[-1.0, 2.0, -3.0, 4.0]);
    }
}