tenferro_tensor/

backend.rs

use crate::config::{
    CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
};
use crate::types::{
    TensorRank, TensorScalar, TensorView, TensorViewMut, TypedTensor, TypedTensorView,
    TypedTensorViewMut,
};
use crate::validate::validate_convert_dtype;
use crate::{
    AllocationDomainId, AllocationId, DType, Error, RuntimeCacheControl, SessionEntryError,
    ShapeMismatch, 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<()> {
    let mut seen = vec![false; rank];
    for &axis in axes {
        if axis >= rank {
            return Err(validation(
                op,
                ValidationError::AxisOutOfBounds { axis, rank },
            ));
        }
        if seen[axis] {
            return Err(validation(
                op,
                ValidationError::DuplicateAxis { axis, role },
            ));
        }
        seen[axis] = true;
    }
    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<Vec<usize>> {
    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]);

    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<Vec<usize>> {
    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().into(),
                actual: out.shape().to_vec().into(),
            }
            .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,
}

/// One matrix multiply in a grouped GEMM over shared flat buffers.
///
/// Offsets are element offsets into the corresponding shared lhs, rhs, and
/// output buffers. Each job computes a column-major `rows x cols` output block
/// from a column-major `rows x contracted` lhs block and a column-major
/// `contracted x cols` rhs block.
///
/// Provider implementations receive these descriptors through the public
/// grouped-GEMM request accessor. The engine validates ranges and pairwise
/// output disjointness before provider entry.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct GroupedGemmJob {
    out_offset: usize,
    lhs_offset: usize,
    rhs_offset: usize,
    rows: usize,
    contracted: usize,
    cols: usize,
}

impl GroupedGemmJob {
    /// Construct a column-major grouped-GEMM job over shared flat buffers.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        out_offset: usize,
        lhs_offset: usize,
        rhs_offset: usize,
        rows: usize,
        contracted: usize,
        cols: usize,
    ) -> Self {
        Self {
            out_offset,
            lhs_offset,
            rhs_offset,
            rows,
            contracted,
            cols,
        }
    }

    /// Return the output element offset.
    pub fn out_offset(&self) -> usize {
        self.out_offset
    }

    /// Return the left-input element offset.
    pub fn lhs_offset(&self) -> usize {
        self.lhs_offset
    }

    /// Return the right-input element offset.
    pub fn rhs_offset(&self) -> usize {
        self.rhs_offset
    }

    /// Return the output row count.
    pub fn rows(&self) -> usize {
        self.rows
    }

    /// Return the contracted dimension.
    pub fn contracted(&self) -> usize {
        self.contracted
    }

    /// Return the output column count.
    pub fn cols(&self) -> usize {
        self.cols
    }
}

/// Shared scalar/update metadata for grouped GEMM execution.
#[doc(hidden)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct GroupedGemmConfig<'a> {
    jobs: &'a [GroupedGemmJob],
    accumulation: DotGeneralAccumulation,
}

impl<'a> GroupedGemmConfig<'a> {
    pub fn new(jobs: &'a [GroupedGemmJob], accumulation: DotGeneralAccumulation) -> Self {
        Self { jobs, accumulation }
    }

    pub fn jobs(&self) -> &'a [GroupedGemmJob] {
        self.jobs
    }

    pub fn accumulation(&self) -> DotGeneralAccumulation {
        self.accumulation
    }
}

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<Vec<usize>> {
    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)
}

fn grouped_checked_product(
    op: &'static str,
    role: &'static str,
    dims: &[usize],
) -> crate::Result<usize> {
    dims.iter().try_fold(1usize, |acc, &dim| {
        acc.checked_mul(dim).ok_or_else(|| {
            invalid_argument(
                op,
                role,
                format!("logical element count overflows usize for shape {dims:?}"),
            )
        })
    })
}

