tenferro_tensor/

backend.rs

use crate::config::{
    CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
};
use crate::types::{
    TensorRank, TensorScalar, TensorView, TypedTensor, TypedTensorView, TypedTensorViewMut,
};
use crate::validate::validate_convert_dtype;
use crate::{
    AllocationDomainId, AllocationId, DType, Error, ShapeMismatch, ShapeVec, Tensor, TensorRead,
    TensorValue, TensorWrite, ValidationError,
};
use num_complex::{Complex32, Complex64};

#[cfg(test)]
mod tests;

fn read_boundary_error(op: &'static str) -> crate::Error {
    crate::Error::unsupported(
        op,
        "backend does not accept borrowed tensor views at this execution boundary",
    )
}

fn validation(op: &'static str, source: ValidationError) -> crate::Error {
    Error::validation(op, source)
}

/// Gather any host-owned view, including strided or offset layouts, into a compact owner.
///
/// This backs the default [`TensorStructural::to_contiguous_read`] for host-owned
/// views. Backend-owned storage must be rejected by the caller first; the typed
/// `to_col_major` gather is metadata-driven element copying and never transfers.
fn default_materialize_host_view(view: TensorView<'_>) -> crate::Result<Tensor> {
    fn typed<T: TensorScalar>(view: &TypedTensorView<'_, T>) -> crate::Result<Tensor> {
        view.to_col_major().map(Tensor::from_typed)
    }

    match view {
        TensorView::F32(view) => typed(&view),
        TensorView::F64(view) => typed(&view),
        TensorView::I32(view) => typed(&view),
        TensorView::I64(view) => typed(&view),
        TensorView::Bool(view) => typed(&view),
        TensorView::C32(view) => typed(&view),
        TensorView::C64(view) => typed(&view),
    }
}

fn invalid_argument(op: &'static str, argument: &'static str, message: impl Into<String>) -> Error {
    Error::invalid_argument(op, argument, message)
}

fn read_tensor<'a>(op: &'static str, input: TensorRead<'a>) -> crate::Result<&'a Tensor> {
    input.as_tensor().ok_or_else(|| read_boundary_error(op))
}

/// Return the owned tensor behind `input`, or the read-boundary error for a borrowed view.
///
/// This is the read-half default a backend receives when it implements only the
/// one-shot form of an operation: an owned tensor is delegated to the one-shot
/// method, and a borrowed view is rejected with [`Error::Unsupported`] instead
/// of being silently materialized.
///
/// Issue #1926 makes the `_read` halves required, so an implementor that relied
/// on the previous default reproduces it by calling this function:
///
/// ```text
/// fn reduce_sum_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> Result<Tensor> {
///     self.reduce_sum(read_owned_tensor("reduce_sum", input)?, axes)
/// }
/// ```
#[doc(hidden)]
pub fn read_owned_tensor<'a>(op: &'static str, input: TensorRead<'a>) -> crate::Result<&'a Tensor> {
    read_tensor(op, input)
}

fn validate_axis_list(
    op: &'static str,
    role: &'static str,
    axes: &[usize],
    rank: usize,
) -> crate::Result<()> {
    // A linear scan over the axes already seen keeps this path free of a
    // rank-sized scratch allocation; the axis lists here are short.
    for (index, &axis) in axes.iter().enumerate() {
        if axis >= rank {
            return Err(validation(
                op,
                ValidationError::AxisOutOfBounds { axis, rank },
            ));
        }
        if axes[..index].contains(&axis) {
            return Err(validation(
                op,
                ValidationError::DuplicateAxis { axis, role },
            ));
        }
    }
    Ok(())
}

fn validate_role_disjoint(
    op: &'static str,
    first_role: &'static str,
    first_axes: &[usize],
    second_role: &'static str,
    second_axes: &[usize],
) -> crate::Result<()> {
    for &axis in first_axes {
        if second_axes.contains(&axis) {
            return Err(validation(
                op,
                ValidationError::AxisRoleConflict {
                    axis,
                    first_role,
                    second_role,
                },
            ));
        }
    }
    Ok(())
}

/// Infer the output shape for a validated dot-general operation.
#[doc(hidden)]
pub fn dot_general_output_shape(
    lhs_shape: &[usize],
    rhs_shape: &[usize],
    config: &DotGeneralConfig,
    op: &'static str,
) -> crate::Result<ShapeVec> {
    if config.lhs_contracting_dims.len() != config.rhs_contracting_dims.len() {
        return Err(invalid_argument(
            op,
            "contracting_dims",
            "lhs/rhs contracting dim counts differ",
        ));
    }
    if config.lhs_batch_dims.len() != config.rhs_batch_dims.len() {
        return Err(invalid_argument(
            op,
            "batch_dims",
            "lhs/rhs batch dim counts differ",
        ));
    }

    let lhs_rank = lhs_shape.len();
    let rhs_rank = rhs_shape.len();
    validate_axis_list(
        op,
        "lhs_contracting",
        &config.lhs_contracting_dims,
        lhs_rank,
    )?;
    validate_axis_list(
        op,
        "rhs_contracting",
        &config.rhs_contracting_dims,
        rhs_rank,
    )?;
    validate_axis_list(op, "lhs_batch", &config.lhs_batch_dims, lhs_rank)?;
    validate_axis_list(op, "rhs_batch", &config.rhs_batch_dims, rhs_rank)?;
    validate_role_disjoint(
        op,
        "lhs_contracting",
        &config.lhs_contracting_dims,
        "lhs_batch",
        &config.lhs_batch_dims,
    )?;
    validate_role_disjoint(
        op,
        "rhs_contracting",
        &config.rhs_contracting_dims,
        "rhs_batch",
        &config.rhs_batch_dims,
    )?;

    for (&lhs_axis, &rhs_axis) in config
        .lhs_contracting_dims
        .iter()
        .zip(&config.rhs_contracting_dims)
    {
        if lhs_shape[lhs_axis] != rhs_shape[rhs_axis] {
            return Err(validation(
                op,
                ShapeMismatch::ContractedDimensions {
                    lhs_axis,
                    lhs_size: lhs_shape[lhs_axis],
                    rhs_axis,
                    rhs_size: rhs_shape[rhs_axis],
                }
                .into(),
            ));
        }
    }
    for (&lhs_axis, &rhs_axis) in config.lhs_batch_dims.iter().zip(&config.rhs_batch_dims) {
        if lhs_shape[lhs_axis] != rhs_shape[rhs_axis] {
            return Err(validation(
                op,
                ShapeMismatch::ContractedDimensions {
                    lhs_axis,
                    lhs_size: lhs_shape[lhs_axis],
                    rhs_axis,
                    rhs_size: rhs_shape[rhs_axis],
                }
                .into(),
            ));
        }
    }

    let lhs_free = (0..lhs_rank)
        .filter(|axis| {
            !config.lhs_contracting_dims.contains(axis) && !config.lhs_batch_dims.contains(axis)
        })
        .map(|axis| lhs_shape[axis]);
    let rhs_free = (0..rhs_rank)
        .filter(|axis| {
            !config.rhs_contracting_dims.contains(axis) && !config.rhs_batch_dims.contains(axis)
        })
        .map(|axis| rhs_shape[axis]);
    let batch = config.lhs_batch_dims.iter().map(|&axis| lhs_shape[axis]);

    // Inline for common ranks: the eager dot entry builds this on every call.
    Ok(lhs_free.chain(rhs_free).chain(batch).collect())
}

/// Validate output dtype and shape for dot-general read-into dispatch.
#[doc(hidden)]
pub fn validate_dot_general_read_into(
    lhs: &TensorRead<'_>,
    rhs: &TensorRead<'_>,
    config: &DotGeneralConfig,
    out: &TensorWrite<'_>,
    op: &'static str,
) -> crate::Result<ShapeVec> {
    if lhs.dtype() != rhs.dtype() {
        return Err(validation(
            op,
            ValidationError::DTypeMismatch {
                expected: lhs.dtype(),
                actual: rhs.dtype(),
            },
        ));
    }
    if lhs.dtype() != out.dtype() {
        return Err(validation(
            op,
            ValidationError::DTypeMismatch {
                expected: lhs.dtype(),
                actual: out.dtype(),
            },
        ));
    }
    let expected = dot_general_output_shape(lhs.shape(), rhs.shape(), config, op)?;
    if out.shape() != expected.as_slice() {
        return Err(validation(
            op,
            ShapeMismatch::ExpectedActual {
                expected: expected.clone(),
                actual: out.shape().iter().copied().collect(),
            }
            .into(),
        ));
    }
    Ok(expected)
}

/// Scalar coefficient accepted by contraction accumulation backends.
///
/// `ContractionScalar` is intentionally narrower than [`crate::TensorScalar`]:
/// dot-general accumulation is only defined for floating and complex tensor
/// dtypes.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{ContractionScalar, DType};
///
/// let alpha = ContractionScalar::F64(2.0);
/// assert_eq!(alpha.dtype(), DType::F64);
/// ```
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum ContractionScalar {
    F32(f32),
    F64(f64),
    C32(Complex32),
    C64(Complex64),
}

impl ContractionScalar {
    /// Return this scalar's tensor dtype.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DType};
    ///
    /// assert_eq!(ContractionScalar::F32(1.0).dtype(), DType::F32);
    /// ```
    pub fn dtype(self) -> DType {
        match self {
            Self::F32(_) => DType::F32,
            Self::F64(_) => DType::F64,
            Self::C32(_) => DType::C32,
            Self::C64(_) => DType::C64,
        }
    }

    /// Return the multiplicative identity for a supported contraction dtype.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DType};
    ///
    /// assert_eq!(ContractionScalar::one(DType::F64).unwrap(), ContractionScalar::F64(1.0));
    /// assert!(ContractionScalar::one(DType::I32).is_err());
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a
    /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` is `I32`,
    /// `I64`, or `Bool`, which do not support contraction scalar identities.
    pub fn one(dtype: DType) -> crate::Result<Self> {
        match dtype {
            DType::F32 => Ok(Self::F32(1.0)),
            DType::F64 => Ok(Self::F64(1.0)),
            DType::C32 => Ok(Self::C32(Complex32::new(1.0, 0.0))),
            DType::C64 => Ok(Self::C64(Complex64::new(1.0, 0.0))),
            DType::I32 | DType::I64 | DType::Bool | DType::External(_) => Err(validation(
                "ContractionScalar::one",
                ValidationError::DTypeMismatch {
                    expected: dtype,
                    actual: DType::F32,
                },
            )),
        }
    }

    /// Return the additive identity for a supported contraction dtype.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DType};
    ///
    /// assert_eq!(ContractionScalar::zero(DType::F64).unwrap(), ContractionScalar::F64(0.0));
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a
    /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` is `I32`,
    /// `I64`, or `Bool`, which do not support contraction scalar identities.
    pub fn zero(dtype: DType) -> crate::Result<Self> {
        match dtype {
            DType::F32 => Ok(Self::F32(0.0)),
            DType::F64 => Ok(Self::F64(0.0)),
            DType::C32 => Ok(Self::C32(Complex32::new(0.0, 0.0))),
            DType::C64 => Ok(Self::C64(Complex64::new(0.0, 0.0))),
            DType::I32 | DType::I64 | DType::Bool | DType::External(_) => Err(validation(
                "ContractionScalar::zero",
                ValidationError::DTypeMismatch {
                    expected: dtype,
                    actual: DType::F32,
                },
            )),
        }
    }
}