fn checked_gemm_span(
    op: &'static str,
    role: &'static str,
    offset: usize,
    rows: usize,
    cols: usize,
) -> crate::Result<Option<std::ops::Range<usize>>> {
    let len = rows.checked_mul(cols).ok_or_else(|| {
        invalid_argument(
            op,
            role,
            format!("matrix element count overflows usize: rows={rows} cols={cols}"),
        )
    })?;
    if len == 0 {
        return Ok(None);
    }
    let end = offset.checked_add(len).ok_or_else(|| {
        invalid_argument(
            op,
            role,
            format!("matrix range overflows usize: offset={offset} len={len}"),
        )
    })?;
    Ok(Some(offset..end))
}

fn validate_grouped_gemm_range(
    op: &'static str,
    role: &'static str,
    len: usize,
    range: Option<std::ops::Range<usize>>,
) -> crate::Result<()> {
    let Some(range) = range else {
        return Ok(());
    };
    if range.end > len {
        return Err(invalid_argument(
            op,
            role,
            format!(
                "matrix range {}..{} exceeds shared buffer logical length {len}",
                range.start, range.end
            ),
        ));
    }
    Ok(())
}

#[doc(hidden)]
pub fn validate_grouped_gemm(
    lhs: &TensorRead<'_>,
    rhs: &TensorRead<'_>,
    out: &TensorWrite<'_>,
    config: &GroupedGemmConfig<'_>,
    op: &'static str,
) -> crate::Result<()> {
    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(),
            },
        ));
    }
    config.accumulation.validate_for_dtype(lhs.dtype())?;

    let lhs_len = grouped_checked_product(op, "lhs", lhs.shape())?;
    let rhs_len = grouped_checked_product(op, "rhs", rhs.shape())?;
    let out_len = grouped_checked_product(op, "out", out.shape())?;
    // Grouped GEMM job count is runtime-controlled and can be large. Keep the
    // validation ranges in a reserved Vec, not SmallVec, so arbitrary batches
    // avoid inline-capacity tuning and can be sorted for O(n log n) overlap
    // validation.
    let mut out_ranges = Vec::<(usize, std::ops::Range<usize>)>::with_capacity(config.jobs.len());
    for (idx, job) in config.jobs.iter().enumerate() {
        validate_grouped_gemm_range(
            op,
            "lhs",
            lhs_len,
            checked_gemm_span(op, "lhs", job.lhs_offset, job.rows, job.contracted)?,
        )?;
        validate_grouped_gemm_range(
            op,
            "rhs",
            rhs_len,
            checked_gemm_span(op, "rhs", job.rhs_offset, job.contracted, job.cols)?,
        )?;
        let out_range = checked_gemm_span(op, "out", job.out_offset, job.rows, job.cols)?;
        validate_grouped_gemm_range(op, "out", out_len, out_range.clone())?;
        if let Some(out_range) = out_range {
            out_ranges.push((idx, out_range));
        }
    }
    out_ranges.sort_unstable_by_key(|(_, range)| range.start);
    for pair in out_ranges.windows(2) {
        let (prev_idx, previous) = &pair[0];
        let (idx, current) = &pair[1];
        if previous.end > current.start {
            return Err(invalid_argument(
                op,
                "jobs",
                format!(
                    "grouped GEMM output range for job {idx} overlaps job {prev_idx} range {}..{}",
                    previous.start, previous.end
                ),
            ));
        }
    }
    Ok(())
}

fn add_element_offsets(
    op: &'static str,
    base: isize,
    offset: usize,
    role: &'static str,
) -> crate::Result<isize> {
    let offset = isize::try_from(offset).map_err(|_| {
        invalid_argument(op, role, format!("offset {offset} does not fit in isize"))
    })?;
    base.checked_add(offset).ok_or_else(|| {
        invalid_argument(
            op,
            role,
            format!("offset overflows isize: base={base} offset={offset}"),
        )
    })
}

fn dim_stride(op: &'static str, dim: usize, role: &'static str) -> crate::Result<isize> {
    isize::try_from(dim).map_err(|_| {
        invalid_argument(
            op,
            role,
            format!("leading dimension {dim} does not fit in isize"),
        )
    })
}