/// Output-update semantics for dot-general accumulation.
///
/// This keeps contraction axes in [`DotGeneralConfig`] and output update
/// semantics here, so cached and non-cached backend traits can share the same
/// accumulation contract.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation, DType};
///
/// let accum = DotGeneralAccumulation::overwrite(DType::F64).unwrap();
/// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
/// assert_eq!(accum.beta, ContractionScalar::F64(0.0));
/// ```
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct DotGeneralAccumulation {
    pub lhs_conj: bool,
    pub rhs_conj: bool,
    pub alpha: ContractionScalar,
    pub beta: ContractionScalar,
}

impl DotGeneralAccumulation {
    fn identity(
        op: &'static str,
        dtype: DType,
        multiplicative: bool,
    ) -> crate::Result<ContractionScalar> {
        let result = if multiplicative {
            ContractionScalar::one(dtype)
        } else {
            ContractionScalar::zero(dtype)
        };
        result.map_err(|error| match error {
            Error::Validation { source, .. } => validation(op, source),
            error => error,
        })
    }

    /// Return overwrite semantics, `out = lhs dot rhs`, for `dtype`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation, DType};
    ///
    /// let accum = DotGeneralAccumulation::overwrite(DType::F64).unwrap();
    /// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
    /// assert_eq!(accum.beta, ContractionScalar::F64(0.0));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a
    /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` does not
    /// support contraction scalar identities.
    pub fn overwrite(dtype: DType) -> crate::Result<Self> {
        Ok(Self {
            lhs_conj: false,
            rhs_conj: false,
            alpha: Self::identity("DotGeneralAccumulation::overwrite", dtype, true)?,
            beta: Self::identity("DotGeneralAccumulation::overwrite", dtype, false)?,
        })
    }

    /// Return additive update semantics, `out += lhs dot rhs`, for `dtype`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DType, DotGeneralAccumulation};
    ///
    /// let accum = DotGeneralAccumulation::add_to(DType::F64)?;
    /// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
    /// assert_eq!(accum.beta, ContractionScalar::F64(1.0));
    /// # Ok::<(), tenferro_tensor::Error>(())
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a
    /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` does not
    /// support contraction scalar identities.
    pub fn add_to(dtype: DType) -> crate::Result<Self> {
        Ok(Self {
            lhs_conj: false,
            rhs_conj: false,
            alpha: Self::identity("DotGeneralAccumulation::add_to", dtype, true)?,
            beta: Self::identity("DotGeneralAccumulation::add_to", dtype, true)?,
        })
    }

    /// Return scaled update semantics, `out = alpha * lhs dot rhs + beta * out`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation};
    ///
    /// let accum = DotGeneralAccumulation::scaled(
    ///     ContractionScalar::F32(0.5),
    ///     ContractionScalar::F32(2.0),
    /// )?;
    /// assert_eq!(accum.alpha, ContractionScalar::F32(0.5));
    /// # Ok::<(), tenferro_tensor::Error>(())
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a
    /// [`crate::ValidationError::DTypeMismatch`] source when `alpha` and `beta`
    /// have different dtypes.
    pub fn scaled(alpha: ContractionScalar, beta: ContractionScalar) -> crate::Result<Self> {
        if alpha.dtype() != beta.dtype() {
            return Err(validation(
                "DotGeneralAccumulation::scaled",
                ValidationError::DTypeMismatch {
                    expected: alpha.dtype(),
                    actual: beta.dtype(),
                },
            ));
        }
        Ok(Self {
            lhs_conj: false,
            rhs_conj: false,
            alpha,
            beta,
        })
    }

    fn validate_for_dtype(self, dtype: DType) -> crate::Result<()> {
        for scalar in [self.alpha, self.beta] {
            if scalar.dtype() != dtype {
                return Err(validation(
                    "dot_general",
                    ValidationError::DTypeMismatch {
                        expected: scalar.dtype(),
                        actual: dtype,
                    },
                ));
            }
        }
        Ok(())
    }
}

#[doc(hidden)]
pub fn validate_dot_general_accumulation(
    lhs: &TensorRead<'_>,
    rhs: &TensorRead<'_>,
    config: &DotGeneralConfig,
    accumulation: DotGeneralAccumulation,
    out: &TensorWrite<'_>,
    op: &'static str,
) -> crate::Result<ShapeVec> {
    let shape = validate_dot_general_read_into(lhs, rhs, config, out, op)?;
    accumulation.validate_for_dtype(lhs.dtype())?;
    Ok(shape)
}

#[doc(hidden)]
pub fn dot_general_accum_via_temp<B: TensorDot + ?Sized>(
    backend: &mut B,
    lhs: TensorRead<'_>,
    rhs: TensorRead<'_>,
    config: &DotGeneralConfig,
    accumulation: DotGeneralAccumulation,
    mut out: TensorWrite<'_>,
) -> crate::Result<()> {
    validate_dot_general_accumulation(&lhs, &rhs, config, accumulation, &out, "dot_general")?;
    let dot = backend.dot_general_with_conj_read(
        lhs,
        rhs,
        config,
        accumulation.lhs_conj,
        accumulation.rhs_conj,
    )?;
    accumulate_dot_result_into(&dot, accumulation, &mut out)
}

#[doc(hidden)]
pub fn accumulate_dot_result_into(
    dot: &Tensor,
    accumulation: DotGeneralAccumulation,
    out: &mut TensorWrite<'_>,
) -> crate::Result<()> {
    macro_rules! dispatch {
        ($variant:ident, $ty:ty) => {
            if dot.dtype() == <$ty as crate::TensorScalar>::dtype() {
                let (ContractionScalar::$variant(alpha), ContractionScalar::$variant(beta)) =
                    (accumulation.alpha, accumulation.beta)
                else {
                    return Err(validation(
                        "dot_general",
                        ValidationError::DTypeMismatch {
                            expected: dot.dtype(),
                            actual: accumulation.alpha.dtype(),
                        },
                    ));
                };
                let dot = dot
                    .as_typed::<$ty>()
                    .expect("the dtype guard selects this arm");
                match out {
                    TensorWrite::Tensor(out) => {
                        let out = out
                            .as_typed_mut::<$ty>()
                            .expect("the dtype guard selects this arm");
                        let mut out = out.as_view_mut();
                        accumulate_typed(dot.as_slice()?, alpha, beta, &mut out)?;
                        return Ok(());
                    }
                    TensorWrite::View(crate::TensorViewMut::$variant(out)) => {
                        accumulate_typed(dot.as_slice()?, alpha, beta, out)?;
                        return Ok(());
                    }
                    _ => {}
                }
            }
        };
    }

    dispatch!(F32, f32);
    dispatch!(F64, f64);
    dispatch!(C32, Complex32);
    dispatch!(C64, Complex64);

    Err(validation(
        "dot_general",
        ValidationError::DTypeMismatch {
            expected: accumulation.alpha.dtype(),
            actual: dot.dtype(),
        },
    ))
}

fn accumulate_typed<T>(
    dot: &[T],
    alpha: T,
    beta: T,
    out: &mut TypedTensorViewMut<'_, T>,
) -> crate::Result<()>
where
    T: Copy
        + PartialEq
        + std::ops::Add<Output = T>
        + std::ops::Mul<Output = T>
        + num_traits::Zero
        + 'static,
{
    let beta_is_zero = beta == T::zero();
    if let Some(output) = compact_host_accumulation_slice(out, dot.len())? {
        for (output, dot_value) in output.iter_mut().zip(dot.iter().copied()) {
            // INVARIANT: beta == 0 follows BLAS GEMM semantics and does not read
            // the existing output element; beta != 0 requires an initialized
            // TensorWrite target and performs a read-modify-write update.
            *output = if beta_is_zero {
                alpha * dot_value
            } else {
                alpha * dot_value + beta * *output
            };
        }
        return Ok(());
    }

    for (linear, dot_value) in dot.iter().copied().enumerate() {
        let indices = flat_to_multi_for_shape(out.shape(), linear);
        let output = out.get_mut(&indices).ok_or_else(|| {
            invalid_argument(
                "dot_general",
                "output",
                format!("index {indices:?} is outside accumulation target"),
            )
        })?;
        // INVARIANT: beta == 0 follows BLAS GEMM semantics and does not read
        // the existing output element; beta != 0 requires an initialized
        // TensorWrite target and performs a read-modify-write update.
        *output = if beta_is_zero {
            alpha * dot_value
        } else {
            alpha * dot_value + beta * *output
        };
    }
    Ok(())
}

fn compact_host_accumulation_slice<'a, T: 'static>(
    out: &'a mut TypedTensorViewMut<'_, T>,
    expected_len: usize,
) -> crate::Result<Option<&'a mut [T]>> {
    if out.backend_buffer().is_some()
        || out.n_elements() != expected_len
        || !out.is_col_major_contiguous()?
    {
        return Ok(None);
    }

    let start = usize::try_from(out.offset()).map_err(|_| {
        invalid_argument("dot_general", "output", "compact output offset is negative")
    })?;
    let end = start
        .checked_add(expected_len)
        .ok_or_else(|| validation("dot_general", ValidationError::IntegerOverflow))?;
    out.host_storage_mut()?
        .get_mut(start..end)
        .map(Some)
        .ok_or_else(|| {
            invalid_argument(
                "dot_general",
                "output",
                "compact output is outside its backing storage",
            )
        })
}

fn flat_to_multi_for_shape(shape: &[usize], mut linear: usize) -> Vec<usize> {
    let mut indices = Vec::with_capacity(shape.len());
    for &dim in shape {
        if dim == 0 {
            indices.push(0);
        } else {
            indices.push(linear % dim);
            linear /= dim;
        }
    }
    indices
}

/// Canonical elementwise fusion plan shared between segmented execution and backends.
#[doc(hidden)]
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct ElementwiseFusionPlan {
    dtype: crate::DType,
    input_count: usize,
    // Keep view metadata in Vecs. A/B benchmarking on the broadcast_mul
    // path showed SmallVec made this metadata path about 6-7% slower.
    input_views: Vec<ElementwiseFusionInputView>,
    outputs: Vec<usize>,
    ops: Vec<ElementwiseFusionInst>,
}

/// Metadata-only view applied to one backend fusion input.
#[doc(hidden)]
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub enum ElementwiseFusionInputView {
    Identity,
    BroadcastInDim {
        // Vec is intentional here; see ElementwiseFusionPlan::input_views.
        shape: Vec<usize>,
        dims: Vec<usize>,
    },
}