fn typed_read_storage<'a, T: crate::TensorScalar>(
    tensor: &'a TypedTensor<T>,
    op: &'static str,
) -> crate::Result<(&'a [T], isize)> {
    tensor.host_data().map(|data| (data, 0)).map_err(|_| {
        crate::Error::runtime_state(
            op,
            "grouped GEMM default path requires host-backed tensor storage",
        )
    })
}

fn grouped_gemm_default_config() -> DotGeneralConfig {
    // DotGeneralConfig owns Vec fields, so this rank-2 fallback config follows
    // that API boundary rather than introducing SmallVec locally.
    DotGeneralConfig {
        lhs_contracting_dims: [1].as_slice().into(),
        rhs_contracting_dims: [0].as_slice().into(),
        lhs_batch_dims: Default::default(),
        rhs_batch_dims: Default::default(),
    }
}

trait GroupedGemmDType<T> {
    fn wrap_read(view: TypedTensorView<'_, T>) -> TensorView<'_>;
    fn wrap_write(view: TypedTensorViewMut<'_, T>) -> TensorViewMut<'_>;
}

struct GroupedF32;
struct GroupedF64;
struct GroupedC32;
struct GroupedC64;

impl GroupedGemmDType<f32> for GroupedF32 {
    fn wrap_read(view: TypedTensorView<'_, f32>) -> TensorView<'_> {
        TensorView::F32(view)
    }

    fn wrap_write(view: TypedTensorViewMut<'_, f32>) -> TensorViewMut<'_> {
        TensorViewMut::F32(view)
    }
}

impl GroupedGemmDType<f64> for GroupedF64 {
    fn wrap_read(view: TypedTensorView<'_, f64>) -> TensorView<'_> {
        TensorView::F64(view)
    }

    fn wrap_write(view: TypedTensorViewMut<'_, f64>) -> TensorViewMut<'_> {
        TensorViewMut::F64(view)
    }
}

impl GroupedGemmDType<Complex32> for GroupedC32 {
    fn wrap_read(view: TypedTensorView<'_, Complex32>) -> TensorView<'_> {
        TensorView::C32(view)
    }

    fn wrap_write(view: TypedTensorViewMut<'_, Complex32>) -> TensorViewMut<'_> {
        TensorViewMut::C32(view)
    }
}

impl GroupedGemmDType<Complex64> for GroupedC64 {
    fn wrap_read(view: TypedTensorView<'_, Complex64>) -> TensorView<'_> {
        TensorView::C64(view)
    }

    fn wrap_write(view: TypedTensorViewMut<'_, Complex64>) -> TensorViewMut<'_> {
        TensorViewMut::C64(view)
    }
}

#[allow(clippy::too_many_arguments)]
fn grouped_gemm_default_loop<B, T, V>(
    backend: &mut B,
    lhs_data: &[T],
    lhs_base: isize,
    rhs_data: &[T],
    rhs_base: isize,
    out_view: &mut TypedTensorViewMut<'_, T>,
    config: &GroupedGemmConfig<'_>,
) -> crate::Result<()>
where
    B: TensorDot + ?Sized,
    T: 'static,
    V: GroupedGemmDType<T>,
{
    let op = "grouped_gemm";
    let dot_config = grouped_gemm_default_config();
    for job in config.jobs {
        let lhs_offset = add_element_offsets(op, lhs_base, job.lhs_offset, "lhs")?;
        let rhs_offset = add_element_offsets(op, rhs_base, job.rhs_offset, "rhs")?;
        let out_offset = add_element_offsets(op, out_view.offset(), job.out_offset, "out")?;
        let lhs_rows = dim_stride(op, job.rows, "lhs")?;
        let rhs_rows = dim_stride(op, job.contracted, "rhs")?;
        let out_rows = dim_stride(op, job.rows, "out")?;
        // TypedTensorView constructors own Vec shape/stride metadata. These
        // fallback rank-2 views are short-lived, but SmallVec is not usable
        // without changing the view API.
        let lhs_matrix = TypedTensorView::from_slice(
            vec![job.rows, job.contracted],
            vec![1, lhs_rows],
            lhs_offset,
            lhs_data,
        )?;
        let rhs_matrix = TypedTensorView::from_slice(
            vec![job.contracted, job.cols],
            vec![1, rhs_rows],
            rhs_offset,
            rhs_data,
        )?;
        let out_storage = out_view.host_storage_mut()?;
        let out_matrix = TypedTensorViewMut::from_slice(
            vec![job.rows, job.cols],
            vec![1, out_rows],
            out_offset,
            out_storage,
        )?;
        backend.dot_general_read_into_accum(
            TensorRead::from_view(V::wrap_read(lhs_matrix)),
            TensorRead::from_view(V::wrap_read(rhs_matrix)),
            &dot_config,
            config.accumulation,
            TensorWrite::from_view(V::wrap_write(out_matrix)),
        )?;
    }
    Ok(())
}

#[doc(hidden)]
pub fn grouped_gemm_via_sequential<B>(
    backend: &mut B,
    lhs: TensorRead<'_>,
    rhs: TensorRead<'_>,
    config: &GroupedGemmConfig<'_>,
    mut out: TensorWrite<'_>,
) -> crate::Result<()>
where
    B: TensorDot + ?Sized,
{
    validate_grouped_gemm(&lhs, &rhs, &out, config, "grouped_gemm")?;
    macro_rules! dispatch {
        ($variant:ident, $scalar:ty, $wrapper:ty) => {
            match (&lhs, &rhs, &mut out) {
                (TensorRead::Tensor(a), TensorRead::Tensor(b), TensorWrite::Tensor(c))
                    if a.dtype() == <$scalar as crate::TensorScalar>::dtype()
                        && b.dtype() == <$scalar as crate::TensorScalar>::dtype()
                        && c.dtype() == <$scalar as crate::TensorScalar>::dtype() =>
                {
                    let a = a
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let b = b
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let c = c
                        .as_typed_mut::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (a_data, a_base) = typed_read_storage(a, "grouped_gemm")?;
                    let (b_data, b_base) = typed_read_storage(b, "grouped_gemm")?;
                    let mut c_view = c.as_view_mut();
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a_data,
                        a_base,
                        b_data,
                        b_base,
                        &mut c_view,
                        config,
                    );
                }
                (
                    TensorRead::Tensor(a),
                    TensorRead::View(TensorView::$variant(b)),
                    TensorWrite::Tensor(c),
                ) if a.dtype() == <$scalar as crate::TensorScalar>::dtype()
                    && c.dtype() == <$scalar as crate::TensorScalar>::dtype() =>
                {
                    let a = a
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let c = c
                        .as_typed_mut::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (a_data, a_base) = typed_read_storage(a, "grouped_gemm")?;
                    let mut c_view = c.as_view_mut();
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a_data,
                        a_base,
                        b.host_storage()?,
                        b.offset(),
                        &mut c_view,
                        config,
                    );
                }
                (
                    TensorRead::View(TensorView::$variant(a)),
                    TensorRead::Tensor(b),
                    TensorWrite::Tensor(c),
                ) if b.dtype() == <$scalar as crate::TensorScalar>::dtype()
                    && c.dtype() == <$scalar as crate::TensorScalar>::dtype() =>
                {
                    let b = b
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let c = c
                        .as_typed_mut::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (b_data, b_base) = typed_read_storage(b, "grouped_gemm")?;
                    let mut c_view = c.as_view_mut();
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a.host_storage()?,
                        a.offset(),
                        b_data,
                        b_base,
                        &mut c_view,
                        config,
                    );
                }
                (
                    TensorRead::View(TensorView::$variant(a)),
                    TensorRead::View(TensorView::$variant(b)),
                    TensorWrite::Tensor(c),
                ) if c.dtype() == <$scalar as crate::TensorScalar>::dtype() => {
                    let c = c
                        .as_typed_mut::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let mut c_view = c.as_view_mut();
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a.host_storage()?,
                        a.offset(),
                        b.host_storage()?,
                        b.offset(),
                        &mut c_view,
                        config,
                    );
                }
                (
                    TensorRead::Tensor(a),
                    TensorRead::Tensor(b),
                    TensorWrite::View(TensorViewMut::$variant(c)),
                ) if a.dtype() == <$scalar as crate::TensorScalar>::dtype()
                    && b.dtype() == <$scalar as crate::TensorScalar>::dtype() =>
                {
                    let a = a
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let b = b
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (a_data, a_base) = typed_read_storage(a, "grouped_gemm")?;
                    let (b_data, b_base) = typed_read_storage(b, "grouped_gemm")?;
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend, a_data, a_base, b_data, b_base, c, config,
                    );
                }
                (
                    TensorRead::Tensor(a),
                    TensorRead::View(TensorView::$variant(b)),
                    TensorWrite::View(TensorViewMut::$variant(c)),
                ) if a.dtype() == <$scalar as crate::TensorScalar>::dtype() => {
                    let a = a
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (a_data, a_base) = typed_read_storage(a, "grouped_gemm")?;
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a_data,
                        a_base,
                        b.host_storage()?,
                        b.offset(),
                        c,
                        config,
                    );
                }
                (
                    TensorRead::View(TensorView::$variant(a)),
                    TensorRead::Tensor(b),
                    TensorWrite::View(TensorViewMut::$variant(c)),
                ) if b.dtype() == <$scalar as crate::TensorScalar>::dtype() => {
                    let b = b
                        .as_typed::<$scalar>()
                        .expect("the dtype guard selects this arm");
                    let (b_data, b_base) = typed_read_storage(b, "grouped_gemm")?;
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a.host_storage()?,
                        a.offset(),
                        b_data,
                        b_base,
                        c,
                        config,
                    );
                }
                (
                    TensorRead::View(TensorView::$variant(a)),
                    TensorRead::View(TensorView::$variant(b)),
                    TensorWrite::View(TensorViewMut::$variant(c)),
                ) => {
                    return grouped_gemm_default_loop::<_, _, $wrapper>(
                        backend,
                        a.host_storage()?,
                        a.offset(),
                        b.host_storage()?,
                        b.offset(),
                        c,
                        config,
                    );
                }
                _ => {}
            }
        };
    }

    dispatch!(F32, f32, GroupedF32);
    dispatch!(F64, f64, GroupedF64);
    dispatch!(C32, Complex32, GroupedC32);
    dispatch!(C64, Complex64, GroupedC64);
    Err(validation(
        "grouped_gemm",
        ValidationError::DTypeMismatch {
            expected: lhs.dtype(),
            actual: out.dtype(),
        },
    ))
}

fn grouped_gemm_default<B>(
    backend: &mut B,
    lhs: TensorRead<'_>,
    rhs: TensorRead<'_>,
    config: &GroupedGemmConfig<'_>,
    out: TensorWrite<'_>,
) -> crate::Result<()>
where
    B: TensorDot + ?Sized,
{
    grouped_gemm_via_sequential(backend, lhs, rhs, config, 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,
}

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 accepts arbitrary valid source and destination strides and performs
    /// no tensor allocation. CUDA currently accepts only a compact column-major
    /// source with offset zero covering its full allocation; CUDA destinations
    /// may be arbitrary valid non-overlapping views. CUDA rejects aliased
    /// allocations and currently reports an explicit unsupported-dtype error
    /// for `Bool`. 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>;
    /// # 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>;
    /// # 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>;
    /// # 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>;
}

/// 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.
    ///
    /// # 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::BackendSession;
///
/// fn accepts_session_dot<S: BackendSession + ?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)
    }

    #[doc(hidden)]
    fn grouped_gemm_cached(
        &mut self,
        _cache_slot: Option<usize>,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &GroupedGemmConfig<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        grouped_gemm_default(self, lhs, rhs, config, out)
    }
}

/// Indexing, slicing, and padding operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorIndexing;
///
/// fn accepts_indexing<B: TensorIndexing>(_backend: &mut B) {}
/// ```
pub trait TensorIndexing {
    /// # 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>;
    /// # 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>;
    /// # 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>;
    /// # 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>;
    /// # 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>;
    /// # 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>;
    /// # 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>;
}

/// 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 [`BackendSession`] so generic
/// typed methods do not change the object-safety contract of `dyn BackendSession`.
///
/// # 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>;
}

/// Runtime cache associated with a backend.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::BackendRuntimeCache;
///
/// fn accepts_runtime_cache<B: BackendRuntimeCache>(_backend: &B) {}
/// ```
pub trait BackendRuntimeCache {
    #[doc(hidden)]
    type RuntimeCache: RuntimeCacheControl + Send + Sync + 'static;
}

/// Backend-owned cached dot-general operations.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::BackendCachedDot;
///
/// fn accepts_backend_cached_dot<B: BackendCachedDot>(_backend: &mut B) {}
/// ```
pub trait BackendCachedDot: BackendRuntimeCache + TensorDot {
    #[doc(hidden)]
    fn dot_general_cached(
        &mut self,
        _cache: &mut Self::RuntimeCache,
        _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: &mut Self::RuntimeCache,
        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, cache_slot, lhs, rhs, config),
            _ => {
                let lhs = self.to_contiguous_read(lhs)?;
                let rhs = self.to_contiguous_read(rhs)?;
                self.dot_general_cached(cache, 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: &mut Self::RuntimeCache,
        _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: &mut Self::RuntimeCache,
        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, 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, cache_slot, lhs_ref, rhs_ref, config, lhs_conj, rhs_conj,
        )
    }

    /// Apply cached scaled dot-general accumulation into caller-provided output.
    ///
    /// The cache slot identifies backend-local analysis metadata only; output
    /// semantics are still fully described by `accumulation`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{
    ///     BackendCachedDot, BackendRuntimeCache, DotGeneralAccumulation, DotGeneralConfig,
    ///     TensorRead, TensorWrite,
    /// };
    ///
    /// fn cached_dot_add_to<B: BackendCachedDot>(
    ///     backend: &mut B,
    ///     cache: &mut B::RuntimeCache,
    ///     lhs: TensorRead<'_>,
    ///     rhs: TensorRead<'_>,
    ///     config: &DotGeneralConfig,
    ///     out: TensorWrite<'_>,
    /// ) -> tenferro_tensor::Result<()>
    /// where
    ///     B: BackendRuntimeCache,
    /// {
    ///     let accumulation = DotGeneralAccumulation::add_to(lhs.dtype())?;
    ///     backend.dot_general_read_into_accum_cached(
    ///         cache,
    ///         Some(0),
    ///         lhs,
    ///         rhs,
    ///         config,
    ///         accumulation,
    ///         out,
    ///     )
    /// }
    /// ```
    #[allow(clippy::too_many_arguments)]
    /// # 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: &mut Self::RuntimeCache,
        _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)
    }

    #[doc(hidden)]
    fn grouped_gemm_cached(
        &mut self,
        _cache: &mut Self::RuntimeCache,
        _cache_slot: Option<usize>,
        lhs: TensorRead<'_>,
        rhs: TensorRead<'_>,
        config: &GroupedGemmConfig<'_>,
        out: TensorWrite<'_>,
    ) -> crate::Result<()> {
        grouped_gemm_default(self, lhs, rhs, config, out)
    }
}