/// One node in a canonical elementwise fusion plan.
#[doc(hidden)]
#[derive(Clone, Debug, Hash, PartialEq, Eq)]
pub struct ElementwiseFusionInst {
    op: ElementwiseFusionOp,
    inputs: Vec<usize>,
}

tenferro_core_ops::define_elementwise_fusion_op!();

impl ElementwiseFusionPlan {
    /// Build a backend elementwise fusion plan.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{
    ///     ElementwiseFusionInst, ElementwiseFusionOp, ElementwiseFusionPlan,
    /// };
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::new(
    ///     DType::F64,
    ///     2,
    ///     vec![2],
    ///     vec![ElementwiseFusionInst::new(ElementwiseFusionOp::Add, vec![0, 1])],
    /// );
    /// assert_eq!(plan.input_count(), 2);
    /// ```
    pub fn new(
        dtype: crate::DType,
        input_count: usize,
        outputs: Vec<usize>,
        ops: Vec<ElementwiseFusionInst>,
    ) -> Self {
        Self::with_input_views(
            dtype,
            vec![ElementwiseFusionInputView::Identity; input_count],
            outputs,
            ops,
        )
    }

    /// Build a backend elementwise fusion plan with input view metadata.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{
    ///     ElementwiseFusionInputView, ElementwiseFusionInst, ElementwiseFusionOp,
    ///     ElementwiseFusionPlan,
    /// };
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::with_input_views(
    ///     DType::F64,
    ///     vec![ElementwiseFusionInputView::broadcast_in_dim(vec![2, 3], vec![0])],
    ///     vec![1],
    ///     vec![ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0])],
    /// );
    /// assert_eq!(plan.input_count(), 1);
    /// ```
    pub fn with_input_views(
        dtype: crate::DType,
        input_views: impl IntoIterator<Item = ElementwiseFusionInputView>,
        outputs: Vec<usize>,
        ops: Vec<ElementwiseFusionInst>,
    ) -> Self {
        let input_views = input_views.into_iter().collect::<Vec<_>>();
        let input_count = input_views.len();
        Self {
            dtype,
            input_count,
            input_views,
            outputs,
            ops,
        }
    }

    /// Return the scalar dtype expected by this fusion plan.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionPlan;
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::new(DType::F32, 0, Vec::new(), Vec::new());
    /// assert_eq!(plan.dtype(), DType::F32);
    /// ```
    pub fn dtype(&self) -> crate::DType {
        self.dtype
    }

    /// Return the number of input tensors expected by this plan.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionPlan;
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::new(DType::F64, 3, Vec::new(), Vec::new());
    /// assert_eq!(plan.input_count(), 3);
    /// ```
    pub fn input_count(&self) -> usize {
        self.input_count
    }

    /// Return metadata views applied to fusion inputs before executing ops.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionPlan;
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::new(DType::F64, 2, Vec::new(), Vec::new());
    /// assert_eq!(plan.input_views().len(), 2);
    /// ```
    pub fn input_views(&self) -> &[ElementwiseFusionInputView] {
        &self.input_views
    }

    /// Return the value ids selected as fusion outputs.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionPlan;
    /// use tenferro_tensor::DType;
    ///
    /// let plan = ElementwiseFusionPlan::new(DType::F64, 0, vec![0], Vec::new());
    /// assert_eq!(plan.outputs(), &[0]);
    /// ```
    pub fn outputs(&self) -> &[usize] {
        &self.outputs
    }

    /// Return the fused elementwise instruction sequence.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{
    ///     ElementwiseFusionInst, ElementwiseFusionOp, ElementwiseFusionPlan,
    /// };
    /// use tenferro_tensor::DType;
    ///
    /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0]);
    /// let plan = ElementwiseFusionPlan::new(DType::F64, 1, vec![1], vec![inst]);
    /// assert_eq!(plan.ops().len(), 1);
    /// ```
    pub fn ops(&self) -> &[ElementwiseFusionInst] {
        &self.ops
    }
}

impl ElementwiseFusionInputView {
    /// Build metadata for a `BroadcastInDim` fusion input view.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionInputView;
    ///
    /// let view = ElementwiseFusionInputView::broadcast_in_dim(vec![2, 3], vec![0]);
    /// assert!(matches!(view, ElementwiseFusionInputView::BroadcastInDim { .. }));
    /// ```
    pub fn broadcast_in_dim(
        shape: impl IntoIterator<Item = usize>,
        dims: impl IntoIterator<Item = usize>,
    ) -> Self {
        Self::BroadcastInDim {
            shape: shape.into_iter().collect(),
            dims: dims.into_iter().collect(),
        }
    }

    /// Return true when this fusion input is an identity view.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::ElementwiseFusionInputView;
    ///
    /// assert!(ElementwiseFusionInputView::Identity.is_identity());
    /// ```
    pub fn is_identity(&self) -> bool {
        matches!(self, Self::Identity)
    }
}

impl ElementwiseFusionInst {
    /// Build a backend elementwise fusion instruction.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
    ///
    /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Add, vec![0, 1]);
    /// assert_eq!(inst.inputs(), &[0, 1]);
    /// ```
    pub fn new(op: ElementwiseFusionOp, inputs: Vec<usize>) -> Self {
        Self { op, inputs }
    }

    /// Return the elementwise op executed by this instruction.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
    ///
    /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0]);
    /// assert_eq!(inst.op(), ElementwiseFusionOp::Negate);
    /// ```
    pub fn op(&self) -> ElementwiseFusionOp {
        self.op
    }

    /// Return this instruction's input value ids.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
    ///
    /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Multiply, vec![2, 0]);
    /// assert_eq!(inst.inputs(), &[2, 0]);
    /// ```
    pub fn inputs(&self) -> &[usize] {
        &self.inputs
    }
}

/// Runtime operation selected by [`TensorElementwise::elementwise_read_into`].
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ElementwiseReadOp {
    /// Binary addition.
    Add,
    /// Binary subtraction.
    Subtract,
    /// Binary multiplication.
    Multiply,
    /// Unary negation.
    Negate,
    /// Unary conjugation.
    Conj,
    /// Binary division.
    Divide,
}

/// Fused real-float activation applied in one elementwise pass.
///
/// The variants name the same functions the composite activation vocabulary
/// exposes; a backend that supports the fused form computes the whole
/// expression in one traversal instead of materializing every intermediate.
///
/// # Examples
///
/// ```
/// use tenferro_tensor::ActivationOp;
/// assert_eq!(ActivationOp::Sigmoid.label(), "sigmoid");
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ActivationOp {
    /// Logistic sigmoid `1 / (1 + exp(-x))`, overflow-free.
    Sigmoid,
    /// SiLU / swish `x * sigmoid(x)`.
    Silu,
    /// Softplus `max(x, 0) + log1p(exp(-|x|))`.
    Softplus,
    /// Exact GELU `x/2 * (1 + erf(x / sqrt(2)))`.
    Gelu,
    /// GELU tanh approximation `x/2 * (1 + tanh(sqrt(2/pi) * (x + 0.044715 x^3)))`.
    GeluTanh,
}

impl ActivationOp {
    /// Stable operation label used in errors and profiling.
    #[doc(hidden)]
    pub fn label(self) -> &'static str {
        match self {
            Self::Sigmoid => "sigmoid",
            Self::Silu => "silu",
            Self::Softplus => "softplus",
            Self::Gelu => "gelu",
            Self::GeluTanh => "gelu_tanh",
        }
    }
}

impl ElementwiseReadOp {
    #[doc(hidden)]
    pub fn label(self) -> &'static str {
        match self {
            Self::Add => "add",
            Self::Subtract => "sub",
            Self::Multiply => "mul",
            Self::Negate => "neg",
            Self::Conj => "conj",
            Self::Divide => "div",
        }
    }

    #[doc(hidden)]
    pub fn arity(self) -> usize {
        match self {
            Self::Negate | Self::Conj => 1,
            Self::Add | Self::Subtract | Self::Multiply | Self::Divide => 2,
        }
    }
}

#[derive(Clone, Copy, Debug)]
enum StorageIdentity {
    Host {
        start: usize,
        end: usize,
    },
    Backend {
        domain: Option<AllocationDomainId>,
        allocation: Option<AllocationId>,
        family: &'static str,
        object: usize,
    },
}

fn host_storage_identity<T>(data: &[T]) -> StorageIdentity {
    let start = data.as_ptr() as usize;
    let bytes = std::mem::size_of_val(data);
    StorageIdentity::Host {
        start,
        end: start.saturating_add(bytes),
    }
}

fn backend_storage_identity<T: 'static>(buffer: &dyn crate::BackendStorage<T>) -> StorageIdentity {
    StorageIdentity::Backend {
        domain: buffer.allocation_domain(),
        allocation: buffer.allocation_id(),
        family: buffer.backend_family(),
        // INVARIANT: every backend buffer is borrowed from the single Box-owned
        // root allocation; the data pointer of this trait object is stable for
        // that owner and is used only as a fallback when provider identity is
        // unavailable.
        object: buffer as *const dyn crate::BackendStorage<T> as *const () as usize,
    }
}

fn typed_tensor_storage_identity<T: crate::TensorScalar>(
    tensor: &TypedTensor<T>,
) -> crate::Result<StorageIdentity> {
    if tensor.backend_buffer().is_some() {
        let buffer = tensor.backend_buffer().ok_or_else(|| {
            crate::Error::runtime_state("typed_tensor_storage_identity", "backend buffer missing")
        })?;
        Ok(backend_storage_identity(buffer))
    } else {
        Ok(host_storage_identity(tensor.host_data()?))
    }
}

fn typed_view_storage_identity<T: crate::TensorScalar + 'static>(
    view: &TypedTensorView<'_, T>,
) -> crate::Result<StorageIdentity> {
    match view.backend_buffer() {
        Some(buffer) => Ok(backend_storage_identity(buffer)),
        None => view.host_storage().map(host_storage_identity),
    }
}

/// The typed tensor behind `value`, or the refusal this module reports for one.
///
/// Callers reach this from a match on the dtype, so `None` means the tag and the runtime dtype
/// disagree rather than a caller mistake.
fn identity_operand<T: TensorScalar>(value: &Tensor) -> crate::Result<&TypedTensor<T>> {
    value.as_typed::<T>().ok_or_else(|| {
        crate::Error::unsupported_dtype(
            "storage_identity",
            value.dtype(),
            "an externally defined payload has no storage identity",
        )
    })
}

fn tensor_read_storage_identity(input: &TensorRead<'_>) -> crate::Result<StorageIdentity> {
    macro_rules! typed_identity {
        ($value:expr) => {
            match $value.dtype() {
                DType::F32 => typed_tensor_storage_identity(identity_operand::<f32>($value)?),
                DType::F64 => typed_tensor_storage_identity(identity_operand::<f64>($value)?),
                DType::I32 => typed_tensor_storage_identity(identity_operand::<i32>($value)?),
                DType::I64 => typed_tensor_storage_identity(identity_operand::<i64>($value)?),
                DType::Bool => typed_tensor_storage_identity(identity_operand::<bool>($value)?),
                DType::C32 => typed_tensor_storage_identity(identity_operand::<Complex32>($value)?),
                DType::C64 => typed_tensor_storage_identity(identity_operand::<Complex64>($value)?),
                // A caller-owned payload has no allocation identity, so it cannot
                // take part in an aliasing check.
                DType::External(_) => {
                    return Err(crate::Error::unsupported_dtype(
                        "storage_identity",
                        $value.dtype(),
                        "an externally defined payload has no storage identity",
                    ));
                }
            }
        };
    }
    macro_rules! view_identity {
        ($value:expr) => {
            match $value {
                TensorView::F32(value) => typed_view_storage_identity(value),
                TensorView::F64(value) => typed_view_storage_identity(value),
                TensorView::I32(value) => typed_view_storage_identity(value),
                TensorView::I64(value) => typed_view_storage_identity(value),
                TensorView::Bool(value) => typed_view_storage_identity(value),
                TensorView::C32(value) => typed_view_storage_identity(value),
                TensorView::C64(value) => typed_view_storage_identity(value),
            }
        };
    }

    match input {
        TensorRead::Tensor(tensor) => typed_identity!(tensor),
        TensorRead::View(view) => view_identity!(view),
    }
}

fn storage_overlaps(lhs: StorageIdentity, rhs: StorageIdentity) -> bool {
    match (lhs, rhs) {
        (
            StorageIdentity::Host {
                start: lhs_start,
                end: lhs_end,
            },
            StorageIdentity::Host {
                start: rhs_start,
                end: rhs_end,
            },
        ) => lhs_start < rhs_end && rhs_start < lhs_end,
        (
            StorageIdentity::Backend {
                domain: lhs_domain,
                allocation: lhs_allocation,
                family: lhs_family,
                object: lhs_object,
            },
            StorageIdentity::Backend {
                domain: rhs_domain,
                allocation: rhs_allocation,
                family: rhs_family,
                object: rhs_object,
            },
        ) => {
            lhs_object == rhs_object
                || matches!(
                    (lhs_domain, rhs_domain, lhs_allocation, rhs_allocation),
                    (Some(lhs_domain), Some(rhs_domain), Some(lhs), Some(rhs))
                        if lhs_domain == rhs_domain && lhs == rhs
                )
                || matches!(
                    (lhs_domain, rhs_domain, lhs_allocation, rhs_allocation),
                    (None, None, Some(lhs), Some(rhs)) if lhs_family == rhs_family && lhs == rhs
                )
        }
        _ => false,
    }
}

/// Validate that a caller-owned destination does not overlap any read input.
///
/// The check is intentionally conservative for host views: two views backed by
/// the same host allocation are treated as overlapping because the allocation
/// identity is the only stable boundary contract available to erased backend
/// code. Backend allocations use their domain/allocation identity when the
/// provider exposes it.
///
/// # Errors
///
/// Returns `tenferro_tensor_core::ValidationError::InvalidArgument` when the
/// destination storage overlaps an input, or `Error::RuntimeState` when
/// storage identity cannot be established safely.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{Tensor, TensorRead, TensorWrite};
/// use tenferro_tensor::backend::validate_read_into_destination;
///
/// let input = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
/// let mut output = Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?;
/// validate_read_into_destination(
///     "example",
///     &[TensorRead::from_tensor(&input)],
///     &TensorWrite::from_tensor(&mut output),
/// )?;
/// # Ok::<(), tenferro_tensor::Error>(())
/// ```
pub fn validate_read_into_destination(
    op: &'static str,
    inputs: &[TensorRead<'_>],
    out: &TensorWrite<'_>,
) -> crate::Result<()> {
    let output_identity = tensor_read_storage_identity(&out.as_read())?;
    for (index, input) in inputs.iter().enumerate() {
        if storage_overlaps(tensor_read_storage_identity(input)?, output_identity) {
            return Err(Error::invalid_argument(
                op,
                "out",
                format!("destination storage overlaps input {index}"),
            ));
        }
    }
    Ok(())
}

/// Execute a read-into elementwise operation through a backend's allocating operations.
///
/// Backend implementations use this helper when their device-native operation
/// APIs already provide the correct placement and copy semantics. It deliberately
/// does not inspect or transfer storage across devices.
///
/// # Errors
///
/// Returns [`Error::Validation`] for wrong arity or overlapping output storage,
/// and propagates the selected backend operation and copy errors.
#[doc(hidden)]
pub fn elementwise_read_into_via_allocating_ops<B: TensorElementwise + ?Sized>(
    backend: &mut B,
    op: ElementwiseReadOp,
    inputs: &[TensorRead<'_>],
    out: TensorWrite<'_>,
) -> crate::Result<()> {
    if inputs.len() != op.arity() {
        return Err(Error::invalid_argument(
            op.label(),
            "inputs",
            format!("expected {} inputs, got {}", op.arity(), inputs.len()),
        ));
    }
    validate_read_into_destination(op.label(), inputs, &out)?;
    let result = match op {
        ElementwiseReadOp::Add => backend.add_read(inputs[0].clone(), inputs[1].clone())?,
        ElementwiseReadOp::Subtract => backend.sub_read(inputs[0].clone(), inputs[1].clone())?,
        ElementwiseReadOp::Multiply => backend.mul_read(inputs[0].clone(), inputs[1].clone())?,
        ElementwiseReadOp::Negate => backend.neg_read(inputs[0].clone())?,
        ElementwiseReadOp::Conj => backend.conj_read(inputs[0].clone())?,
        ElementwiseReadOp::Divide => backend.div_read(inputs[0].clone(), inputs[1].clone())?,
    };
    backend.copy_read_into(TensorRead::from_tensor(&result), out)
}

/// Elementwise tensor operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorElementwise;
///
/// fn accepts_elementwise<B: TensorElementwise>(_backend: &mut B) {}
/// ```
pub trait TensorElementwise: TensorStructural {
    /// Execute an elementwise operation into caller-owned storage.
    ///
    /// Every backend must implement this hook with its explicit execution
    /// context, placement checks, and output-storage policy. The hook is the
    /// backend boundary for borrowed inputs and caller-owned output; it must not
    /// silently transfer data between devices.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{ElementwiseReadOp, TensorElementwise, TensorRead, TensorWrite};
    ///
    /// fn run_into<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()> {
    ///     backend.elementwise_read_into(ElementwiseReadOp::Conj, &[input], out)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] for invalid arity, metadata, or
    /// overlapping storage. Backend-specific placement, unsupported-operation,
    /// and execution errors are returned unchanged by the implementation.
    fn elementwise_read_into(
        &mut self,
        op: ElementwiseReadOp,
        inputs: &[TensorRead<'_>],
        out: TensorWrite<'_>,
    ) -> crate::Result<()>;

    /// Elementwise addition accepting either owned tensors or borrowed views.
    ///
    /// Backends that implement this method must not silently move data across
    /// devices. A backend that cannot consume views should return an explicit
    /// backend error rather than materializing or transferring implicitly.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
    ///
    /// fn add_owned<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: &Tensor,
    ///     rhs: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.add_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn add_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise addition.
    ///
    /// `_into` methods never accumulate into the previous output value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorElementwise, TensorWrite};
    ///
    /// fn add_into<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: &Tensor,
    ///     rhs: &Tensor,
    ///     mut out: Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.add_into(lhs, rhs, TensorWrite::from_tensor(&mut out))?;
    ///     Ok(out)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn add_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.add_read_into(
            TensorRead::from_tensor(lhs),
            TensorRead::from_tensor(rhs),
            out,
        )
    }

    /// Overwrite caller-provided output with elementwise addition from reads.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, TensorRead, TensorWrite};
    ///
    /// fn add_read_into<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()> {
    ///     backend.add_read_into(lhs, rhs, out)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn add_read_into(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Add, &[lhs, rhs], out)
    }

    /// Elementwise subtraction accepting either owned tensors or borrowed views.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
    ///
    /// fn sub_owned<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: &Tensor,
    ///     rhs: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.sub_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sub_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise subtraction.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sub_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.sub_read_into(
            TensorRead::from_tensor(lhs),
            TensorRead::from_tensor(rhs),
            out,
        )
    }

    /// Overwrite caller-provided output with elementwise subtraction from reads.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sub_read_into(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Subtract, &[lhs, rhs], out)
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn mul_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.mul_read(lhs, rhs)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn mul_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise multiplication.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn mul_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.mul_read_into(
            TensorRead::from_tensor(lhs),
            TensorRead::from_tensor(rhs),
            out,
        )
    }

    /// Overwrite caller-provided output with elementwise multiplication from reads.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn mul_read_into(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Multiply, &[lhs, rhs], out)
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn neg_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.neg_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn neg_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise negation.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn neg_into(&mut self, input: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.neg_read_into(TensorRead::from_tensor(input), out)
    }

    /// Overwrite caller-provided output with elementwise negation from a read.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn neg_read_into(&mut self, input: TensorRead<'_>, out: TensorWrite<'_>) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Negate, &[input], out)
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn conj_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.conj_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn conj_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise conjugation.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn conj_into(&mut self, input: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.conj_read_into(TensorRead::from_tensor(input), out)
    }

    /// Overwrite caller-provided output with elementwise conjugation from a read.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn conj_read_into(&mut self, input: TensorRead<'_>, out: TensorWrite<'_>) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Conj, &[input], out)
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn div_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.div_read(lhs, rhs)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn div_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with elementwise division.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn div_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
        self.div_read_into(
            TensorRead::from_tensor(lhs),
            TensorRead::from_tensor(rhs),
            out,
        )
    }

    /// Overwrite caller-provided output with elementwise division from reads.
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn div_read_into(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        self.elementwise_read_into(ElementwiseReadOp::Divide, &[lhs, rhs], out)
    }

    /// Elementwise remainder.
    ///
    /// The default is an explicit unsupported error so backend implementors can
    /// opt in without silent fallback.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorElementwise};
    ///
    /// fn rem_owned<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: &Tensor,
    ///     rhs: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.rem(lhs, rhs)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn rem(&mut self, lhs: &Tensor, _rhs: &Tensor) -> crate::Result<Tensor> {
        Err(crate::Error::unsupported(
            "rem",
            format!("backend does not implement rem for dtype {:?}", lhs.dtype()),
        ))
    }

    /// Elementwise remainder accepting owned tensors or borrowed views.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
    ///
    /// fn rem_read<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: &Tensor,
    ///     rhs: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.rem_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn rem_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor> {
        self.rem(read_tensor("rem", lhs)?, read_tensor("rem", rhs)?)
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn abs_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.abs_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn abs_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn sign_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.sign_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sign_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn maximum_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.maximum_read(lhs, rhs)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn maximum_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
    ///
    /// fn minimum_read_in_session<B: TensorElementwise>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.minimum_read(lhs, rhs)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn minimum_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn compare_read(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        dir: &CompareDir,
    ) -> crate::Result<Tensor>;

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn select_read(
        &mut self,
        pred: TensorRead<'_>,
        on_true: TensorRead<'_>,
        on_false: TensorRead<'_>,
    ) -> crate::Result<Tensor>;

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn clamp_read(
        &mut self,
        input: TensorRead<'_>,
        lower: TensorRead<'_>,
        upper: TensorRead<'_>,
    ) -> crate::Result<Tensor>;
}