/// Backend execution-session entry points.
///
/// `with_backend_session` is the canonical user entry and the only way an
/// operation is reached from a backend; `with_backend_session_cached` is the
/// runtime-cache-aware entry used by the runtime layer.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::BackendSessionHost;
///
/// fn accepts_session_host<B: BackendSessionHost>(_backend: &mut B) {}
/// ```
///
/// The session factory this trait's default bodies used to call was deleted
/// with the one-shot spellings, so naming it does not compile:
///
/// ```compile_fail
/// use tenferro_tensor::default_backend_session;
/// ```
pub trait BackendSessionHost: BackendRuntimeCache {
    /// Open one backend session and run `f` inside it.
    ///
    /// The session is built by the backend rather than by coercing the owner, so
    /// this is the only way an operation is reached from a backend.
    ///
    /// Admission happens before `f` runs. A backend may wait for resources that
    /// another thread will release (CPU resource permits are granted in FIFO
    /// order), but it never runs `f` twice, never retries `f` through a fallback
    /// path, and never reports a failure of `f` as an admission failure: the
    /// callback's own value, including its own `Result`, is returned unchanged in
    /// `Ok`.
    ///
    /// # Errors
    ///
    /// Returns [`SessionEntryError`] without running `f` when the backend cannot
    /// admit the session: [`SessionEntryError::Reentered`] for a nested entry on
    /// the calling thread, [`SessionEntryError::Contended`] for a busy resource
    /// that admission cannot wait for, [`SessionEntryError::IncompatibleContext`]
    /// for a mismatched execution scope or executor declaration,
    /// [`SessionEntryError::ResourcePoisoned`] for poisoned admission state, and
    /// [`SessionEntryError::Executor`] when the executor cannot be entered.
    fn with_backend_session<R: Send>(
        &mut self,
        f: impl FnOnce(&mut dyn BackendSession) -> R + Send,
    ) -> Result<R, SessionEntryError>;