/// Analytic unary and binary tensor operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorAnalytic;
///
/// fn accepts_analytic<B: TensorAnalytic>(_backend: &mut B) {}
/// ```
pub trait TensorAnalytic {
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn exp_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.exp_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn exp_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn log_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.log_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn log_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn sin_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.sin_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sin_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn cos_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.cos_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn cos_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn tanh_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.tanh_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn tanh_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn sqrt_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.sqrt_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn sqrt_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn rsqrt_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.rsqrt_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn rsqrt_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn pow_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.pow_read(lhs, rhs)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn pow_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn expm1_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.expm1_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn expm1_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn log1p_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.log1p_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn log1p_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Elementwise error function `erf(x) = 2/sqrt(pi) * integral_0^x exp(-t^2) dt`.
    ///
    /// Defined for real `F32` and `F64` input only; the result has the input
    /// dtype and shape. `erf(+-0) = +-0`, `erf(+-inf) = +-1`, and `NaN` stays
    /// `NaN`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
    ///
    /// fn erf_read_in_session<B: TensorAnalytic>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.erf_read(input)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::UnsupportedDType`] for a complex, integer, or `Bool`
    /// input dtype, [`crate::Error::Validation`] with a typed `ValidationError`
    /// source for invalid shapes or output metadata, and
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn erf_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
}

/// Shape, layout, and dtype transformation operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorStructural;
///
/// fn accepts_structural<B: TensorStructural>(_backend: &mut B) {}
/// ```
pub trait TensorStructural {
    /// Materialize an owned tensor or borrowed view into fresh compact storage.
    ///
    /// The result has the input's shape and dtype, uses compact column-major
    /// layout, and remains in the input's placement. This operation is a
    /// same-placement canonicalization boundary, never an implicit host/device
    /// transfer. The conservative default accepts host-owned tensors and host
    /// views; a view is gathered over its layout, so transposed, sliced, and
    /// negative-stride views materialize. It rejects backend buffers and device
    /// placement because only an owning backend can materialize those safely.
    ///
    /// Backend overrides may also accept backend-owned strided views. CUDA
    /// accepts numeric and complex views on its active device, including
    /// arbitrary valid strides; for `Bool` it copies owned tensors but
    /// reports an explicit unsupported-dtype error for strided views.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural};
    ///
    /// struct HostDefaults;
    /// impl TensorStructural for HostDefaults {
    ///     fn transpose_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn reshape_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn broadcast_in_dim_read(&mut self, _: TensorRead<'_>, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    /// }
    ///
    /// let input = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
    /// let mut backend = HostDefaults;
    /// let structural: &mut dyn TensorStructural = &mut backend;
    /// let output = structural.to_contiguous_read(TensorRead::from_tensor(&input))?;
    /// assert_eq!(output.shape(), &[2]);
    /// assert_eq!(output.as_slice::<i32>()?, &[1, 2]);
    /// # Ok::<(), tenferro_tensor::Error>(())
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::RuntimeState`] for backend-owned or device-placed input,
    /// which only the owning backend can materialize, or
    /// [`crate::Error::BackendFailure`] / [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor> {
        match input {
            TensorRead::Tensor(input) => {
                if input.is_backend_buffer()
                    || !matches!(
                        input.placement().memory_kind,
                        crate::MemoryKind::PinnedHost | crate::MemoryKind::UnpinnedHost
                    )
                {
                    return Err(crate::Error::runtime_state(
                        "to_contiguous_read",
                        "default materialization accepts only host-owned tensors; use the storage's owning backend",
                    ));
                }
                input.duplicate()
            }
            TensorRead::View(view) => {
                if view.backend_family().is_some()
                    || !matches!(
                        view.placement().memory_kind,
                        crate::MemoryKind::PinnedHost | crate::MemoryKind::UnpinnedHost
                    )
                {
                    return Err(crate::Error::runtime_state(
                        "to_contiguous_read",
                        "default materialization accepts only host-owned tensors; use the storage's owning backend",
                    ));
                }
                default_materialize_host_view(view)
            }
        }
    }

    /// Overwrite caller-provided storage from a readable tensor or view.
    ///
    /// Source and destination must have identical dtype and shape and belong to
    /// the executing backend's placement. The destination is not resized, and
    /// every logical destination element is overwritten without reading its old
    /// value. Source and destination allocations must not alias. Implementations
    /// must not materialize through host memory or perform an implicit transfer.
    ///
    /// CPU and CUDA accept arbitrary valid source and destination strides: the
    /// source is read where it lives and a destination region is written in
    /// place, so neither side is copied. CUDA stages only a source view wider
    /// than its catalogue's by-value layout rank, through one compact copy. A
    /// destination *view* wider than that rank is a typed refusal there, while
    /// an owned destination of the same rank is served. The conservative
    /// default is explicitly unsupported.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural, TensorWrite};
    ///
    /// struct ConservativeDefaults;
    /// impl TensorStructural for ConservativeDefaults {
    ///     fn transpose_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn reshape_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn broadcast_in_dim_read(&mut self, _: TensorRead<'_>, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    ///     fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
    /// }
    ///
    /// let src = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
    /// let mut dst = Tensor::from_vec_col_major(vec![2], vec![0_i32, 0])?;
    /// let mut backend = ConservativeDefaults;
    /// let structural: &mut dyn TensorStructural = &mut backend;
    /// let error = structural.copy_read_into(
    ///     TensorRead::from_tensor(&src),
    ///     TensorWrite::from_tensor(&mut dst),
    /// ).unwrap_err();
    /// assert!(error.to_string().contains("unsupported"));
    /// assert_eq!(dst.as_slice::<i32>()?, &[0, 0]);
    /// # Ok::<(), tenferro_tensor::Error>(())
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn copy_read_into(&mut self, _src: TensorRead<'_>, _dst: TensorWrite<'_>) -> crate::Result<()> {
        Err(crate::Error::unsupported(
            "copy_read_into",
            "backend-owned runtime copy is unsupported by this backend",
        ))
    }

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorStructural, Tensor, TensorRead};
    ///
    /// fn transpose_read_in_session<B: TensorStructural>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    ///     perm: &[usize],
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.transpose_read(input, perm)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn transpose_read(&mut self, input: TensorRead<'_>, perm: &[usize]) -> crate::Result<Tensor>;

    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{TensorStructural, Tensor, TensorRead};
    ///
    /// fn reshape_read_in_session<B: TensorStructural>(
    ///     backend: &mut B,
    ///     input: TensorRead<'_>,
    ///     shape: &[usize],
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.reshape_read(input, shape)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reshape_read(&mut self, input: TensorRead<'_>, shape: &[usize]) -> crate::Result<Tensor>;

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn broadcast_in_dim_read(
        &mut self,
        input: TensorRead<'_>,
        shape: &[usize],
        dims: &[usize],
    ) -> crate::Result<Tensor>;

    /// Cast a tensor to another dtype using explicit dtype projection.
    ///
    /// Backends may truncate, narrow precision, project complex values, or use
    /// boolean truthiness according to their documented cast support.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{DType, Tensor, TensorStructural};
    ///
    /// fn cast_to_i32<B: TensorStructural>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.cast(input, DType::I32)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn cast(&mut self, input: &Tensor, to: crate::DType) -> crate::Result<Tensor>;

    /// Convert a tensor to another dtype using checked dtype conversion.
    ///
    /// `convert` accepts only conversions allowed by tenferro's dtype-promotion
    /// lattice. Use [`TensorStructural::cast`] for explicit lossy projection.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{DType, Tensor, TensorStructural};
    ///
    /// fn convert_to_f64<B: TensorStructural>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.convert(input, DType::F64)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn convert(&mut self, input: &Tensor, to: crate::DType) -> crate::Result<Tensor> {
        validate_convert_dtype("convert", input.dtype(), to)?;
        self.cast(input, to)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn extract_diagonal(
        &mut self,
        input: &Tensor,
        axis_a: usize,
        axis_b: usize,
    ) -> crate::Result<Tensor>;
    /// Extract the diagonal with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.extract_diagonal_read(x, 0, 1)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn extract_diagonal_read(
        &mut self,
        input: TensorRead<'_>,
        axis_a: usize,
        axis_b: usize,
    ) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.extract_diagonal(&input, axis_a, axis_b)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn embed_diagonal(
        &mut self,
        input: &Tensor,
        axis_a: usize,
        axis_b: usize,
    ) -> crate::Result<Tensor>;
    /// Embed the input as a diagonal with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.embed_diagonal_read(x, 0, 1)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn embed_diagonal_read(
        &mut self,
        input: TensorRead<'_>,
        axis_a: usize,
        axis_b: usize,
    ) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.embed_diagonal(&input, axis_a, axis_b)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn tril(&mut self, input: &Tensor, k: i64) -> crate::Result<Tensor>;
    /// Lower-triangular mask with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.tril_read(x, 0)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn tril_read(&mut self, input: TensorRead<'_>, k: i64) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.tril(&input, k)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn triu(&mut self, input: &Tensor, k: i64) -> crate::Result<Tensor>;
    /// Upper-triangular mask with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.triu_read(x, 0)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn triu_read(&mut self, input: TensorRead<'_>, k: i64) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.triu(&input, k)
    }
}

/// Reduction operations.
///
/// Reducing over an axis whose extent is zero returns an error for every
/// reduction operation. Passing an empty `axes` slice is a no-op for the public
/// reductions and returns the input values unchanged. Internal mapped
/// reductions document their own empty-axis semantics.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorReduction;
///
/// fn accepts_reduction<B: TensorReduction>(_backend: &mut B) {}
/// ```
pub trait TensorReduction {
    /// Sum elements across axes from an owned tensor or borrowed view.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
    ///
    /// fn sum_owned<B: TensorReduction>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.reduce_sum_read(TensorRead::from_tensor(input), &[0])
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reduce_sum_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;

    /// Sum elementwise squares across axes.
    ///
    /// This execution hook is used by composite operations that avoid a
    /// materialized square. Empty axes produce an elementwise square. Backends
    /// that support this optimized path must override the hook directly.
    ///
    /// # Errors
    ///
    /// Returns the typed validation, unsupported, runtime-state, or backend
    /// error produced by multiplication or reduction.
    #[doc(hidden)]
    fn reduce_sum_squares_read(
        &mut self,
        _input: TensorRead<'_>,
        _axes: &[usize],
    ) -> crate::Result<Tensor> {
        Err(crate::Error::unsupported(
            "reduce_sum_squares",
            "backend does not implement fused sum-of-squares reduction",
        ))
    }

    /// Multiply elements across axes from an owned tensor or borrowed view.
    ///
    /// # Overflow policy
    ///
    /// Backends may reassociate a floating-point or complex product across
    /// lanes, chunks and threads, and the CPU and CUDA kernels do so
    /// differently. Rounding and range behaviour therefore depend on the
    /// backend, the layout and the thread count: a partial product can overflow
    /// to `inf` or underflow to `0`, and combining the partials can then give
    /// `inf`, `0` or `NaN` even where the sequential product is representable.
    /// The `#2150` alternating `2.0, 0.5` axis is one example: an `f32`
    /// sequential product is exactly `1.0`, while a reassociated one may return
    /// `NaN`. This is the same trade-off `torch.prod` makes. Integer products
    /// are exact and wrap on overflow.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
    ///
    /// fn prod_owned<B: TensorReduction>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.reduce_prod_read(TensorRead::from_tensor(input), &[0])
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reduce_prod_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;

    /// Take maximum values across axes from an owned tensor or borrowed view.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
    ///
    /// fn max_owned<B: TensorReduction>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.reduce_max_read(TensorRead::from_tensor(input), &[0])
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reduce_max_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;

    /// Take minimum values across axes from an owned tensor or borrowed view.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
    ///
    /// fn min_owned<B: TensorReduction>(
    ///     backend: &mut B,
    ///     input: &Tensor,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     backend.reduce_min_read(TensorRead::from_tensor(input), &[0])
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reduce_min_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;
}

/// Dot-general operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorDot;
///
/// fn accepts_dot<B: TensorDot>(_backend: &mut B) {}
/// ```
pub trait TensorDot: TensorElementwise {
    #[doc(hidden)]
    fn dot_general_read(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
    ) -> crate::Result<Tensor>;

    /// Overwrite caller-provided output with dot-general from read inputs.
    ///
    /// This is the dot/GEMM spelling of `_into`: the previous output value is
    /// not read. Use [`TensorDot::dot_general_read_into_accum`] for explicit
    /// read-modify-write accumulation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{DotGeneralConfig, TensorDot, TensorRead, TensorWrite};
    ///
    /// fn dot_into<B: TensorDot>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    ///     config: &DotGeneralConfig,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()> {
    ///     backend.dot_general_read_into(lhs, rhs, config, out)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dot_general_read_into(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        let accumulation = DotGeneralAccumulation::overwrite(lhs.dtype())?;
        self.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
    }

    #[doc(hidden)]
    fn dot_general_with_conj(
        &mut self,
        lhs: &Tensor,
        rhs: &Tensor,
        config: &DotGeneralConfig,
        lhs_conj: bool,
        rhs_conj: bool,
    ) -> crate::Result<Tensor> {
        if !lhs_conj && !rhs_conj {
            return self.dot_general_read(
                TensorRead::from_tensor(lhs),
                TensorRead::from_tensor(rhs),
                config,
            );
        }

        let lhs_tmp;
        let lhs_ref = if lhs_conj {
            lhs_tmp = self.conj_read(TensorRead::from_tensor(lhs))?;
            &lhs_tmp
        } else {
            lhs
        };
        let rhs_tmp;
        let rhs_ref = if rhs_conj {
            rhs_tmp = self.conj_read(TensorRead::from_tensor(rhs))?;
            &rhs_tmp
        } else {
            rhs
        };
        self.dot_general_read(
            TensorRead::from_tensor(lhs_ref),
            TensorRead::from_tensor(rhs_ref),
            config,
        )
    }

    #[allow(clippy::too_many_arguments)]
    #[doc(hidden)]
    fn dot_general_with_conj_read(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
        lhs_conj: bool,
        rhs_conj: bool,
    ) -> crate::Result<Tensor> {
        if !lhs_conj && !rhs_conj {
            return self.dot_general_read(lhs, rhs, config);
        }

        let lhs_tmp;
        let lhs_ref = if let Some(tensor) = lhs.as_tensor() {
            tensor
        } else {
            lhs_tmp = self.to_contiguous_read(lhs)?;
            &lhs_tmp
        };
        let rhs_tmp;
        let rhs_ref = if let Some(tensor) = rhs.as_tensor() {
            tensor
        } else {
            rhs_tmp = self.to_contiguous_read(rhs)?;
            &rhs_tmp
        };
        self.dot_general_with_conj(lhs_ref, rhs_ref, config, lhs_conj, rhs_conj)
    }

    /// Apply scaled dot-general accumulation into caller-provided output.
    ///
    /// This is explicitly read-modify-write when `accumulation.beta` is nonzero:
    /// `out = alpha * dot_general(lhs, rhs) + beta * out`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{
    ///     DotGeneralAccumulation, DotGeneralConfig, TensorDot, TensorRead, TensorWrite,
    /// };
    ///
    /// fn dot_add_to<B: TensorDot>(
    ///     backend: &mut B,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    ///     config: &DotGeneralConfig,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()> {
    ///     let accumulation = DotGeneralAccumulation::add_to(lhs.dtype())?;
    ///     backend.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dot_general_read_into_accum(
        &mut self,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
        accumulation: DotGeneralAccumulation,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        dot_general_accum_via_temp(self, lhs, rhs, config, accumulation, out)
    }
}

/// Session-scoped cached dot-general operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::Engine;
///
/// fn accepts_session_dot<S: Engine + ?Sized>(_session: &mut S) {}
/// ```
pub trait SessionCachedDot: TensorDot {
    #[doc(hidden)]
    fn dot_general_cached(
        &mut self,
        _cache_slot: Option<usize>,
        lhs: &Tensor,
        rhs: &Tensor,
        config: &DotGeneralConfig,
    ) -> crate::Result<Tensor> {
        self.dot_general_read(
            TensorRead::from_tensor(lhs),
            TensorRead::from_tensor(rhs),
            config,
        )
    }

    #[doc(hidden)]
    fn dot_general_read_cached(
        &mut self,
        cache_slot: Option<usize>,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
    ) -> crate::Result<Tensor> {
        match (lhs.as_tensor(), rhs.as_tensor()) {
            (Some(lhs), Some(rhs)) => self.dot_general_cached(cache_slot, lhs, rhs, config),
            _ => {
                let lhs = self.to_contiguous_read(lhs)?;
                let rhs = self.to_contiguous_read(rhs)?;
                self.dot_general_cached(cache_slot, &lhs, &rhs, config)
            }
        }
    }

    // Mirrors the dot-general signature plus runtime-cache metadata.
    #[allow(clippy::too_many_arguments)]
    #[doc(hidden)]
    fn dot_general_with_conj_cached(
        &mut self,
        _cache_slot: Option<usize>,
        lhs: &Tensor,
        rhs: &Tensor,
        config: &DotGeneralConfig,
        lhs_conj: bool,
        rhs_conj: bool,
    ) -> crate::Result<Tensor> {
        self.dot_general_with_conj(lhs, rhs, config, lhs_conj, rhs_conj)
    }

    // Mirrors the dot-general read signature plus runtime-cache metadata.
    #[allow(clippy::too_many_arguments)]
    #[doc(hidden)]
    fn dot_general_with_conj_read_cached(
        &mut self,
        cache_slot: Option<usize>,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
        lhs_conj: bool,
        rhs_conj: bool,
    ) -> crate::Result<Tensor> {
        if !lhs_conj && !rhs_conj {
            return self.dot_general_read_cached(cache_slot, lhs, rhs, config);
        }

        let lhs_tmp;
        let lhs_ref = if let Some(tensor) = lhs.as_tensor() {
            tensor
        } else {
            lhs_tmp = self.to_contiguous_read(lhs)?;
            &lhs_tmp
        };
        let rhs_tmp;
        let rhs_ref = if let Some(tensor) = rhs.as_tensor() {
            tensor
        } else {
            rhs_tmp = self.to_contiguous_read(rhs)?;
            &rhs_tmp
        };
        self.dot_general_with_conj_cached(cache_slot, lhs_ref, rhs_ref, config, lhs_conj, rhs_conj)
    }

    /// Apply session-cached scaled dot-general accumulation into output.
    ///
    /// The cache slot is session-local metadata; `accumulation` still controls
    /// overwrite versus read-modify-write semantics.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{
    ///     DotGeneralAccumulation, DotGeneralConfig, SessionCachedDot, TensorRead, TensorWrite,
    /// };
    ///
    /// fn session_cached_dot_add_to<S: SessionCachedDot + ?Sized>(
    ///     session: &mut S,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    ///     config: &DotGeneralConfig,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()> {
    ///     let accumulation = DotGeneralAccumulation::add_to(lhs.dtype())?;
    ///     session.dot_general_read_into_accum_cached(
    ///         Some(0),
    ///         lhs,
    ///         rhs,
    ///         config,
    ///         accumulation,
    ///         out,
    ///     )
    /// }
    /// ```
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dot_general_read_into_accum_cached(
        &mut self,
        _cache_slot: Option<usize>,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &DotGeneralConfig,
        accumulation: DotGeneralAccumulation,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        self.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
    }
}