    #[doc(hidden)]
    fn with_backend_session_cached<R: Send>(
        &mut self,
        _cache: &mut Self::RuntimeCache,
        f: impl FnOnce(&mut dyn BackendSession) -> R + Send,
    ) -> Result<R, SessionEntryError> {
        self.with_backend_session(f)
    }
}

/// Operation capabilities shared by backends and backend sessions.
#[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 [`BackendSession::vdot_read`].
#[doc(hidden)]
pub fn validate_vdot_read(lhs: &TensorRead<'_>, rhs: &TensorRead<'_>) -> crate::Result<()> {
    let op = "BackendSession::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 [`BackendSession::norm_squared_read`].
#[doc(hidden)]
pub fn validate_norm_squared_read(input: &TensorRead<'_>) -> crate::Result<()> {
    validate_supported_blas1_dtype("BackendSession::norm_squared_read", input.dtype())?;
    validate_shape_product("BackendSession::norm_squared_read", input.shape()).map(|_| ())
}

/// Validate the shared input and destination contract for
/// [`BackendSession::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 = "BackendSession::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())?;
    if !y.as_read().is_col_major_contiguous()? {
        return Err(Error::invalid_argument(
            op,
            "y",
            "destination must be compact column-major and injective",
        ));
    }
    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(())
}