/// Indexing, slicing, and padding operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorIndexing;
///
/// fn accepts_indexing<B: TensorIndexing>(_backend: &mut B) {}
/// ```
pub trait TensorIndexing: TensorStructural {
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn gather(
        &mut self,
        operand: &Tensor,
        start_indices: &Tensor,
        config: &GatherConfig,
    ) -> crate::Result<Tensor>;
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn scatter(
        &mut self,
        operand: &Tensor,
        scatter_indices: &Tensor,
        updates: &Tensor,
        config: &ScatterConfig,
    ) -> crate::Result<Tensor>;
    /// Scatter with every input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, ScatterConfig, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, idx: TensorRead<'_>, updates: TensorRead<'_>, config: &ScatterConfig)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.scatter_read(x, idx, updates, config)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn scatter_read(
        &mut self,
        operand: TensorRead<'_>,
        scatter_indices: TensorRead<'_>,
        updates: TensorRead<'_>,
        config: &ScatterConfig,
    ) -> crate::Result<Tensor> {
        let operand = stage_view(self, operand)?;
        let scatter_indices = stage_view(self, scatter_indices)?;
        let updates = stage_view(self, updates)?;
        self.scatter(&operand, &scatter_indices, &updates, config)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. In
    /// particular, a limit greater than the corresponding input dimension is
    /// reported as [`crate::ValidationError::InvalidArgument`] with the
    /// `"configuration"` argument. It returns [`crate::Error::BackendFailure`]
    /// or [`crate::Error::BackendSource`] when backend execution or storage
    /// access cannot provide the requested result.
    fn slice(&mut self, input: &Tensor, config: &SliceConfig) -> crate::Result<Tensor>;
    /// Slice with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, SliceConfig, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, config: &SliceConfig)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.slice_read(x, config)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn slice_read(&mut self, input: TensorRead<'_>, config: &SliceConfig) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.slice(&input, config)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dynamic_slice(
        &mut self,
        input: &Tensor,
        starts: &Tensor,
        slice_sizes: &[usize],
    ) -> crate::Result<Tensor>;
    /// Dynamic slice with every input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, starts: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.dynamic_slice_read(x, starts, &[2])
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dynamic_slice_read(
        &mut self,
        input: TensorRead<'_>,
        starts: TensorRead<'_>,
        slice_sizes: &[usize],
    ) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        let starts = stage_view(self, starts)?;
        self.dynamic_slice(&input, &starts, slice_sizes)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dynamic_update_slice(
        &mut self,
        operand: &Tensor,
        update: &Tensor,
        starts: &Tensor,
    ) -> crate::Result<Tensor>;
    /// Dynamic-update-slice with every input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a
    /// backend whose kernel consumes a borrowed operand should override this so
    /// a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
    ///
    /// fn run(
    ///     session: &mut dyn TensorIndexing,
    ///     x: TensorRead<'_>,
    ///     update: TensorRead<'_>,
    ///     starts: TensorRead<'_>,
    /// ) -> tenferro_tensor::Result<Tensor> {
    ///     session.dynamic_update_slice_read(x, update, starts)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn dynamic_update_slice_read(
        &mut self,
        operand: TensorRead<'_>,
        update: TensorRead<'_>,
        starts: TensorRead<'_>,
    ) -> crate::Result<Tensor> {
        let operand = stage_view(self, operand)?;
        let update = stage_view(self, update)?;
        let starts = stage_view(self, starts)?;
        self.dynamic_update_slice(&operand, &update, &starts)
    }
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn pad(&mut self, input: &Tensor, config: &PadConfig) -> crate::Result<Tensor>;
    /// Pad with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, PadConfig, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, config: &PadConfig)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.pad_read(x, config)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn pad_read(&mut self, input: TensorRead<'_>, config: &PadConfig) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.pad(&input, config)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn concatenate(&mut self, inputs: &[&Tensor], axis: usize) -> crate::Result<Tensor>;
    /// Concatenate with every input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, a: TensorRead<'_>, b: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.concatenate_read(&[a, b], 0)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn concatenate_read(
        &mut self,
        inputs: &[TensorRead<'_>],
        axis: usize,
    ) -> crate::Result<Tensor> {
        let staged = inputs
            .iter()
            .map(|input| stage_view(self, input.clone()))
            .collect::<crate::Result<Vec<_>>>()?;
        let refs: Vec<&Tensor> = staged.iter().map(|input| &**input).collect();
        self.concatenate(&refs, axis)
    }

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reverse(&mut self, input: &Tensor, axes: &[usize]) -> crate::Result<Tensor>;
    /// Reverse with the input taken as a read.
    ///
    /// The default stages each borrowed view into compact storage (an owned
    /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
    /// should override this so a view is not copied (#2214).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
    ///
    /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Tensor>
    /// {
    ///     session.reverse_read(x, &[0])
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn reverse_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor> {
        let input = stage_view(self, input)?;
        self.reverse(&input, axes)
    }
}

/// Backend-owned canonicalization for typed tensor views.
///
/// Implementations must preserve the input placement family. CPU backends
/// canonicalize host views through explicit host copies and reject backend
/// buffers with a diagnostic that asks the caller to download first. GPU
/// backends canonicalize GPU-resident views on the same device and reject host
/// buffers with an upload hint.
///
/// [`TensorViewCanonicalization::copy_into`] requires source and destination
/// shapes, scalar dtypes, and placement families to match. The destination
/// view must be internally non-overlapping, and source and destination backing
/// allocations must not alias unless an implementation explicitly documents
/// and supports that case. Implementations may reject layouts their native
/// kernels cannot consume.
///
/// CUDA currently accepts only a compact column-major source view with offset
/// zero that covers its full allocation; arbitrary-stride destinations remain
/// supported. Canonicalization and copying are same-placement operations: they
/// must not perform hidden host/device transfers or silently materialize an
/// unsupported source layout.
///
/// This trait is intentionally separate from [`Engine`] so generic
/// typed methods do not change the object-safety contract of `dyn Engine`.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{DynRank, TensorViewCanonicalization, TypedTensor};
///
/// fn compact_i32<B: TensorViewCanonicalization<i32, DynRank>>(
///     backend: &mut B,
///     tensor: &TypedTensor<i32>,
/// ) -> tenferro_tensor::Result<TypedTensor<i32>> {
///     backend.to_contiguous(&tensor.as_view())
/// }
///
/// fn copy_i32<B: TensorViewCanonicalization<i32, DynRank>>(
///     backend: &mut B,
///     src: &TypedTensor<i32>,
///     dst: &mut TypedTensor<i32>,
/// ) -> tenferro_tensor::Result<()> {
///     backend.copy_into(&src.as_view(), &mut dst.as_view_mut())
/// }
/// ```
pub trait TensorViewCanonicalization<T: TensorScalar, R: TensorRank> {
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn to_contiguous(
        &mut self,
        view: &TypedTensorView<'_, T, R>,
    ) -> crate::Result<TypedTensor<T, R>>;

    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
    /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    fn copy_into(
        &mut self,
        src: &TypedTensorView<'_, T, R>,
        dst: &mut TypedTensorViewMut<'_, T, R>,
    ) -> crate::Result<()>;
}

/// Optional elementwise fusion execution.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorFusion;
///
/// fn accepts_fusion<B: TensorFusion>(_backend: &mut B) {}
/// ```
pub trait TensorFusion {
    #[doc(hidden)]
    fn execute_elementwise_fusion(
        &mut self,
        _inputs: &[&Tensor],
        _plan: &ElementwiseFusionPlan,
    ) -> crate::Result<Option<Vec<Tensor>>> {
        Ok(None)
    }

    #[doc(hidden)]
    #[allow(clippy::too_many_arguments)]
    fn execute_broadcast_multiply(
        &mut self,
        _lhs: TensorRead<'_>,
        _lhs_shape: &[usize],
        _lhs_dims: &[usize],
        _rhs: TensorRead<'_>,
        _rhs_shape: &[usize],
        _rhs_dims: &[usize],
    ) -> crate::Result<Option<Tensor>> {
        Ok(None)
    }

    #[doc(hidden)]
    #[allow(clippy::too_many_arguments)]
    fn execute_broadcast_multiply_value(
        &mut self,
        lhs: TensorRead<'_>,
        lhs_shape: &[usize],
        lhs_dims: &[usize],
        rhs: TensorRead<'_>,
        rhs_shape: &[usize],
        rhs_dims: &[usize],
    ) -> crate::Result<Option<TensorValue>> {
        self.execute_broadcast_multiply(lhs, lhs_shape, lhs_dims, rhs, rhs_shape, rhs_dims)
            .map(|tensor| tensor.map(TensorValue::from_tensor))
    }
}

/// Backend buffer lifecycle operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorBuffer;
///
/// fn accepts_buffer<B: TensorBuffer>(_backend: &mut B) {}
/// ```
pub trait TensorBuffer {
    fn reclaim_buffer(&mut self, _tensor: Tensor) {}
}