/// Execution session surface for dense tensor backends.
///
/// All operations run within a backend-owned execution scope such as a CPU
/// thread policy or a GPU stream. Individual ops must not try to re-enter that
/// scope.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::{BackendSessionHost, Tensor, TensorRead, TypedTensor};
///
/// fn add_in_session<B: BackendSessionHost>(
///     backend: &mut B,
///     a: &Tensor,
///     b: &Tensor,
/// ) -> tenferro_tensor::Result<Tensor>
/// where
///     B: tenferro_tensor::TensorBackend,
/// {
///     // Admission failure converts into `tenferro_tensor::Error::SessionEntry`;
///     // the operation's own result is returned unchanged.
///     backend.with_backend_session(|exec| {
///         exec.add_read(TensorRead::from_tensor(a), TensorRead::from_tensor(b))
///     })?
/// }
/// ```
///
/// The operation one-shot spelling is gone; a session only answers to the read
/// form:
///
/// ```compile_fail
/// use tenferro_tensor::{BackendSessionHost, Tensor, TensorBackend};
///
/// fn add_in_session<B: BackendSessionHost + TensorBackend>(
///     backend: &mut B,
///     a: &Tensor,
///     b: &Tensor,
/// ) {
///     backend.with_backend_session(|exec| {
///         let _ = exec.add(a, b);
///     });
/// }
/// ```
pub trait BackendSession: TensorBackendOps + SessionCachedDot + TensorDeviceTransfer {
    /// 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::{BackendSession, TensorRead};
    ///
    /// fn vdot(session: &mut dyn BackendSession, 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(
            "BackendSession::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::{BackendSession, TensorRead};
    ///
    /// fn norm_squared(session: &mut dyn BackendSession, 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(
            "BackendSession::norm_squared_read",
            "backend session does not implement norm_squared_read",
        ))
    }

    /// 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 compact and injective, and any x/y storage overlap
    /// is rejected before mutation.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use tenferro_tensor::{BackendSession, ContractionScalar, TensorRead, TensorWrite};
    ///
    /// fn axpby(session: &mut dyn BackendSession, 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, compactness, 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(
            "BackendSession::axpby_read_into_accum",
            "backend session does not implement axpby_read_into_accum",
        ))
    }

    /// Return this session's backend-leaf native capability, if it has one.
    ///
    /// Standard CPU, CUDA and WebGPU sessions return a token their own safe
    /// visitors (`with_cpu_exec_session`, `with_cuda_exec_session`,
    /// `with_webgpu_exec_session`) recover. The default is `None`: a custom
    /// session has no native services unless it forwards the token of a
    /// standard session 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::BackendSession;
    ///
    /// fn native_services_available(session: &mut dyn BackendSession) -> bool {
    ///     session.native_session().is_some()
    /// }
    /// ```
    fn native_session(&mut self) -> Option<crate::NativeSessionRef<'_>> {
        None
    }
}

/// Standard runtime backend over dynamic [`Tensor`] values.
///
/// # Examples
///
/// ```rust
/// use tenferro_tensor::TensorBackend;
///
/// fn accepts_backend<B: TensorBackend>(_backend: &mut B) {}
/// ```
pub trait TensorBackend: BackendRuntimeCache + TensorDeviceTransfer + BackendSessionHost {}

impl<T> SessionCachedDot for T where T: TensorBackend + TensorDot + ?Sized {}

thread_local! {
    /// Tracks whether a session-entry closure is currently running on this
    /// thread, so nested session entry is caught in debug builds even for
    /// backends that do not override
    /// [`BackendSessionHost::with_backend_session`].
    static IN_SESSION: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
}

/// Sets the in-session flag for the duration of a session closure and restores
/// it on exit, including on panic.
struct InSessionGuard;

impl InSessionGuard {
    /// Set the in-session flag for one session closure.
    ///
    /// # Errors
    ///
    /// Returns [`SessionEntryError::Reentered`] when a session closure is
    /// already running on this thread.
    fn enter(backend: &'static str) -> Result<Self, SessionEntryError> {
        if IN_SESSION.get() {
            return Err(SessionEntryError::Reentered { backend });
        }
        IN_SESSION.set(true);
        Ok(InSessionGuard)
    }
}

impl Drop for InSessionGuard {
    fn drop(&mut self) {
        IN_SESSION.set(false);
    }
}

/// Whether a portable backend-session closure is running on the current thread.
///
/// Hosts that enter through [`with_session_entry_guard`] (CUDA, WebGPU and
/// backends keeping the default entry) set this flag for the duration of their
/// session closure. An owner that serializes callers with a blocking lock must
/// check it, together with its backend's own admission state, *before* waiting
/// on that lock: a thread holding a session must not wait on an owner another
/// thread holds while that thread waits for the same session's resources.
///
/// # Examples
///
/// ```
/// assert!(!tenferro_tensor::has_active_backend_session());
/// tenferro_tensor::with_session_entry_guard("doc", || {
///     assert!(tenferro_tensor::has_active_backend_session());
/// })?;
/// assert!(!tenferro_tensor::has_active_backend_session());
/// # Ok::<(), tenferro_tensor::SessionEntryError>(())
/// ```
pub fn has_active_backend_session() -> bool {
    IN_SESSION.get()
}

/// Run `f` with the thread-local in-session flag set, restoring it on exit
/// including on panic.
///
/// This is the portable nested-entry guard shared by backend-session entry
/// points that have no resource permit of their own. A nested entry on the same
/// thread is rejected with [`SessionEntryError::Reentered`] before `f` runs, in
/// every build profile. CPU admission tracks reentry through its execution
/// owner instead.
#[doc(hidden)]
pub fn with_session_entry_guard<R>(
    backend: &'static str,
    f: impl FnOnce() -> R,
) -> Result<R, SessionEntryError> {
    let _guard = InSessionGuard::enter(backend)?;
    Ok(f())
}