/// Device transfer operations on backend boundaries.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorDeviceTransfer;
///
/// fn accepts_transfer<B: TensorDeviceTransfer>(_backend: &mut B) {}
/// ```
pub trait TensorDeviceTransfer {
    /// Explicitly copy a provider-owned read target into host storage.
    ///
    /// Implementations must not return the input unchanged or stage through an
    /// unrelated provider. A backend that cannot transfer the requested read
    /// target returns a typed unsupported error.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Unsupported`] when the implementation cannot
    /// perform the requested transfer, or a typed validation/backend error when
    /// the source cannot be read.
    fn download_to_host(&mut self, tensor: TensorRead<'_>) -> crate::Result<Tensor>;

    /// Explicitly copy a host read target into provider storage.
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Unsupported`] when the implementation cannot
    /// perform the requested transfer, or a typed validation/backend error when
    /// the source cannot be read.
    fn upload_host_tensor(&mut self, tensor: TensorRead<'_>) -> crate::Result<Tensor>;
}

#[doc(hidden)]
pub trait TensorBackendOps:
    TensorElementwise
    + TensorAnalytic
    + TensorStructural
    + TensorReduction
    + TensorIndexing
    + TensorDot
    + TensorFusion
    + TensorBuffer
{
}

impl<T> TensorBackendOps for T where
    T: TensorElementwise
        + TensorAnalytic
        + TensorStructural
        + TensorReduction
        + TensorIndexing
        + TensorDot
        + TensorFusion
        + TensorBuffer
        + ?Sized
{
}

/// Validate the shared input contract for [`Engine::vdot_read`].
#[doc(hidden)]
pub fn validate_vdot_read(lhs: &TensorRead<'_>, rhs: &TensorRead<'_>) -> crate::Result<()> {
    let op = "Engine::vdot_read";
    validate_supported_blas1_dtype(op, lhs.dtype())?;
    if rhs.dtype() != lhs.dtype() {
        return Err(Error::dtype_mismatch(op, lhs.dtype(), rhs.dtype()));
    }
    if lhs.shape() != rhs.shape() {
        return Err(Error::shape_mismatch(
            op,
            lhs.shape().to_vec(),
            rhs.shape().to_vec(),
        ));
    }
    validate_shape_product(op, lhs.shape())?;
    validate_compatible_placement(op, lhs, rhs)
}

/// Validate the shared input contract for [`Engine::norm_squared_read`].
#[doc(hidden)]
pub fn validate_norm_squared_read(input: &TensorRead<'_>) -> crate::Result<()> {
    validate_supported_blas1_dtype("Engine::norm_squared_read", input.dtype())?;
    validate_shape_product("Engine::norm_squared_read", input.shape()).map(|_| ())
}

/// Validate the shared input and destination contract for
/// [`Engine::axpby_read_into_accum`].
#[doc(hidden)]
pub fn validate_axpby_read_into_accum(
    alpha: ContractionScalar,
    x: &TensorRead<'_>,
    beta: ContractionScalar,
    y: &TensorWrite<'_>,
) -> crate::Result<()> {
    let op = "Engine::axpby_read_into_accum";
    validate_supported_blas1_dtype(op, x.dtype())?;
    if y.dtype() != x.dtype() {
        return Err(Error::dtype_mismatch(op, x.dtype(), y.dtype()));
    }
    if alpha.dtype() != x.dtype() {
        return Err(Error::dtype_mismatch(op, x.dtype(), alpha.dtype()));
    }
    if beta.dtype() != x.dtype() {
        return Err(Error::dtype_mismatch(op, x.dtype(), beta.dtype()));
    }
    if x.shape() != y.shape() {
        return Err(Error::shape_mismatch(
            op,
            x.shape().to_vec(),
            y.shape().to_vec(),
        ));
    }
    validate_shape_product(op, x.shape())?;
    // INVARIANT: write-injectivity is already proved when a destination view is
    // constructed (`validate_mutable_no_overlap`), and an owned destination is
    // compact by construction, so no element-wise re-check is needed here. Only
    // the `x`/`y` alias rejection below remains.
    validate_compatible_placement(op, x, &y.as_read())?;
    validate_read_into_destination(op, std::slice::from_ref(x), y)
}

/// # Errors
///
/// Returns [`Error::Unsupported`] when `dtype` is not floating or complex.
fn validate_supported_blas1_dtype(op: &'static str, dtype: DType) -> crate::Result<()> {
    if matches!(dtype, DType::F32 | DType::F64 | DType::C32 | DType::C64) {
        Ok(())
    } else {
        Err(Error::unsupported(
            op,
            format!("unsupported dtype {dtype:?}; supported dtypes: F32/F64/C32/C64"),
        ))
    }
}

/// # Errors
///
/// Returns [`Error::Validation`] with [`ValidationError::IntegerOverflow`] when
/// the checked shape product overflows.
fn validate_shape_product(op: &'static str, shape: &[usize]) -> crate::Result<usize> {
    crate::validate::checked_shape_product(op, "shape", shape)
}

/// # Errors
///
/// Returns [`Error::Validation`] with [`ValidationError::InvalidArgument`] when
/// placements differ.
fn validate_compatible_placement(
    op: &'static str,
    lhs: &TensorRead<'_>,
    rhs: &TensorRead<'_>,
) -> crate::Result<()> {
    if lhs.placement() != rhs.placement() {
        return Err(Error::invalid_argument(
            op,
            "placement",
            "tensor inputs must have compatible placement",
        ));
    }
    Ok(())
}

/// The execution trait every tensor operation runs on.
///
/// An engine is a caller-held value (a CPU engine owns a Rayon pool and a
/// workspace; a GPU engine owns a stream and a workspace). Operations take
/// `&mut` of the engine, so one computation uses an engine at a time without
/// any runtime lock. There is no separate session object.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{Engine, Tensor, TensorRead};
///
/// fn add_on(engine: &mut dyn Engine, a: &Tensor, b: &Tensor) -> tenferro_tensor::Result<Tensor> {
///     engine.add_read(TensorRead::from_tensor(a), TensorRead::from_tensor(b))
/// }
/// ```
///
/// The operation one-shot spelling is gone; an engine only answers to the read
/// form:
///
/// ```compile_fail
/// use tenferro_tensor::{Engine, Tensor};
///
/// fn add_on(engine: &mut dyn Engine, a: &Tensor, b: &Tensor) {
///     let _ = engine.add(a, b);
/// }
/// ```
pub trait Engine: TensorBackendOps + SessionCachedDot + TensorDeviceTransfer {
    /// Gather with both operands taken as reads.
    ///
    /// The default stages each borrowed view (an owned tensor is passed
    /// through) and delegates to [`TensorIndexing::gather`]; a backend whose gather kernel consumes the
    /// operand's strides overrides this so a borrowed operand needs no copy
    /// (invariant I1: the runtime must not materialize by default).
    ///
    /// # Errors
    ///
    /// Returns [`crate::Error::Validation`] with a typed `ValidationError`
    /// source for invalid shapes, ranks, axes, dtypes or output metadata, and
    /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
    /// backend execution or storage access cannot provide the requested result.
    /// The default implementation stages a view first, so it also returns
    /// whatever [`TensorStructural::to_contiguous_read`] reports for a view the backend
    /// cannot materialize.
    fn gather_read(
        &mut self,
        operand: TensorRead<'_>,
        start_indices: TensorRead<'_>,
        config: &GatherConfig,
    ) -> crate::Result<Tensor> {
        let operand = stage_view(self, operand)?;
        let start_indices = stage_view(self, start_indices)?;
        self.gather(&operand, &start_indices, config)
    }

    /// Compute the all-axis conjugating dot product without transferring either input.
    ///
    /// The result is a rank-0 tensor with the input dtype and has the value
    /// `sum(conj(lhs) * rhs)`. Borrowed views remain borrowed through the
    /// backend's existing same-placement planning boundary.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Engine, TensorRead};
    ///
    /// fn vdot(session: &mut dyn Engine, x: TensorRead<'_>, y: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<tenferro_tensor::Tensor>
    /// {
    ///     session.vdot_read(x, y)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::Unsupported`] when the backend does not override this
    /// capability or the dtype is unsupported; [`Error::Validation`] with
    /// `DTypeMismatch`, `ShapeMismatch`, or `InvalidArgument` when dtype, shape,
    /// or placement differs; [`Error::RuntimeState`] for inaccessible backend
    /// storage; or [`Error::BackendSource`] when provider execution fails.
    fn vdot_read(&mut self, _lhs: TensorRead<'_>, _rhs: TensorRead<'_>) -> crate::Result<Tensor> {
        Err(Error::unsupported(
            "Engine::vdot_read",
            "backend session does not implement vdot_read",
        ))
    }

    /// Compute the all-axis sum of squared magnitudes without taking a square root.
    ///
    /// The result is rank 0 and is F32 for F32/C32 input or F64 for F64/C64
    /// input. No transfer or full-size algebra temporary is implied by this
    /// session contract.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Engine, TensorRead};
    ///
    /// fn norm_squared(session: &mut dyn Engine, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<tenferro_tensor::Tensor>
    /// {
    ///     session.norm_squared_read(x)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::Unsupported`] when the backend does not override this
    /// capability or the dtype is unsupported, [`Error::RuntimeState`] when
    /// backend storage is not host-accessible, or [`Error::BackendSource`] when
    /// reduction execution fails.
    fn norm_squared_read(&mut self, _input: TensorRead<'_>) -> crate::Result<Tensor> {
        Err(Error::unsupported(
            "Engine::norm_squared_read",
            "backend session does not implement norm_squared_read",
        ))
    }

    /// Compute a fused activation in one pass, or decline with `Ok(None)`.
    ///
    /// This is an optional fast path. A backend that returns `Ok(None)` keeps
    /// the shared composite formulation of the same function, so declining is
    /// always correct. A backend that returns `Ok(Some(output))` must produce
    /// the value
    /// defined by [`ActivationOp`] for an `F32`/`F64` input in one elementwise
    /// traversal.
    ///
    /// # Examples
    ///
    /// ```
    /// use tenferro_tensor::{ActivationOp, Engine, TensorRead};
    ///
    /// fn fused(session: &mut dyn Engine, x: TensorRead<'_>)
    ///     -> tenferro_tensor::Result<Option<tenferro_tensor::Tensor>>
    /// {
    ///     session.fused_activation_read(ActivationOp::Sigmoid, x)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a typed validation error for an unsupported dtype, a backend
    /// error when storage cannot be read, or a kernel error from the fused
    /// traversal. Returning `Ok(None)` declines the fast path.
    fn fused_activation_read(
        &mut self,
        op: ActivationOp,
        input: TensorRead<'_>,
    ) -> crate::Result<Option<Tensor>> {
        let _ = (op, input);
        Ok(None)
    }

    /// Fused real-float softmax along `axis`.
    ///
    /// This is an optional fast path for the shared runtime composite
    /// formulation. A backend that returns `Ok(Some(output))` must produce the
    /// same value as the composite: a max-subtracted softmax over `axis`, with
    /// an all-`-inf` slice yielding zeros and NaN propagating.
    ///
    /// # Examples
    ///
    /// ```
    /// use tenferro_tensor::{Engine, TensorRead};
    ///
    /// fn softmax(session: &mut dyn Engine, x: TensorRead<'_>, axis: usize)
    ///     -> tenferro_tensor::Result<Option<tenferro_tensor::Tensor>>
    /// {
    ///     session.softmax_read(x, axis)
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a typed validation error for an invalid axis or unsupported
    /// dtype, a backend error when storage cannot be read, or a kernel error.
    /// Returning `Ok(None)` declines the fast path.
    fn softmax_read(
        &mut self,
        input: TensorRead<'_>,
        axis: usize,
    ) -> crate::Result<Option<Tensor>> {
        let _ = (input, axis);
        Ok(None)
    }

    /// Apply `y <- alpha * x + beta * y` in one pass into caller-owned storage.
    ///
    /// Scalars must have the exact tensor dtype; real coefficients for complex
    /// vectors are represented as complex values with zero imaginary part. The
    /// destination must be write-injective and disjoint from `x`; any x/y
    /// storage overlap is rejected before mutation. A strided or offset
    /// destination view is accepted, so a caller can accumulate into a region
    /// of a larger allocation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{Engine, ContractionScalar, TensorRead, TensorWrite};
    ///
    /// fn axpby(session: &mut dyn Engine, x: TensorRead<'_>, y: TensorWrite<'_>)
    ///     -> tenferro_tensor::Result<()>
    /// {
    ///     session.axpby_read_into_accum(
    ///         ContractionScalar::F64(1.0), x, ContractionScalar::F64(0.0), y,
    ///     )
    /// }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`Error::Unsupported`] when the backend does not override this
    /// capability or the dtype is unsupported; [`Error::Validation`] with
    /// `DTypeMismatch`, `ShapeMismatch`, or `InvalidArgument` for scalar/dtype,
    /// shape, placement, injectivity, or overlap failures; or
    /// [`Error::RuntimeState`] for inaccessible backend storage. Invalid
    /// requests leave the destination unchanged.
    fn axpby_read_into_accum(
        &mut self,
        _alpha: ContractionScalar,
        _x: TensorRead<'_>,
        _beta: ContractionScalar,
        _y: TensorWrite<'_>,
    ) -> crate::Result<()> {
        Err(Error::unsupported(
            "Engine::axpby_read_into_accum",
            "backend session does not implement axpby_read_into_accum",
        ))
    }

    /// Return this engine's backend-leaf native capability, if it has one.
    ///
    /// The standard engines return a token that their own safe visitors
    /// (`with_cpu_engine`, `with_cuda_engine`) recover. The default is `None`:
    /// a custom engine has no native services unless it forwards the token of a
    /// standard engine it owns. A wrapper that overrides operation dispatch
    /// (for example a custom GEMM) should keep the default, because an
    /// operation family that finds a native token may call the delegate's
    /// native services directly and so bypass the wrapper's override.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::Engine;
    ///
    /// fn native_services_available(session: &mut dyn Engine) -> bool {
    ///     session.native_engine().is_some()
    /// }
    /// ```
    fn native_engine(&mut self) -> Option<crate::NativeSessionRef<'_>> {
        None
    }
}

/// A read handed to an owned-input method by a materializing `*_read` default.
///
/// An owned tensor is already compact, so it is borrowed as is; only a view is
/// staged.
enum StagedRead<'a> {
    Borrowed(&'a Tensor),
    Staged(Box<Tensor>),
}

impl std::ops::Deref for StagedRead<'_> {
    type Target = Tensor;

    fn deref(&self) -> &Tensor {
        match self {
            Self::Borrowed(tensor) => tensor,
            Self::Staged(tensor) => tensor,
        }
    }
}

/// Stage `read` for an owned-input method, copying only when it is a view.
fn stage_view<'a, S: TensorStructural + ?Sized>(
    session: &mut S,
    read: TensorRead<'a>,
) -> crate::Result<StagedRead<'a>> {
    match read {
        TensorRead::Tensor(tensor) => Ok(StagedRead::Borrowed(tensor)),
        view => Ok(StagedRead::Staged(Box::new(
            session.to_contiguous_read(view)?,
        ))),
    }
}