Skip to main content

tenferro_tensor/
types.rs

1use num_complex::{Complex, Complex32, Complex64};
2use num_traits::{One, Zero};
3use std::any::Any;
4use std::fmt::Debug;
5use std::marker::PhantomData;
6use std::mem::{align_of, needs_drop, offset_of, size_of};
7use std::num::NonZeroUsize;
8use std::ops::Deref;
9use std::sync::atomic::{AtomicU64, Ordering};
10
11use crate::config::SliceConfig;
12use crate::error::ReinterpretError;
13pub use tenferro_tensor_core::{DType, DynRank, Rank, TensorLayout, TensorRank};
14use tenferro_tensor_core::{ShapeVec, StrideVec};
15use tenferro_tensor_core::{SliceSpec as CoreSliceSpec, ValidationError};
16use tinyvec::TinyVec;
17
18use crate::storage::{
19    AllocationGroup, AllocationSlot, BackendAllocation, DescriptorSlot, GroupError, GroupReadView,
20    GroupWriteView,
21};
22
23mod accessors;
24mod col_major;
25mod shape_packing;
26mod strided_view;
27#[cfg(test)]
28mod tests;
29
30pub use col_major::{ColMajorView, ColMajorViewMut};
31pub use strided_view::StridedSliceSpec;
32
33pub(crate) fn shape_vec(shape: &[usize]) -> ShapeVec {
34    shape.iter().copied().collect()
35}
36
37pub(crate) fn stride_vec(strides: &[isize]) -> StrideVec {
38    strides.iter().copied().collect()
39}
40
41pub(crate) fn shape_vec_zeros(len: usize) -> ShapeVec {
42    std::iter::repeat_n(0, len).collect()
43}
44
45fn representation_pair_error(
46    op: &'static str,
47    from: DType,
48    to: DType,
49    message: impl Into<String>,
50) -> crate::Error {
51    crate::Error::unsupported_dtype_conversion(op, from, to, message)
52}
53
54fn validate_representation_pair(op: &'static str, from: DType, to: DType) -> crate::Result<()> {
55    let valid = match (from, to) {
56        (DType::C32, DType::F32) | (DType::F32, DType::C32) => {
57            size_of::<Complex32>() == 2 * size_of::<f32>()
58                && align_of::<Complex32>() == align_of::<f32>()
59                && offset_of!(Complex32, re) == 0
60                && offset_of!(Complex32, im) == size_of::<f32>()
61                && !needs_drop::<Complex32>()
62                && !needs_drop::<f32>()
63        }
64        (DType::C64, DType::F64) | (DType::F64, DType::C64) => {
65            size_of::<Complex64>() == 2 * size_of::<f64>()
66                && align_of::<Complex64>() == align_of::<f64>()
67                && offset_of!(Complex64, re) == 0
68                && offset_of!(Complex64, im) == size_of::<f64>()
69                && !needs_drop::<Complex64>()
70                && !needs_drop::<f64>()
71        }
72        _ => false,
73    };
74    if valid {
75        Ok(())
76    } else {
77        Err(representation_pair_error(
78            op,
79            from,
80            to,
81            "only the sealed Complex<f32><->f32 and Complex<f64><->f64 representations are supported",
82        ))
83    }
84}
85
86fn reinterpret_complex_to_real_layout(
87    shape: &[usize],
88    strides: &[isize],
89    offset: isize,
90    complex_buffer_len: usize,
91    op: &'static str,
92) -> crate::Result<TensorLayout<DynRank>> {
93    let real_buffer_len = complex_buffer_len
94        .checked_mul(2)
95        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
96    let rank = shape
97        .len()
98        .checked_add(1)
99        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
100    let mut real_shape = ShapeVec::with_capacity(rank);
101    real_shape.push(2);
102    real_shape.extend_from_slice(shape);
103    let mut real_strides = StrideVec::with_capacity(rank);
104    real_strides.push(1);
105    for &stride in strides {
106        real_strides.push(
107            stride
108                .checked_mul(2)
109                .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
110        );
111    }
112    let real_offset = offset
113        .checked_mul(2)
114        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
115    TensorLayout::from_parts(real_shape, real_strides, real_offset, real_buffer_len)
116        .map_err(|err| tensor_layout_error(op, err))
117}
118
119fn reinterpret_real_to_complex_layout(
120    shape: &[usize],
121    strides: &[isize],
122    offset: isize,
123    real_buffer_len: usize,
124    op: &'static str,
125) -> crate::Result<TensorLayout<DynRank>> {
126    if shape.first().copied() != Some(2) {
127        return Err(crate::Error::invalid_argument(
128            op,
129            "shape",
130            "the leading extent must be 2 for a complex reinterpretation",
131        ));
132    }
133    if strides.first().copied() != Some(1) {
134        return Err(crate::Error::invalid_argument(
135            op,
136            "strides",
137            "the leading stride must be 1 for a complex reinterpretation",
138        ));
139    }
140    if offset % 2 != 0 {
141        return Err(crate::Error::invalid_argument(
142            op,
143            "offset",
144            "the offset must be divisible by 2 for a complex reinterpretation",
145        ));
146    }
147    let mut complex_strides = StrideVec::with_capacity(strides.len() - 1);
148    for &stride in &strides[1..] {
149        if stride % 2 != 0 {
150            return Err(crate::Error::invalid_argument(
151                op,
152                "strides",
153                "all non-leading strides must be divisible by 2",
154            ));
155        }
156        complex_strides.push(stride / 2);
157    }
158    let complex_buffer_len = real_buffer_len / 2;
159    TensorLayout::from_parts(
160        shape[1..].iter().copied().collect(),
161        complex_strides,
162        offset / 2,
163        complex_buffer_len,
164    )
165    .map_err(|err| tensor_layout_error(op, err))
166}
167
168fn reinterpret_host_slice<'a, T: TensorScalar, U: TensorScalar>(
169    data: &'a [T],
170    op: &'static str,
171) -> crate::Result<&'a [U]> {
172    let byte_len = data
173        .len()
174        .checked_mul(size_of::<T>())
175        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
176    if !byte_len.is_multiple_of(size_of::<U>()) {
177        return Err(crate::Error::validation(
178            op,
179            ValidationError::ViewOutOfBounds,
180        ));
181    }
182    if data.as_ptr().align_offset(align_of::<U>()) != 0 {
183        return Err(crate::Error::invalid_argument(
184            op,
185            "alignment",
186            "the source allocation is not aligned for the target representation",
187        ));
188    }
189    // SAFETY: `validate_representation_pair` seals the only supported pairs;
190    // sizes, alignment, field order, and drop properties are checked before
191    // exposing the borrowed target slice.
192    Ok(unsafe { std::slice::from_raw_parts(data.as_ptr().cast::<U>(), byte_len / size_of::<U>()) })
193}
194
195fn reinterpret_host_slice_mut<'a, T: TensorScalar, U: TensorScalar>(
196    data: &'a mut [T],
197    op: &'static str,
198) -> crate::Result<&'a mut [U]> {
199    let byte_len = data
200        .len()
201        .checked_mul(size_of::<T>())
202        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
203    if !byte_len.is_multiple_of(size_of::<U>()) {
204        return Err(crate::Error::validation(
205            op,
206            ValidationError::ViewOutOfBounds,
207        ));
208    }
209    if data.as_mut_ptr().align_offset(align_of::<U>()) != 0 {
210        return Err(crate::Error::invalid_argument(
211            op,
212            "alignment",
213            "the source allocation is not aligned for the target representation",
214        ));
215    }
216    // SAFETY: the mutable source borrow is unique and the sealed pair has no
217    // padding or drop glue, so the target slice covers the same bytes exactly.
218    Ok(unsafe {
219        std::slice::from_raw_parts_mut(data.as_mut_ptr().cast::<U>(), byte_len / size_of::<U>())
220    })
221}
222
223/// Memory location for tensor storage.
224///
225/// # Examples
226///
227/// ```rust
228/// use tenferro_tensor::MemoryKind;
229///
230/// let kind = MemoryKind::UnpinnedHost;
231/// ```
232#[derive(Clone, Debug, PartialEq, Eq, Hash)]
233pub enum MemoryKind {
234    Device,
235    PinnedHost,
236    UnpinnedHost,
237    Managed,
238    Other(String),
239}
240
241/// Compute device family.
242///
243/// # Examples
244///
245/// ```rust
246/// use tenferro_tensor::DeviceKind;
247///
248/// let kind = DeviceKind::Cpu;
249/// ```
250#[derive(Clone, Debug, PartialEq, Eq, Hash)]
251pub enum DeviceKind {
252    Cpu,
253    Gpu(GpuBackendKind),
254    Other(String),
255}
256
257/// GPU backend family used by placement metadata.
258///
259/// # Examples
260///
261/// ```rust
262/// use tenferro_tensor::GpuBackendKind;
263///
264/// let kind = GpuBackendKind::Cuda;
265/// let webgpu = GpuBackendKind::WebGpu;
266/// assert_ne!(kind, webgpu);
267/// ```
268#[derive(Clone, Debug, PartialEq, Eq, Hash)]
269pub enum GpuBackendKind {
270    Cuda,
271    WebGpu,
272    Rocm,
273    /// Apple GPU through Metal (design `metal-backend.md`, issue tenferro-rs#2402).
274    Metal,
275    Other(String),
276}
277
278/// Concrete compute device identifier.
279///
280/// # Examples
281///
282/// ```rust
283/// use tenferro_tensor::{DeviceId, DeviceKind, GpuBackendKind};
284///
285/// let device = DeviceId {
286///     kind: DeviceKind::Gpu(GpuBackendKind::Cuda),
287///     ordinal: 0,
288/// };
289/// ```
290#[derive(Clone, Debug, PartialEq, Eq, Hash)]
291pub struct DeviceId {
292    pub kind: DeviceKind,
293    pub ordinal: usize,
294}
295
296/// Caller-stable identity for a CPU execution domain.
297///
298/// Domain IDs are metadata supplied by the caller or execution coordinator;
299/// creating an ID does not allocate a process-global identity.
300///
301/// # Examples
302///
303/// ```rust
304/// use tenferro_tensor::CpuDomainId;
305///
306/// let domain = CpuDomainId::new(17);
307/// assert_eq!(domain.as_u64(), 17);
308/// ```
309#[repr(transparent)]
310#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
311pub struct CpuDomainId(u64);
312
313impl CpuDomainId {
314    /// Create a caller-stable CPU domain identity.
315    ///
316    /// # Examples
317    ///
318    /// ```rust
319    /// use tenferro_tensor::CpuDomainId;
320    ///
321    /// assert_eq!(CpuDomainId::new(3), CpuDomainId::new(3));
322    /// ```
323    pub const fn new(id: u64) -> Self {
324        Self(id)
325    }
326
327    /// Return the caller-supplied integer identity.
328    ///
329    /// # Examples
330    ///
331    /// ```rust
332    /// use tenferro_tensor::CpuDomainId;
333    ///
334    /// assert_eq!(CpuDomainId::new(9).as_u64(), 9);
335    /// ```
336    pub const fn as_u64(self) -> u64 {
337        self.0
338    }
339}
340
341/// Placement metadata for a tensor buffer.
342///
343/// # Examples
344///
345/// ```rust
346/// use tenferro_tensor::{DeviceId, DeviceKind, GpuBackendKind, MemoryKind, Placement};
347///
348/// let placement = Placement {
349///     memory_kind: MemoryKind::Device,
350///     device: Some(DeviceId {
351///         kind: DeviceKind::Gpu(GpuBackendKind::Cuda),
352///         ordinal: 0,
353///     }),
354///     cpu_affinity: None,
355/// };
356/// assert!(placement.cpu_affinity.is_none());
357/// ```
358#[derive(Clone, Debug, PartialEq, Eq, Hash)]
359pub struct Placement {
360    /// Storage memory class, independent of execution routing metadata.
361    pub memory_kind: MemoryKind,
362    /// Device that owns or addresses the storage, when applicable.
363    pub device: Option<DeviceId>,
364    /// Preferred or producing CPU execution domain for routing and locality.
365    ///
366    /// This tag is not proof of allocation ownership, page residency, NUMA
367    /// pinning, or worker-affinity enforcement. Backend allocation-domain
368    /// metadata remains attached to the buffer independently.
369    pub cpu_affinity: Option<CpuDomainId>,
370}
371
372impl Default for Placement {
373    fn default() -> Self {
374        default_placement()
375    }
376}
377
378/// Backend-owned buffer handle.
379///
380/// `BackendStorageHandle::new` creates an empty opaque handle. Use
381/// [`BackendStorageHandle::new_with_len`] when test or adapter code needs to model a
382/// non-empty backend allocation.
383///
384/// # Examples
385///
386/// ```rust
387/// use tenferro_tensor::BackendStorageHandle;
388///
389/// let handle = BackendStorageHandle::<f64>::new(7);
390/// ```
391pub struct BackendStorageHandle<T> {
392    id: u64,
393    len: usize,
394    allocation_domain: AllocationDomainId,
395    _phantom: std::marker::PhantomData<T>,
396}
397
398/// Identity of a backend-owned allocation domain.
399///
400/// Domains let cooperating backends accept shared allocations without treating
401/// another context's physically similar buffer as compatible.
402///
403/// # Examples
404///
405/// ```rust
406/// use tenferro_tensor::AllocationDomainId;
407///
408/// assert_ne!(AllocationDomainId::fresh(), AllocationDomainId::fresh());
409/// ```
410#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
411pub struct AllocationDomainId(u64);
412
413impl AllocationDomainId {
414    /// Create a process-unique allocation-domain identity.
415    ///
416    /// # Examples
417    ///
418    /// ```rust
419    /// use tenferro_tensor::AllocationDomainId;
420    ///
421    /// let domain = AllocationDomainId::fresh();
422    /// assert_eq!(domain, domain);
423    /// ```
424    pub fn fresh() -> Self {
425        static NEXT_DOMAIN_ID: AtomicU64 = AtomicU64::new(1);
426        Self(NEXT_DOMAIN_ID.fetch_add(1, Ordering::Relaxed))
427    }
428}
429
430/// Stable physical identity of one backend allocation.
431///
432/// # Examples
433///
434/// ```rust
435/// use tenferro_tensor::AllocationId;
436///
437/// assert_eq!(AllocationId::from_backend_id(7), AllocationId::from_backend_id(7));
438/// ```
439#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
440pub struct AllocationId(u64);
441
442impl AllocationId {
443    /// Wrap an allocation identity supplied by the owning backend.
444    ///
445    /// # Examples
446    ///
447    /// ```rust
448    /// use tenferro_tensor::AllocationId;
449    ///
450    /// let id = AllocationId::from_backend_id(3);
451    /// assert_eq!(id, AllocationId::from_backend_id(3));
452    /// ```
453    pub const fn from_backend_id(id: u64) -> Self {
454        Self(id)
455    }
456}
457
458/// Typed failure returned by guarded backend host access.
459///
460/// # Examples
461///
462/// ```rust
463/// use tenferro_tensor::HostAccessError;
464///
465/// let error = HostAccessError::Unsupported { backend: "opaque" };
466/// assert!(error.to_string().contains("opaque"));
467/// ```
468#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
469#[non_exhaustive]
470pub enum HostAccessError {
471    /// The backend does not expose guarded host access for this allocation.
472    #[error("backend `{backend}` does not support guarded host access")]
473    Unsupported { backend: &'static str },
474    /// The allocation belongs to another shared-allocation domain.
475    #[error("allocation belongs to domain {actual:?}, expected {expected:?}")]
476    ForeignDomain {
477        expected: AllocationDomainId,
478        actual: AllocationDomainId,
479    },
480    /// Another host mapping overlaps this allocation.
481    #[error("the allocation already has an active host mapping")]
482    OverlappingHostMapping,
483    /// GPU work currently owns or has reserved the allocation.
484    #[error("GPU access is in progress for the allocation")]
485    GpuAccessInProgress,
486    /// Host mapping is active while GPU access was requested.
487    #[error("the allocation is mapped for host access")]
488    MappedForHost,
489    /// The backend failed to complete the map operation.
490    #[error("backend host mapping failed: {message}")]
491    BackendFailure { message: String },
492    /// The source did not cover the full write-only mapping.
493    #[error("host write length mismatch: expected {expected}, got {actual}")]
494    LengthMismatch { expected: usize, actual: usize },
495}
496
497/// Metadata sealed at the tensor/root boundary before a provider launch.
498///
499/// Providers receive this request exactly once for a prepared access. Binding
500/// code consumes the resulting opaque state and does not receive replacement
501/// storage, ranges, or raw pointers.
502#[doc(hidden)]
503#[derive(Clone, Copy, Debug)]
504pub struct DeviceAccessRequest<'a> {
505    allocation_domain: AllocationDomainId,
506    allocation_id: AllocationId,
507    byte_len: usize,
508    element_size: usize,
509    shape: &'a [usize],
510    strides: &'a [isize],
511    offset: isize,
512}
513
514impl<'a> DeviceAccessRequest<'a> {
515    pub(crate) fn new(
516        allocation_domain: AllocationDomainId,
517        allocation_id: AllocationId,
518        byte_len: usize,
519        element_size: usize,
520        shape: &'a [usize],
521        strides: &'a [isize],
522        offset: isize,
523    ) -> Self {
524        Self {
525            allocation_domain,
526            allocation_id,
527            byte_len,
528            element_size,
529            shape,
530            strides,
531            offset,
532        }
533    }
534
535    pub fn allocation_domain(&self) -> AllocationDomainId {
536        self.allocation_domain
537    }
538
539    pub fn allocation_id(&self) -> AllocationId {
540        self.allocation_id
541    }
542
543    pub fn byte_len(&self) -> usize {
544        self.byte_len
545    }
546
547    pub fn element_size(&self) -> usize {
548        self.element_size
549    }
550
551    pub fn shape(&self) -> &[usize] {
552        self.shape
553    }
554
555    pub fn strides(&self) -> &[isize] {
556        self.strides
557    }
558
559    pub fn offset(&self) -> isize {
560        self.offset
561    }
562}
563
564/// Typed failure returned while preparing a provider-native device access.
565#[doc(hidden)]
566#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
567pub enum DeviceAccessError {
568    #[error("backend `{backend}` does not support prepared device access")]
569    Unsupported { backend: &'static str },
570    #[error("prepared device access request is invalid: {message}")]
571    InvalidRequest { message: String },
572    #[error("provider device preparation failed: {message}")]
573    ProviderFailure { message: String },
574}
575
576/// Opaque provider-prepared state retained for one device binding.
577#[doc(hidden)]
578pub trait PreparedDeviceAccess: Debug {
579    fn as_any(&self) -> &dyn Any;
580
581    fn into_any(self: Box<Self>) -> Box<dyn Any>;
582}
583
584trait ReadGuardAccess<T> {
585    fn as_slice(&self) -> &[T];
586}
587
588impl<T, G> ReadGuardAccess<T> for G
589where
590    G: Deref,
591    G::Target: AsRef<[T]>,
592{
593    fn as_slice(&self) -> &[T] {
594        self.deref().as_ref()
595    }
596}
597
598/// Closure-scoped read mapping of a backend allocation.
599///
600/// # Examples
601///
602/// ```rust
603/// use tenferro_tensor::HostReadGuard;
604///
605/// let guard = HostReadGuard::new(vec![1_u32, 2]);
606/// assert_eq!(&*guard, &[1, 2]);
607/// ```
608pub struct HostReadGuard<'a, T> {
609    access: Box<dyn ReadGuardAccess<T> + 'a>,
610}
611
612impl<T> Debug for HostReadGuard<'_, T> {
613    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
614        formatter
615            .debug_struct("HostReadGuard")
616            .field("len", &self.len())
617            .finish_non_exhaustive()
618    }
619}
620
621impl<'a, T> HostReadGuard<'a, T> {
622    /// Wrap a backend-native read guard without exposing its concrete type.
623    ///
624    /// # Examples
625    ///
626    /// ```rust
627    /// use tenferro_tensor::HostReadGuard;
628    ///
629    /// let guard = HostReadGuard::new(vec![3_i32]);
630    /// assert_eq!(guard[0], 3);
631    /// ```
632    pub fn new<G>(guard: G) -> Self
633    where
634        G: Deref + 'a,
635        G::Target: AsRef<[T]>,
636        T: 'a,
637    {
638        Self {
639            access: Box::new(guard),
640        }
641    }
642
643    /// Borrow the mapped elements as a rank-1 host view.
644    ///
645    /// The view lends the mapping's shared borrow, so the guard stays alive for
646    /// as long as the view is used and no copy or transfer happens.
647    ///
648    /// # Examples
649    ///
650    /// ```rust
651    /// use tenferro_tensor::HostReadGuard;
652    ///
653    /// let guard = HostReadGuard::new(vec![3_i32, 4]);
654    /// let view = guard.as_view()?;
655    /// assert_eq!(view.shape(), &[2]);
656    /// assert_eq!(view.get(&[1]), Some(&4));
657    /// # Ok::<(), tenferro_tensor::Error>(())
658    /// ```
659    ///
660    /// # Errors
661    ///
662    /// Returns [`crate::Error::Validation`] with
663    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] or
664    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
665    /// mapped length cannot be represented as a rank-1 layout.
666    pub fn as_view(&self) -> crate::Result<TypedTensorView<'_, T, DynRank>>
667    where
668        T: 'static,
669    {
670        let data: &[T] = self;
671        TypedTensorView::from_slice(vec![data.len()], vec![1], 0, data)
672    }
673}
674
675impl<T> Deref for HostReadGuard<'_, T> {
676    type Target = [T];
677
678    fn deref(&self) -> &Self::Target {
679        self.access.as_slice()
680    }
681}
682
683/// Backend-neutral owner of one shared tensor allocation domain.
684///
685/// CPU operation crates use this object-safe boundary to allocate results in
686/// the same managed domain without depending on a GPU provider crate.
687///
688/// # Examples
689///
690/// ```rust
691/// use std::sync::Arc;
692/// use tenferro_tensor::SharedTensorAllocationDomain;
693///
694/// let _domain: Option<Arc<dyn SharedTensorAllocationDomain>> = None;
695/// ```
696pub trait SharedTensorAllocationDomain: Debug + Send + Sync + 'static {
697    /// Return the stable identity shared by every allocation from this owner.
698    fn id(&self) -> AllocationDomainId;
699
700    /// Allocate an uninitialized compact column-major tensor in this domain.
701    ///
702    /// # Errors
703    ///
704    /// Returns a typed validation, unsupported-dtype, or backend allocation error.
705    fn allocate(&self, dtype: DType, shape: &[usize]) -> crate::Result<Tensor>;
706}
707
708type HostWriteCopy<'a, T> = dyn FnMut(&[T]) -> Result<(), HostAccessError> + 'a;
709
710/// Closure-scoped write-only mapping of a backend allocation.
711///
712/// # Examples
713///
714/// ```rust
715/// use tenferro_tensor::{HostAccessError, HostWriteGuard};
716///
717/// let mut written = Vec::new();
718/// {
719///     let mut guard = HostWriteGuard::new(2, |source: &[u32]| {
720///         written.extend_from_slice(source);
721///         Ok::<(), HostAccessError>(())
722///     });
723///     guard.copy_from_slice(&[4, 5]).unwrap();
724/// }
725/// assert_eq!(written, [4, 5]);
726/// ```
727pub struct HostWriteGuard<'a, T> {
728    len: usize,
729    copy: Box<HostWriteCopy<'a, T>>,
730}
731
732impl<T> Debug for HostWriteGuard<'_, T> {
733    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
734        formatter
735            .debug_struct("HostWriteGuard")
736            .field("len", &self.len)
737            .finish_non_exhaustive()
738    }
739}
740
741impl<'a, T> HostWriteGuard<'a, T> {
742    /// Wrap a backend-native write guard without exposing its concrete type.
743    ///
744    /// # Examples
745    ///
746    /// ```rust
747    /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
748    ///
749    /// let guard = HostWriteGuard::new(0, |_source: &[f32]| Ok::<(), HostAccessError>(()));
750    /// assert!(guard.is_empty());
751    /// ```
752    ///
753    /// # Errors
754    ///
755    /// Construction is infallible. A callback failure such as
756    /// [`HostAccessError::BackendFailure`] is returned later by
757    /// [`Self::copy_from_slice`].
758    pub fn new<F>(len: usize, copy: F) -> Self
759    where
760        F: FnMut(&[T]) -> Result<(), HostAccessError> + 'a,
761        T: 'a,
762    {
763        Self {
764            len,
765            copy: Box::new(copy),
766        }
767    }
768
769    /// Number of elements covered by this write-only mapping.
770    ///
771    /// # Examples
772    ///
773    /// ```rust
774    /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
775    ///
776    /// let guard = HostWriteGuard::new(2, |_source: &[f32]| Ok::<(), HostAccessError>(()));
777    /// assert_eq!(guard.len(), 2);
778    /// ```
779    pub fn len(&self) -> usize {
780        self.len
781    }
782
783    /// Returns `true` when this mapping covers no elements.
784    ///
785    /// # Examples
786    ///
787    /// ```rust
788    /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
789    ///
790    /// let guard = HostWriteGuard::new(0, |_source: &[f32]| Ok::<(), HostAccessError>(()));
791    /// assert!(guard.is_empty());
792    /// ```
793    pub fn is_empty(&self) -> bool {
794        self.len == 0
795    }
796
797    /// Replace the full mapped allocation contents.
798    ///
799    /// # Examples
800    ///
801    /// ```rust
802    /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
803    ///
804    /// let mut guard = HostWriteGuard::new(1, |_source: &[f32]| Ok::<(), HostAccessError>(()));
805    /// guard.copy_from_slice(&[1.0]).unwrap();
806    /// ```
807    ///
808    /// # Errors
809    ///
810    /// Returns [`HostAccessError::LengthMismatch`] when `source` does not cover
811    /// the complete mapping, or the typed backend error returned by the owning
812    /// write guard.
813    pub fn copy_from_slice(&mut self, source: &[T]) -> Result<(), HostAccessError> {
814        if source.len() != self.len {
815            return Err(HostAccessError::LengthMismatch {
816                expected: self.len,
817                actual: source.len(),
818            });
819        }
820        (self.copy)(source)
821    }
822}
823
824impl<T> Debug for BackendStorageHandle<T> {
825    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
826        f.debug_struct("BackendStorageHandle")
827            .field("id", &self.id)
828            .finish()
829    }
830}
831
832impl<T> BackendStorageHandle<T> {
833    /// Create a new backend buffer handle.
834    ///
835    /// # Examples
836    ///
837    /// ```rust
838    /// use tenferro_tensor::BackendStorageHandle;
839    ///
840    /// let handle = BackendStorageHandle::<f64>::new(1);
841    /// assert_eq!(tenferro_tensor::BackendStorage::len(&handle), 0);
842    /// ```
843    pub fn new(id: u64) -> Self {
844        Self::new_with_len(id, 0)
845    }
846
847    /// Create a new backend buffer handle with a logical element count.
848    ///
849    /// # Examples
850    ///
851    /// ```rust
852    /// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
853    ///
854    /// let handle = BackendStorageHandle::<f64>::new_with_len(1, 4);
855    /// assert_eq!(BackendStorage::len(&handle), 4);
856    /// ```
857    pub fn new_with_len(id: u64, len: usize) -> Self {
858        Self {
859            id,
860            len,
861            // Synthetic opaque handles are test/adapter allocations. Give
862            // each one an explicit domain so root import never fabricates
863            // identity from a missing provider field.
864            allocation_domain: AllocationDomainId::fresh(),
865            _phantom: std::marker::PhantomData,
866        }
867    }
868}
869
870/// Opaque backend-owned tensor buffer.
871///
872/// Tensor core never inspects backend-native allocations directly. Backend
873/// crates store their own concrete handle types behind this trait and
874/// downcast inside the owning backend only.
875///
876/// # Examples
877///
878/// ```rust
879/// use std::sync::Arc;
880/// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
881///
882/// let buffer: Arc<dyn BackendStorage<f64>> = Arc::new(BackendStorageHandle::<f64>::new_with_len(7, 2));
883/// assert_eq!(buffer.backend_family(), "opaque");
884/// assert_eq!(buffer.len(), 2);
885/// ```
886pub trait BackendStorage<T>: Debug + Send + Sync + 'static {
887    /// Stable backend family identifier.
888    fn backend_family(&self) -> &'static str;
889
890    /// Number of logical elements in the backend allocation.
891    fn len(&self) -> usize;
892
893    /// Returns `true` when the backend allocation is empty.
894    fn is_empty(&self) -> bool {
895        self.len() == 0
896    }
897
898    /// Return the shared-allocation domain, when this buffer belongs to one.
899    fn allocation_domain(&self) -> Option<AllocationDomainId> {
900        None
901    }
902
903    /// Return the stable physical allocation identity, when available.
904    fn allocation_id(&self) -> Option<AllocationId> {
905        None
906    }
907
908    /// Prepare one provider-native device access from the root-owned buffer.
909    ///
910    /// The returned state is consumed by the provider binding path. Providers
911    /// that do not expose device launches return [`DeviceAccessError::Unsupported`].
912    #[doc(hidden)]
913    fn prepare_device_access(
914        &self,
915        _request: DeviceAccessRequest<'_>,
916    ) -> Result<Box<dyn PreparedDeviceAccess>, DeviceAccessError> {
917        Err(DeviceAccessError::Unsupported {
918            backend: self.backend_family(),
919        })
920    }
921
922    /// Map the allocation for closure-scoped host reads.
923    ///
924    /// # Errors
925    ///
926    /// The default returns [`HostAccessError::Unsupported`]. Host-visible
927    /// backends return typed overlap, pending-GPU, or backend mapping failures.
928    fn map_read(&self) -> Result<HostReadGuard<'_, T>, HostAccessError> {
929        Err(HostAccessError::Unsupported {
930            backend: self.backend_family(),
931        })
932    }
933
934    /// Map the allocation for closure-scoped host writes.
935    ///
936    /// The mutable receiver keeps write authority with the owning tensor or
937    /// provider object; borrowed views do not clone or share that authority.
938    ///
939    /// # Errors
940    ///
941    /// The default returns [`HostAccessError::Unsupported`]. Host-visible
942    /// backends return typed overlap, pending-GPU, or backend mapping failures.
943    fn map_write(&mut self) -> Result<HostWriteGuard<'_, T>, HostAccessError> {
944        Err(HostAccessError::Unsupported {
945            backend: self.backend_family(),
946        })
947    }
948
949    /// Borrow the allocation as shared memory the CPU and the device both address.
950    ///
951    /// A provider implements this only for an allocation whose elements are
952    /// readable at the same address from the host and from the device (a shared
953    /// allocation domain). **The call is the wait**: an implementation waits for
954    /// its pending device writes before it hands out the borrow, so there is no
955    /// separate fence call and no copy, and the borrow itself is the only host
956    /// access that exists for such an allocation.
957    ///
958    /// This is deliberately a borrow rather than a closure-scoped guard like
959    /// [`Self::map_read`]: a shared allocation is never mapped or unmapped, and
960    /// a CPU kernel needs a `StridedView<'a, T>` that outlives such a guard.
961    /// Exclusive CPU writes still go through [`Self::map_write`] and the
962    /// ownership kernel's exclusive capability.
963    ///
964    /// # Examples
965    ///
966    /// ```rust
967    /// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
968    ///
969    /// // An opaque handle exposes no shared memory, so it keeps the refusal.
970    /// let buffer = BackendStorageHandle::<f32>::new_with_len(1, 4);
971    /// assert!(buffer.shared_host_slice().is_err());
972    /// ```
973    ///
974    /// # Errors
975    ///
976    /// The default returns [`HostAccessError::Unsupported`], so every
977    /// device-local backend refuses shared host access exactly as before. A
978    /// provider that cannot serve the borrow returns its own typed failure.
979    fn shared_host_slice(&self) -> Result<&[T], HostAccessError> {
980        Err(HostAccessError::Unsupported {
981            backend: self.backend_family(),
982        })
983    }
984
985    /// Type-erased access for the backend crate that owns the concrete handle.
986    fn as_any(&self) -> &dyn Any;
987}
988
989impl<T: Send + Sync + 'static> BackendStorage<T> for BackendStorageHandle<T> {
990    fn backend_family(&self) -> &'static str {
991        "opaque"
992    }
993
994    fn len(&self) -> usize {
995        self.len
996    }
997
998    fn allocation_domain(&self) -> Option<AllocationDomainId> {
999        Some(self.allocation_domain)
1000    }
1001
1002    fn allocation_id(&self) -> Option<AllocationId> {
1003        Some(AllocationId::from_backend_id(self.id))
1004    }
1005
1006    fn as_any(&self) -> &dyn Any {
1007        self
1008    }
1009}
1010
1011/// Tensor storage.
1012///
1013/// # Examples
1014///
1015/// ```rust
1016/// use tenferro_tensor::StorageBuffer;
1017///
1018/// let host = StorageBuffer::Host(vec![1.0_f64, 2.0]);
1019/// ```
1020#[derive(Debug)]
1021pub enum StorageBuffer<T> {
1022    Host(Vec<T>),
1023    Backend(Box<dyn BackendStorage<T>>),
1024}
1025
1026impl<T: 'static> StorageBuffer<T> {
1027    /// Return the physical element count in this buffer.
1028    ///
1029    /// # Examples
1030    ///
1031    /// ```rust
1032    /// use tenferro_tensor::StorageBuffer;
1033    ///
1034    /// assert_eq!(StorageBuffer::Host(vec![1_i32, 2]).len(), 2);
1035    /// ```
1036    pub fn len(&self) -> usize {
1037        match self {
1038            Self::Host(data) => data.len(),
1039            Self::Backend(buffer) => buffer.len(),
1040        }
1041    }
1042
1043    /// Return whether this buffer has no physical elements.
1044    ///
1045    /// # Examples
1046    ///
1047    /// ```rust
1048    /// use tenferro_tensor::StorageBuffer;
1049    ///
1050    /// assert!(StorageBuffer::<i32>::Host(Vec::new()).is_empty());
1051    /// ```
1052    pub fn is_empty(&self) -> bool {
1053        self.len() == 0
1054    }
1055
1056    /// Return whether the storage is backend-owned rather than host-owned.
1057    ///
1058    /// # Examples
1059    ///
1060    /// ```rust
1061    /// use tenferro_tensor::StorageBuffer;
1062    ///
1063    /// assert!(!StorageBuffer::Host(vec![1_i32]).is_backend());
1064    /// ```
1065    pub fn is_backend(&self) -> bool {
1066        matches!(self, Self::Backend(_))
1067    }
1068}
1069
1070/// Sealed marker for the plain and pooled host payload of a [`TypedTensor`].
1071///
1072/// `TypedTensor<T, R, Host>` owns host elements directly, so it offers
1073/// infallible host access (`as_slice`, `get`, `get_mut`, `Index`/`IndexMut`)
1074/// and [`Clone`] without a runtime device check. `T` needs no `Copy`,
1075/// [`TensorScalar`] or arithmetic bound for that.
1076///
1077/// # Examples
1078///
1079/// ```
1080/// use tenferro_tensor::{DynRank, Host, TypedTensor};
1081///
1082/// let tensor: TypedTensor<f64, DynRank, Host> =
1083///     TypedTensor::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1084/// assert_eq!(tensor.as_slice(), &[1.0, 2.0]);
1085/// assert_eq!(tensor[&[1]], 2.0);
1086/// # Ok::<(), tenferro_tensor::Error>(())
1087/// ```
1088#[derive(Debug)]
1089pub struct Host;
1090
1091/// Sealed marker for the group-backed payload of a [`TypedTensor`].
1092///
1093/// `TypedTensor<T, R, Gpu>` carries provider allocation authority, identity
1094/// and retirement state through its allocation group, so host access stays
1095/// fallible and must be prepared or mapped explicitly. The marker is not proof
1096/// of a particular device ordinal or provider.
1097///
1098/// # Examples
1099///
1100/// ```
1101/// use tenferro_tensor::{DynRank, Gpu, Host, TypedTensor};
1102///
1103/// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1104/// let gpu: TypedTensor<f64, DynRank, Gpu> = host.promote()?;
1105/// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
1106/// # Ok::<(), tenferro_tensor::Error>(())
1107/// ```
1108#[derive(Debug)]
1109pub struct Gpu;
1110
1111/// Sealed marker for the runtime union of the host and group-backed payloads.
1112///
1113/// This is the default representation: one type for ordinary tensors that may
1114/// be host-resident or backend-resident at runtime.
1115///
1116/// # Examples
1117///
1118/// ```
1119/// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
1120///
1121/// let host = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1122/// let dynamic: TypedTensor<i32, DynRank, Dynamic> = host.into_dynamic();
1123/// assert_eq!(dynamic.host_data()?, &[1, 2]);
1124/// # Ok::<(), tenferro_tensor::Error>(())
1125/// ```
1126#[derive(Debug)]
1127pub struct Dynamic;
1128
1129mod representation_sealed {
1130    pub trait Sealed {}
1131    impl Sealed for super::Host {}
1132    impl Sealed for super::Gpu {}
1133    impl Sealed for super::Dynamic {}
1134}
1135
1136/// Sealed selector for the owned payload representation of a [`TypedTensor`].
1137///
1138/// The three markers are [`Host`], [`Gpu`] and [`Dynamic`]. The trait is
1139/// sealed: downstream crates select an existing representation, they do not
1140/// define one.
1141///
1142/// # Examples
1143///
1144/// ```
1145/// use tenferro_tensor::{Dynamic, DynRank, Host, Representation, TypedTensor};
1146///
1147/// fn extent<D: Representation>(tensor: &TypedTensor<f64, DynRank, D>) -> usize {
1148///     tensor.shape()[0]
1149/// }
1150/// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![3], vec![0.0; 3])?;
1151/// assert_eq!(extent(&host), 3);
1152/// let dynamic: TypedTensor<f64, DynRank, Dynamic> = host.into_dynamic();
1153/// assert_eq!(extent(&dynamic), 3);
1154/// # Ok::<(), tenferro_tensor::Error>(())
1155/// ```
1156pub trait Representation: representation_sealed::Sealed + 'static {
1157    /// Owned payload stored for this representation.
1158    #[doc(hidden)]
1159    type Storage<T, R: TensorRank>;
1160
1161    /// Placement given to an owner of this representation built without one.
1162    ///
1163    /// Placement metadata is fixed when a [`Host`] or [`Gpu`] owner is built:
1164    /// only a [`Dynamic`] owner can replace it afterwards, through
1165    /// [`TypedTensor::set_placement`]. [`Host`] constructors use this
1166    /// placement, unpinned host memory with no device and no CPU affinity.
1167    /// [`Gpu`] and [`Dynamic`] use the same default when no placement is
1168    /// supplied; a device-resident owner receives its device placement from
1169    /// the constructor that adopts the backend buffer.
1170    ///
1171    /// # Examples
1172    ///
1173    /// ```
1174    /// use tenferro_tensor::{DynRank, Host, MemoryKind, Representation, TypedTensor};
1175    ///
1176    /// let expected = <Host as Representation>::default_placement();
1177    /// assert_eq!(expected.memory_kind, MemoryKind::UnpinnedHost);
1178    /// assert!(expected.device.is_none());
1179    /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0])?;
1180    /// assert_eq!(host.placement(), &expected);
1181    /// # Ok::<(), tenferro_tensor::Error>(())
1182    /// ```
1183    fn default_placement() -> Placement;
1184}
1185
1186impl Representation for Host {
1187    #[doc(hidden)]
1188    type Storage<T, R: TensorRank> = HostStorage<T>;
1189
1190    fn default_placement() -> Placement {
1191        default_placement()
1192    }
1193}
1194
1195impl Representation for Gpu {
1196    #[doc(hidden)]
1197    type Storage<T, R: TensorRank> = GroupStorage<R>;
1198
1199    fn default_placement() -> Placement {
1200        // The only Gpu constructor without an explicit placement is
1201        // `TypedTensor<_, _, Host>::promote`, which keeps the host owner's
1202        // placement: unpinned host memory on the CPU provider.
1203        default_placement()
1204    }
1205}
1206
1207impl Representation for Dynamic {
1208    #[doc(hidden)]
1209    type Storage<T, R: TensorRank> = DynamicStorage<T, R>;
1210
1211    fn default_placement() -> Placement {
1212        default_placement()
1213    }
1214}
1215
1216/// Directly owned plain or pooled host elements.
1217#[doc(hidden)]
1218pub struct HostStorage<T> {
1219    data: HostData<T>,
1220}
1221
1222/// Group-backed payload: provider allocation authority, identity and retirement.
1223#[doc(hidden)]
1224pub struct GroupStorage<R: TensorRank> {
1225    group: Box<OwnedTensorGroup<R>>,
1226}
1227
1228/// Runtime union of the [`Host`] and [`Gpu`] owned payloads.
1229#[doc(hidden)]
1230pub enum DynamicStorage<T, R: TensorRank> {
1231    Host(HostStorage<T>),
1232    Group(GroupStorage<R>),
1233}
1234
1235impl<T> std::fmt::Debug for HostStorage<T> {
1236    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1237        self.data.fmt(formatter)
1238    }
1239}
1240
1241impl<R: TensorRank> std::fmt::Debug for GroupStorage<R> {
1242    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1243        formatter
1244            .debug_struct("GroupStorage")
1245            .field("group", &self.group)
1246            .finish()
1247    }
1248}
1249
1250impl<T, R: TensorRank> std::fmt::Debug for DynamicStorage<T, R> {
1251    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1252        match self {
1253            Self::Host(host) => formatter.debug_tuple("Host").field(host).finish(),
1254            Self::Group(group) => formatter.debug_tuple("Group").field(group).finish(),
1255        }
1256    }
1257}
1258
1259/// Owned compact column-major typed tensor.
1260///
1261/// `T` is the element type, `R` the rank metadata (default [`DynRank`]) and `D`
1262/// the owned representation (default [`Dynamic`]). Shape and placement live on
1263/// the tensor itself, once, never inside a storage arm.
1264///
1265/// No bound is imposed on `T` by the type: plain host adoption only needs the
1266/// constructor's own requirements, and `T: Clone` is required only by the
1267/// copying constructors. A preset [`TensorScalar`] appears only where a dtype
1268/// identity or a numerical capability is actually used, never for plain host
1269/// ownership.
1270///
1271/// Owned tensors are compact column-major. Arbitrary strides and metadata-only
1272/// layout changes are represented by [`TypedTensorView`] and
1273/// [`TypedTensorViewMut`].
1274///
1275/// # Examples
1276///
1277/// ```
1278/// use tenferro_tensor::{DynRank, Host, Rank, Tensor, TypedTensor};
1279///
1280/// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
1281/// assert_eq!(t.shape(), &[2, 2]);
1282///
1283/// let static_rank = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
1284/// assert_eq!(static_rank.rank(), 2);
1285///
1286/// let host: TypedTensor<i32, DynRank, Host> =
1287///     TypedTensor::from_host_vec_col_major(vec![2], vec![1, 2]).unwrap();
1288/// assert_eq!(host.get(&[1])?, &2);
1289///
1290/// let dynamic = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1291/// assert_eq!(dynamic.shape(), &[2, 2]);
1292/// # Ok::<(), tenferro_tensor::Error>(())
1293/// ```
1294pub struct TypedTensor<T, R: TensorRank = DynRank, D: Representation = Dynamic> {
1295    shape: R::Shape,
1296    placement: Placement,
1297    /// Column-major element strides, cached at construction so a strided view of
1298    /// this tensor borrows its layout instead of recomputing it per operation.
1299    layout: StrideVec,
1300    storage: D::Storage<T, R>,
1301}
1302
1303/// Validate and adopt a column-major host vector as a statically host-owned tensor.
1304fn typed_host_tensor_from_vec_col_major<T, R: TensorRank>(
1305    shape: impl tenferro_tensor_core::IntoRankShape<R>,
1306    data: Vec<T>,
1307    op: &'static str,
1308) -> crate::Result<TypedTensor<T, R, Host>> {
1309    let shape = shape
1310        .into_rank_shape()
1311        .map_err(|err| tensor_layout_error(op, err))?;
1312    let layout = tenferro_tensor_core::col_major_strides(shape.as_ref())
1313        .map_err(|err| tensor_layout_error(op, err))?;
1314    try_checked_shape_len(shape.as_ref(), data.len(), op)?;
1315    Ok(TypedTensor {
1316        shape,
1317        placement: <Host as Representation>::default_placement(),
1318        layout,
1319        storage: HostStorage {
1320            data: HostData::new(data),
1321        },
1322    })
1323}
1324
1325/// Reorder explicit row-major host values into column-major order.
1326fn row_major_reorder<T: Clone, R: TensorRank>(
1327    shape: impl tenferro_tensor_core::IntoRankShape<R>,
1328    data: Vec<T>,
1329    op: &'static str,
1330) -> crate::Result<(R::Shape, Vec<T>)> {
1331    let shape = shape
1332        .into_rank_shape()
1333        .map_err(|err| tensor_layout_error(op, err))?;
1334    tenferro_tensor_core::col_major_strides(shape.as_ref())
1335        .map_err(|err| tensor_layout_error(op, err))?;
1336    try_checked_shape_len(shape.as_ref(), data.len(), op)?;
1337    let mut row_strides = shape_vec_zeros(shape.as_ref().len());
1338    let mut stride = 1usize;
1339    for axis in (0..row_strides.len()).rev() {
1340        row_strides[axis] = stride;
1341        stride = stride
1342            .checked_mul(shape.as_ref()[axis])
1343            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
1344    }
1345    let mut coordinates = shape_vec_zeros(row_strides.len());
1346    let mut source_offset = 0usize;
1347    let mut reordered = Vec::with_capacity(data.len());
1348    for _ in 0..data.len() {
1349        reordered.push(data[source_offset].clone());
1350        for axis in 0..coordinates.len() {
1351            coordinates[axis] += 1;
1352            if coordinates[axis] < shape.as_ref()[axis] {
1353                source_offset += row_strides[axis];
1354                break;
1355            }
1356            coordinates[axis] = 0;
1357            source_offset -= row_strides[axis] * (shape.as_ref()[axis] - 1);
1358        }
1359    }
1360    Ok((shape, reordered))
1361}
1362
1363impl<T, R: TensorRank> TypedTensor<T, R, Host> {
1364    /// Adopt a column-major host `Vec<T>` as a statically host-owned tensor.
1365    ///
1366    /// The payload is the caller's vector itself; `T` needs no `Copy`,
1367    /// [`TensorScalar`] or arithmetic bound, and no group, session or device is
1368    /// involved.
1369    ///
1370    /// # Examples
1371    /// ```
1372    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1373    /// struct Custom(String);
1374    /// let tensor = TypedTensor::<Custom, Rank<2>, Host>::from_host_vec_col_major(
1375    ///     [1, 2], vec![Custom("a".into()), Custom("b".into())],
1376    /// )?;
1377    /// assert_eq!(tensor[&[0, 1]].0.as_str(), "b");
1378    /// # Ok::<(), tenferro_tensor::Error>(())
1379    /// ```
1380    /// # Errors
1381    /// Returns [`crate::Error::Validation`] for a rank mismatch, shape/data
1382    /// length mismatch or shape/stride arithmetic overflow.
1383    pub fn from_host_vec_col_major(
1384        shape: impl tenferro_tensor_core::IntoRankShape<R>,
1385        data: Vec<T>,
1386    ) -> crate::Result<Self> {
1387        typed_host_tensor_from_vec_col_major(shape, data, "from_host_vec_col_major")
1388    }
1389
1390    /// Explicitly import row-major host values into column-major storage.
1391    ///
1392    /// Clones each input element once.
1393    ///
1394    /// # Examples
1395    /// ```
1396    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1397    /// let tensor = TypedTensor::<i32, Rank<2>, Host>::from_host_vec_row_major(
1398    ///     [2, 3], vec![1, 2, 3, 4, 5, 6],
1399    /// )?;
1400    /// assert_eq!(tensor[&[1, 0]], 4);
1401    /// assert_eq!(tensor[&[0, 2]], 3);
1402    /// # Ok::<(), tenferro_tensor::Error>(())
1403    /// ```
1404    /// # Errors
1405    /// Returns [`crate::Error::Validation`] for a rank, shape-length or stride
1406    /// overflow, or when the shape product disagrees with the input length.
1407    pub fn from_host_vec_row_major(
1408        shape: impl tenferro_tensor_core::IntoRankShape<R>,
1409        data: Vec<T>,
1410    ) -> crate::Result<Self>
1411    where
1412        T: Clone,
1413    {
1414        let (shape, data) = row_major_reorder(shape, data, "from_host_vec_row_major")?;
1415        typed_host_tensor_from_vec_col_major(shape, data, "from_host_vec_row_major")
1416    }
1417
1418    /// Borrow the owned host elements.
1419    ///
1420    /// # Examples
1421    /// ```
1422    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1423    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1424    /// assert_eq!(tensor.as_slice(), &[1, 2]);
1425    /// # Ok::<(), tenferro_tensor::Error>(())
1426    /// ```
1427    pub fn as_slice(&self) -> &[T] {
1428        self.storage.data.as_slice()
1429    }
1430
1431    /// Alias of [`Self::as_slice`].
1432    ///
1433    /// # Examples
1434    ///
1435    /// ```
1436    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1437    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1438    /// assert_eq!(tensor.host_data(), &[1, 2]);
1439    /// # Ok::<(), tenferro_tensor::Error>(())
1440    /// ```
1441    pub fn host_data(&self) -> &[T] {
1442        self.as_slice()
1443    }
1444
1445    /// Exclusively borrow the owned host elements.
1446    ///
1447    /// # Examples
1448    ///
1449    /// ```
1450    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1451    /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1452    /// tensor.host_data_mut()[0] = 5;
1453    /// assert_eq!(tensor.as_slice(), &[5, 2]);
1454    /// # Ok::<(), tenferro_tensor::Error>(())
1455    /// ```
1456    pub fn host_data_mut(&mut self) -> &mut [T] {
1457        self.storage.data.as_mut_slice()
1458    }
1459
1460    /// Borrow one element by checked column-major multi-index.
1461    ///
1462    /// # Examples
1463    ///
1464    /// ```
1465    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1466    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 2], vec![1, 2, 3, 4])?;
1467    /// assert_eq!(tensor.get(&[1, 1])?, &4);
1468    /// assert!(tensor.get(&[2, 0]).is_err());
1469    /// # Ok::<(), tenferro_tensor::Error>(())
1470    /// ```
1471    ///
1472    /// # Errors
1473    /// Returns [`crate::Error::Validation`] for a wrong rank, an out-of-range
1474    /// coordinate or offset arithmetic overflow.
1475    pub fn get(&self, indices: &[usize]) -> crate::Result<&T> {
1476        let offset = self.linear_offset(indices)?;
1477        self.as_slice().get(offset).ok_or_else(|| {
1478            crate::Error::validation("TypedTensor::get", ValidationError::ViewOutOfBounds)
1479        })
1480    }
1481
1482    /// Exclusively borrow one element by checked column-major multi-index.
1483    ///
1484    /// # Examples
1485    ///
1486    /// ```
1487    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1488    /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1489    /// *tensor.get_mut(&[1])? = 9;
1490    /// assert_eq!(tensor.as_slice(), &[1, 9]);
1491    /// # Ok::<(), tenferro_tensor::Error>(())
1492    /// ```
1493    ///
1494    /// # Errors
1495    /// Returns [`crate::Error::Validation`] for a wrong rank, an out-of-range
1496    /// coordinate or offset arithmetic overflow.
1497    pub fn get_mut(&mut self, indices: &[usize]) -> crate::Result<&mut T> {
1498        let offset = self.linear_offset(indices)?;
1499        self.host_data_mut().get_mut(offset).ok_or_else(|| {
1500            crate::Error::validation("TypedTensor::get_mut", ValidationError::ViewOutOfBounds)
1501        })
1502    }
1503
1504    /// Consume this tensor and return the original host vector.
1505    ///
1506    /// # Examples
1507    ///
1508    /// ```
1509    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1510    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1511    /// assert_eq!(tensor.into_host_vec(), vec![1, 2]);
1512    /// # Ok::<(), tenferro_tensor::Error>(())
1513    /// ```
1514    pub fn into_host_vec(self) -> Vec<T> {
1515        self.storage.data.into_vec()
1516    }
1517
1518    /// Consume this tensor and return its shape and column-major host vector.
1519    ///
1520    /// # Examples
1521    ///
1522    /// ```
1523    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1524    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 1], vec![1, 2])?;
1525    /// let (shape, data) = tensor.into_vec_col_major();
1526    /// assert_eq!(shape, vec![2, 1]);
1527    /// assert_eq!(data, vec![1, 2]);
1528    /// # Ok::<(), tenferro_tensor::Error>(())
1529    /// ```
1530    pub fn into_vec_col_major(self) -> (Vec<usize>, Vec<T>) {
1531        let shape = self.shape().to_vec();
1532        (shape, self.into_host_vec())
1533    }
1534
1535    /// Make an explicit independent host copy with the same placement.
1536    ///
1537    /// # Examples
1538    /// ```
1539    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1540    /// let tensor = TypedTensor::<String, DynRank, Host>::from_host_vec_col_major(vec![1], vec!["a".into()])?;
1541    /// let copy = tensor.clone();
1542    /// assert_eq!(copy[&[0]], "a");
1543    /// # Ok::<(), tenferro_tensor::Error>(())
1544    /// ```
1545    pub fn duplicate(&self) -> Self
1546    where
1547        T: Clone,
1548    {
1549        let mut copy = typed_host_tensor_from_vec_col_major::<T, R>(
1550            self.shape.clone(),
1551            self.as_slice().to_vec(),
1552            "TypedTensor::duplicate",
1553        )
1554        .unwrap_or_else(|err| unreachable!("a validated host owner re-copies: {err}"));
1555        copy.placement = self.placement.clone();
1556        copy
1557    }
1558
1559    /// Move this host owner into the runtime union without copying or regrouping.
1560    ///
1561    /// # Examples
1562    /// ```
1563    /// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
1564    /// let host = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7])?;
1565    /// let dynamic: TypedTensor<i32, DynRank, Dynamic> = host.into_dynamic();
1566    /// assert_eq!(dynamic.host_data()?, &[7]);
1567    /// # Ok::<(), tenferro_tensor::Error>(())
1568    /// ```
1569    pub fn into_dynamic(self) -> TypedTensor<T, R, Dynamic> {
1570        TypedTensor {
1571            shape: self.shape,
1572            placement: self.placement,
1573            layout: self.layout,
1574            storage: DynamicStorage::Host(self.storage),
1575        }
1576    }
1577
1578    /// Borrow this host owner as a typed view.
1579    ///
1580    /// # Examples
1581    ///
1582    /// ```
1583    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1584    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1585    /// let view = tensor.as_view();
1586    /// assert_eq!(view.shape(), &[2]);
1587    /// assert_eq!(view.as_host_slice(), &[1, 2]);
1588    /// # Ok::<(), tenferro_tensor::Error>(())
1589    /// ```
1590    pub fn as_view(&self) -> TypedTensorView<'_, T, R, Host> {
1591        TypedTensorView {
1592            buffer: TensorStorageRef::Host(self.as_slice()),
1593            root: None,
1594            layout: self.layout(),
1595            placement: self.placement.clone(),
1596            _representation: std::marker::PhantomData,
1597        }
1598    }
1599
1600    /// Exclusively borrow this host owner as a mutable typed view.
1601    ///
1602    /// # Examples
1603    ///
1604    /// ```
1605    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1606    /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1607    /// tensor.as_view_mut().as_host_slice_mut()[1] = 4;
1608    /// assert_eq!(tensor.as_slice(), &[1, 4]);
1609    /// # Ok::<(), tenferro_tensor::Error>(())
1610    /// ```
1611    pub fn as_view_mut(&mut self) -> TypedTensorViewMut<'_, T, R, Host> {
1612        let layout = self.layout();
1613        let placement = self.placement.clone();
1614        TypedTensorViewMut {
1615            buffer: TensorStorageRefMut::Host(self.storage.data.as_mut_slice()),
1616            root: None,
1617            layout,
1618            placement,
1619            _representation: std::marker::PhantomData,
1620        }
1621    }
1622}
1623
1624impl<T: Clone, R: TensorRank> Clone for TypedTensor<T, R, Host> {
1625    fn clone(&self) -> Self {
1626        self.duplicate()
1627    }
1628}
1629
1630impl<T, R: TensorRank> std::ops::Index<&[usize]> for TypedTensor<T, R, Host> {
1631    type Output = T;
1632
1633    /// # Panics
1634    ///
1635    /// Panics when the index has the wrong rank or is out of bounds, like any
1636    /// other slice indexing. Use [`TypedTensor::get`] for the checked form.
1637    fn index(&self, indices: &[usize]) -> &T {
1638        match self.get(indices) {
1639            Ok(value) => value,
1640            Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1641        }
1642    }
1643}
1644
1645impl<T, R: TensorRank> std::ops::IndexMut<&[usize]> for TypedTensor<T, R, Host> {
1646    /// # Panics
1647    ///
1648    /// Panics when the index has the wrong rank or is out of bounds, like any
1649    /// other slice indexing. Use [`TypedTensor::get_mut`] for the checked form.
1650    fn index_mut(&mut self, indices: &[usize]) -> &mut T {
1651        match self.get_mut(indices) {
1652            Ok(value) => value,
1653            Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1654        }
1655    }
1656}
1657
1658impl<T, const N: usize> std::ops::Index<[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1659    type Output = T;
1660
1661    /// # Panics
1662    ///
1663    /// Panics when an index is out of bounds, like any other slice indexing.
1664    /// Use [`TypedTensor::get`] for the checked form.
1665    ///
1666    /// # Examples
1667    ///
1668    /// ```rust
1669    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1670    /// let tensor =
1671    ///     TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1672    /// assert_eq!(tensor[[0, 1]], 3);
1673    /// # Ok::<(), tenferro_tensor::Error>(())
1674    /// ```
1675    fn index(&self, indices: [usize; N]) -> &T {
1676        match self.get(&indices) {
1677            Ok(value) => value,
1678            Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1679        }
1680    }
1681}
1682
1683impl<T, const N: usize> std::ops::Index<&[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1684    type Output = T;
1685
1686    /// The `&[usize; N]` spelling, which keeps a bare `&[i, j]` literal
1687    /// resolving as an integer index rather than forcing `usize` inference to
1688    /// choose between the slice and array spellings.
1689    ///
1690    /// # Panics
1691    ///
1692    /// Panics when an index is out of bounds, like any other slice indexing.
1693    /// Use [`TypedTensor::get`] for the checked form.
1694    ///
1695    /// # Examples
1696    ///
1697    /// ```rust
1698    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1699    /// let tensor =
1700    ///     TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1701    /// assert_eq!(tensor[&[0, 1]], 3);
1702    /// # Ok::<(), tenferro_tensor::Error>(())
1703    /// ```
1704    fn index(&self, indices: &[usize; N]) -> &T {
1705        std::ops::Index::index(self, *indices)
1706    }
1707}
1708
1709impl<T, const N: usize> std::ops::IndexMut<[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1710    /// # Panics
1711    ///
1712    /// Panics when an index is out of bounds, like any other slice indexing.
1713    /// Use [`TypedTensor::get_mut`] for the checked form.
1714    ///
1715    /// # Examples
1716    ///
1717    /// ```rust
1718    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1719    /// let mut tensor =
1720    ///     TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1721    /// tensor[[1, 0]] = 7;
1722    /// assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);
1723    /// # Ok::<(), tenferro_tensor::Error>(())
1724    /// ```
1725    fn index_mut(&mut self, indices: [usize; N]) -> &mut T {
1726        match self.get_mut(&indices) {
1727            Ok(value) => value,
1728            Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1729        }
1730    }
1731}
1732
1733impl<T, const N: usize> std::ops::IndexMut<&[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1734    /// # Panics
1735    ///
1736    /// Panics when an index is out of bounds, like any other slice indexing.
1737    /// Use [`TypedTensor::get_mut`] for the checked form.
1738    ///
1739    /// # Examples
1740    ///
1741    /// ```rust
1742    /// use tenferro_tensor::{Host, Rank, TypedTensor};
1743    /// let mut tensor =
1744    ///     TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1745    /// tensor[&[1, 0]] = 7;
1746    /// assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);
1747    /// # Ok::<(), tenferro_tensor::Error>(())
1748    /// ```
1749    fn index_mut(&mut self, indices: &[usize; N]) -> &mut T {
1750        std::ops::IndexMut::index_mut(self, *indices)
1751    }
1752}
1753
1754impl<T, const N: usize> std::ops::Index<[usize; N]> for TypedTensor<T, Rank<N>> {
1755    type Output = T;
1756
1757    /// # Panics
1758    ///
1759    /// Panics when an index is out of bounds or when the storage is not
1760    /// host-accessible, like any other slice indexing. Use
1761    /// [`TypedTensor::get`] for the checked form.
1762    ///
1763    /// # Examples
1764    ///
1765    /// ```rust
1766    /// use tenferro_tensor::{Rank, TypedTensor};
1767    /// let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
1768    /// assert_eq!(tensor[[0, 1]], 3.);
1769    /// # Ok::<(), tenferro_tensor::Error>(())
1770    /// ```
1771    fn index(&self, indices: [usize; N]) -> &T {
1772        match self.get(&indices) {
1773            Ok(value) => value,
1774            Err(err) => panic!("TypedTensor index {indices:?} is invalid: {err}"),
1775        }
1776    }
1777}
1778
1779impl<T, const N: usize> std::ops::IndexMut<[usize; N]> for TypedTensor<T, Rank<N>> {
1780    /// # Panics
1781    ///
1782    /// Panics when an index is out of bounds or when the storage is not
1783    /// host-accessible, like any other slice indexing. Use
1784    /// [`TypedTensor::get_mut`] for the checked form.
1785    ///
1786    /// # Examples
1787    ///
1788    /// ```rust
1789    /// use tenferro_tensor::{Rank, TypedTensor};
1790    /// let mut tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
1791    /// tensor[[1, 0]] = 7.;
1792    /// assert_eq!(tensor.as_slice()?, &[1., 7., 3., 4.]);
1793    /// # Ok::<(), tenferro_tensor::Error>(())
1794    /// ```
1795    fn index_mut(&mut self, indices: [usize; N]) -> &mut T {
1796        match self.get_mut(&indices) {
1797            Ok(value) => value,
1798            Err(err) => panic!("TypedTensor index {indices:?} is invalid: {err}"),
1799        }
1800    }
1801}
1802
1803/// Read mapping over a host slice, as one owning guard.
1804fn host_read_guard<T>(data: &[T]) -> HostReadGuard<'_, T> {
1805    HostReadGuard::new(data)
1806}
1807
1808/// Write mapping over an exclusive host slice, as one owning guard.
1809fn host_write_guard<T: Clone>(data: &mut [T]) -> HostWriteGuard<'_, T> {
1810    let len = data.len();
1811    HostWriteGuard::new(len, move |source| {
1812        data.clone_from_slice(source);
1813        Ok(())
1814    })
1815}
1816
1817/// Promote a plain host payload into a group-backed root without copying elements.
1818fn promote_host_group<T: TensorScalar, R: TensorRank>(
1819    shape: R::Shape,
1820    host: HostData<T>,
1821) -> crate::Result<OwnedTensorGroup<R>> {
1822    let recycler = host.recycler.clone();
1823    let mut group = OwnedTensorGroup::from_host_vec(shape, host.into_vec())?;
1824    if let Some(recycler) = recycler {
1825        group
1826            .group
1827            .set_host_recycler(group.allocation_index.index(), recycler)
1828            .map_err(|error| crate::Error::runtime_state_source("TypedTensor::promote", error))?;
1829    }
1830    Ok(group)
1831}
1832
1833impl<T, R: TensorRank> TypedTensor<T, R, Host> {
1834    /// Borrow the owned host elements through one owning read mapping.
1835    ///
1836    /// The guard retains the exclusive borrow of this owner, so no other access
1837    /// can overlap it while the mapping is alive.
1838    ///
1839    /// # Examples
1840    /// ```
1841    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1842    /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1843    /// let guard = tensor.map_read();
1844    /// assert_eq!(&guard[..], &[1, 2]);
1845    /// # Ok::<(), tenferro_tensor::Error>(())
1846    /// ```
1847    pub fn map_read(&self) -> HostReadGuard<'_, T> {
1848        host_read_guard(self.as_slice())
1849    }
1850
1851    /// Exclusively borrow the owned host elements through one owning write mapping.
1852    ///
1853    /// Publish data with [`HostWriteGuard::copy_from_slice`]; the mapping is
1854    /// released when the guard is dropped.
1855    ///
1856    /// # Examples
1857    /// ```
1858    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1859    /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1860    /// tensor.map_write().copy_from_slice(&[3, 4]).unwrap();
1861    /// assert_eq!(tensor.as_slice(), &[3, 4]);
1862    /// # Ok::<(), tenferro_tensor::Error>(())
1863    /// ```
1864    pub fn map_write(&mut self) -> HostWriteGuard<'_, T>
1865    where
1866        T: Clone,
1867    {
1868        host_write_guard(self.host_data_mut())
1869    }
1870}
1871
1872impl<T: TensorScalar, R: TensorRank> TypedTensor<T, R, Host> {
1873    /// Promote this plain host owner into a group-backed owner.
1874    ///
1875    /// The payload is adopted as a provider root: no element is copied and a
1876    /// pooled return target survives the promotion.
1877    ///
1878    /// # Examples
1879    /// ```
1880    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1881    /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1882    /// let gpu = host.promote()?;
1883    /// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
1884    /// # Ok::<(), tenferro_tensor::Error>(())
1885    /// ```
1886    /// # Errors
1887    /// Returns [`crate::Error::RuntimeState`] when the new allocation group
1888    /// rejects the promoted root or its recycler.
1889    pub fn promote(self) -> crate::Result<TypedTensor<T, R, Gpu>> {
1890        let TypedTensor {
1891            shape,
1892            placement,
1893            layout,
1894            storage,
1895        } = self;
1896        let group = promote_host_group(shape.clone(), storage.data)?;
1897        Ok(TypedTensor {
1898            shape,
1899            placement,
1900            layout,
1901            storage: GroupStorage {
1902                group: Box::new(group),
1903            },
1904        })
1905    }
1906}
1907
1908impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
1909    /// Borrow host elements through one owning read mapping.
1910    ///
1911    /// # Examples
1912    ///
1913    /// ```
1914    /// use tenferro_tensor::TypedTensor;
1915    /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
1916    /// let guard = tensor.map_read()?;
1917    /// assert_eq!(&guard[..], &[1, 2]);
1918    /// # Ok::<(), tenferro_tensor::Error>(())
1919    /// ```
1920    ///
1921    /// # Errors
1922    /// Returns [`crate::Error::HostAccess`] with
1923    /// [`HostAccessError::Unsupported`] when the group's allocation is not
1924    /// host-accessible, or [`crate::Error::Validation`] with
1925    /// [`ValidationError::NonContiguousViewAsSlice`] or
1926    /// [`ValidationError::ViewOutOfBounds`] when the owner has no contiguous
1927    /// logical extent inside its backing storage.
1928    pub fn map_read(&self) -> crate::Result<HostReadGuard<'_, T>> {
1929        match &self.storage {
1930            DynamicStorage::Host(host) => Ok(host_read_guard(host.data.as_slice())),
1931            DynamicStorage::Group(core) => {
1932                // A root-preserving extraction exports only its descriptor
1933                // extent (#2023), so the mapping must not expose the root.
1934                let range = group_logical_range(&core.group, "TypedTensor::map_read")?;
1935                let data = core.group.host_slice::<T>()?;
1936                data.get(range).map(host_read_guard).ok_or_else(|| {
1937                    crate::Error::validation(
1938                        "TypedTensor::map_read",
1939                        ValidationError::ViewOutOfBounds,
1940                    )
1941                })
1942            }
1943        }
1944    }
1945
1946    /// Exclusively borrow host elements through one owning write mapping.
1947    ///
1948    /// Publish data with [`HostWriteGuard::copy_from_slice`].
1949    ///
1950    /// # Examples
1951    ///
1952    /// ```
1953    /// use tenferro_tensor::{Error, TypedTensor};
1954    /// let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
1955    /// tensor
1956    ///     .map_write()?
1957    ///     .copy_from_slice(&[3, 4])
1958    ///     .map_err(|err| Error::host_access("map_write", err))?;
1959    /// assert_eq!(tensor.host_data()?, &[3, 4]);
1960    /// # Ok::<(), tenferro_tensor::Error>(())
1961    /// ```
1962    ///
1963    /// # Errors
1964    /// Returns [`crate::Error::HostAccess`] with
1965    /// [`HostAccessError::Unsupported`] when the group's allocation is not
1966    /// host-writable, or [`crate::Error::Validation`] with
1967    /// [`ValidationError::NonContiguousViewAsSlice`] or
1968    /// [`ValidationError::ViewOutOfBounds`] when the owner has no contiguous
1969    /// logical extent inside its backing storage.
1970    pub fn map_write(&mut self) -> crate::Result<HostWriteGuard<'_, T>>
1971    where
1972        T: Clone,
1973    {
1974        match &mut self.storage {
1975            DynamicStorage::Host(host) => Ok(host_write_guard(host.data.as_mut_slice())),
1976            DynamicStorage::Group(core) => {
1977                let range = group_logical_range(&core.group, "TypedTensor::map_write")?;
1978                let data = core.group.host_slice_mut::<T>()?;
1979                data.get_mut(range).map(host_write_guard).ok_or_else(|| {
1980                    crate::Error::validation(
1981                        "TypedTensor::map_write",
1982                        ValidationError::ViewOutOfBounds,
1983                    )
1984                })
1985            }
1986        }
1987    }
1988}
1989
1990impl<T, R: TensorRank> TypedTensor<T, R, Gpu> {
1991    /// Adopt a backend-owned buffer as a statically group-backed owner.
1992    ///
1993    /// A host buffer belongs to the [`Host`] representation; pass it to
1994    /// `TypedTensor::<T, R, Host>` instead of silently regrouping it here.
1995    ///
1996    /// # Examples
1997    /// ```
1998    /// use tenferro_tensor::{BackendStorageHandle, Placement, StorageBuffer, TypedTensor};
1999    /// let handle = BackendStorageHandle::<f32>::new_with_len(1, 2);
2000    /// let gpu = TypedTensor::<f32, tenferro_tensor::DynRank, tenferro_tensor::Gpu>::from_backend_buffer_col_major(
2001    ///     vec![2],
2002    ///     StorageBuffer::Backend(Box::new(handle)),
2003    ///     Placement::default(),
2004    /// )?;
2005    /// assert!(gpu.is_backend_buffer());
2006    /// # Ok::<(), tenferro_tensor::Error>(())
2007    /// ```
2008    /// # Errors
2009    /// Returns [`crate::Error::Validation`] when the compact shape disagrees
2010    /// with the buffer length, [`crate::Error::RuntimeState`] for a host buffer,
2011    /// or a runtime-state error when the allocation group cannot be built.
2012    pub fn from_backend_buffer_col_major(
2013        shape: impl tenferro_tensor_core::IntoRankShape<R>,
2014        buffer: StorageBuffer<T>,
2015        placement: Placement,
2016    ) -> crate::Result<Self>
2017    where
2018        T: TensorScalar + Send + Sync + 'static,
2019    {
2020        let op = "TypedTensor::from_backend_buffer_col_major";
2021        let layout = try_compact_layout(shape, op)?;
2022        try_checked_shape_len(layout.shape(), buffer.len(), op)?;
2023        let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
2024            .map_err(|err| tensor_layout_error(op, err))?;
2025        match buffer {
2026            StorageBuffer::Host(_) => Err(crate::Error::runtime_state(
2027                op,
2028                "a host buffer is plain host storage; use TypedTensor::<T, R, Host>::from_vec_col_major",
2029            )),
2030            StorageBuffer::Backend(buffer) => {
2031                let group = OwnedTensorGroup::from_backend_buffer(
2032                    group_shape.clone(),
2033                    StorageBuffer::Backend(buffer),
2034                    placement.clone(),
2035                )?;
2036                Ok(TypedTensor {
2037                    shape: group_shape,
2038                    placement,
2039                    layout: stride_vec(layout.strides()),
2040                    storage: GroupStorage {
2041                        group: Box::new(group),
2042                    },
2043                })
2044            }
2045        }
2046    }
2047
2048    /// Move this group-backed owner into the runtime union without rewriting it.
2049    ///
2050    /// # Examples
2051    ///
2052    /// ```
2053    /// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
2054    /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
2055    /// let dynamic: TypedTensor<f64, DynRank, Dynamic> = gpu.into_dynamic();
2056    /// assert_eq!(dynamic.host_data()?, &[7.0]);
2057    /// # Ok::<(), tenferro_tensor::Error>(())
2058    /// ```
2059    pub fn into_dynamic(self) -> TypedTensor<T, R, Dynamic> {
2060        TypedTensor {
2061            shape: self.shape,
2062            placement: self.placement,
2063            layout: self.layout,
2064            storage: DynamicStorage::Group(self.storage),
2065        }
2066    }
2067
2068    /// Whether this group's descriptor names a non-CPU provider.
2069    ///
2070    /// # Examples
2071    ///
2072    /// ```
2073    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2074    /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
2075    /// // A promoted host payload stays on the CPU provider.
2076    /// assert!(!gpu.is_backend_buffer());
2077    /// # Ok::<(), tenferro_tensor::Error>(())
2078    /// ```
2079    pub fn is_backend_buffer(&self) -> bool {
2080        self.storage.group.is_backend_buffer()
2081    }
2082
2083    /// Borrow host elements when the group's allocation is host-accessible.
2084    ///
2085    /// # Examples
2086    ///
2087    /// ```
2088    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2089    /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
2090    /// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
2091    /// # Ok::<(), tenferro_tensor::Error>(())
2092    /// ```
2093    ///
2094    /// # Errors
2095    /// Returns [`crate::Error::RuntimeState`] for a device-only allocation and
2096    /// the non-compact-descriptor validation error for a strided owner.
2097    pub fn host_data(&self) -> crate::Result<&[T]> {
2098        let data = self.storage.group.host_slice::<T>()?;
2099        let range = group_logical_range(&self.storage.group, "TypedTensor::host_data")?;
2100        data.get(range).ok_or_else(|| {
2101            crate::Error::validation("TypedTensor::host_data", ValidationError::ViewOutOfBounds)
2102        })
2103    }
2104
2105    /// Exclusively borrow host elements when the group's allocation is host-accessible.
2106    ///
2107    /// # Examples
2108    ///
2109    /// ```
2110    /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2111    /// let mut gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
2112    /// gpu.host_data_mut()?[0] = 3.0;
2113    /// assert_eq!(gpu.host_data()?, &[3.0, 2.0]);
2114    /// # Ok::<(), tenferro_tensor::Error>(())
2115    /// ```
2116    ///
2117    /// # Errors
2118    /// Returns [`crate::Error::RuntimeState`] for a device-only allocation and
2119    /// the non-compact-descriptor validation error for a strided owner.
2120    pub fn host_data_mut(&mut self) -> crate::Result<&mut [T]> {
2121        let range = group_logical_range(&self.storage.group, "TypedTensor::host_data_mut")?;
2122        let data = self.storage.group.host_slice_mut::<T>()?;
2123        data.get_mut(range).ok_or_else(|| {
2124            crate::Error::validation(
2125                "TypedTensor::host_data_mut",
2126                ValidationError::ViewOutOfBounds,
2127            )
2128        })
2129    }
2130
2131    /// Prepare this group-backed owner for one provider-native read binding.
2132    ///
2133    /// # Errors
2134    /// Returns a provider preparation error when the group has no device-read
2135    /// path for this layout.
2136    #[doc(hidden)]
2137    pub fn prepare_device_read(
2138        &self,
2139        op: &'static str,
2140    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
2141    where
2142        T: TensorScalar + 'static,
2143    {
2144        let layout = group_physical_layout(&self.storage.group);
2145        self.storage
2146            .group
2147            .prepare_device_read_for_layout::<T>(&layout)
2148            .map_err(|error| crate::Error::runtime_state_source(op, error))
2149    }
2150
2151    /// Prepare this group-backed owner for one provider-native write binding.
2152    ///
2153    /// # Errors
2154    /// Returns a provider preparation error when the group has no device-write
2155    /// path for this layout.
2156    #[doc(hidden)]
2157    pub fn prepare_device_write(
2158        &mut self,
2159        op: &'static str,
2160    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
2161    where
2162        T: TensorScalar + 'static,
2163    {
2164        let layout = group_physical_layout(&self.storage.group);
2165        self.storage
2166            .group
2167            .prepare_device_write_for_layout::<T>(&layout)
2168            .map_err(|error| crate::Error::runtime_state_source(op, error))
2169    }
2170}
2171
2172impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
2173    /// Checked narrowing to the statically host-owned representation.
2174    ///
2175    /// Fails without consuming ownership of the source tensor.
2176    ///
2177    /// # Examples
2178    /// ```
2179    /// use tenferro_tensor::TypedTensor;
2180    /// let dynamic = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![7])?;
2181    /// let host = dynamic.into_host().unwrap();
2182    /// assert_eq!(host.as_slice(), &[7]);
2183    /// # Ok::<(), tenferro_tensor::Error>(())
2184    /// ```
2185    /// # Errors
2186    /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is
2187    /// group-backed rather than plain host storage.
2188    #[allow(clippy::result_large_err)]
2189    pub fn into_host(self) -> Result<TypedTensor<T, R, Host>, ReinterpretError<Self>> {
2190        let TypedTensor {
2191            shape,
2192            placement,
2193            layout,
2194            storage,
2195        } = self;
2196        match storage {
2197            // This is the only way a value becomes `TypedTensor<_, _, Host>`, so it is where the
2198            // representation's one invariant is established: a host-backed tensor never carries a
2199            // device memory label. `TypedTensor::set_placement` refuses that label on host storage,
2200            // and the buffers that reach here are built with a matching one, so the narrowing only
2201            // has to move the payload across; an entry point that takes `Host` may skip a runtime
2202            // placement check (the CPU entry points narrow once, through `TensorRead::try_host`).
2203            DynamicStorage::Host(host) => Ok(TypedTensor {
2204                shape,
2205                placement,
2206                layout,
2207                storage: host,
2208            }),
2209            DynamicStorage::Group(group) => Err(ReinterpretError::new(
2210                TypedTensor {
2211                    shape,
2212                    placement,
2213                    layout,
2214                    storage: DynamicStorage::Group(group),
2215                },
2216                crate::Error::runtime_state(
2217                    "TypedTensor::into_host",
2218                    "the tensor is group-backed rather than plain host storage",
2219                ),
2220            )),
2221        }
2222    }
2223
2224    /// Checked narrowing to the group-backed representation.
2225    ///
2226    /// Fails without consuming ownership of the source tensor.
2227    ///
2228    /// # Examples
2229    ///
2230    /// ```
2231    /// use tenferro_tensor::{DynRank, Gpu, Host, TypedTensor};
2232    /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![2.0])?;
2233    /// let dynamic = host.promote()?.into_dynamic();
2234    /// let gpu: TypedTensor<f64, DynRank, Gpu> = dynamic.into_gpu().map_err(|f| f.into_parts().1)?;
2235    /// assert_eq!(gpu.host_data()?, &[2.0]);
2236    /// let plain = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![2.0])?;
2237    /// assert!(plain.into_gpu().is_err());
2238    /// # Ok::<(), tenferro_tensor::Error>(())
2239    /// ```
2240    ///
2241    /// # Errors
2242    /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is a
2243    /// plain host owner rather than a group-backed one.
2244    #[allow(clippy::result_large_err)]
2245    pub fn into_gpu(self) -> Result<TypedTensor<T, R, Gpu>, ReinterpretError<Self>> {
2246        let TypedTensor {
2247            shape,
2248            placement,
2249            layout,
2250            storage,
2251        } = self;
2252        match storage {
2253            DynamicStorage::Group(group) => Ok(TypedTensor {
2254                shape,
2255                placement,
2256                layout,
2257                storage: group,
2258            }),
2259            DynamicStorage::Host(host) => Err(ReinterpretError::new(
2260                TypedTensor {
2261                    shape,
2262                    placement,
2263                    layout,
2264                    storage: DynamicStorage::Host(host),
2265                },
2266                crate::Error::runtime_state(
2267                    "TypedTensor::into_gpu",
2268                    "the tensor is a plain host owner rather than group-backed storage",
2269                ),
2270            )),
2271        }
2272    }
2273}
2274
2275impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
2276    /// Replace placement metadata without changing the storage buffer.
2277    ///
2278    /// Placement is metadata on top of the payload, and it must describe it:
2279    /// a plain host payload accepts [`MemoryKind::PinnedHost`],
2280    /// [`MemoryKind::UnpinnedHost`] or [`MemoryKind::Other`], a backend payload
2281    /// accepts [`MemoryKind::Device`], [`MemoryKind::Managed`] or
2282    /// [`MemoryKind::Other`], and the two contradicting pairs are refused.
2283    /// This is the only place a payload and a label meet after construction, so
2284    /// refusing here is what lets every consumer answer "is this host memory?"
2285    /// from the payload alone instead of re-reading the label.
2286    ///
2287    /// Only the runtime union can be relabelled. A [`Host`] or [`Gpu`] owner
2288    /// keeps the placement it was built with; move it through `into_dynamic()`
2289    /// first to relabel it.
2290    ///
2291    /// ```compile_fail
2292    /// use tenferro_tensor::{DynRank, Host, Placement, TypedTensor};
2293    /// let mut host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0])?;
2294    /// host.set_placement(Placement::default());
2295    /// # Ok::<(), tenferro_tensor::Error>(())
2296    /// ```
2297    ///
2298    /// # Examples
2299    ///
2300    /// ```rust
2301    /// use tenferro_tensor::{MemoryKind, Placement, TypedTensor};
2302    ///
2303    /// let mut t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
2304    /// t.set_placement(Placement {
2305    ///     memory_kind: MemoryKind::PinnedHost,
2306    ///     device: None,
2307    ///     cpu_affinity: None,
2308    /// })?;
2309    /// assert_eq!(t.placement().memory_kind, MemoryKind::PinnedHost);
2310    /// # Ok::<(), tenferro_tensor::Error>(())
2311    /// ```
2312    ///
2313    /// # Errors
2314    ///
2315    /// Returns [`crate::Error::RuntimeState`] when `placement.memory_kind`
2316    /// names a memory class the payload cannot be, and stores nothing in that
2317    /// case.
2318    pub fn set_placement(&mut self, placement: Placement) -> crate::Result<()> {
2319        validate_placement_for_payload(
2320            "TypedTensor::set_placement",
2321            self.is_host_memory(),
2322            &placement,
2323        )?;
2324        self.placement = placement;
2325        Ok(())
2326    }
2327
2328    /// Replace only CPU routing/locality metadata without changing storage.
2329    ///
2330    /// Device, memory kind, backend allocation domain, and allocation identity
2331    /// remain unchanged.
2332    ///
2333    /// # Examples
2334    ///
2335    /// ```rust
2336    /// use tenferro_tensor::{CpuDomainId, TypedTensor};
2337    ///
2338    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0])?;
2339    /// tensor.set_cpu_affinity(Some(CpuDomainId::new(4)));
2340    /// assert_eq!(tensor.placement().cpu_affinity, Some(CpuDomainId::new(4)));
2341    /// # Ok::<(), tenferro_tensor::Error>(())
2342    /// ```
2343    pub fn set_cpu_affinity(&mut self, cpu_affinity: Option<CpuDomainId>) {
2344        self.placement.cpu_affinity = cpu_affinity;
2345    }
2346
2347    /// Whether this owner's payload is host-addressed memory.
2348    ///
2349    /// This is the one host/device answer in the workspace: the payload
2350    /// decides, never [`Placement::memory_kind`]. A plain host payload and a
2351    /// CPU-resident allocation group are host memory; a group backed by another
2352    /// provider is not. CPU and linalg entry points both ask this question, so
2353    /// a tensor cannot be host memory for one and device memory for the other.
2354    /// [`Self::set_placement`] refuses a label this answer contradicts, so the
2355    /// two never disagree.
2356    ///
2357    /// # Examples
2358    ///
2359    /// ```rust
2360    /// use tenferro_tensor::TypedTensor;
2361    ///
2362    /// let host = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
2363    /// assert!(host.is_host_memory());
2364    /// assert!(host.as_view().is_host_memory());
2365    /// # Ok::<(), tenferro_tensor::Error>(())
2366    /// ```
2367    pub fn is_host_memory(&self) -> bool {
2368        match &self.storage {
2369            DynamicStorage::Host(_) => true,
2370            // The same root fact `as_view()` reads to choose a host slice over a
2371            // root handle, so an owner and its views cannot answer differently.
2372            DynamicStorage::Group(core) => core.group.payload_is_host_memory(),
2373        }
2374    }
2375
2376    /// Layout that reflects the owned storage rather than the compact shape.
2377    ///
2378    /// [`Self::layout`] reports the compact construction layout. A
2379    /// root-preserving extraction may instead carry a nonzero descriptor offset
2380    /// and fewer logical elements than the backing root, so callers that
2381    /// canonicalize an owned tensor must use this accessor.
2382    pub(crate) fn physical_layout(&self) -> TensorLayout<R> {
2383        match &self.storage {
2384            DynamicStorage::Host(_) => TensorLayout::<R>::compact(self.shape.clone())
2385                .unwrap_or_else(|err| unreachable!("validated owned shape: {err}")),
2386            DynamicStorage::Group(core) => group_physical_layout(&core.group),
2387        }
2388    }
2389}
2390
2391/// Descriptor layout of a group-backed owner over its whole backing root.
2392///
2393/// The descriptor is the storage truth for a root-preserving extraction, so its
2394/// offset and backing length override the compact logical shape cached on the
2395/// tensor.
2396fn group_physical_layout<R: TensorRank>(core: &OwnedTensorGroup<R>) -> TensorLayout<R> {
2397    let descriptor = core
2398        .group
2399        .descriptor_layout(core.slot)
2400        .unwrap_or_else(|| unreachable!("a live group carries its descriptor layout"));
2401    let shape = R::shape_from_vec(shape_vec(descriptor.shape()))
2402        .unwrap_or_else(|err| unreachable!("validated descriptor shape: {err:?}"));
2403    let strides = R::strides_from_vec(stride_vec(descriptor.strides()))
2404        .unwrap_or_else(|err| unreachable!("validated descriptor strides: {err:?}"));
2405    let buffer_len = core
2406        .group
2407        .descriptor_backing_len(core.slot)
2408        .unwrap_or_else(|| unreachable!("a live group carries its root length"));
2409    TensorLayout::<R>::from_parts(shape, strides, descriptor.offset(), buffer_len)
2410        .unwrap_or_else(|err| unreachable!("validated descriptor layout: {err:?}"))
2411}
2412
2413/// Contiguous logical element range of a group-backed owner inside its root.
2414fn group_logical_range<R: TensorRank>(
2415    core: &OwnedTensorGroup<R>,
2416    op: &'static str,
2417) -> crate::Result<std::ops::Range<usize>> {
2418    core.group
2419        .descriptor_logical_range(core.slot)
2420        .ok_or_else(|| crate::Error::validation(op, ValidationError::NonContiguousViewAsSlice))
2421}
2422
2423impl<T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensor<T, R, D> {
2424    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2425        formatter
2426            .debug_struct("TypedTensor")
2427            .field("shape", &self.shape.as_ref())
2428            .field("placement", &self.placement)
2429            .finish_non_exhaustive()
2430    }
2431}
2432
2433impl<T, R: TensorRank, D: Representation> TypedTensor<T, R, D> {
2434    /// Number of elements in the tensor.
2435    ///
2436    /// # Examples
2437    ///
2438    /// ```rust
2439    /// use tenferro_tensor::TypedTensor;
2440    ///
2441    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2442    /// assert_eq!(t.n_elements(), 6);
2443    /// ```
2444    pub fn n_elements(&self) -> usize {
2445        // Invariant: owned tensor constructors validate compact shape length against buffer length.
2446        match try_shape_product(self.shape(), "TypedTensor::n_elements") {
2447            Ok(n) => n,
2448            Err(err) => {
2449                unreachable!("TypedTensor compact shape is validated at construction: {err}")
2450            }
2451        }
2452    }
2453
2454    /// Tensor shape.
2455    ///
2456    /// # Examples
2457    ///
2458    /// ```
2459    /// use tenferro_tensor::TypedTensor;
2460    ///
2461    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
2462    /// assert_eq!(t.shape(), &[2]);
2463    /// ```
2464    pub fn shape(&self) -> &[usize] {
2465        self.shape.as_ref()
2466    }
2467
2468    /// Column-major element strides of this compact tensor.
2469    ///
2470    /// The layout is cached at construction, so views of a tensor borrow it
2471    /// rather than computing (and allocating) it once per operation.
2472    ///
2473    /// # Examples
2474    ///
2475    /// ```
2476    /// use tenferro_tensor::TypedTensor;
2477    ///
2478    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2479    /// assert_eq!(t.strides(), &[1, 2]);
2480    /// ```
2481    pub fn strides(&self) -> &[isize] {
2482        &self.layout
2483    }
2484
2485    /// Tensor rank.
2486    ///
2487    /// # Examples
2488    ///
2489    /// ```
2490    /// use tenferro_tensor::TypedTensor;
2491    ///
2492    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2493    /// assert_eq!(t.rank(), 2);
2494    /// ```
2495    pub fn rank(&self) -> usize {
2496        self.shape().len()
2497    }
2498
2499    /// Tensor layout metadata.
2500    ///
2501    /// Owned typed tensors are always compact column-major layouts.
2502    ///
2503    /// # Examples
2504    ///
2505    /// ```
2506    /// use tenferro_tensor::TypedTensor;
2507    ///
2508    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2509    /// assert_eq!(t.layout().strides(), &[1, 2]);
2510    /// ```
2511    pub fn layout(&self) -> TensorLayout<R> {
2512        TensorLayout::compact(self.shape.clone())
2513            .unwrap_or_else(|err| unreachable!("validated owned shape: {err}"))
2514    }
2515
2516    /// Return placement metadata for this tensor.
2517    ///
2518    /// # Examples
2519    ///
2520    /// ```
2521    /// use tenferro_tensor::{MemoryKind, TypedTensor};
2522    ///
2523    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
2524    /// assert_eq!(t.placement().memory_kind, MemoryKind::UnpinnedHost);
2525    /// ```
2526    pub fn placement(&self) -> &Placement {
2527        &self.placement
2528    }
2529
2530    /// Compute the checked compact column-major offset of an element.
2531    ///
2532    /// # Examples
2533    /// ```
2534    /// use tenferro_tensor::TypedTensor;
2535    /// let tensor = TypedTensor::<String>::from_vec_col_major([2, 3], vec![String::new(); 6])?;
2536    /// assert_eq!(tensor.linear_offset(&[1, 2])?, 5);
2537    /// # Ok::<(), tenferro_tensor::Error>(())
2538    /// ```
2539    /// # Errors
2540    /// Wrong rank, out-of-range coordinates or arithmetic overflow return
2541    /// [`crate::Error::Validation`].
2542    pub fn linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
2543        try_linear_offset_for_shape(self.shape(), indices, "TypedTensor::linear_offset")
2544    }
2545
2546    /// Consume this tensor and return its layout metadata.
2547    ///
2548    /// # Examples
2549    ///
2550    /// ```
2551    /// use tenferro_tensor::TypedTensor;
2552    ///
2553    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
2554    /// assert!(t.into_layout().is_compact_col_major().unwrap());
2555    /// ```
2556    pub fn into_layout(self) -> TensorLayout<R> {
2557        self.layout()
2558    }
2559
2560    /// Compute the physical element offset for a logical index.
2561    ///
2562    /// # Examples
2563    ///
2564    /// ```rust
2565    /// use tenferro_tensor::TypedTensor;
2566    ///
2567    /// let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
2568    /// assert_eq!(t.layout_linear_offset(&[1, 2])?, 5);
2569    /// # Ok::<(), tenferro_tensor::Error>(())
2570    /// ```
2571    /// # Errors
2572    ///
2573    /// Returns [`crate::Error::Validation`] with
2574    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
2575    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
2576    /// when an index is outside its axis extent, or
2577    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
2578    /// arithmetic overflows.
2579    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
2580        try_linear_offset_for_shape(self.shape(), indices, "TypedTensor::layout_linear_offset")
2581    }
2582
2583    /// Return whether this owned tensor is compact column-major.
2584    ///
2585    /// # Examples
2586    ///
2587    /// ```rust
2588    /// use tenferro_tensor::TypedTensor;
2589    ///
2590    /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2591    /// assert!(t.is_col_major_contiguous()?);
2592    /// # Ok::<(), tenferro_tensor::Error>(())
2593    /// ```
2594    /// # Errors
2595    ///
2596    /// Returns [`crate::Error::Validation`] with
2597    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
2598    /// compactness arithmetic overflows.
2599    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
2600        self.layout()
2601            .is_compact_col_major()
2602            .map_err(|err| tensor_layout_error("TypedTensor::is_col_major_contiguous", err))
2603    }
2604
2605    /// Return a compact string summary of this tensor's layout metadata.
2606    ///
2607    /// # Examples
2608    ///
2609    /// ```rust
2610    /// use tenferro_tensor::TypedTensor;
2611    ///
2612    /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2613    /// assert!(t.layout_summary().contains("shape=[2]"));
2614    /// # Ok::<(), tenferro_tensor::Error>(())
2615    /// ```
2616    pub fn layout_summary(&self) -> String {
2617        let layout = self.layout();
2618        layout_summary(self.shape(), layout.strides(), layout.offset())
2619    }
2620
2621    /// Assert this tensor is compact column-major.
2622    ///
2623    /// # Examples
2624    ///
2625    /// ```rust
2626    /// use tenferro_tensor::TypedTensor;
2627    ///
2628    /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2629    /// t.assert_col_major_contiguous()?;
2630    /// # Ok::<(), tenferro_tensor::Error>(())
2631    /// ```
2632    /// # Errors
2633    ///
2634    /// Returns [`crate::Error::Validation`] with
2635    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
2636    /// compactness arithmetic overflows, or
2637    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
2638    /// tensor is not compact column-major.
2639    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
2640        let layout = self.layout();
2641        assert_layout_col_major_contiguous(
2642            self.is_col_major_contiguous()?,
2643            self.shape(),
2644            layout.strides(),
2645            layout.offset(),
2646            "TypedTensor::assert_col_major_contiguous",
2647        )
2648    }
2649}
2650
2651struct HostData<T> {
2652    buffer: StorageBuffer<T>,
2653    recycler: Option<std::sync::Weak<dyn crate::HostBufferRecycler<T>>>,
2654}
2655
2656impl<T> std::fmt::Debug for HostData<T> {
2657    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2658        formatter
2659            .debug_struct("HostData")
2660            .field("pooled", &self.recycler.is_some())
2661            .finish_non_exhaustive()
2662    }
2663}
2664
2665impl<T> HostData<T> {
2666    fn new(data: Vec<T>) -> Self {
2667        Self {
2668            buffer: StorageBuffer::Host(data),
2669            recycler: None,
2670        }
2671    }
2672
2673    fn into_vec(mut self) -> Vec<T> {
2674        self.recycler = None;
2675        match std::mem::replace(&mut self.buffer, StorageBuffer::Host(Vec::new())) {
2676            StorageBuffer::Host(data) => data,
2677            StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2678        }
2679    }
2680
2681    fn as_slice(&self) -> &[T] {
2682        match &self.buffer {
2683            StorageBuffer::Host(data) => data,
2684            StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2685        }
2686    }
2687
2688    fn as_mut_slice(&mut self) -> &mut [T] {
2689        match &mut self.buffer {
2690            StorageBuffer::Host(data) => data,
2691            StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2692        }
2693    }
2694}
2695
2696impl<T> Drop for HostData<T> {
2697    fn drop(&mut self) {
2698        let Some(recycler) = self.recycler.take().and_then(|weak| weak.upgrade()) else {
2699            return;
2700        };
2701        if let StorageBuffer::Host(data) = &mut self.buffer {
2702            recycler.recycle(std::mem::take(data));
2703        }
2704    }
2705}
2706
2707/// The sole owner handle for host tensors. The allocation group owns the
2708/// provider root; the descriptor slot carries only the logical view metadata.
2709pub(crate) struct OwnedTensorGroup<R: TensorRank> {
2710    group: AllocationGroup,
2711    slot: DescriptorSlot,
2712    allocation_index: AllocationSlot,
2713    // INVARIANT: this non-owning address points into the group root, whose host
2714    // vector cannot resize while the owning tensor is borrowed. It is stored as
2715    // `NonZeroUsize` rather than `NonNull<u8>`: the niche keeps the field at one
2716    // word, and unlike `NonNull` it preserves the `Send`/`Sync` auto traits the
2717    // typed tensor contract requires.
2718    host_ptr: Option<NonZeroUsize>,
2719    host_byte_len: usize,
2720    _rank: PhantomData<R>,
2721}
2722
2723impl<R: TensorRank> Debug for OwnedTensorGroup<R> {
2724    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2725        formatter
2726            .debug_struct("OwnedTensorGroup")
2727            .field("slot", &self.slot)
2728            .finish_non_exhaustive()
2729    }
2730}
2731
2732impl<R: TensorRank> OwnedTensorGroup<R> {
2733    fn from_host_vec<T: TensorScalar>(shape: R::Shape, data: Vec<T>) -> crate::Result<Self> {
2734        let (group, slot) = AllocationGroup::from_host_vec::<T, R>(shape, data)
2735            .map_err(|error| group_error("TypedTensor::from_host_vec", error))?;
2736        let allocation_index = group
2737            .allocation_index(slot)
2738            .map_err(|error| group_error("TypedTensor::from_host_vec", error))?;
2739        let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
2740        Ok(Self {
2741            group,
2742            slot,
2743            allocation_index,
2744            host_ptr,
2745            host_byte_len,
2746            _rank: PhantomData,
2747        })
2748    }
2749
2750    fn from_backend_buffer<T: TensorScalar + Send + Sync + 'static>(
2751        shape: R::Shape,
2752        buffer: StorageBuffer<T>,
2753        placement: Placement,
2754    ) -> crate::Result<Self> {
2755        let (mut group, slot) = AllocationGroup::from_backend_buffer::<T, R>(shape, buffer)
2756            .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2757        group
2758            .set_descriptor_placement(slot, placement)
2759            .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2760        let allocation_index = group
2761            .allocation_index(slot)
2762            .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2763        let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
2764        Ok(Self {
2765            group,
2766            slot,
2767            allocation_index,
2768            host_ptr,
2769            host_byte_len,
2770            _rank: PhantomData,
2771        })
2772    }
2773
2774    fn view<T: TensorScalar>(&self) -> crate::Result<GroupReadView<'_, T, R>> {
2775        self.group
2776            .view(self.slot)
2777            .map_err(|error| group_error("TypedTensor::group_view", error))
2778    }
2779
2780    fn view_dyn<T: TensorScalar>(&self) -> crate::Result<GroupReadView<'_, T, DynRank>> {
2781        self.group
2782            .view(self.slot)
2783            .map_err(|error| group_error("TypedTensor::group_view", error))
2784    }
2785
2786    fn view_mut<T: TensorScalar>(&mut self) -> crate::Result<GroupWriteView<'_, T, R>> {
2787        self.group
2788            .view_mut(self.slot)
2789            .map_err(|error| group_error("TypedTensor::group_view_mut", error))
2790    }
2791
2792    fn view_mut_dyn<T: TensorScalar>(&mut self) -> crate::Result<GroupWriteView<'_, T, DynRank>> {
2793        self.group
2794            .view_mut(self.slot)
2795            .map_err(|error| group_error("TypedTensor::group_view_mut", error))
2796    }
2797
2798    fn prepare_device_read_for_layout<T: TensorScalar>(
2799        &self,
2800        layout: &TensorLayout<R>,
2801    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>> {
2802        self.group
2803            .prepare_device_read_for_layout::<T, R>(self.slot, layout)
2804            .map_err(|error| {
2805                crate::Error::runtime_state_source("TypedTensor::prepare_device_read", error)
2806            })
2807    }
2808
2809    fn prepare_device_write_for_layout<T: TensorScalar>(
2810        &mut self,
2811        layout: &TensorLayout<R>,
2812    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>> {
2813        self.group
2814            .prepare_device_write_for_layout::<T, R>(self.slot, layout)
2815            .map_err(|error| {
2816                crate::Error::runtime_state_source("TypedTensor::prepare_device_write", error)
2817            })
2818    }
2819
2820    fn host_buffer<T: 'static>(&self) -> Option<&StorageBuffer<T>> {
2821        self.group.host_buffer_at::<T>(self.allocation_index)
2822    }
2823
2824    fn host_slice<T>(&self) -> crate::Result<&[T]> {
2825        let Some(pointer) = self.host_ptr else {
2826            return Err(crate::Error::runtime_state(
2827                "TypedTensor::host_data",
2828                "backend storage cannot be borrowed as host data; download explicitly first",
2829            ));
2830        };
2831        let element_size = size_of::<T>();
2832        let Some(element_count) = self.host_byte_len.checked_div(element_size) else {
2833            return Err(crate::Error::runtime_state(
2834                "TypedTensor::host_data",
2835                "host allocation byte length is not aligned to the requested dtype",
2836            ));
2837        };
2838        // SAFETY: the pointer and byte length were captured from the unique
2839        // root's full host allocation; the root cannot resize while borrowed.
2840        Ok(unsafe { std::slice::from_raw_parts(pointer.get() as *const T, element_count) })
2841    }
2842
2843    fn host_slice_mut<T>(&mut self) -> crate::Result<&mut [T]> {
2844        let Some(pointer) = self.host_ptr else {
2845            return Err(crate::Error::runtime_state(
2846                "TypedTensor::host_data_mut",
2847                "backend storage cannot be borrowed as host data; download explicitly first",
2848            ));
2849        };
2850        let element_size = size_of::<T>();
2851        let Some(element_count) = self.host_byte_len.checked_div(element_size) else {
2852            return Err(crate::Error::runtime_state(
2853                "TypedTensor::host_data_mut",
2854                "host allocation byte length is not aligned to the requested dtype",
2855            ));
2856        };
2857        // SAFETY: the pointer and byte length were captured from the unique
2858        // root; this method has the only mutable borrow of that root.
2859        Ok(unsafe { std::slice::from_raw_parts_mut(pointer.get() as *mut T, element_count) })
2860    }
2861
2862    fn backend_buffer<T: 'static>(&self) -> Option<&StorageBuffer<T>> {
2863        self.group.backend_buffer::<T>(self.slot)
2864    }
2865
2866    fn backend_buffer_mut<T: 'static>(&mut self) -> Option<&mut StorageBuffer<T>> {
2867        self.group.backend_buffer_mut::<T>(self.slot)
2868    }
2869
2870    // INVARIANT: the failure carrier must return the unchanged group owner, so
2871    // the wide `(Self, Error)` pair is deliberate rather than a boxing bug.
2872    #[allow(clippy::result_large_err)]
2873    fn into_host_vec<T: 'static>(self) -> std::result::Result<Vec<T>, (Self, crate::Error)> {
2874        if self.backend_buffer::<T>().is_some() {
2875            return Err((
2876                self,
2877                crate::Error::runtime_state(
2878                    "TypedTensor::into_host_vec",
2879                    "backend buffers cannot be exported as host Vec; download the tensor first",
2880                ),
2881            ));
2882        }
2883        let OwnedTensorGroup {
2884            group,
2885            slot,
2886            allocation_index,
2887            host_ptr,
2888            host_byte_len,
2889            ..
2890        } = self;
2891        match group.into_host_vec::<T>(slot) {
2892            Ok(data) => Ok(data),
2893            Err((group, error)) => Err((
2894                OwnedTensorGroup {
2895                    group,
2896                    slot,
2897                    allocation_index,
2898                    host_ptr,
2899                    host_byte_len,
2900                    _rank: PhantomData,
2901                },
2902                crate::Error::runtime_state("TypedTensor::into_host_vec", error),
2903            )),
2904        }
2905    }
2906
2907    fn into_parts(self) -> (AllocationGroup, DescriptorSlot) {
2908        (self.group, self.slot)
2909    }
2910
2911    #[allow(clippy::result_large_err)]
2912    fn reinterpret<T: TensorScalar, U: TensorScalar>(
2913        self,
2914        shape: Vec<usize>,
2915        strides: Vec<isize>,
2916        offset: isize,
2917    ) -> Result<OwnedTensorGroup<DynRank>, (Self, crate::Error)> {
2918        let OwnedTensorGroup {
2919            group,
2920            slot,
2921            allocation_index,
2922            host_ptr,
2923            host_byte_len,
2924            _rank: _,
2925        } = self;
2926        match group.reinterpret_descriptor::<T, U>(slot, shape, strides, offset) {
2927            Ok(group) => Ok(OwnedTensorGroup {
2928                group,
2929                slot,
2930                allocation_index,
2931                host_ptr,
2932                host_byte_len,
2933                _rank: PhantomData,
2934            }),
2935            Err((group, error)) => Err((
2936                OwnedTensorGroup {
2937                    group,
2938                    slot,
2939                    allocation_index,
2940                    host_ptr,
2941                    host_byte_len,
2942                    _rank: PhantomData,
2943                },
2944                group_error("TypedTensor::reinterpret", error),
2945            )),
2946        }
2947    }
2948}
2949
2950fn host_metadata<T: TensorScalar>(
2951    group: &AllocationGroup,
2952    slot: DescriptorSlot,
2953) -> (Option<NonZeroUsize>, usize) {
2954    group
2955        .host_root_metadata::<T>(slot)
2956        .map_or((None, 0), |(pointer, byte_len)| {
2957            // INVARIANT: `host_root_metadata` reports the base address of the group's live
2958            // host allocation, which is non-null for any slice, empty included.
2959            (NonZeroUsize::new(pointer), byte_len)
2960        })
2961}
2962
2963fn group_error(op: &'static str, error: GroupError) -> crate::Error {
2964    crate::Error::runtime_state(op, error.to_string())
2965}
2966
2967/// Borrowed tensor buffer reference used by read-only typed views.
2968///
2969/// # Examples
2970///
2971/// ```rust
2972/// use tenferro_tensor::TensorStorageRef;
2973///
2974/// let data = [1_i32, 2];
2975/// let buffer = TensorStorageRef::Host(&data);
2976/// assert_eq!(buffer.len(), 2);
2977/// ```
2978#[derive(Debug)]
2979pub enum TensorStorageRef<'a, T> {
2980    Host(&'a [T]),
2981    Backend(&'a dyn BackendStorage<T>),
2982    #[doc(hidden)]
2983    Root(&'a dyn BackendAllocation),
2984}
2985
2986impl<T> Clone for TensorStorageRef<'_, T> {
2987    fn clone(&self) -> Self {
2988        match self {
2989            Self::Host(data) => Self::Host(data),
2990            Self::Backend(buffer) => Self::Backend(*buffer),
2991            Self::Root(allocation) => Self::Root(*allocation),
2992        }
2993    }
2994}
2995
2996impl<T: 'static> TensorStorageRef<'_, T> {
2997    /// Return the logical length of the backing allocation.
2998    ///
2999    /// # Examples
3000    ///
3001    /// ```rust
3002    /// use tenferro_tensor::TensorStorageRef;
3003    ///
3004    /// let data = [1_i32, 2, 3];
3005    /// assert_eq!(TensorStorageRef::Host(&data).len(), 3);
3006    /// ```
3007    pub fn len(&self) -> usize {
3008        match self {
3009            Self::Host(data) => data.len(),
3010            Self::Backend(buffer) => buffer.len(),
3011            Self::Root(allocation) => allocation
3012                .root_extent()
3013                .byte_len()
3014                .checked_div(std::mem::size_of::<T>())
3015                .unwrap_or(0),
3016        }
3017    }
3018
3019    /// Return whether the backing allocation is empty.
3020    ///
3021    /// # Examples
3022    ///
3023    /// ```rust
3024    /// use tenferro_tensor::TensorStorageRef;
3025    ///
3026    /// let data: [f64; 0] = [];
3027    /// assert!(TensorStorageRef::Host(&data).is_empty());
3028    /// ```
3029    pub fn is_empty(&self) -> bool {
3030        self.len() == 0
3031    }
3032}
3033
3034/// Borrowed tensor buffer reference used by mutable typed views.
3035///
3036/// Backend buffers can be represented for residency metadata, but this crate
3037/// does not expose host mutation for backend-native allocations.
3038///
3039/// # Examples
3040///
3041/// ```rust
3042/// use tenferro_tensor::TensorStorageRefMut;
3043///
3044/// let mut data = [1_i32, 2];
3045/// let buffer = TensorStorageRefMut::Host(&mut data);
3046/// assert_eq!(buffer.len(), 2);
3047/// ```
3048#[derive(Debug)]
3049pub enum TensorStorageRefMut<'a, T> {
3050    Host(&'a mut [T]),
3051    Backend(&'a mut dyn BackendStorage<T>),
3052}
3053
3054impl<T: 'static> TensorStorageRefMut<'_, T> {
3055    /// Return the logical length of the backing allocation.
3056    ///
3057    /// # Examples
3058    ///
3059    /// ```rust
3060    /// use tenferro_tensor::TensorStorageRefMut;
3061    ///
3062    /// let mut data = [1_i32, 2, 3];
3063    /// assert_eq!(TensorStorageRefMut::Host(&mut data).len(), 3);
3064    /// ```
3065    pub fn len(&self) -> usize {
3066        match self {
3067            Self::Host(data) => data.len(),
3068            Self::Backend(buffer) => buffer.len(),
3069        }
3070    }
3071
3072    /// Return whether the backing allocation is empty.
3073    ///
3074    /// # Examples
3075    ///
3076    /// ```rust
3077    /// use tenferro_tensor::TensorStorageRefMut;
3078    ///
3079    /// let mut data: [f64; 0] = [];
3080    /// assert!(TensorStorageRefMut::Host(&mut data).is_empty());
3081    /// ```
3082    pub fn is_empty(&self) -> bool {
3083        self.len() == 0
3084    }
3085}
3086
3087/// Read-only borrowed view of typed tensor storage with arbitrary strides.
3088///
3089/// `TypedTensorView` is the typed representation for layout-only tensor
3090/// transformations. It borrows an existing host or backend allocation and
3091/// carries a logical shape, strides, and an offset. Slicing, reshaping when
3092/// stride-compatible, and [`transpose_view`](TypedTensorView::transpose_view)
3093/// update only metadata and do not copy storage.
3094///
3095/// Materialize through [`TensorStructural::to_contiguous_read`](crate::TensorStructural::to_contiguous_read)
3096/// on the active backend session when a compact owned [`TypedTensor`] is
3097/// required. Use [`TypedTensorView::as_slice`] only when the current view is
3098/// contiguous in the requested layout.
3099///
3100/// # Examples
3101///
3102/// ```rust
3103/// use tenferro_tensor::{Rank, TypedTensorView};
3104///
3105/// let data = [1_i32, 2, 3, 4];
3106/// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &data)?;
3107/// assert_eq!(view.get(&[1, 1]), Some(&4));
3108/// # Ok::<(), tenferro_tensor::Error>(())
3109/// ```
3110/// Borrowed typed view of one tensor representation.
3111///
3112/// The buffer stays concrete on purpose: a generic-associated buffer would make
3113/// the projection invariant in `'a`, and the borrowed-read surface relies on
3114/// `TensorRead<'long>` shortening to `TensorRead<'short>`. `D` therefore marks
3115/// which representation produced the view - `Host` is only ever built from host
3116/// slices, with no retained region.
3117pub struct TypedTensorView<'a, T, R: TensorRank = DynRank, D: Representation = Dynamic> {
3118    buffer: TensorStorageRef<'a, T>,
3119    root: Option<GroupReadView<'a, T, R>>,
3120    layout: TensorLayout<R>,
3121    placement: Placement,
3122    _representation: std::marker::PhantomData<D>,
3123}
3124
3125impl<'a, T, R: TensorRank, D: Representation> Clone for TypedTensorView<'a, T, R, D> {
3126    fn clone(&self) -> Self {
3127        Self {
3128            buffer: self.buffer.clone(),
3129            root: self.root.clone(),
3130            layout: self.layout.clone(),
3131            placement: self.placement.clone(),
3132            _representation: std::marker::PhantomData,
3133        }
3134    }
3135}
3136
3137impl<'a, T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensorView<'a, T, R, D> {
3138    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3139        formatter
3140            .debug_struct("TypedTensorView")
3141            .field("shape", &self.layout.shape())
3142            .field("placement", &self.placement)
3143            .finish_non_exhaustive()
3144    }
3145}
3146
3147impl<'a, T: 'static> TypedTensorView<'a, T, DynRank> {
3148    /// Create a borrowed dynamic-rank view over compact column-major host data.
3149    ///
3150    /// # Examples
3151    ///
3152    /// ```rust
3153    /// use tenferro_tensor::TypedTensorView;
3154    ///
3155    /// let data = [1_i32, 2, 3, 4];
3156    /// let view = TypedTensorView::from_col_major(&[2, 2], &data)?;
3157    /// assert_eq!(view.strides(), &[1, 2]);
3158    /// # Ok::<(), tenferro_tensor::Error>(())
3159    /// ```
3160    ///
3161    /// # Errors
3162    ///
3163    /// Returns [`crate::Error::Validation`] with
3164    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when compact
3165    /// strides or reachable bounds overflow, or
3166    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3167    /// requested shape reaches beyond `data`.
3168    pub fn from_col_major(shape: &[usize], data: &'a [T]) -> crate::Result<Self> {
3169        let layout = TensorLayout::<DynRank>::compact(shape_vec(shape))
3170            .map_err(|err| tensor_layout_error("TypedTensorView::from_col_major", err))?;
3171        Self::from_buffer_ref(
3172            shape_vec(layout.shape()),
3173            stride_vec(layout.strides()),
3174            layout.offset(),
3175            TensorStorageRef::Host(data),
3176            default_placement(),
3177            "TypedTensorView::from_col_major",
3178        )
3179    }
3180
3181    /// Create a borrowed host view from explicit layout metadata.
3182    ///
3183    /// # Examples
3184    ///
3185    /// ```rust
3186    /// use tenferro_tensor::TypedTensorView;
3187    ///
3188    /// let data = [1_i32, 2, 3];
3189    /// let view = TypedTensorView::from_slice(vec![3], vec![-1], 2, &data)?;
3190    /// assert_eq!(view.get(&[2]), Some(&1));
3191    /// # Ok::<(), tenferro_tensor::Error>(())
3192    /// ```
3193    ///
3194    /// # Errors
3195    ///
3196    /// Returns [`crate::Error::Validation`] with
3197    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `shape` and
3198    /// `strides` have different ranks,
3199    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3200    /// reachable layout exceeds `data`, or
3201    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when layout
3202    /// arithmetic overflows.
3203    pub fn from_slice(
3204        shape: impl AsRef<[usize]>,
3205        strides: impl AsRef<[isize]>,
3206        offset: isize,
3207        data: &'a [T],
3208    ) -> crate::Result<Self> {
3209        Self::from_buffer_ref(
3210            shape_vec(shape.as_ref()),
3211            stride_vec(strides.as_ref()),
3212            offset,
3213            TensorStorageRef::Host(data),
3214            default_placement(),
3215            "TypedTensorView::from_slice",
3216        )
3217    }
3218}
3219
3220impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3221    /// Create a rank-generic borrowed host view from explicit layout metadata.
3222    ///
3223    /// # Examples
3224    ///
3225    /// ```rust
3226    /// use tenferro_tensor::{Rank, TypedTensorView};
3227    ///
3228    /// let data = [1_i32, 2, 3, 4];
3229    /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &data)?;
3230    /// assert_eq!(view.get(&[1, 1]), Some(&4));
3231    /// # Ok::<(), tenferro_tensor::Error>(())
3232    /// ```
3233    ///
3234    /// # Errors
3235    ///
3236    /// Returns [`crate::Error::Validation`] with
3237    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the typed
3238    /// rank does not match `shape` or `strides`,
3239    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3240    /// reachable layout exceeds `data`, or
3241    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when layout
3242    /// arithmetic overflows.
3243    pub fn from_slice_ranked(
3244        shape: impl Into<R::Shape>,
3245        strides: impl Into<R::Strides>,
3246        offset: isize,
3247        data: &'a [T],
3248    ) -> crate::Result<Self> {
3249        Self::from_buffer_ref(
3250            shape,
3251            strides,
3252            offset,
3253            TensorStorageRef::Host(data),
3254            default_placement(),
3255            "TypedTensorView::from_slice_ranked",
3256        )
3257    }
3258}
3259
3260impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3261    fn from_buffer_ref(
3262        shape: impl Into<R::Shape>,
3263        strides: impl Into<R::Strides>,
3264        offset: isize,
3265        buffer: TensorStorageRef<'a, T>,
3266        placement: Placement,
3267        op: &'static str,
3268    ) -> crate::Result<Self> {
3269        let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
3270            .map_err(|err| tensor_layout_error(op, err))?;
3271        Ok(Self {
3272            buffer,
3273            root: None,
3274            layout,
3275            placement,
3276            _representation: std::marker::PhantomData,
3277        })
3278    }
3279}
3280
3281impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Dynamic> {
3282    /// The host elements this view borrows, or `None` when it borrows a
3283    /// backend buffer.
3284    ///
3285    /// The one match that decides host memory for borrowed views. Both
3286    /// [`Self::is_host_memory`] and [`Self::try_host`] read it, so the
3287    /// predicate and the narrowing cannot drift apart.
3288    fn host_elements(&self) -> Option<&'a [T]> {
3289        match &self.buffer {
3290            TensorStorageRef::Host(data) => Some(*data),
3291            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => None,
3292        }
3293    }
3294
3295    /// Whether this view borrows host-addressed memory.
3296    ///
3297    /// The same answer [`Self::try_host`] acts on and
3298    /// [`TypedTensor::is_host_memory`] gives for the owner: the borrowed payload
3299    /// decides, never [`Placement::memory_kind`].
3300    ///
3301    /// # Examples
3302    ///
3303    /// ```rust
3304    /// use tenferro_tensor::TypedTensor;
3305    ///
3306    /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
3307    /// assert!(tensor.as_view().is_host_memory());
3308    /// # Ok::<(), tenferro_tensor::Error>(())
3309    /// ```
3310    pub fn is_host_memory(&self) -> bool {
3311        self.host_elements().is_some()
3312    }
3313
3314    /// Checked narrowing of a borrowed view to the host representation.
3315    ///
3316    /// This is the one place a borrowed dynamic view becomes `Host`-marked: it
3317    /// succeeds exactly when the view borrows host elements (a plain host
3318    /// owner, a host slice, or a CPU-resident allocation group) and keeps the
3319    /// layout and the placement label. It runs [`Self::is_host_memory`], so a
3320    /// CPU entry point that narrows here and a CPU entry point that validates
3321    /// without narrowing reach the same verdict. A consumer that receives the
3322    /// result reads it through [`TypedTensorView::as_host_slice`] without a
3323    /// further check.
3324    ///
3325    /// # Examples
3326    ///
3327    /// ```rust
3328    /// use tenferro_tensor::TypedTensor;
3329    ///
3330    /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
3331    /// let host = tensor.as_view().try_host("example")?;
3332    /// assert_eq!(host.as_host_slice(), &[1.0, 2.0]);
3333    /// # Ok::<(), tenferro_tensor::Error>(())
3334    /// ```
3335    ///
3336    /// # Errors
3337    ///
3338    /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
3339    /// borrows backend (device) storage; download the tensor to host first.
3340    pub fn try_host(self, op: &'static str) -> crate::Result<TypedTensorView<'a, T, R, Host>> {
3341        let Some(data) = self.host_elements() else {
3342            return Err(crate::Error::runtime_state(
3343                op,
3344                "CPU backend received a backend buffer; download the tensor to host before CPU execution",
3345            ));
3346        };
3347        Ok(TypedTensorView {
3348            buffer: TensorStorageRef::Host(data),
3349            // A host-marked view carries no retained region: the borrow of
3350            // `data` is what keeps the owner alive for `'a`.
3351            root: None,
3352            layout: self.layout,
3353            placement: self.placement,
3354            _representation: std::marker::PhantomData,
3355        })
3356    }
3357}
3358
3359impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Host> {
3360    /// Widen a host-marked view to the runtime union without copying.
3361    ///
3362    /// # Examples
3363    ///
3364    /// ```rust
3365    /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3366    ///
3367    /// let data = [1_i32, 2];
3368    /// let host: TypedTensorView<'_, i32, DynRank, Host> =
3369    ///     TypedTensorView::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &data)?;
3370    /// let dynamic = host.into_dynamic();
3371    /// assert_eq!(dynamic.host_storage()?, &[1, 2]);
3372    /// # Ok::<(), tenferro_tensor::Error>(())
3373    /// ```
3374    pub fn into_dynamic(self) -> TypedTensorView<'a, T, R, Dynamic> {
3375        TypedTensorView {
3376            buffer: self.buffer,
3377            root: self.root,
3378            layout: self.layout,
3379            placement: self.placement,
3380            _representation: std::marker::PhantomData,
3381        }
3382    }
3383}
3384
3385impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Host> {
3386    /// Create a representation-marked view over an explicit host layout.
3387    ///
3388    /// A `Host`-marked view is only ever built from a host slice, so it carries
3389    /// no retained region and its host slice needs no runtime check.
3390    ///
3391    /// # Examples
3392    ///
3393    /// ```rust
3394    /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3395    ///
3396    /// let data = [1_i32, 2, 3, 4];
3397    /// let view: TypedTensorView<'_, i32, DynRank, Host> =
3398    ///     TypedTensorView::from_host_slice(vec![2, 2].as_slice(), vec![1, 2].as_slice(), 0, &data)?;
3399    /// assert_eq!(view.as_host_slice(), &[1, 2, 3, 4]);
3400    /// # Ok::<(), tenferro_tensor::Error>(())
3401    /// ```
3402    ///
3403    /// # Errors
3404    ///
3405    /// Returns [`crate::Error::Validation`] with
3406    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `strides`
3407    /// has a different rank, or
3408    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] /
3409    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
3410    /// reachable layout leaves `data` or overflows.
3411    pub fn from_host_slice(
3412        shape: impl Into<R::Shape>,
3413        strides: impl Into<R::Strides>,
3414        offset: isize,
3415        data: &'a [T],
3416    ) -> crate::Result<Self> {
3417        // Built here rather than through the shared helper so that the Host
3418        // marker can only ever be paired with a host slice.
3419        let buffer = TensorStorageRef::Host(data);
3420        let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
3421            .map_err(|err| tensor_layout_error("TypedTensorView::from_host_slice", err))?;
3422        Ok(Self {
3423            buffer,
3424            root: None,
3425            layout,
3426            placement: default_placement(),
3427            _representation: std::marker::PhantomData,
3428        })
3429    }
3430
3431    /// Borrow the host elements without a runtime representation check.
3432    ///
3433    /// # Examples
3434    ///
3435    /// ```rust
3436    /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3437    ///
3438    /// let data = [1_i32, 2];
3439    /// let view: TypedTensorView<'_, i32, DynRank, Host> =
3440    ///     TypedTensorView::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &data)?;
3441    /// assert_eq!(view.as_host_slice(), &[1, 2]);
3442    /// # Ok::<(), tenferro_tensor::Error>(())
3443    /// ```
3444    ///
3445    /// # Panics
3446    ///
3447    /// Panics only if a `Host`-marked view was built from non-host storage,
3448    /// which no constructor in this crate does.
3449    pub fn as_host_slice(&self) -> &'a [T] {
3450        match &self.buffer {
3451            TensorStorageRef::Host(data) => data,
3452            // INVARIANT: `Host`-marked views are constructed only by
3453            // `from_host_slice` and by `TypedTensor<_, _, Host>::as_view`.
3454            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3455                unreachable!("a Host-marked view always borrows host storage")
3456            }
3457        }
3458    }
3459}
3460
3461impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3462    /// Erase a borrowed view's rank and dtype for session dispatch without
3463    /// allocating tensor storage or promoting it into an allocation group.
3464    /// Common ranks use the existing inline shape and stride metadata.
3465    ///
3466    /// # Examples
3467    ///
3468    /// ```rust
3469    /// use tenferro_tensor::{Rank, TypedTensorView};
3470    /// let data = [1.0_f64, 2.0];
3471    /// let view = TypedTensorView::<_, Rank<1>>::from_slice_ranked([2], [1], 0, &data)?;
3472    /// let read = view.into_tensor_read()?;
3473    /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
3474    /// # Ok::<(), tenferro_tensor::Error>(())
3475    /// ```
3476    /// # Errors
3477    /// Returns [`crate::Error::Validation`] with
3478    /// [`ValidationError::IntegerOverflow`] for unrepresentable metadata or
3479    /// [`ValidationError::ViewOutOfBounds`] if the layout leaves its allocation.
3480    pub fn into_tensor_read(self) -> crate::Result<TensorRead<'a>>
3481    where
3482        T: TensorScalar,
3483    {
3484        let layout = TensorLayout::<DynRank>::from_parts(
3485            shape_vec(self.layout.shape()),
3486            stride_vec(self.layout.strides()),
3487            self.layout.offset(),
3488            self.buffer.len(),
3489        )
3490        .map_err(|err| tensor_layout_error("TypedTensorView::into_tensor_read", err))?;
3491        let view = TypedTensorView {
3492            buffer: self.buffer,
3493            root: self.root.map(GroupReadView::into_dyn),
3494            layout,
3495            placement: self.placement,
3496            _representation: std::marker::PhantomData,
3497        };
3498        Ok(TensorRead::from_view(T::tensor_view(view)))
3499    }
3500
3501    /// Return the logical shape.
3502    ///
3503    /// # Examples
3504    ///
3505    /// ```rust
3506    /// use tenferro_tensor::TypedTensorView;
3507    ///
3508    /// let data = [0_i32; 2];
3509    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3510    /// assert_eq!(view.shape(), &[2]);
3511    /// # Ok::<(), tenferro_tensor::Error>(())
3512    /// ```
3513    pub fn shape(&self) -> &[usize] {
3514        self.layout.shape()
3515    }
3516
3517    /// Return the logical rank carried by this view.
3518    ///
3519    /// # Examples
3520    ///
3521    /// ```
3522    /// use tenferro_tensor::TypedTensorView;
3523    ///
3524    /// let data = [0_i32; 6];
3525    /// let view = TypedTensorView::from_slice(vec![2, 3], vec![1, 2], 0, &data)?;
3526    /// assert_eq!(view.rank(), 2);
3527    /// # Ok::<(), tenferro_tensor::Error>(())
3528    /// ```
3529    pub fn rank(&self) -> usize {
3530        self.shape().len()
3531    }
3532
3533    /// Return strides in element units.
3534    ///
3535    /// # Examples
3536    ///
3537    /// ```rust
3538    /// use tenferro_tensor::TypedTensorView;
3539    ///
3540    /// let data = [0_i32; 2];
3541    /// let view = TypedTensorView::from_slice(vec![2], vec![-1], 1, &data)?;
3542    /// assert_eq!(view.strides(), &[-1]);
3543    /// # Ok::<(), tenferro_tensor::Error>(())
3544    /// ```
3545    pub fn strides(&self) -> &[isize] {
3546        self.layout.strides()
3547    }
3548
3549    /// Return the physical element offset.
3550    ///
3551    /// # Examples
3552    ///
3553    /// ```rust
3554    /// use tenferro_tensor::TypedTensorView;
3555    ///
3556    /// let data = [1_i32, 2];
3557    /// let view = TypedTensorView::from_slice(vec![1], vec![1], 1, &data)?;
3558    /// assert_eq!(view.offset(), 1);
3559    /// # Ok::<(), tenferro_tensor::Error>(())
3560    /// ```
3561    pub fn offset(&self) -> isize {
3562        self.layout.offset()
3563    }
3564
3565    /// Return the borrowed host storage backing this view.
3566    ///
3567    /// This exposes the entire backing host allocation, not just the logical
3568    /// slice covered by this view. Use [`TypedTensorView::as_slice`] when the
3569    /// caller needs the contiguous logical region instead.
3570    ///
3571    /// # Examples
3572    ///
3573    /// ```rust
3574    /// use tenferro_tensor::TypedTensorView;
3575    ///
3576    /// let data = [1_i32, 2];
3577    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3578    /// assert_eq!(view.host_storage()?, &[1, 2]);
3579    /// # Ok::<(), tenferro_tensor::Error>(())
3580    /// ```
3581    ///
3582    /// # Errors
3583    ///
3584    /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
3585    /// buffer; backend storage must be downloaded before host inspection.
3586    pub fn host_storage(&self) -> crate::Result<&'a [T]> {
3587        match &self.buffer {
3588            TensorStorageRef::Host(data) => Ok(data),
3589            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3590                Err(crate::Error::runtime_state(
3591                    "TypedTensorView::host_storage",
3592                    "backend buffers cannot expose host storage; download explicitly first",
3593                ))
3594            }
3595        }
3596    }
3597
3598    /// Return the number of logical elements in this view.
3599    ///
3600    /// # Examples
3601    ///
3602    /// ```rust
3603    /// use tenferro_tensor::TypedTensorView;
3604    ///
3605    /// let data = [0_i32; 6];
3606    /// let view = TypedTensorView::from_slice(vec![2, 3], vec![1, 2], 0, &data)?;
3607    /// assert_eq!(view.n_elements(), 6);
3608    /// # Ok::<(), tenferro_tensor::Error>(())
3609    /// ```
3610    pub fn n_elements(&self) -> usize {
3611        // Invariant: public view constructors validate logical element count.
3612        match checked_view_element_count(self.shape(), "TypedTensorView::n_elements") {
3613            Ok(n) => n,
3614            Err(err) => {
3615                unreachable!("TypedTensorView layout shape is validated at construction: {err}")
3616            }
3617        }
3618    }
3619
3620    /// Return layout metadata for this view.
3621    ///
3622    /// # Examples
3623    ///
3624    /// ```rust
3625    /// use tenferro_tensor::TypedTensorView;
3626    ///
3627    /// let data = [1_i32, 2];
3628    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3629    /// assert!(view.layout().is_compact_col_major().unwrap());
3630    /// # Ok::<(), tenferro_tensor::Error>(())
3631    /// ```
3632    pub fn layout(&self) -> &TensorLayout<R> {
3633        &self.layout
3634    }
3635
3636    /// Return placement metadata for this view.
3637    ///
3638    /// # Examples
3639    ///
3640    /// ```rust
3641    /// use tenferro_tensor::{MemoryKind, TypedTensorView};
3642    ///
3643    /// let data = [1_i32];
3644    /// let view = TypedTensorView::from_slice(vec![1], vec![1], 0, &data)?;
3645    /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
3646    /// # Ok::<(), tenferro_tensor::Error>(())
3647    /// ```
3648    pub fn placement(&self) -> &Placement {
3649        &self.placement
3650    }
3651
3652    /// Return the backend allocation for backend integrations.
3653    #[doc(hidden)]
3654    pub fn backing_len(&self) -> usize {
3655        self.buffer.len()
3656    }
3657
3658    /// Return the backend allocation for backend integrations.
3659    #[doc(hidden)]
3660    pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>> {
3661        match &self.buffer {
3662            TensorStorageRef::Host(_) => None,
3663            TensorStorageRef::Backend(buffer) => Some(*buffer),
3664            TensorStorageRef::Root(_) => {
3665                self.root
3666                    .as_ref()?
3667                    .backend_buffer()
3668                    .and_then(|buffer| match buffer {
3669                        StorageBuffer::Host(_) => None,
3670                        StorageBuffer::Backend(buffer) => Some(buffer.as_ref()),
3671                    })
3672            }
3673        }
3674    }
3675
3676    /// Return the backend allocation with the view's storage lifetime.
3677    ///
3678    /// [`Self::backend_buffer`] keeps the borrow of the view itself, which is
3679    /// enough to start a provider mapping but not to carry a shared-memory
3680    /// borrow out of this call. A CPU admission point needs the latter, so this
3681    /// accessor resolves through the root the view already holds instead.
3682    #[doc(hidden)]
3683    pub fn shared_backend_storage(&self) -> Option<&'a dyn BackendStorage<T>>
3684    where
3685        T: 'static,
3686    {
3687        match &self.buffer {
3688            TensorStorageRef::Host(_) => None,
3689            TensorStorageRef::Backend(buffer) => Some(*buffer),
3690            TensorStorageRef::Root(allocation) => {
3691                let allocation = allocation
3692                    .as_any()
3693                    .downcast_ref::<crate::storage::BackendStorageAllocation<T>>()?;
3694                match allocation.buffer() {
3695                    StorageBuffer::Host(_) => None,
3696                    StorageBuffer::Backend(buffer) => Some(buffer.as_ref()),
3697                }
3698            }
3699        }
3700    }
3701
3702    /// Return the provider family for this view when it is backend-owned.
3703    #[doc(hidden)]
3704    pub fn backend_family(&self) -> Option<&'static str>
3705    where
3706        T: TensorScalar + 'static,
3707    {
3708        self.root
3709            .as_ref()
3710            .and_then(|root| {
3711                root.backend_allocation()
3712                    .map(|_| root.provider_kind().as_str())
3713            })
3714            .or_else(|| self.backend_buffer().map(|buffer| buffer.backend_family()))
3715    }
3716
3717    /// Return the shared allocation domain for this view when backend-owned.
3718    #[doc(hidden)]
3719    pub fn allocation_domain(&self) -> Option<AllocationDomainId>
3720    where
3721        T: TensorScalar + 'static,
3722    {
3723        self.root
3724            .as_ref()
3725            .and_then(|root| root.backend_identity().map(|(domain, _)| domain))
3726            .or_else(|| {
3727                self.backend_buffer()
3728                    .and_then(|buffer| buffer.allocation_domain())
3729            })
3730    }
3731
3732    /// Return the physical allocation identity for this view when backend-owned.
3733    #[doc(hidden)]
3734    pub fn allocation_id(&self) -> Option<AllocationId>
3735    where
3736        T: TensorScalar + 'static,
3737    {
3738        self.root
3739            .as_ref()
3740            .and_then(|root| root.backend_identity().map(|(_, id)| id))
3741            .or_else(|| {
3742                self.backend_buffer()
3743                    .and_then(|buffer| buffer.allocation_id())
3744            })
3745    }
3746
3747    /// Prepare this backend view for one provider-native read binding.
3748    #[doc(hidden)]
3749    pub fn prepare_device_read(
3750        &self,
3751        op: &'static str,
3752    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
3753    where
3754        T: TensorScalar + 'static,
3755    {
3756        if let Some(root) = &self.root {
3757            return root
3758                .prepare_device_read_for_layout(&self.layout)
3759                .map_err(|error| crate::Error::runtime_state_source(op, error));
3760        }
3761        let buffer = self.backend_buffer().ok_or_else(|| {
3762            crate::Error::runtime_state_source(
3763                op,
3764                crate::AccessError::Unsupported { backend: "host" },
3765            )
3766        })?;
3767        prepare_backend_access(buffer, &self.layout, op)
3768    }
3769
3770    /// Compute the physical element offset for a logical index.
3771    ///
3772    /// # Examples
3773    ///
3774    /// ```rust
3775    /// use tenferro_tensor::TypedTensorView;
3776    ///
3777    /// let data = [1_i32, 2, 3];
3778    /// let view = TypedTensorView::from_slice(vec![3], vec![-1], 2, &data)?;
3779    /// assert_eq!(view.linear_offset(&[2]), Some(0));
3780    /// # Ok::<(), tenferro_tensor::Error>(())
3781    /// ```
3782    pub fn linear_offset(&self, indices: &[usize]) -> Option<usize> {
3783        checked_view_offset(self.shape(), self.strides(), self.offset(), indices)
3784    }
3785
3786    /// Compute the physical element offset for a logical index, returning a typed error.
3787    ///
3788    /// # Examples
3789    ///
3790    /// ```rust
3791    /// use tenferro_tensor::TypedTensorView;
3792    ///
3793    /// let data = [1_i32, 2, 3];
3794    /// let view = TypedTensorView::from_slice([3], [-1], 2, &data)?;
3795    /// assert_eq!(view.layout_linear_offset(&[2])?, 0);
3796    /// # Ok::<(), tenferro_tensor::Error>(())
3797    /// ```
3798    ///
3799    /// # Errors
3800    ///
3801    /// Returns [`crate::Error::Validation`] with
3802    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
3803    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
3804    /// when an index is outside its axis extent, or
3805    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
3806    /// arithmetic overflows.
3807    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
3808        checked_view_offset_result(
3809            self.shape(),
3810            self.strides(),
3811            self.offset(),
3812            indices,
3813            "TypedTensorView::layout_linear_offset",
3814        )
3815    }
3816
3817    /// Return whether this view is compact column-major.
3818    ///
3819    /// # Examples
3820    ///
3821    /// ```rust
3822    /// use tenferro_tensor::TypedTensorView;
3823    ///
3824    /// let data = [1_i32, 2];
3825    /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3826    /// assert!(view.is_col_major_contiguous()?);
3827    /// # Ok::<(), tenferro_tensor::Error>(())
3828    /// ```
3829    ///
3830    /// # Errors
3831    ///
3832    /// Returns [`crate::Error::Validation`] with
3833    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] if compactness
3834    /// arithmetic overflows.
3835    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
3836        self.layout
3837            .is_compact_col_major()
3838            .map_err(|err| tensor_layout_error("TypedTensorView::is_col_major_contiguous", err))
3839    }
3840
3841    /// Return a compact string summary of this view's layout metadata.
3842    ///
3843    /// # Examples
3844    ///
3845    /// ```rust
3846    /// use tenferro_tensor::TypedTensorView;
3847    ///
3848    /// let data = [1_i32, 2];
3849    /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3850    /// assert!(view.layout_summary().contains("shape=[2]"));
3851    /// # Ok::<(), tenferro_tensor::Error>(())
3852    /// ```
3853    pub fn layout_summary(&self) -> String {
3854        layout_summary(self.shape(), self.strides(), self.offset())
3855    }
3856
3857    /// Assert this view is compact column-major.
3858    ///
3859    /// # Examples
3860    ///
3861    /// ```rust
3862    /// use tenferro_tensor::TypedTensorView;
3863    ///
3864    /// let data = [1_i32, 2];
3865    /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3866    /// view.assert_col_major_contiguous()?;
3867    /// # Ok::<(), tenferro_tensor::Error>(())
3868    /// ```
3869    ///
3870    /// # Errors
3871    ///
3872    /// Returns [`crate::Error::Validation`] with
3873    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
3874    /// compactness arithmetic overflows, or
3875    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
3876    /// view is not compact column-major.
3877    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
3878        assert_layout_col_major_contiguous(
3879            self.is_col_major_contiguous()?,
3880            self.shape(),
3881            self.strides(),
3882            self.offset(),
3883            "TypedTensorView::assert_col_major_contiguous",
3884        )
3885    }
3886
3887    /// Borrow one host element by logical index.
3888    ///
3889    /// Returns `None` for out-of-bounds indices and backend buffers.
3890    ///
3891    /// # Examples
3892    ///
3893    /// ```rust
3894    /// use tenferro_tensor::TypedTensorView;
3895    ///
3896    /// let data = [1_i32, 2];
3897    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3898    /// assert_eq!(view.get(&[1]), Some(&2));
3899    /// # Ok::<(), tenferro_tensor::Error>(())
3900    /// ```
3901    pub fn get(&self, indices: &[usize]) -> Option<&T> {
3902        let offset = self.linear_offset(indices)?;
3903        match &self.buffer {
3904            TensorStorageRef::Host(data) => data.get(offset),
3905            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => None,
3906        }
3907    }
3908
3909    /// Borrow the contiguous host slice covered by this view.
3910    ///
3911    /// Returns an explicit error for backend buffers and for non-contiguous
3912    /// layouts. This method never downloads or materializes backend data.
3913    ///
3914    /// # Examples
3915    ///
3916    /// ```rust
3917    /// use tenferro_tensor::TypedTensorView;
3918    ///
3919    /// let data = [1_i32, 2, 3];
3920    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 1, &data)?;
3921    /// assert_eq!(view.as_slice()?, &[2, 3]);
3922    /// # Ok::<(), tenferro_tensor::Error>(())
3923    /// ```
3924    ///
3925    /// # Errors
3926    ///
3927    /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
3928    /// buffer, [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]
3929    /// when the layout is not compact column-major,
3930    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the view
3931    /// offset is negative, or [`crate::Error::Validation`] with
3932    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] or
3933    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
3934    /// requested host range is invalid.
3935    pub fn as_slice(&self) -> crate::Result<&'a [T]> {
3936        let data = match &self.buffer {
3937            TensorStorageRef::Host(data) => data,
3938            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3939                return Err(crate::Error::runtime_state(
3940                    "TypedTensorView::as_slice",
3941                    "backend buffers cannot be inspected as host slices; download explicitly first",
3942                ))
3943            }
3944        };
3945        contiguous_layout_slice(self.layout(), data, "TypedTensorView::as_slice")
3946    }
3947
3948    /// Borrow the compact logical region through a scoped host mapping.
3949    ///
3950    /// Backend integrations must validate placement and allocation-domain ownership
3951    /// before mapping. The guard cannot escape the callback; no transfer is performed.
3952    ///
3953    /// # Errors
3954    ///
3955    /// Returns a host-access or provider-preparation error when mapping fails,
3956    /// or a validation/unsupported error for a non-contiguous or invalid layout.
3957    #[doc(hidden)]
3958    pub fn with_host_read<U>(&self, f: impl FnOnce(&[T]) -> U) -> crate::Result<U>
3959    where
3960        T: TensorScalar + 'static,
3961    {
3962        const OP: &str = "TypedTensorView::with_host_read";
3963        if !self.is_col_major_contiguous()? {
3964            return Err(crate::Error::unsupported(
3965                OP,
3966                "host guard access requires a compact descriptor",
3967            ));
3968        }
3969        if let Some(buffer) = self.backend_buffer() {
3970            let guard = buffer
3971                .map_read()
3972                .map_err(|error| crate::Error::host_access(OP, error))?;
3973            return Ok(f(contiguous_layout_slice(self.layout(), &guard, OP)?));
3974        }
3975        if let Some(root) = &self.root {
3976            let prepared = root
3977                .prepare_host_read_for_layout(self.layout())
3978                .map_err(|error| crate::Error::runtime_state_source(OP, error))?;
3979            let slice = prepared.as_slice().ok_or_else(|| {
3980                crate::Error::unsupported(OP, "host guard access requires a compact descriptor")
3981            })?;
3982            return Ok(f(slice));
3983        }
3984        Ok(f(self.as_slice()?))
3985    }
3986
3987    /// Explicitly duplicate a compact host view into a new owner.
3988    ///
3989    /// Backend views require an explicit provider canonicalization or download
3990    /// boundary; this method never transfers or materializes them implicitly.
3991    ///
3992    /// # Examples
3993    ///
3994    /// ```
3995    /// use tenferro_tensor::TypedTensorView;
3996    ///
3997    /// let data = [1_i32, 2];
3998    /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3999    /// let copy = view.duplicate()?;
4000    /// assert_eq!(copy.as_slice()?, &[1, 2]);
4001    /// # Ok::<(), tenferro_tensor::Error>(())
4002    /// ```
4003    ///
4004    /// # Errors
4005    ///
4006    /// Returns [`crate::Error::HostAccess`] or
4007    /// [`ValidationError::NonContiguousViewAsSlice`] when the view is backend
4008    /// owned or not contiguous, and [`ValidationError::InvalidArgument`] when
4009    /// the static-rank shape cannot be reconstructed.
4010    pub fn duplicate(&self) -> crate::Result<TypedTensor<T, R>>
4011    where
4012        T: Clone,
4013    {
4014        let data = self.as_slice()?.to_vec();
4015        let shape = R::shape_from_vec(shape_vec(self.shape()))
4016            .map_err(|err| tensor_layout_error("TypedTensorView::duplicate", err))?;
4017        let mut tensor = TypedTensor::from_vec_col_major(shape, data)?;
4018        tensor.set_placement(self.placement.clone())?;
4019        Ok(tensor)
4020    }
4021
4022    /// Explicitly copy a host view, including strided/offset views, to a compact owner.
4023    ///
4024    /// # Examples
4025    /// ```
4026    /// use tenferro_tensor::{Rank, TypedTensorView};
4027    /// let storage = [1, 4, 2, 5, 3, 6];
4028    /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked(
4029    ///     [2, 3], [1, 2], 0, &storage,
4030    /// )?;
4031    /// let transposed = view.transpose_view([1, 0])?;
4032    /// assert_eq!(transposed.to_col_major()?.as_slice()?, &[1, 2, 3, 4, 5, 6]);
4033    /// # Ok::<(), tenferro_tensor::Error>(())
4034    /// ```
4035    /// # Errors
4036    /// Backend-only storage returns [`crate::Error::RuntimeState`]; invalid
4037    /// layout or rank conversion returns [`crate::Error::Validation`].
4038    pub fn to_col_major(&self) -> crate::Result<TypedTensor<T, R>>
4039    where
4040        T: Clone,
4041    {
4042        let data = self.host_storage()?;
4043        let mut coordinates = shape_vec_zeros(self.shape().len());
4044        let element_count = self.n_elements();
4045        let mut copied = Vec::with_capacity(element_count);
4046        for _ in 0..element_count {
4047            let offset = self.layout_linear_offset(&coordinates)?;
4048            let value = data.get(offset).ok_or_else(|| {
4049                crate::Error::validation(
4050                    "TypedTensorView::to_col_major",
4051                    ValidationError::ViewOutOfBounds,
4052                )
4053            })?;
4054            copied.push(value.clone());
4055            for axis in 0..coordinates.len() {
4056                coordinates[axis] += 1;
4057                if coordinates[axis] < self.shape()[axis] {
4058                    break;
4059                }
4060                coordinates[axis] = 0;
4061            }
4062        }
4063        let shape = R::shape_from_vec(shape_vec(self.shape()))
4064            .map_err(|err| tensor_layout_error("TypedTensorView::to_col_major", err))?;
4065        let mut tensor = TypedTensor::from_vec_col_major(shape, copied)?;
4066        tensor.set_placement(self.placement.clone())?;
4067        Ok(tensor)
4068    }
4069
4070    /// Return a metadata-only axis permutation.
4071    ///
4072    /// # Examples
4073    ///
4074    /// ```rust
4075    /// use tenferro_tensor::{Rank, TypedTensorView};
4076    ///
4077    /// let data = [1_i32, 2, 3, 4, 5, 6];
4078    /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 3], [1, 2], 0, &data)?;
4079    /// let transposed = view.transpose_view([1, 0])?;
4080    /// assert_eq!(transposed.shape(), &[3, 2]);
4081    /// # Ok::<(), tenferro_tensor::Error>(())
4082    /// ```
4083    /// # Errors
4084    ///
4085    /// Returns [`crate::Error::Validation`] with
4086    /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
4087    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
4088    /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
4089    /// not a valid permutation of the view rank.
4090    pub fn transpose_view(&self, axes: impl AsRef<[usize]>) -> crate::Result<Self> {
4091        let layout = self
4092            .layout
4093            .transpose_view(axes)
4094            .map_err(|err| tensor_layout_error("TypedTensorView::transpose_view", err))?;
4095        Ok(Self {
4096            buffer: self.buffer.clone(),
4097            root: self.root.clone(),
4098            layout,
4099            placement: self.placement.clone(),
4100            _representation: std::marker::PhantomData,
4101        })
4102    }
4103
4104    /// Return a metadata-only slice using one [`StridedSliceSpec`] per axis.
4105    ///
4106    /// # Examples
4107    ///
4108    /// ```rust
4109    /// use tenferro_tensor::{StridedSliceSpec, TypedTensorView};
4110    ///
4111    /// let data = [1_i32, 2, 3];
4112    /// let view = TypedTensorView::from_slice(vec![3], vec![1], 0, &data)?;
4113    /// let reversed = view.slice_view(&[StridedSliceSpec::reverse()])?;
4114    /// assert_eq!(reversed.get(&[0]), Some(&3));
4115    /// # Ok::<(), tenferro_tensor::Error>(())
4116    /// ```
4117    /// # Errors
4118    ///
4119    /// Returns [`crate::Error::Validation`] with
4120    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the slice
4121    /// count differs from the view rank,
4122    /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
4123    /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
4124    /// invalid slice, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
4125    /// for slice arithmetic overflow, or
4126    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4127    /// resulting layout exceeds the backing buffer.
4128    pub fn slice_view(&self, slices: &[StridedSliceSpec]) -> crate::Result<Self> {
4129        let specs = core_slice_specs(slices, self.shape(), "TypedTensorView::slice_view")?;
4130        let layout = self
4131            .layout
4132            .slice_view(specs, self.buffer.len())
4133            .map_err(|err| tensor_layout_error("TypedTensorView::slice_view", err))?;
4134        Ok(Self {
4135            buffer: self.buffer.clone(),
4136            root: self.root.clone(),
4137            layout,
4138            placement: self.placement.clone(),
4139            _representation: std::marker::PhantomData,
4140        })
4141    }
4142
4143    /// Return a metadata-only slice along one axis.
4144    ///
4145    /// # Examples
4146    ///
4147    /// ```rust
4148    /// use tenferro_tensor::{StridedSliceSpec, TypedTensorView};
4149    ///
4150    /// let data = [1_i32, 2, 3, 4];
4151    /// let view = TypedTensorView::from_slice(vec![2, 2], vec![1, 2], 0, &data)?;
4152    /// assert_eq!(view.slice_axis_view(1, StridedSliceSpec::reverse())?.get(&[0, 0]), Some(&3));
4153    /// # Ok::<(), tenferro_tensor::Error>(())
4154    /// ```
4155    /// # Errors
4156    ///
4157    /// Returns [`crate::Error::Validation`] with
4158    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`] when `axis`
4159    /// is outside the view rank, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
4160    /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
4161    /// invalid slice, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
4162    /// for slice arithmetic overflow, or
4163    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4164    /// resulting layout exceeds the backing buffer.
4165    pub fn slice_axis_view(&self, axis: usize, slice: StridedSliceSpec) -> crate::Result<Self> {
4166        let slices = slice_axis_specs(
4167            self.shape().len(),
4168            axis,
4169            slice,
4170            "TypedTensorView::slice_axis_view",
4171        )?;
4172        self.slice_view(&slices)
4173    }
4174
4175    /// Return a metadata-only dynamic-rank reshape for contiguous column-major views.
4176    ///
4177    /// # Examples
4178    ///
4179    /// ```rust
4180    /// use tenferro_tensor::TypedTensorView;
4181    ///
4182    /// let data = [1_i32, 2, 3, 4];
4183    /// let view = TypedTensorView::from_slice(vec![2, 2], vec![1, 2], 0, &data)?;
4184    /// assert_eq!(view.reshape_view(&[4])?.shape(), &[4]);
4185    /// # Ok::<(), tenferro_tensor::Error>(())
4186    /// ```
4187    /// # Errors
4188    ///
4189    /// Returns [`crate::Error::Validation`] with
4190    /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
4191    /// the source is not compact column-major,
4192    /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
4193    /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
4194    /// records the counts) when element counts differ,
4195    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for shape
4196    /// arithmetic overflow, or
4197    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4198    /// reshaped view exceeds the backing buffer.
4199    pub fn reshape_view(
4200        &self,
4201        shape: &[usize],
4202    ) -> crate::Result<TypedTensorView<'a, T, DynRank, D>> {
4203        let layout = reshape_layout_dyn(
4204            &self.layout,
4205            shape,
4206            self.buffer.len(),
4207            "TypedTensorView::reshape_view",
4208        )?;
4209        Ok(TypedTensorView {
4210            buffer: self.buffer.clone(),
4211            root: self.root.as_ref().map(GroupReadView::clone_dyn),
4212            layout,
4213            placement: self.placement.clone(),
4214            _representation: std::marker::PhantomData,
4215        })
4216    }
4217}
4218
4219impl<'a, R: TensorRank> TypedTensorView<'a, Complex32, R> {
4220    /// Borrow this complex view as an interleaved real view without copying.
4221    ///
4222    /// The result has dynamic rank because reinterpretation prepends the
4223    /// component axis `[2, ...]`. Only `Complex32 <-> f32` is sealed in this
4224    /// API; this is representation reinterpretation, not numeric conversion.
4225    ///
4226    /// # Examples
4227    ///
4228    /// ```
4229    /// use tenferro_tensor::{Complex32, TypedTensorView};
4230    ///
4231    /// let data = [Complex32::new(1.0, 2.0)];
4232    /// let view = TypedTensorView::from_col_major(&[1], &data)?;
4233    /// let real = view.as_real_view()?;
4234    /// assert_eq!(real.shape(), &[2, 1]);
4235    /// assert_eq!(real.as_slice()?, &[1.0_f32, 2.0]);
4236    /// # Ok::<(), tenferro_tensor::Error>(())
4237    /// ```
4238    ///
4239    /// # Errors
4240    ///
4241    /// Returns an error when the view layout is not a valid sealed
4242    /// representation or when backend reinterpretation is unsupported.
4243    pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'a, f32, DynRank>> {
4244        let op = "TypedTensorView::as_real_view";
4245        validate_representation_pair(op, DType::C32, DType::F32)?;
4246        let layout = reinterpret_complex_to_real_layout(
4247            self.shape(),
4248            self.strides(),
4249            self.offset(),
4250            self.buffer.len(),
4251            op,
4252        )?;
4253        let buffer = match &self.buffer {
4254            TensorStorageRef::Host(data) => {
4255                TensorStorageRef::Host(reinterpret_host_slice::<Complex32, f32>(data, op)?)
4256            }
4257            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4258                return Err(crate::Error::unsupported(
4259                    op,
4260                    "backend representation reinterpretation is enabled by the provider phases",
4261                ))
4262            }
4263        };
4264        Ok(TypedTensorView {
4265            buffer,
4266            root: None,
4267            layout,
4268            placement: self.placement.clone(),
4269            _representation: std::marker::PhantomData,
4270        })
4271    }
4272}
4273
4274impl<'a, R: TensorRank> TypedTensorView<'a, Complex64, R> {
4275    /// Borrow this complex view as an interleaved real view without copying.
4276    ///
4277    /// The result has dynamic rank because reinterpretation prepends the
4278    /// component axis `[2, ...]`. Only `Complex64 <-> f64` is sealed in this
4279    /// API; this is representation reinterpretation, not numeric conversion.
4280    ///
4281    /// # Examples
4282    ///
4283    /// ```
4284    /// use tenferro_tensor::{Complex64, TypedTensorView};
4285    ///
4286    /// let data = [Complex64::new(1.0, 2.0)];
4287    /// let view = TypedTensorView::from_col_major(&[1], &data)?;
4288    /// let real = view.as_real_view()?;
4289    /// assert_eq!(real.shape(), &[2, 1]);
4290    /// assert_eq!(real.as_slice()?, &[1.0_f64, 2.0]);
4291    /// # Ok::<(), tenferro_tensor::Error>(())
4292    /// ```
4293    ///
4294    /// # Errors
4295    ///
4296    /// Returns an error when the view layout is not a valid sealed
4297    /// representation or when backend reinterpretation is unsupported.
4298    pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'a, f64, DynRank>> {
4299        let op = "TypedTensorView::as_real_view";
4300        validate_representation_pair(op, DType::C64, DType::F64)?;
4301        let layout = reinterpret_complex_to_real_layout(
4302            self.shape(),
4303            self.strides(),
4304            self.offset(),
4305            self.buffer.len(),
4306            op,
4307        )?;
4308        let buffer = match &self.buffer {
4309            TensorStorageRef::Host(data) => {
4310                TensorStorageRef::Host(reinterpret_host_slice::<Complex64, f64>(data, op)?)
4311            }
4312            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4313                return Err(crate::Error::unsupported(
4314                    op,
4315                    "backend representation reinterpretation is enabled by the provider phases",
4316                ))
4317            }
4318        };
4319        Ok(TypedTensorView {
4320            buffer,
4321            root: None,
4322            layout,
4323            placement: self.placement.clone(),
4324            _representation: std::marker::PhantomData,
4325        })
4326    }
4327}
4328
4329impl<'a, R: TensorRank> TypedTensorView<'a, f32, R> {
4330    /// Borrow this interleaved real view as a complex view without copying.
4331    ///
4332    /// The source must have a leading extent and stride of `2` and `1`, and
4333    /// every remaining stride plus the offset must be divisible by `2`.
4334    ///
4335    /// # Examples
4336    ///
4337    /// ```
4338    /// use tenferro_tensor::{Complex32, TypedTensorView};
4339    ///
4340    /// let data = [1.0_f32, 2.0];
4341    /// let view = TypedTensorView::from_col_major(&[2, 1], &data)?;
4342    /// let complex = view.as_complex_view()?;
4343    /// assert_eq!(complex.shape(), &[1]);
4344    /// assert_eq!(complex.as_slice()?, &[Complex32::new(1.0, 2.0)]);
4345    /// # Ok::<(), tenferro_tensor::Error>(())
4346    /// ```
4347    ///
4348    /// # Errors
4349    ///
4350    /// Returns an error when the view layout is not a valid sealed
4351    /// representation or when backend reinterpretation is unsupported.
4352    pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'a, Complex32, DynRank>> {
4353        let op = "TypedTensorView::as_complex_view";
4354        validate_representation_pair(op, DType::F32, DType::C32)?;
4355        let layout = reinterpret_real_to_complex_layout(
4356            self.shape(),
4357            self.strides(),
4358            self.offset(),
4359            self.buffer.len(),
4360            op,
4361        )?;
4362        let buffer = match &self.buffer {
4363            TensorStorageRef::Host(data) => {
4364                TensorStorageRef::Host(reinterpret_host_slice::<f32, Complex32>(data, op)?)
4365            }
4366            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4367                return Err(crate::Error::unsupported(
4368                    op,
4369                    "backend representation reinterpretation is enabled by the provider phases",
4370                ))
4371            }
4372        };
4373        Ok(TypedTensorView {
4374            buffer,
4375            root: None,
4376            layout,
4377            placement: self.placement.clone(),
4378            _representation: std::marker::PhantomData,
4379        })
4380    }
4381}
4382
4383impl<'a, R: TensorRank> TypedTensorView<'a, f64, R> {
4384    /// Borrow this interleaved real view as a complex view without copying.
4385    ///
4386    /// The source must have a leading extent and stride of `2` and `1`, and
4387    /// every remaining stride plus the offset must be divisible by `2`.
4388    ///
4389    /// # Examples
4390    ///
4391    /// ```
4392    /// use tenferro_tensor::{Complex64, TypedTensorView};
4393    ///
4394    /// let data = [1.0_f64, 2.0];
4395    /// let view = TypedTensorView::from_col_major(&[2, 1], &data)?;
4396    /// let complex = view.as_complex_view()?;
4397    /// assert_eq!(complex.shape(), &[1]);
4398    /// assert_eq!(complex.as_slice()?, &[Complex64::new(1.0, 2.0)]);
4399    /// # Ok::<(), tenferro_tensor::Error>(())
4400    /// ```
4401    ///
4402    /// # Errors
4403    ///
4404    /// Returns an error when the view layout is not a valid sealed
4405    /// representation or when backend reinterpretation is unsupported.
4406    pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'a, Complex64, DynRank>> {
4407        let op = "TypedTensorView::as_complex_view";
4408        validate_representation_pair(op, DType::F64, DType::C64)?;
4409        let layout = reinterpret_real_to_complex_layout(
4410            self.shape(),
4411            self.strides(),
4412            self.offset(),
4413            self.buffer.len(),
4414            op,
4415        )?;
4416        let buffer = match &self.buffer {
4417            TensorStorageRef::Host(data) => {
4418                TensorStorageRef::Host(reinterpret_host_slice::<f64, Complex64>(data, op)?)
4419            }
4420            TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4421                return Err(crate::Error::unsupported(
4422                    op,
4423                    "backend representation reinterpretation is enabled by the provider phases",
4424                ))
4425            }
4426        };
4427        Ok(TypedTensorView {
4428            buffer,
4429            root: None,
4430            layout,
4431            placement: self.placement.clone(),
4432            _representation: std::marker::PhantomData,
4433        })
4434    }
4435}
4436
4437/// Mutable borrowed view of typed tensor storage with arbitrary strides.
4438///
4439/// # Examples
4440///
4441/// ```rust
4442/// use tenferro_tensor::TypedTensorViewMut;
4443///
4444/// let mut data = [1_i32, 2, 3];
4445/// let mut view = TypedTensorViewMut::from_slice(vec![3], vec![-1], 2, &mut data)?;
4446/// *view.get_mut(&[2]).unwrap() = 10;
4447/// assert_eq!(view.as_read_only().get(&[2]), Some(&10));
4448/// # Ok::<(), tenferro_tensor::Error>(())
4449/// ```
4450/// Exclusive typed view of one tensor representation.
4451///
4452/// As with [`TypedTensorView`], the buffer stays concrete so the view keeps its
4453/// lifetime covariance, and `D` marks which representation produced the view.
4454pub struct TypedTensorViewMut<'a, T, R: TensorRank = DynRank, D: Representation = Dynamic> {
4455    buffer: TensorStorageRefMut<'a, T>,
4456    root: Option<GroupWriteView<'a, T, R>>,
4457    layout: TensorLayout<R>,
4458    placement: Placement,
4459    _representation: std::marker::PhantomData<D>,
4460}
4461
4462impl<'a, T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensorViewMut<'a, T, R, D> {
4463    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4464        formatter
4465            .debug_struct("TypedTensorViewMut")
4466            .field("shape", &self.layout.shape())
4467            .field("placement", &self.placement)
4468            .finish_non_exhaustive()
4469    }
4470}
4471
4472/// Pair of mutable tensor views returned by disjoint multi-slice operations.
4473///
4474/// # Examples
4475///
4476/// ```rust
4477/// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut, TypedTensorViewMutSplit};
4478///
4479/// let mut data = [1_i32, 2, 3, 4];
4480/// let mut view = TypedTensorViewMut::from_slice(vec![4], vec![1], 0, &mut data)?;
4481/// let pair: TypedTensorViewMutSplit<'_, i32> = view
4482///     .try_multi_slice_mut(
4483///         &[StridedSliceSpec::new(0, Some(2), 1)],
4484///         &[StridedSliceSpec::new(2, Some(4), 1)],
4485///     )
4486///     ?
4487///     .unwrap();
4488/// assert_eq!(pair.0.shape(), &[2]);
4489/// assert_eq!(pair.1.shape(), &[2]);
4490/// # Ok::<(), tenferro_tensor::Error>(())
4491/// ```
4492pub type TypedTensorViewMutSplit<'a, T, R = DynRank> =
4493    (TypedTensorViewMut<'a, T, R>, TypedTensorViewMut<'a, T, R>);
4494
4495impl<'a, T: 'static> TypedTensorViewMut<'a, T, DynRank> {
4496    /// Create a mutable dynamic-rank view over compact column-major host data.
4497    ///
4498    /// # Examples
4499    ///
4500    /// ```rust
4501    /// use tenferro_tensor::TypedTensorViewMut;
4502    ///
4503    /// let mut data = [1_i32, 2, 3, 4];
4504    /// let view = TypedTensorViewMut::from_col_major(&[2, 2], &mut data)?;
4505    /// assert_eq!(view.strides(), &[1, 2]);
4506    /// # Ok::<(), tenferro_tensor::Error>(())
4507    /// ```
4508    /// # Errors
4509    ///
4510    /// Returns [`crate::Error::Validation`] with
4511    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
4512    /// shape or offset arithmetic overflow, or
4513    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4514    /// compact shape reaches beyond `data`.
4515    pub fn from_col_major(shape: &[usize], data: &'a mut [T]) -> crate::Result<Self> {
4516        let layout = TensorLayout::<DynRank>::compact(shape_vec(shape))
4517            .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_col_major", err))?;
4518        Self::from_buffer_ref_mut(
4519            shape_vec(layout.shape()),
4520            stride_vec(layout.strides()),
4521            layout.offset(),
4522            TensorStorageRefMut::Host(data),
4523            default_placement(),
4524            "TypedTensorViewMut::from_col_major",
4525        )
4526    }
4527
4528    /// Create a mutable host view from explicit layout metadata.
4529    ///
4530    /// Layouts where distinct logical elements can alias the same physical
4531    /// element are rejected.
4532    ///
4533    /// # Examples
4534    ///
4535    /// ```rust
4536    /// use tenferro_tensor::TypedTensorViewMut;
4537    ///
4538    /// let mut data = [1_i32, 2];
4539    /// assert!(TypedTensorViewMut::from_slice(vec![2], vec![0], 0, &mut data).is_err());
4540    /// ```
4541    /// # Errors
4542    ///
4543    /// Returns [`crate::Error::Validation`] with
4544    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `shape` and
4545    /// `strides` have different ranks,
4546    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4547    /// layout reaches beyond `data`,
4548    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
4549    /// logical elements alias, or
4550    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
4551    /// arithmetic overflow.
4552    pub fn from_slice(
4553        shape: impl AsRef<[usize]>,
4554        strides: impl AsRef<[isize]>,
4555        offset: isize,
4556        data: &'a mut [T],
4557    ) -> crate::Result<Self> {
4558        Self::from_buffer_ref_mut(
4559            shape_vec(shape.as_ref()),
4560            stride_vec(strides.as_ref()),
4561            offset,
4562            TensorStorageRefMut::Host(data),
4563            default_placement(),
4564            "TypedTensorViewMut::from_slice",
4565        )
4566    }
4567}
4568
4569impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4570    /// Create a rank-generic mutable host view from explicit layout metadata.
4571    ///
4572    /// # Examples
4573    ///
4574    /// ```rust
4575    /// use tenferro_tensor::{Rank, TypedTensorViewMut};
4576    ///
4577    /// let mut data = [1_i32, 2, 3, 4];
4578    /// let view = TypedTensorViewMut::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &mut data)?;
4579    /// assert_eq!(view.shape(), &[2, 2]);
4580    /// # Ok::<(), tenferro_tensor::Error>(())
4581    /// ```
4582    /// # Errors
4583    ///
4584    /// Returns [`crate::Error::Validation`] with
4585    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the typed
4586    /// rank does not match `shape` or `strides`,
4587    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4588    /// layout reaches beyond `data`,
4589    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
4590    /// logical elements alias, or
4591    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
4592    /// arithmetic overflow.
4593    pub fn from_slice_ranked(
4594        shape: impl Into<R::Shape>,
4595        strides: impl Into<R::Strides>,
4596        offset: isize,
4597        data: &'a mut [T],
4598    ) -> crate::Result<Self> {
4599        Self::from_buffer_ref_mut(
4600            shape,
4601            strides,
4602            offset,
4603            TensorStorageRefMut::Host(data),
4604            default_placement(),
4605            "TypedTensorViewMut::from_slice_ranked",
4606        )
4607    }
4608}
4609
4610impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4611    fn from_buffer_ref_mut(
4612        shape: impl Into<R::Shape>,
4613        strides: impl Into<R::Strides>,
4614        offset: isize,
4615        buffer: TensorStorageRefMut<'a, T>,
4616        placement: Placement,
4617        op: &'static str,
4618    ) -> crate::Result<Self> {
4619        let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
4620            .map_err(|err| tensor_layout_error(op, err))?;
4621        layout
4622            .validate_mutable_no_overlap()
4623            .map_err(|err| tensor_layout_error(op, err))?;
4624        Ok(Self {
4625            buffer,
4626            root: None,
4627            layout,
4628            placement,
4629            _representation: std::marker::PhantomData,
4630        })
4631    }
4632}
4633
4634impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Dynamic> {
4635    /// Whether this mutable view writes host-addressed memory.
4636    ///
4637    /// The one host/device answer for a write target, decided by the borrowed
4638    /// payload and never by [`Placement::memory_kind`]; it is the same answer
4639    /// [`Self::try_mut_host`] acts on.
4640    ///
4641    /// # Examples
4642    ///
4643    /// ```rust
4644    /// use tenferro_tensor::TypedTensor;
4645    ///
4646    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
4647    /// assert!(tensor.as_view_mut().is_host_memory());
4648    /// # Ok::<(), tenferro_tensor::Error>(())
4649    /// ```
4650    pub fn is_host_memory(&self) -> bool {
4651        matches!(self.buffer, TensorStorageRefMut::Host(_))
4652    }
4653
4654    /// Checked narrowing of a mutable view to the host representation.
4655    ///
4656    /// The mutable counterpart of [`TypedTensorView::try_host`]: it succeeds
4657    /// exactly when the view writes host elements (a plain host owner, a host
4658    /// slice, or a CPU-resident allocation group) and keeps the layout and the
4659    /// placement label. A consumer that receives the result writes it through
4660    /// [`TypedTensorViewMut::as_host_slice_mut`] without a further check.
4661    ///
4662    /// # Examples
4663    ///
4664    /// ```rust
4665    /// use tenferro_tensor::TypedTensor;
4666    ///
4667    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
4668    /// let mut host = tensor.as_view_mut().try_mut_host("example")?;
4669    /// host.as_host_slice_mut()[0] = 5.0;
4670    /// assert_eq!(tensor.as_slice()?, &[5.0, 2.0]);
4671    /// # Ok::<(), tenferro_tensor::Error>(())
4672    /// ```
4673    ///
4674    /// # Errors
4675    ///
4676    /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
4677    /// borrows backend (device) storage; download the tensor to host first.
4678    pub fn try_mut_host(
4679        self,
4680        op: &'static str,
4681    ) -> crate::Result<TypedTensorViewMut<'a, T, R, Host>> {
4682        match self.buffer {
4683            TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
4684                buffer: TensorStorageRefMut::Host(data),
4685                // A host-marked view carries no retained region: the exclusive
4686                // borrow of `data` is what keeps the owner alive for `'a`, and
4687                // the group child has no drop-time obligation.
4688                root: None,
4689                layout: self.layout,
4690                placement: self.placement,
4691                _representation: std::marker::PhantomData,
4692            }),
4693            TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4694                op,
4695                "CPU backend received a backend buffer; download the tensor to host before CPU execution",
4696            )),
4697        }
4698    }
4699}
4700
4701impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Host> {
4702    /// Widen a host-marked mutable view to the runtime union without copying.
4703    ///
4704    /// # Examples
4705    ///
4706    /// ```rust
4707    /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4708    ///
4709    /// let mut data = [1_i32, 2];
4710    /// let host: TypedTensorViewMut<'_, i32, DynRank, Host> =
4711    ///     TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4712    /// let dynamic = host.into_dynamic();
4713    /// assert_eq!(dynamic.as_read_only().host_storage()?, &[1, 2]);
4714    /// # Ok::<(), tenferro_tensor::Error>(())
4715    /// ```
4716    pub fn into_dynamic(self) -> TypedTensorViewMut<'a, T, R, Dynamic> {
4717        TypedTensorViewMut {
4718            buffer: self.buffer,
4719            root: self.root,
4720            layout: self.layout,
4721            placement: self.placement,
4722            _representation: std::marker::PhantomData,
4723        }
4724    }
4725}
4726
4727impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Host> {
4728    /// Create a representation-marked mutable view over an explicit host layout.
4729    ///
4730    /// # Examples
4731    ///
4732    /// ```rust
4733    /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4734    ///
4735    /// let mut data = [1_i32, 2];
4736    /// let mut view: TypedTensorViewMut<'_, i32, DynRank, Host> =
4737    ///     TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4738    /// view.slice_view(&[tenferro_tensor::StridedSliceSpec::all()])?;
4739    /// # Ok::<(), tenferro_tensor::Error>(())
4740    /// ```
4741    ///
4742    /// # Errors
4743    ///
4744    /// Returns [`crate::Error::Validation`] with
4745    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `strides`
4746    /// has a different rank, [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`]
4747    /// when logical elements alias, or
4748    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] /
4749    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
4750    /// reachable layout leaves `data` or overflows.
4751    pub fn from_host_slice(
4752        shape: impl Into<R::Shape>,
4753        strides: impl Into<R::Strides>,
4754        offset: isize,
4755        data: &'a mut [T],
4756    ) -> crate::Result<Self> {
4757        // Built here rather than through the shared helper so that the Host
4758        // marker can only ever be paired with a host slice.
4759        let buffer = TensorStorageRefMut::Host(data);
4760        let layout =
4761            TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
4762                .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_host_slice", err))?;
4763        layout
4764            .validate_mutable_no_overlap()
4765            .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_host_slice", err))?;
4766        Ok(Self {
4767            buffer,
4768            root: None,
4769            layout,
4770            placement: default_placement(),
4771            _representation: std::marker::PhantomData,
4772        })
4773    }
4774
4775    /// Exclusively borrow the host elements without a runtime check.
4776    ///
4777    /// # Examples
4778    ///
4779    /// ```
4780    /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4781    ///
4782    /// let mut data = [1_i32, 2];
4783    /// let mut view: TypedTensorViewMut<'_, i32, DynRank, Host> =
4784    ///     TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4785    /// view.as_host_slice_mut()[0] = 5;
4786    /// assert_eq!(data, [5, 2]);
4787    /// # Ok::<(), tenferro_tensor::Error>(())
4788    /// ```
4789    ///
4790    /// # Panics
4791    ///
4792    /// Panics only if a `Host`-marked view was built from non-host storage,
4793    /// which no constructor in this crate does.
4794    pub fn as_host_slice_mut(&mut self) -> &mut [T] {
4795        match &mut self.buffer {
4796            TensorStorageRefMut::Host(data) => data,
4797            // INVARIANT: `Host`-marked views are constructed only by
4798            // `from_host_slice` and by `TypedTensor<_, _, Host>::as_view_mut`.
4799            TensorStorageRefMut::Backend(_) => {
4800                unreachable!("a Host-marked view always borrows host storage")
4801            }
4802        }
4803    }
4804}
4805
4806impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4807    /// Return the logical shape.
4808    ///
4809    /// # Examples
4810    ///
4811    /// ```rust
4812    /// use tenferro_tensor::TypedTensorViewMut;
4813    ///
4814    /// let mut data = [0_i32; 2];
4815    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4816    /// assert_eq!(view.shape(), &[2]);
4817    /// # Ok::<(), tenferro_tensor::Error>(())
4818    /// ```
4819    pub fn shape(&self) -> &[usize] {
4820        self.layout.shape()
4821    }
4822
4823    /// Return the logical rank carried by this mutable view.
4824    ///
4825    /// # Examples
4826    ///
4827    /// ```
4828    /// use tenferro_tensor::TypedTensorViewMut;
4829    ///
4830    /// let mut data = [0_i32; 6];
4831    /// let view = TypedTensorViewMut::from_slice(vec![2, 3], vec![1, 2], 0, &mut data)?;
4832    /// assert_eq!(view.rank(), 2);
4833    /// # Ok::<(), tenferro_tensor::Error>(())
4834    /// ```
4835    pub fn rank(&self) -> usize {
4836        self.shape().len()
4837    }
4838
4839    /// Return strides in element units.
4840    ///
4841    /// # Examples
4842    ///
4843    /// ```rust
4844    /// use tenferro_tensor::TypedTensorViewMut;
4845    ///
4846    /// let mut data = [0_i32; 2];
4847    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![-1], 1, &mut data)?;
4848    /// assert_eq!(view.strides(), &[-1]);
4849    /// # Ok::<(), tenferro_tensor::Error>(())
4850    /// ```
4851    pub fn strides(&self) -> &[isize] {
4852        self.layout.strides()
4853    }
4854
4855    /// Return the physical element offset.
4856    ///
4857    /// # Examples
4858    ///
4859    /// ```rust
4860    /// use tenferro_tensor::TypedTensorViewMut;
4861    ///
4862    /// let mut data = [1_i32, 2];
4863    /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 1, &mut data)?;
4864    /// assert_eq!(view.offset(), 1);
4865    /// # Ok::<(), tenferro_tensor::Error>(())
4866    /// ```
4867    pub fn offset(&self) -> isize {
4868        self.layout.offset()
4869    }
4870
4871    /// Return the borrowed host storage backing this view.
4872    ///
4873    /// This exposes the entire backing host allocation, not just the logical
4874    /// slice covered by this view. Use [`TypedTensorViewMut::as_read_only`]
4875    /// with [`TypedTensorView::as_slice`] when the caller needs the contiguous
4876    /// logical region instead.
4877    ///
4878    /// # Examples
4879    ///
4880    /// ```rust
4881    /// use tenferro_tensor::TypedTensorViewMut;
4882    ///
4883    /// let mut data = [1_i32, 2];
4884    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4885    /// assert_eq!(view.host_storage()?, &[1, 2]);
4886    /// # Ok::<(), tenferro_tensor::Error>(())
4887    /// ```
4888    /// # Errors
4889    ///
4890    /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
4891    /// buffer; backend storage must be downloaded before host inspection.
4892    pub fn host_storage(&self) -> crate::Result<&[T]> {
4893        match &self.buffer {
4894            TensorStorageRefMut::Host(data) => Ok(data),
4895            TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4896                "TypedTensorViewMut::host_storage",
4897                "backend buffers cannot expose host storage; download explicitly first",
4898            )),
4899        }
4900    }
4901
4902    /// Mutably borrow the host storage backing this view.
4903    ///
4904    /// This exposes the entire backing host allocation, not just the logical
4905    /// slice covered by this view. Prefer scalar element accessors when mutating
4906    /// a logical region; tensor-sized copies belong to an active backend.
4907    ///
4908    /// # Examples
4909    ///
4910    /// ```rust
4911    /// use tenferro_tensor::TypedTensorViewMut;
4912    ///
4913    /// let mut data = [1_i32, 2];
4914    /// let mut view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4915    /// view.host_storage_mut()?[0] = 3;
4916    /// assert_eq!(view.get(&[0]), Some(&3));
4917    /// # Ok::<(), tenferro_tensor::Error>(())
4918    /// ```
4919    /// # Errors
4920    ///
4921    /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
4922    /// buffer; backend storage must be downloaded before host inspection.
4923    pub fn host_storage_mut(&mut self) -> crate::Result<&mut [T]> {
4924        match &mut self.buffer {
4925            TensorStorageRefMut::Host(data) => Ok(data),
4926            TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4927                "TypedTensorViewMut::host_storage_mut",
4928                "backend buffers cannot expose mutable host storage; download explicitly first",
4929            )),
4930        }
4931    }
4932
4933    /// Return the number of logical elements in this view.
4934    ///
4935    /// # Examples
4936    ///
4937    /// ```rust
4938    /// use tenferro_tensor::TypedTensorViewMut;
4939    ///
4940    /// let mut data = [0_i32; 6];
4941    /// let view = TypedTensorViewMut::from_slice(vec![2, 3], vec![1, 2], 0, &mut data)?;
4942    /// assert_eq!(view.n_elements(), 6);
4943    /// # Ok::<(), tenferro_tensor::Error>(())
4944    /// ```
4945    pub fn n_elements(&self) -> usize {
4946        // Invariant: public mutable view constructors validate logical element count.
4947        match checked_view_element_count(self.shape(), "TypedTensorViewMut::n_elements") {
4948            Ok(n) => n,
4949            Err(err) => {
4950                unreachable!("TypedTensorViewMut layout shape is validated at construction: {err}")
4951            }
4952        }
4953    }
4954
4955    /// Return layout metadata for this view.
4956    ///
4957    /// # Examples
4958    ///
4959    /// ```rust
4960    /// use tenferro_tensor::TypedTensorViewMut;
4961    ///
4962    /// let mut data = [1_i32, 2];
4963    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4964    /// assert!(view.layout().is_compact_col_major().unwrap());
4965    /// # Ok::<(), tenferro_tensor::Error>(())
4966    /// ```
4967    pub fn layout(&self) -> &TensorLayout<R> {
4968        &self.layout
4969    }
4970
4971    /// Return placement metadata for this view.
4972    ///
4973    /// # Examples
4974    ///
4975    /// ```rust
4976    /// use tenferro_tensor::{MemoryKind, TypedTensorViewMut};
4977    ///
4978    /// let mut data = [1_i32];
4979    /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
4980    /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
4981    /// # Ok::<(), tenferro_tensor::Error>(())
4982    /// ```
4983    pub fn placement(&self) -> &Placement {
4984        &self.placement
4985    }
4986
4987    /// Return the backend allocation for backend integrations.
4988    #[doc(hidden)]
4989    pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>> {
4990        match &self.buffer {
4991            TensorStorageRefMut::Host(_) => None,
4992            TensorStorageRefMut::Backend(buffer) => Some(&**buffer),
4993        }
4994    }
4995
4996    /// Prepare this backend view for one provider-native write binding.
4997    #[doc(hidden)]
4998    pub fn prepare_device_write(
4999        &mut self,
5000        op: &'static str,
5001    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
5002    where
5003        T: TensorScalar + 'static,
5004    {
5005        let layout = self.layout.clone();
5006        if self.root.is_none() {
5007            let buffer = self.backend_buffer().ok_or_else(|| {
5008                crate::Error::runtime_state_source(
5009                    op,
5010                    crate::AccessError::Unsupported { backend: "host" },
5011                )
5012            })?;
5013            return prepare_backend_access(buffer, &self.layout, op);
5014        }
5015        let root = self
5016            .root
5017            .as_mut()
5018            .ok_or_else(|| crate::Error::runtime_state(op, "expected a root-backed tensor view"))?;
5019        root.prepare_device_write_for_layout(&layout)
5020            .map_err(|error| crate::Error::runtime_state_source(op, error))
5021    }
5022
5023    /// Compute the physical element offset for a logical index.
5024    ///
5025    /// # Examples
5026    ///
5027    /// ```rust
5028    /// use tenferro_tensor::TypedTensorViewMut;
5029    ///
5030    /// let mut data = [1_i32, 2, 3];
5031    /// let view = TypedTensorViewMut::from_slice(vec![3], vec![-1], 2, &mut data)?;
5032    /// assert_eq!(view.linear_offset(&[2]), Some(0));
5033    /// # Ok::<(), tenferro_tensor::Error>(())
5034    /// ```
5035    pub fn linear_offset(&self, indices: &[usize]) -> Option<usize> {
5036        checked_view_offset(self.shape(), self.strides(), self.offset(), indices)
5037    }
5038
5039    /// Compute the physical element offset for a logical index, returning a typed error.
5040    ///
5041    /// # Examples
5042    ///
5043    /// ```rust
5044    /// use tenferro_tensor::TypedTensorViewMut;
5045    ///
5046    /// let mut data = [1_i32, 2, 3];
5047    /// let view = TypedTensorViewMut::from_slice([3], [-1], 2, &mut data)?;
5048    /// assert_eq!(view.layout_linear_offset(&[2])?, 0);
5049    /// # Ok::<(), tenferro_tensor::Error>(())
5050    /// ```
5051    /// # Errors
5052    ///
5053    /// Returns [`crate::Error::Validation`] with
5054    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
5055    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
5056    /// when an index is outside its axis extent, or
5057    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
5058    /// arithmetic overflows.
5059    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
5060        checked_view_offset_result(
5061            self.shape(),
5062            self.strides(),
5063            self.offset(),
5064            indices,
5065            "TypedTensorViewMut::layout_linear_offset",
5066        )
5067    }
5068
5069    /// Return whether this mutable view is compact column-major.
5070    ///
5071    /// # Examples
5072    ///
5073    /// ```rust
5074    /// use tenferro_tensor::TypedTensorViewMut;
5075    ///
5076    /// let mut data = [1_i32, 2];
5077    /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5078    /// assert!(view.is_col_major_contiguous()?);
5079    /// # Ok::<(), tenferro_tensor::Error>(())
5080    /// ```
5081    /// # Errors
5082    ///
5083    /// Returns [`crate::Error::Validation`] with
5084    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
5085    /// compactness arithmetic overflows.
5086    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
5087        self.layout
5088            .is_compact_col_major()
5089            .map_err(|err| tensor_layout_error("TypedTensorViewMut::is_col_major_contiguous", err))
5090    }
5091
5092    /// Return a compact string summary of this mutable view's layout metadata.
5093    ///
5094    /// # Examples
5095    ///
5096    /// ```rust
5097    /// use tenferro_tensor::TypedTensorViewMut;
5098    ///
5099    /// let mut data = [1_i32, 2];
5100    /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5101    /// assert!(view.layout_summary().contains("shape=[2]"));
5102    /// # Ok::<(), tenferro_tensor::Error>(())
5103    /// ```
5104    pub fn layout_summary(&self) -> String {
5105        layout_summary(self.shape(), self.strides(), self.offset())
5106    }
5107
5108    /// Assert this mutable view is compact column-major.
5109    ///
5110    /// # Examples
5111    ///
5112    /// ```rust
5113    /// use tenferro_tensor::TypedTensorViewMut;
5114    ///
5115    /// let mut data = [1_i32, 2];
5116    /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5117    /// view.assert_col_major_contiguous()?;
5118    /// # Ok::<(), tenferro_tensor::Error>(())
5119    /// ```
5120    /// # Errors
5121    ///
5122    /// Returns [`crate::Error::Validation`] with
5123    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
5124    /// compactness arithmetic overflows, or
5125    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
5126    /// view is not compact column-major.
5127    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
5128        assert_layout_col_major_contiguous(
5129            self.is_col_major_contiguous()?,
5130            self.shape(),
5131            self.strides(),
5132            self.offset(),
5133            "TypedTensorViewMut::assert_col_major_contiguous",
5134        )
5135    }
5136
5137    /// Borrow one host element by logical index.
5138    ///
5139    /// # Examples
5140    ///
5141    /// ```rust
5142    /// use tenferro_tensor::TypedTensorViewMut;
5143    ///
5144    /// let mut data = [1_i32, 2];
5145    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5146    /// assert_eq!(view.get(&[1]), Some(&2));
5147    /// # Ok::<(), tenferro_tensor::Error>(())
5148    /// ```
5149    pub fn get(&self, indices: &[usize]) -> Option<&T> {
5150        let offset = self.linear_offset(indices)?;
5151        match &self.buffer {
5152            TensorStorageRefMut::Host(data) => data.get(offset),
5153            TensorStorageRefMut::Backend(_) => None,
5154        }
5155    }
5156
5157    /// Mutably borrow one host element by logical index.
5158    ///
5159    /// # Examples
5160    ///
5161    /// ```rust
5162    /// use tenferro_tensor::TypedTensorViewMut;
5163    ///
5164    /// let mut data = [1_i32, 2];
5165    /// let mut view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5166    /// *view.get_mut(&[1]).unwrap() = 20;
5167    /// assert_eq!(view.get(&[1]), Some(&20));
5168    /// # Ok::<(), tenferro_tensor::Error>(())
5169    /// ```
5170    pub fn get_mut(&mut self, indices: &[usize]) -> Option<&mut T> {
5171        let offset = self.linear_offset(indices)?;
5172        match &mut self.buffer {
5173            TensorStorageRefMut::Host(data) => data.get_mut(offset),
5174            TensorStorageRefMut::Backend(_) => None,
5175        }
5176    }
5177
5178    /// Borrow this mutable view as a read-only view.
5179    ///
5180    /// # Examples
5181    ///
5182    /// ```rust
5183    /// use tenferro_tensor::TypedTensorViewMut;
5184    ///
5185    /// let mut data = [1_i32];
5186    /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
5187    /// assert_eq!(view.as_read_only().get(&[0]), Some(&1));
5188    /// # Ok::<(), tenferro_tensor::Error>(())
5189    /// ```
5190    /// Explicitly duplicate the compact host data visible through this
5191    /// mutable view into a new owner.
5192    ///
5193    /// # Errors
5194    ///
5195    /// Returns [`crate::Error::HostAccess`] or
5196    /// [`ValidationError::NonContiguousViewAsSlice`] when the view is backend
5197    /// owned or not contiguous, and [`ValidationError::InvalidArgument`] when
5198    /// the static-rank shape cannot be reconstructed.
5199    ///
5200    /// # Examples
5201    ///
5202    /// ```
5203    /// use tenferro_tensor::TypedTensorViewMut;
5204    ///
5205    /// let mut data = [1_i32, 2];
5206    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5207    /// let copy = view.duplicate()?;
5208    /// assert_eq!(copy.as_slice()?, &[1, 2]);
5209    /// # Ok::<(), tenferro_tensor::Error>(())
5210    /// ```
5211    pub fn duplicate(&self) -> crate::Result<TypedTensor<T, R>>
5212    where
5213        T: Clone,
5214    {
5215        self.as_read_only().duplicate()
5216    }
5217
5218    /// Explicitly copy this host view to a compact column-major owner.
5219    ///
5220    /// # Examples
5221    /// ```
5222    /// use tenferro_tensor::TypedTensorViewMut;
5223    /// let mut values = ["a".to_owned(), "b".to_owned()];
5224    /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut values)?;
5225    /// assert_eq!(view.to_col_major()?.as_slice()?, &["a", "b"]);
5226    /// # Ok::<(), tenferro_tensor::Error>(())
5227    /// ```
5228    /// # Errors
5229    /// Backend-only storage returns [`crate::Error::RuntimeState`]; invalid
5230    /// layout or rank conversion returns [`crate::Error::Validation`].
5231    pub fn to_col_major(&self) -> crate::Result<TypedTensor<T, R>>
5232    where
5233        T: Clone,
5234    {
5235        self.as_read_only().to_col_major()
5236    }
5237
5238    /// Borrow this mutable view as a read-only typed view over the same storage.
5239    ///
5240    /// # Examples
5241    ///
5242    /// ```
5243    /// use tenferro_tensor::TypedTensorViewMut;
5244    ///
5245    /// let mut data = [1_i32, 2];
5246    /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5247    /// assert_eq!(view.as_read_only().as_slice()?, &[1, 2]);
5248    /// # Ok::<(), tenferro_tensor::Error>(())
5249    /// ```
5250    pub fn as_read_only(&self) -> TypedTensorView<'_, T, R, D> {
5251        let buffer = match &self.buffer {
5252            TensorStorageRefMut::Host(data) => TensorStorageRef::Host(data),
5253            TensorStorageRefMut::Backend(buffer) => TensorStorageRef::Backend(&**buffer),
5254        };
5255        TypedTensorView {
5256            buffer,
5257            root: None,
5258            layout: self.layout.clone(),
5259            placement: self.placement.clone(),
5260            _representation: std::marker::PhantomData,
5261        }
5262    }
5263
5264    /// Convert this mutable view into a read-only view.
5265    ///
5266    /// # Examples
5267    ///
5268    /// ```rust
5269    /// use tenferro_tensor::TypedTensorViewMut;
5270    ///
5271    /// let mut data = [1_i32];
5272    /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
5273    /// assert_eq!(view.into_read_only().get(&[0]), Some(&1));
5274    /// # Ok::<(), tenferro_tensor::Error>(())
5275    /// ```
5276    pub fn into_read_only(self) -> TypedTensorView<'a, T, R, D> {
5277        let buffer = match self.buffer {
5278            TensorStorageRefMut::Host(data) => TensorStorageRef::Host(data),
5279            TensorStorageRefMut::Backend(buffer) => TensorStorageRef::Backend(buffer),
5280        };
5281        TypedTensorView {
5282            buffer,
5283            root: None,
5284            layout: self.layout,
5285            placement: self.placement,
5286            _representation: std::marker::PhantomData,
5287        }
5288    }
5289
5290    /// Consume this mutable view and return a metadata-only axis permutation.
5291    ///
5292    /// # Examples
5293    ///
5294    /// ```rust
5295    /// use tenferro_tensor::{Rank, TypedTensorViewMut};
5296    ///
5297    /// let mut data = [1_i32, 2, 3, 4];
5298    /// let view = TypedTensorViewMut::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &mut data)?;
5299    /// let transposed = view.transpose_view([1, 0])?;
5300    /// assert_eq!(transposed.strides(), &[2, 1]);
5301    /// # Ok::<(), tenferro_tensor::Error>(())
5302    /// ```
5303    /// # Errors
5304    ///
5305    /// Returns [`crate::Error::Validation`] with
5306    /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
5307    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
5308    /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
5309    /// not a valid permutation, [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`]
5310    /// when the permutation creates aliases, or
5311    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5312    /// arithmetic overflow.
5313    pub fn transpose_view(
5314        self,
5315        axes: impl AsRef<[usize]>,
5316    ) -> crate::Result<TypedTensorViewMut<'a, T, R>> {
5317        let Self {
5318            buffer,
5319            root,
5320            layout,
5321            placement,
5322            _representation: std::marker::PhantomData,
5323        } = self;
5324        let layout = layout
5325            .transpose_view(axes)
5326            .map_err(|err| tensor_layout_error("TypedTensorViewMut::transpose_view", err))?;
5327        layout
5328            .validate_mutable_no_overlap()
5329            .map_err(|err| tensor_layout_error("TypedTensorViewMut::transpose_view", err))?;
5330        match buffer {
5331            TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5332                buffer: TensorStorageRefMut::Host(data),
5333                root,
5334                layout,
5335                placement,
5336                _representation: std::marker::PhantomData,
5337            }),
5338            TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5339                buffer: TensorStorageRefMut::Backend(buffer),
5340                root,
5341                layout,
5342                placement,
5343                _representation: std::marker::PhantomData,
5344            }),
5345        }
5346    }
5347
5348    /// Return a mutable metadata-only slice using one [`StridedSliceSpec`] per axis.
5349    ///
5350    /// # Examples
5351    ///
5352    /// ```rust
5353    /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5354    ///
5355    /// let mut data = [1_i32, 2, 3];
5356    /// let mut view = TypedTensorViewMut::from_slice(vec![3], vec![1], 0, &mut data)?;
5357    /// *view.slice_view(&[StridedSliceSpec::reverse()])?.get_mut(&[0]).unwrap() = 30;
5358    /// assert_eq!(view.get(&[2]), Some(&30));
5359    /// # Ok::<(), tenferro_tensor::Error>(())
5360    /// ```
5361    /// # Errors
5362    ///
5363    /// Returns [`crate::Error::Validation`] with
5364    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the slice
5365    /// count differs from the view rank,
5366    /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
5367    /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
5368    /// invalid slice, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5369    /// when the result exceeds the backing buffer,
5370    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5371    /// logical elements alias, or
5372    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5373    /// arithmetic overflow.
5374    pub fn slice_view(
5375        &mut self,
5376        slices: &[StridedSliceSpec],
5377    ) -> crate::Result<TypedTensorViewMut<'_, T, R>> {
5378        let specs = core_slice_specs(slices, self.shape(), "TypedTensorViewMut::slice_view")?;
5379        let layout = self
5380            .layout
5381            .slice_view(specs, self.buffer.len())
5382            .map_err(|err| tensor_layout_error("TypedTensorViewMut::slice_view", err))?;
5383        layout
5384            .validate_mutable_no_overlap()
5385            .map_err(|err| tensor_layout_error("TypedTensorViewMut::slice_view", err))?;
5386        let placement = self.placement.clone();
5387        match &mut self.buffer {
5388            TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5389                buffer: TensorStorageRefMut::Host(data),
5390                root: None,
5391                layout,
5392                placement,
5393                _representation: std::marker::PhantomData,
5394            }),
5395            TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5396                buffer: TensorStorageRefMut::Backend(*buffer),
5397                root: None,
5398                layout,
5399                placement,
5400                _representation: std::marker::PhantomData,
5401            }),
5402        }
5403    }
5404
5405    /// Return a mutable metadata-only slice along one axis.
5406    ///
5407    /// # Examples
5408    ///
5409    /// ```rust
5410    /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5411    ///
5412    /// let mut data = [1_i32, 2, 3, 4];
5413    /// let mut view = TypedTensorViewMut::from_slice(vec![2, 2], vec![1, 2], 0, &mut data)?;
5414    /// assert_eq!(view.slice_axis_view(1, StridedSliceSpec::reverse())?.get(&[0, 0]), Some(&3));
5415    /// # Ok::<(), tenferro_tensor::Error>(())
5416    /// ```
5417    /// # Errors
5418    ///
5419    /// Returns [`crate::Error::Validation`] with
5420    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`] when `axis`
5421    /// is outside the view rank, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
5422    /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
5423    /// invalid slice, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5424    /// when the result exceeds the backing buffer,
5425    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5426    /// logical elements alias, or
5427    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5428    /// arithmetic overflow.
5429    pub fn slice_axis_view(
5430        &mut self,
5431        axis: usize,
5432        slice: StridedSliceSpec,
5433    ) -> crate::Result<TypedTensorViewMut<'_, T, R>> {
5434        let slices = slice_axis_specs(
5435            self.shape().len(),
5436            axis,
5437            slice,
5438            "TypedTensorViewMut::slice_axis_view",
5439        )?;
5440        self.slice_view(&slices)
5441    }
5442
5443    /// Return two mutable metadata-only slices when their physical ranges are disjoint.
5444    ///
5445    /// # Examples
5446    ///
5447    /// ```rust
5448    /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5449    ///
5450    /// let mut data = [1_i32, 2, 3, 4];
5451    /// let mut view = TypedTensorViewMut::from_slice(vec![4], vec![1], 0, &mut data)?;
5452    /// let (left, right) = view
5453    ///     .try_multi_slice_mut(
5454    ///         &[StridedSliceSpec::new(0, Some(2), 1)],
5455    ///         &[StridedSliceSpec::new(2, Some(4), 1)],
5456    ///     )
5457    ///     ?
5458    ///     .unwrap();
5459    /// assert_eq!(left.shape(), &[2]);
5460    /// assert_eq!(right.shape(), &[2]);
5461    /// # Ok::<(), tenferro_tensor::Error>(())
5462    /// ```
5463    /// # Errors
5464    ///
5465    /// Returns [`crate::Error::Validation`] with
5466    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for either
5467    /// slice count, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
5468    /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for
5469    /// invalid parameters, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5470    /// when a result exceeds the backing buffer,
5471    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5472    /// a result aliases, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
5473    /// for a negative reachable offset, or
5474    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5475    /// arithmetic overflow. The method returns `Ok(None)` when the two ranges
5476    /// overlap or the view uses backend storage.
5477    pub fn try_multi_slice_mut(
5478        &mut self,
5479        first: &[StridedSliceSpec],
5480        second: &[StridedSliceSpec],
5481    ) -> crate::Result<Option<TypedTensorViewMutSplit<'_, T, R>>> {
5482        let op = "TypedTensorViewMut::try_multi_slice_mut";
5483        let first_specs = core_slice_specs(first, self.shape(), op)?;
5484        let second_specs = core_slice_specs(second, self.shape(), op)?;
5485        let buffer_len = self.buffer.len();
5486        let first_layout = self
5487            .layout
5488            .slice_view(first_specs, buffer_len)
5489            .map_err(|err| tensor_layout_error(op, err))?;
5490        let second_layout = self
5491            .layout
5492            .slice_view(second_specs, buffer_len)
5493            .map_err(|err| tensor_layout_error(op, err))?;
5494        first_layout
5495            .validate_mutable_no_overlap()
5496            .map_err(|err| tensor_layout_error(op, err))?;
5497        second_layout
5498            .validate_mutable_no_overlap()
5499            .map_err(|err| tensor_layout_error(op, err))?;
5500
5501        match (
5502            reachable_layout_span(
5503                first_layout.shape(),
5504                first_layout.strides(),
5505                first_layout.offset(),
5506            )?,
5507            reachable_layout_span(
5508                second_layout.shape(),
5509                second_layout.strides(),
5510                second_layout.offset(),
5511            )?,
5512        ) {
5513            (Some(first_span), Some(second_span)) => {
5514                let first_offset = adjusted_view_offset(first_layout.offset(), first_span.0)?;
5515                let second_offset = adjusted_view_offset(second_layout.offset(), second_span.0)?;
5516                let (first_data, second_data) = match &mut self.buffer {
5517                    TensorStorageRefMut::Host(data) => {
5518                        match split_two_mut_ranges(data, first_span, second_span) {
5519                            Some(ranges) => ranges,
5520                            None => return Ok(None),
5521                        }
5522                    }
5523                    TensorStorageRefMut::Backend(_) => return Ok(None),
5524                };
5525                let first_view = view_mut_from_layout_and_slice(
5526                    &first_layout,
5527                    first_offset,
5528                    first_data,
5529                    self.placement.clone(),
5530                )?;
5531                let second_view = view_mut_from_layout_and_slice(
5532                    &second_layout,
5533                    second_offset,
5534                    second_data,
5535                    self.placement.clone(),
5536                )?;
5537                Ok(Some((first_view, second_view)))
5538            }
5539            (None, Some(second_span)) => {
5540                let second_offset = adjusted_view_offset(second_layout.offset(), second_span.0)?;
5541                let (_, after_start) = match &mut self.buffer {
5542                    TensorStorageRefMut::Host(data) => data.split_at_mut(second_span.0),
5543                    TensorStorageRefMut::Backend(_) => return Ok(None),
5544                };
5545                let (second_data, _) = after_start.split_at_mut(second_span.1 - second_span.0 + 1);
5546                let first_view = view_mut_from_layout_and_slice(
5547                    &first_layout,
5548                    0,
5549                    &mut [],
5550                    self.placement.clone(),
5551                )?;
5552                let second_view = view_mut_from_layout_and_slice(
5553                    &second_layout,
5554                    second_offset,
5555                    second_data,
5556                    self.placement.clone(),
5557                )?;
5558                Ok(Some((first_view, second_view)))
5559            }
5560            (Some(first_span), None) => {
5561                let first_offset = adjusted_view_offset(first_layout.offset(), first_span.0)?;
5562                let (_, after_start) = match &mut self.buffer {
5563                    TensorStorageRefMut::Host(data) => data.split_at_mut(first_span.0),
5564                    TensorStorageRefMut::Backend(_) => return Ok(None),
5565                };
5566                let (first_data, _) = after_start.split_at_mut(first_span.1 - first_span.0 + 1);
5567                let first_view = view_mut_from_layout_and_slice(
5568                    &first_layout,
5569                    first_offset,
5570                    first_data,
5571                    self.placement.clone(),
5572                )?;
5573                let second_view = view_mut_from_layout_and_slice(
5574                    &second_layout,
5575                    0,
5576                    &mut [],
5577                    self.placement.clone(),
5578                )?;
5579                Ok(Some((first_view, second_view)))
5580            }
5581            (None, None) => {
5582                let first_view = view_mut_from_layout_and_slice(
5583                    &first_layout,
5584                    0,
5585                    &mut [],
5586                    self.placement.clone(),
5587                )?;
5588                let second_view = view_mut_from_layout_and_slice(
5589                    &second_layout,
5590                    0,
5591                    &mut [],
5592                    self.placement.clone(),
5593                )?;
5594                Ok(Some((first_view, second_view)))
5595            }
5596        }
5597    }
5598
5599    /// Return a mutable metadata-only dynamic-rank reshape for contiguous views.
5600    ///
5601    /// # Examples
5602    ///
5603    /// ```rust
5604    /// use tenferro_tensor::TypedTensorViewMut;
5605    ///
5606    /// let mut data = [1_i32, 2, 3, 4];
5607    /// let mut view = TypedTensorViewMut::from_slice(vec![2, 2], vec![1, 2], 0, &mut data)?;
5608    /// assert_eq!(view.reshape_view(&[4])?.shape(), &[4]);
5609    /// # Ok::<(), tenferro_tensor::Error>(())
5610    /// ```
5611    /// # Errors
5612    ///
5613    /// Returns [`crate::Error::Validation`] with
5614    /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
5615    /// the source is not compact column-major,
5616    /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
5617    /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
5618    /// records the counts) when element counts differ,
5619    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5620    /// the reshaped layout aliases, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
5621    /// for shape or layout arithmetic overflow, or
5622    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
5623    /// reshaped view exceeds the backing buffer.
5624    pub fn reshape_view(
5625        &mut self,
5626        shape: &[usize],
5627    ) -> crate::Result<TypedTensorViewMut<'_, T, DynRank, D>> {
5628        let layout = reshape_layout_dyn(
5629            &self.layout,
5630            shape,
5631            self.buffer.len(),
5632            "TypedTensorViewMut::reshape_view",
5633        )?;
5634        layout
5635            .validate_mutable_no_overlap()
5636            .map_err(|err| tensor_layout_error("TypedTensorViewMut::reshape_view", err))?;
5637        let placement = self.placement.clone();
5638        match &mut self.buffer {
5639            TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5640                buffer: TensorStorageRefMut::Host(data),
5641                root: None,
5642                layout,
5643                placement,
5644                _representation: std::marker::PhantomData,
5645            }),
5646            TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5647                buffer: TensorStorageRefMut::Backend(*buffer),
5648                root: None,
5649                layout,
5650                placement,
5651                _representation: std::marker::PhantomData,
5652            }),
5653        }
5654    }
5655}
5656
5657impl<'a, R: TensorRank> TypedTensorViewMut<'a, Complex32, R> {
5658    /// Borrow this mutable complex view as an interleaved real view.
5659    ///
5660    /// This changes only the typed descriptor and borrows the same host
5661    /// allocation. The result has dynamic rank because the component axis is
5662    /// prepended. Backend-native buffers are rejected until their provider
5663    /// phase supplies the corresponding mapping capability.
5664    ///
5665    /// # Examples
5666    ///
5667    /// ```
5668    /// use tenferro_tensor::{Complex32, TypedTensorViewMut};
5669    ///
5670    /// let mut data = [Complex32::new(1.0, 2.0)];
5671    /// let mut view = TypedTensorViewMut::from_col_major(&[1], &mut data)?;
5672    /// let real = view.as_real_view_mut()?;
5673    /// assert_eq!(real.shape(), &[2, 1]);
5674    /// assert_eq!(real.as_read_only().as_slice()?, &[1.0_f32, 2.0]);
5675    /// # Ok::<(), tenferro_tensor::Error>(())
5676    /// ```
5677    ///
5678    /// # Errors
5679    ///
5680    /// Returns an error when the view layout is not injective, the sealed
5681    /// representation is invalid, or backend reinterpretation is unsupported.
5682    pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f32, DynRank>> {
5683        let op = "TypedTensorViewMut::as_real_view_mut";
5684        validate_representation_pair(op, DType::C32, DType::F32)?;
5685        let layout = reinterpret_complex_to_real_layout(
5686            self.shape(),
5687            self.strides(),
5688            self.offset(),
5689            self.buffer.len(),
5690            op,
5691        )?;
5692        layout
5693            .validate_mutable_no_overlap()
5694            .map_err(|err| tensor_layout_error(op, err))?;
5695        let buffer = match &mut self.buffer {
5696            TensorStorageRefMut::Host(data) => {
5697                TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex32, f32>(data, op)?)
5698            }
5699            TensorStorageRefMut::Backend(_) => {
5700                return Err(crate::Error::unsupported(
5701                    op,
5702                    "backend representation reinterpretation is enabled by the provider phases",
5703                ))
5704            }
5705        };
5706        Ok(TypedTensorViewMut {
5707            buffer,
5708            root: None,
5709            layout,
5710            placement: self.placement.clone(),
5711            _representation: std::marker::PhantomData,
5712        })
5713    }
5714}
5715
5716impl<'a, R: TensorRank> TypedTensorViewMut<'a, Complex64, R> {
5717    /// Borrow this mutable complex view as an interleaved real view.
5718    ///
5719    /// This changes only the typed descriptor and borrows the same host
5720    /// allocation. The result has dynamic rank because the component axis is
5721    /// prepended. Backend-native buffers are rejected until their provider
5722    /// phase supplies the corresponding mapping capability.
5723    ///
5724    /// # Examples
5725    ///
5726    /// ```
5727    /// use tenferro_tensor::{Complex64, TypedTensorViewMut};
5728    ///
5729    /// let mut data = [Complex64::new(1.0, 2.0)];
5730    /// let mut view = TypedTensorViewMut::from_col_major(&[1], &mut data)?;
5731    /// let real = view.as_real_view_mut()?;
5732    /// assert_eq!(real.shape(), &[2, 1]);
5733    /// assert_eq!(real.as_read_only().as_slice()?, &[1.0_f64, 2.0]);
5734    /// # Ok::<(), tenferro_tensor::Error>(())
5735    /// ```
5736    ///
5737    /// # Errors
5738    ///
5739    /// Returns an error when the view layout is not injective, the sealed
5740    /// representation is invalid, or backend reinterpretation is unsupported.
5741    pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f64, DynRank>> {
5742        let op = "TypedTensorViewMut::as_real_view_mut";
5743        validate_representation_pair(op, DType::C64, DType::F64)?;
5744        let layout = reinterpret_complex_to_real_layout(
5745            self.shape(),
5746            self.strides(),
5747            self.offset(),
5748            self.buffer.len(),
5749            op,
5750        )?;
5751        layout
5752            .validate_mutable_no_overlap()
5753            .map_err(|err| tensor_layout_error(op, err))?;
5754        let buffer = match &mut self.buffer {
5755            TensorStorageRefMut::Host(data) => {
5756                TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex64, f64>(data, op)?)
5757            }
5758            TensorStorageRefMut::Backend(_) => {
5759                return Err(crate::Error::unsupported(
5760                    op,
5761                    "backend representation reinterpretation is enabled by the provider phases",
5762                ))
5763            }
5764        };
5765        Ok(TypedTensorViewMut {
5766            buffer,
5767            root: None,
5768            layout,
5769            placement: self.placement.clone(),
5770            _representation: std::marker::PhantomData,
5771        })
5772    }
5773}
5774
5775impl<'a, R: TensorRank> TypedTensorViewMut<'a, f32, R> {
5776    /// Borrow this mutable interleaved real view as a complex view.
5777    ///
5778    /// The source must have a leading extent and stride of `2` and `1`, and
5779    /// all remaining strides plus the offset must be divisible by `2`.
5780    ///
5781    /// # Examples
5782    ///
5783    /// ```
5784    /// use tenferro_tensor::{Complex32, TypedTensorViewMut};
5785    ///
5786    /// let mut data = [1.0_f32, 2.0];
5787    /// let mut view = TypedTensorViewMut::from_col_major(&[2, 1], &mut data)?;
5788    /// let complex = view.as_complex_view_mut()?;
5789    /// assert_eq!(complex.shape(), &[1]);
5790    /// assert_eq!(complex.as_read_only().as_slice()?, &[Complex32::new(1.0, 2.0)]);
5791    /// # Ok::<(), tenferro_tensor::Error>(())
5792    /// ```
5793    ///
5794    /// # Errors
5795    ///
5796    /// Returns an error when the view layout is not injective, the sealed
5797    /// representation is invalid, or backend reinterpretation is unsupported.
5798    pub fn as_complex_view_mut(
5799        &mut self,
5800    ) -> crate::Result<TypedTensorViewMut<'_, Complex32, DynRank>> {
5801        let op = "TypedTensorViewMut::as_complex_view_mut";
5802        validate_representation_pair(op, DType::F32, DType::C32)?;
5803        let layout = reinterpret_real_to_complex_layout(
5804            self.shape(),
5805            self.strides(),
5806            self.offset(),
5807            self.buffer.len(),
5808            op,
5809        )?;
5810        layout
5811            .validate_mutable_no_overlap()
5812            .map_err(|err| tensor_layout_error(op, err))?;
5813        let buffer = match &mut self.buffer {
5814            TensorStorageRefMut::Host(data) => {
5815                TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f32, Complex32>(data, op)?)
5816            }
5817            TensorStorageRefMut::Backend(_) => {
5818                return Err(crate::Error::unsupported(
5819                    op,
5820                    "backend representation reinterpretation is enabled by the provider phases",
5821                ))
5822            }
5823        };
5824        Ok(TypedTensorViewMut {
5825            buffer,
5826            root: None,
5827            layout,
5828            placement: self.placement.clone(),
5829            _representation: std::marker::PhantomData,
5830        })
5831    }
5832}
5833
5834impl<'a, R: TensorRank> TypedTensorViewMut<'a, f64, R> {
5835    /// Borrow this mutable interleaved real view as a complex view.
5836    ///
5837    /// The source must have a leading extent and stride of `2` and `1`, and
5838    /// all remaining strides plus the offset must be divisible by `2`.
5839    ///
5840    /// # Examples
5841    ///
5842    /// ```
5843    /// use tenferro_tensor::{Complex64, TypedTensorViewMut};
5844    ///
5845    /// let mut data = [1.0_f64, 2.0];
5846    /// let mut view = TypedTensorViewMut::from_col_major(&[2, 1], &mut data)?;
5847    /// let complex = view.as_complex_view_mut()?;
5848    /// assert_eq!(complex.shape(), &[1]);
5849    /// assert_eq!(complex.as_read_only().as_slice()?, &[Complex64::new(1.0, 2.0)]);
5850    /// # Ok::<(), tenferro_tensor::Error>(())
5851    /// ```
5852    ///
5853    /// # Errors
5854    ///
5855    /// Returns an error when the view layout is not injective, the sealed
5856    /// representation is invalid, or backend reinterpretation is unsupported.
5857    pub fn as_complex_view_mut(
5858        &mut self,
5859    ) -> crate::Result<TypedTensorViewMut<'_, Complex64, DynRank>> {
5860        let op = "TypedTensorViewMut::as_complex_view_mut";
5861        validate_representation_pair(op, DType::F64, DType::C64)?;
5862        let layout = reinterpret_real_to_complex_layout(
5863            self.shape(),
5864            self.strides(),
5865            self.offset(),
5866            self.buffer.len(),
5867            op,
5868        )?;
5869        layout
5870            .validate_mutable_no_overlap()
5871            .map_err(|err| tensor_layout_error(op, err))?;
5872        let buffer = match &mut self.buffer {
5873            TensorStorageRefMut::Host(data) => {
5874                TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f64, Complex64>(data, op)?)
5875            }
5876            TensorStorageRefMut::Backend(_) => {
5877                return Err(crate::Error::unsupported(
5878                    op,
5879                    "backend representation reinterpretation is enabled by the provider phases",
5880                ))
5881            }
5882        };
5883        Ok(TypedTensorViewMut {
5884            buffer,
5885            root: None,
5886            layout,
5887            placement: self.placement.clone(),
5888            _representation: std::marker::PhantomData,
5889        })
5890    }
5891}
5892
5893/// Sealed trait for scalar types that can be stored in a [`Tensor`].
5894///
5895/// This trait is implemented for `f64`, `f32`, `i32`, `i64`, `bool`,
5896/// [`Complex64`], and [`Complex32`].
5897///
5898/// # Examples
5899///
5900/// ```
5901/// use tenferro_tensor::TensorScalar;
5902///
5903/// let tensor = <f64 as TensorScalar>::into_tensor(vec![2], vec![1.0, 2.0])?;
5904/// assert_eq!(tensor.as_slice::<f64>()?, [1.0, 2.0].as_slice());
5905/// # Ok::<(), tenferro_tensor::Error>(())
5906/// ```
5907pub trait TensorScalar: Copy + Clone + Send + Sync + 'static + private::Sealed {
5908    /// Real-valued counterpart of this scalar type.
5909    type Real: TensorScalar;
5910
5911    /// The [`DType`] tag corresponding to this scalar type.
5912    ///
5913    /// # Examples
5914    ///
5915    /// ```
5916    /// use tenferro_tensor::{DType, TensorScalar};
5917    ///
5918    /// assert_eq!(f64::dtype(), DType::F64);
5919    /// assert_eq!(f32::dtype(), DType::F32);
5920    /// ```
5921    fn dtype() -> DType;
5922
5923    /// Build the crate's default scalar set from validated column-major data.
5924    ///
5925    /// # Examples
5926    ///
5927    /// ```
5928    /// use tenferro_tensor::{DType, TensorScalar};
5929    ///
5930    /// let set = <f64 as TensorScalar>::into_default_scalars(vec![2], vec![1.0, 2.0])?;
5931    /// assert_eq!(set.dtype(), DType::F64);
5932    /// # Ok::<(), tenferro_tensor::Error>(())
5933    /// ```
5934    ///
5935    /// # Errors
5936    ///
5937    /// Returns a validation error carrying
5938    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when the shape product
5939    /// differs from `data.len()`, or [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
5940    /// when shape arithmetic overflows.
5941    fn into_default_scalars(
5942        shape: Vec<usize>,
5943        data: Vec<Self>,
5944    ) -> crate::Result<crate::DefaultScalars>;
5945
5946    /// Borrow the default scalar set's values when it holds this scalar type.
5947    ///
5948    /// Returns `None` when the set currently holds another member.
5949    ///
5950    /// # Examples
5951    ///
5952    /// ```
5953    /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5954    ///
5955    /// let set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5956    /// assert_eq!(<f64 as TensorScalar>::default_scalars_slice(&set), Some(&[1.0, 2.0][..]));
5957    /// assert!(<f32 as TensorScalar>::default_scalars_slice(&set).is_none());
5958    /// # Ok::<(), tenferro_tensor::Error>(())
5959    /// ```
5960    fn default_scalars_slice(set: &crate::DefaultScalars) -> Option<&[Self]>;
5961
5962    /// Exclusively borrow the default scalar set's values when it holds this scalar type.
5963    ///
5964    /// Returns `None` when the set currently holds another member.
5965    ///
5966    /// # Examples
5967    ///
5968    /// ```
5969    /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5970    ///
5971    /// let mut set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5972    /// if let Some(values) = <f64 as TensorScalar>::default_scalars_slice_mut(&mut set) {
5973    ///     values[0] = 5.0;
5974    /// }
5975    /// assert_eq!(set.as_slice::<f64>()?, &[5.0, 2.0]);
5976    /// # Ok::<(), tenferro_tensor::Error>(())
5977    /// ```
5978    fn default_scalars_slice_mut(set: &mut crate::DefaultScalars) -> Option<&mut [Self]>;
5979
5980    /// Move the host tensor out of the default scalar set when it holds this scalar type.
5981    ///
5982    /// Returns `None` when the set currently holds another member.
5983    ///
5984    /// # Examples
5985    ///
5986    /// ```
5987    /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5988    ///
5989    /// let set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5990    /// let host = <f64 as TensorScalar>::from_default_scalars(set);
5991    /// assert_eq!(host.as_ref().map(|t| t.shape()), Some(&[2][..]));
5992    /// assert_eq!(host.as_ref().map(|t| t.as_slice()), Some(&[1.0, 2.0][..]));
5993    /// # Ok::<(), tenferro_tensor::Error>(())
5994    /// ```
5995    fn from_default_scalars(set: crate::DefaultScalars)
5996        -> Option<TypedTensor<Self, DynRank, Host>>;
5997
5998    /// Wrap typed column-major data into a [`Tensor`] enum variant.
5999    ///
6000    /// # Examples
6001    ///
6002    /// ```
6003    /// use tenferro_tensor::{DType, TensorScalar};
6004    ///
6005    /// let tensor = <f64 as TensorScalar>::into_tensor(vec![2], vec![1.0, 2.0])?;
6006    /// assert_eq!(tensor.dtype(), DType::F64);
6007    /// assert_eq!(tensor.shape(), &[2]);
6008    /// assert!(<f64 as TensorScalar>::into_tensor(vec![3], vec![1.0]).is_err());
6009    /// # Ok::<(), tenferro_tensor::Error>(())
6010    /// ```
6011    ///
6012    /// # Errors
6013    ///
6014    /// Returns [`crate::Error::Validation`] with
6015    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
6016    /// the shape product differs from `data.len()`, or
6017    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
6018    /// arithmetic overflows.
6019    fn into_tensor(shape: Vec<usize>, data: Vec<Self>) -> crate::Result<Tensor>;
6020
6021    /// Wrap a typed tensor into its dynamic [`Tensor`] enum variant.
6022    ///
6023    /// # Examples
6024    ///
6025    /// ```
6026    /// use tenferro_tensor::{DType, Tensor, TensorScalar, TypedTensor};
6027    ///
6028    /// let typed = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![3.0])?;
6029    /// let tensor = <f64 as TensorScalar>::typed_tensor_into_tensor(typed);
6030    /// assert!(matches!(tensor.dtype(), DType::F64));
6031    /// # Ok::<(), tenferro_tensor::Error>(())
6032    /// ```
6033    fn typed_tensor_into_tensor(tensor: TypedTensor<Self>) -> Tensor;
6034
6035    /// Borrow a typed tensor as a dtype-erased [`TensorRead`] view.
6036    ///
6037    /// This keeps the typed tensor borrowed instead of copying host data into
6038    /// a new dynamic tensor.
6039    ///
6040    /// # Examples
6041    ///
6042    /// ```
6043    /// use tenferro_tensor::{DType, TensorScalar, TypedTensor};
6044    ///
6045    /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
6046    /// let read = f64::tensor_read(&tensor);
6047    /// assert_eq!(read.dtype(), DType::F64);
6048    /// assert_eq!(read.shape(), &[2]);
6049    /// ```
6050    fn tensor_read(tensor: &TypedTensor<Self>) -> TensorRead<'_>;
6051
6052    /// Wrap a typed borrowed view as a dtype-erased [`TensorView`].
6053    ///
6054    /// # Examples
6055    ///
6056    /// ```
6057    /// use tenferro_tensor::{DType, TensorScalar, TypedTensorView};
6058    ///
6059    /// let data = [1.0_f64];
6060    /// let view = TypedTensorView::from_col_major(&[1], &data)?;
6061    /// assert_eq!(f64::tensor_view(view).dtype(), DType::F64);
6062    /// # Ok::<(), tenferro_tensor::Error>(())
6063    /// ```
6064    fn tensor_view<'a>(view: TypedTensorView<'a, Self>) -> TensorView<'a>;
6065
6066    /// Wrap a typed mutable borrowed view as a dtype-erased [`TensorViewMut`].
6067    ///
6068    /// # Examples
6069    ///
6070    /// ```
6071    /// use tenferro_tensor::{DType, TensorScalar, TypedTensorViewMut};
6072    ///
6073    /// let mut data = [1.0_f64, 2.0];
6074    /// let view = TypedTensorViewMut::from_col_major(&[2], &mut data)?;
6075    /// let erased = f64::tensor_view_mut(view);
6076    /// assert_eq!(erased.dtype(), DType::F64);
6077    /// assert_eq!(erased.shape(), &[2]);
6078    /// # Ok::<(), tenferro_tensor::Error>(())
6079    /// ```
6080    fn tensor_view_mut<'a>(view: TypedTensorViewMut<'a, Self>) -> TensorViewMut<'a>;
6081
6082    /// Mutably borrow a typed tensor as a dtype-erased [`TensorWrite`] view.
6083    ///
6084    /// This keeps the typed output borrowed instead of wrapping it in a
6085    /// temporary dynamic tensor.
6086    ///
6087    /// # Examples
6088    ///
6089    /// ```
6090    /// use tenferro_tensor::{DType, TensorScalar, TypedTensor};
6091    ///
6092    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![0.0]).unwrap();
6093    /// let write = f64::tensor_write(&mut tensor);
6094    /// assert_eq!(write.dtype(), DType::F64);
6095    /// ```
6096    fn tensor_write(tensor: &mut TypedTensor<Self>) -> TensorWrite<'_>;
6097
6098    /// Borrow the host data from a [`Tensor`].
6099    ///
6100    /// # Examples
6101    ///
6102    /// ```
6103    /// use tenferro_tensor::{Tensor, TensorScalar};
6104    ///
6105    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6106    /// assert_eq!(<f64 as TensorScalar>::as_slice(&tensor)?, &[1.0, 2.0]);
6107    /// assert!(<f32 as TensorScalar>::as_slice(&tensor).is_err());
6108    /// # Ok::<(), tenferro_tensor::Error>(())
6109    /// ```
6110    ///
6111    /// # Errors
6112    ///
6113    /// Returns [`crate::Error::Validation`] with
6114    /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `tensor`
6115    /// is not the scalar type represented by this implementation, or
6116    /// [`crate::Error::RuntimeState`] when the matching tensor uses backend
6117    /// storage that has not been downloaded.
6118    fn as_slice(tensor: &Tensor) -> crate::Result<&[Self]>;
6119
6120    /// Mutably borrow the host data from a [`Tensor`].
6121    ///
6122    /// # Examples
6123    ///
6124    /// ```
6125    /// use tenferro_tensor::{Tensor, TensorScalar};
6126    ///
6127    /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?;
6128    /// <f64 as TensorScalar>::as_slice_mut(&mut tensor)?[0] = 3.0;
6129    ///
6130    /// assert_eq!(tensor.as_slice::<f64>()?, &[3.0]);
6131    /// # Ok::<(), tenferro_tensor::Error>(())
6132    /// ```
6133    /// # Errors
6134    ///
6135    /// Returns [`crate::Error::Validation`] with
6136    /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `tensor`
6137    /// is not the scalar type represented by this implementation, or
6138    /// [`crate::Error::RuntimeState`] when the matching tensor uses backend
6139    /// storage that has not been downloaded.
6140    fn as_slice_mut(tensor: &mut Tensor) -> crate::Result<&mut [Self]>;
6141
6142    /// Extract a [`TypedTensor<Self>`] from a dynamic [`Tensor`].
6143    ///
6144    /// # Examples
6145    ///
6146    /// ```
6147    /// use tenferro_tensor::{Tensor, TensorScalar};
6148    ///
6149    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6150    /// let Ok(typed) = <f64 as TensorScalar>::into_typed(tensor) else {
6151    ///     panic!("the dtype matches by construction")
6152    /// };
6153    ///
6154    /// assert_eq!(typed.as_slice()?, &[1.0, 2.0]);
6155    /// # Ok::<(), tenferro_tensor::Error>(())
6156    /// ```
6157    /// # Errors
6158    ///
6159    /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is
6160    /// not the scalar type represented by this implementation, with
6161    /// [`crate::Error::Validation`] and
6162    /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] as the cause.
6163    fn into_typed(
6164        tensor: Tensor,
6165    ) -> std::result::Result<TypedTensor<Self>, ReinterpretError<Tensor>>;
6166}
6167
6168mod private {
6169    pub trait Sealed {}
6170
6171    impl Sealed for f64 {}
6172    impl Sealed for f32 {}
6173    impl Sealed for i32 {}
6174    impl Sealed for i64 {}
6175    impl Sealed for bool {}
6176    impl Sealed for num_complex::Complex64 {}
6177    impl Sealed for num_complex::Complex32 {}
6178}
6179
6180macro_rules! impl_tensor_scalar {
6181    ($ty:ty, $real:ty, $dtype:ident, $variant:ident) => {
6182        impl TensorScalar for $ty {
6183            type Real = $real;
6184
6185            #[inline]
6186            fn dtype() -> DType {
6187                DType::$dtype
6188            }
6189
6190            fn into_default_scalars(
6191                shape: Vec<usize>,
6192                data: Vec<Self>,
6193            ) -> crate::Result<crate::DefaultScalars> {
6194                TypedTensor::<Self, DynRank, Host>::from_host_vec_col_major(shape, data).map(
6195                    |tensor| {
6196                        crate::DefaultScalars::from_payload(
6197                            crate::default_scalars::DefaultScalarsValue::$variant(tensor),
6198                        )
6199                    },
6200                )
6201            }
6202
6203            fn default_scalars_slice(set: &crate::DefaultScalars) -> Option<&[Self]> {
6204                match set.payload() {
6205                    crate::default_scalars::DefaultScalarsValue::$variant(tensor) => {
6206                        Some(tensor.as_slice())
6207                    }
6208                    _ => None,
6209                }
6210            }
6211
6212            fn default_scalars_slice_mut(set: &mut crate::DefaultScalars) -> Option<&mut [Self]> {
6213                match set.payload_mut() {
6214                    crate::default_scalars::DefaultScalarsValue::$variant(tensor) => {
6215                        Some(tensor.host_data_mut())
6216                    }
6217                    _ => None,
6218                }
6219            }
6220
6221            fn from_default_scalars(
6222                set: crate::DefaultScalars,
6223            ) -> Option<TypedTensor<Self, DynRank, Host>> {
6224                match set.into_payload() {
6225                    crate::default_scalars::DefaultScalarsValue::$variant(tensor) => Some(tensor),
6226                    _ => None,
6227                }
6228            }
6229
6230            fn into_tensor(shape: Vec<usize>, data: Vec<Self>) -> crate::Result<Tensor> {
6231                TypedTensor::from_vec_col_major(shape, data).map(Self::typed_tensor_into_tensor)
6232            }
6233
6234            fn typed_tensor_into_tensor(tensor: TypedTensor<Self>) -> Tensor {
6235                Tensor {
6236                    payload: TensorPayload::Native(PresetTensor::$variant(tensor)),
6237                }
6238            }
6239
6240            fn tensor_read(tensor: &TypedTensor<Self>) -> TensorRead<'_> {
6241                TensorRead::from_view(TensorView::$variant(tensor.as_view()))
6242            }
6243
6244            #[inline]
6245            fn tensor_view<'a>(view: TypedTensorView<'a, Self>) -> TensorView<'a> {
6246                TensorView::$variant(view)
6247            }
6248
6249            #[inline]
6250            fn tensor_view_mut<'a>(view: TypedTensorViewMut<'a, Self>) -> TensorViewMut<'a> {
6251                TensorViewMut::$variant(view)
6252            }
6253
6254            fn tensor_write(tensor: &mut TypedTensor<Self>) -> TensorWrite<'_> {
6255                TensorWrite::from_view(TensorViewMut::$variant(tensor.as_view_mut()))
6256            }
6257
6258            fn as_slice(tensor: &Tensor) -> crate::Result<&[Self]> {
6259                tensor
6260                    .as_typed::<Self>()
6261                    .ok_or_else(|| {
6262                        crate::Error::validation(
6263                            "Tensor::as_slice",
6264                            ValidationError::DTypeMismatch {
6265                                expected: Self::dtype(),
6266                                actual: tensor.dtype(),
6267                            },
6268                        )
6269                    })?
6270                    .host_data()
6271            }
6272
6273            fn as_slice_mut(tensor: &mut Tensor) -> crate::Result<&mut [Self]> {
6274                let actual = tensor.dtype();
6275                let typed = tensor.as_typed_mut::<Self>().ok_or_else(|| {
6276                    crate::Error::validation(
6277                        "Tensor::as_slice_mut",
6278                        ValidationError::DTypeMismatch {
6279                            expected: Self::dtype(),
6280                            actual,
6281                        },
6282                    )
6283                })?;
6284                typed.host_data_mut()
6285            }
6286
6287            fn into_typed(
6288                tensor: Tensor,
6289            ) -> std::result::Result<TypedTensor<Self>, ReinterpretError<Tensor>> {
6290                let actual = tensor.dtype();
6291                match tensor.payload {
6292                    TensorPayload::Native(PresetTensor::$variant(typed)) => Ok(typed),
6293                    payload => Err(ReinterpretError::new(
6294                        Tensor { payload },
6295                        crate::Error::validation(
6296                            "TensorScalar::into_typed",
6297                            ValidationError::DTypeMismatch {
6298                                expected: Self::dtype(),
6299                                actual,
6300                            },
6301                        ),
6302                    )),
6303                }
6304            }
6305        }
6306    };
6307}
6308
6309impl_tensor_scalar!(f64, f64, F64, F64);
6310impl_tensor_scalar!(f32, f32, F32, F32);
6311impl_tensor_scalar!(i64, i64, I64, I64);
6312impl_tensor_scalar!(i32, i32, I32, I32);
6313impl_tensor_scalar!(bool, bool, Bool, Bool);
6314impl_tensor_scalar!(Complex64, f64, C64, C64);
6315impl_tensor_scalar!(Complex32, f32, C32, C32);
6316
6317/// Dynamic tensor enum over the supported scalar types.
6318///
6319/// The enum keeps dtype dynamic and rank dynamic. Use
6320/// [`TypedTensor<T, R>`](TypedTensor) directly when the scalar type or rank
6321/// should be represented in Rust's type system.
6322///
6323/// # Examples
6324///
6325/// ```rust
6326/// use tenferro_tensor::{Tensor, TypedTensor};
6327///
6328/// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap());
6329/// assert_eq!(t.shape(), &[2]);
6330///
6331/// let erased = Tensor::from_vec_col_major(vec![1, 2], vec![1.0_f64, 2.0]).unwrap();
6332/// assert_eq!(erased.shape().len(), 2);
6333/// ```
6334/// The owning payload behind the erased [`Tensor`].
6335///
6336/// `Native` stores a preset scalar owner directly; `External` retains its
6337/// existing explicit caller-owned host payload.
6338#[derive(Debug)]
6339enum TensorPayload {
6340    Native(PresetTensor),
6341    External(crate::ErasedHostTensor, Placement),
6342}
6343
6344#[derive(Debug)]
6345enum PresetTensor {
6346    F32(TypedTensor<f32>),
6347    F64(TypedTensor<f64>),
6348    I32(TypedTensor<i32>),
6349    I64(TypedTensor<i64>),
6350    Bool(TypedTensor<bool>),
6351    C32(TypedTensor<Complex32>),
6352    C64(TypedTensor<Complex64>),
6353}
6354
6355macro_rules! with_preset {
6356    ($preset:expr, |$value:ident| $body:expr) => {
6357        match $preset {
6358            PresetTensor::F32($value) => $body,
6359            PresetTensor::F64($value) => $body,
6360            PresetTensor::I32($value) => $body,
6361            PresetTensor::I64($value) => $body,
6362            PresetTensor::Bool($value) => $body,
6363            PresetTensor::C32($value) => $body,
6364            PresetTensor::C64($value) => $body,
6365        }
6366    };
6367}
6368
6369/// Dynamic tensor over the supported scalar types.
6370///
6371/// The erased tensor keeps dtype and rank dynamic: each preset scalar retains its
6372/// typed owner without constructing a group, while caller-owned scalars remain
6373/// `External` payloads recovered by their own type. Use [`TypedTensor<T, R>`](TypedTensor)
6374/// directly when the scalar type or rank should be represented in Rust's type system.
6375///
6376/// # Examples
6377///
6378/// ```
6379/// use tenferro_tensor::{DType, Tensor};
6380///
6381/// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6382/// assert_eq!(tensor.dtype(), DType::F64);
6383/// # Ok::<(), tenferro_tensor::Error>(())
6384/// ```
6385#[derive(Debug)]
6386pub struct Tensor {
6387    payload: TensorPayload,
6388}
6389
6390impl<R: TensorRank> OwnedTensorGroup<R> {
6391    /// Whether this group's slot is host-addressed memory.
6392    fn payload_is_host_memory(&self) -> bool {
6393        !self.group.slot_root_is_backend(self.slot)
6394    }
6395
6396    /// Whether this group's descriptor names a non-CPU provider.
6397    fn is_backend_buffer(&self) -> bool {
6398        !matches!(
6399            self.group.provider_kind(self.slot),
6400            None | Some(crate::storage::ProviderKind::Cpu)
6401        )
6402    }
6403}
6404
6405impl Tensor {
6406    /// Carry an externally defined scalar as a caller-owned payload.
6407    ///
6408    /// The payload keeps its own element type and is recovered by that type, so no
6409    /// bytes are reinterpreted. Placement defaults to unpinned host memory, which
6410    /// is where a caller-owned payload lives.
6411    ///
6412    /// # Examples
6413    ///
6414    /// ```rust
6415    /// use tenferro_tensor::{DType, Tensor};
6416    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6417    ///
6418    /// let payload = ErasedHostTensor::new(
6419    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6420    /// );
6421    /// let element = payload.element_type_id();
6422    /// let tensor = Tensor::external(payload);
6423    /// assert_eq!(tensor.dtype(), DType::External(element));
6424    /// assert_eq!(tensor.shape(), &[1]);
6425    /// # Ok::<(), tenferro_tensor::Error>(())
6426    /// ```
6427    #[must_use]
6428    pub fn external(payload: crate::ErasedHostTensor) -> Self {
6429        Self {
6430            payload: TensorPayload::External(payload, Placement::default()),
6431        }
6432    }
6433
6434    /// Build a tensor from a typed one, without naming its variant.
6435    ///
6436    /// A call site that constructs a tensor from a typed tensor should use this rather than a variant, so
6437    /// that changing how the erased representation is stored changes this function and not its 1290 call
6438    /// sites. The variants remain until the removal's last step, so both forms currently produce the same
6439    /// value.
6440    ///
6441    /// # Examples
6442    ///
6443    /// ```
6444    /// use tenferro_tensor::Tensor;
6445    ///
6446    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6447    /// let typed = tensor.into_typed::<f64>().unwrap();
6448    /// let rebuilt = Tensor::from_typed(typed);
6449    /// assert_eq!(rebuilt.as_typed::<f64>().unwrap().shape(), &[2]);
6450    /// # Ok::<(), tenferro_tensor::Error>(())
6451    /// ```
6452    #[must_use]
6453    pub fn from_typed<T: TensorScalar>(typed: TypedTensor<T>) -> Self {
6454        T::typed_tensor_into_tensor(typed)
6455    }
6456
6457    /// Borrow the erased payload of an externally defined tensor.
6458    ///
6459    /// This is the counterpart of [`Tensor::external`] for dispatch: a table that matches on
6460    /// [`Tensor::dtype`] reaches the externally defined tag and needs the payload that tag stands
6461    /// for, just as the typed tags reach theirs through [`Tensor::as_typed`]. Every other tag
6462    /// returns `None`.
6463    ///
6464    /// # Examples
6465    ///
6466    /// ```
6467    /// use tenferro_tensor::Tensor;
6468    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6469    ///
6470    /// let payload = ErasedHostTensor::new(
6471    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6472    /// );
6473    /// let tensor = Tensor::external(payload);
6474    /// assert!(tensor.external_payload().is_some());
6475    /// # Ok::<(), tenferro_tensor::Error>(())
6476    /// ```
6477    #[must_use]
6478    pub fn external_payload(&self) -> Option<&crate::ErasedHostTensor> {
6479        match &self.payload {
6480            TensorPayload::External(payload, _) => Some(payload),
6481            TensorPayload::Native(_) => None,
6482        }
6483    }
6484
6485    /// Carry an externally defined payload with an explicit placement.
6486    ///
6487    /// [`Tensor::external`] defaults the placement to unpinned host memory, which is where
6488    /// a caller-owned payload normally lives; this entry point is for a caller that knows
6489    /// the placement it wants.
6490    ///
6491    /// # Examples
6492    ///
6493    /// ```
6494    /// use tenferro_tensor::{Placement, Tensor};
6495    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6496    ///
6497    /// let payload = ErasedHostTensor::new(
6498    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6499    /// );
6500    /// let tensor = Tensor::external_with_placement(payload, Placement::default());
6501    /// assert!(tensor.external_payload().is_some());
6502    /// # Ok::<(), tenferro_tensor::Error>(())
6503    /// ```
6504    #[must_use]
6505    pub fn external_with_placement(payload: crate::ErasedHostTensor, placement: Placement) -> Self {
6506        Self {
6507            payload: TensorPayload::External(payload, placement),
6508        }
6509    }
6510
6511    /// Mutably borrow the erased payload of an externally defined tensor.
6512    ///
6513    /// The counterpart of [`Tensor::external_payload`] for callers that update the payload
6514    /// in place, such as a mutation test that checks the copy boundary.
6515    ///
6516    /// # Examples
6517    ///
6518    /// ```
6519    /// use tenferro_tensor::Tensor;
6520    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6521    ///
6522    /// let mut tensor = Tensor::external(ErasedHostTensor::new(
6523    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6524    /// ));
6525    /// assert!(tensor.external_payload_mut().is_some());
6526    /// # Ok::<(), tenferro_tensor::Error>(())
6527    /// ```
6528    #[must_use]
6529    pub fn external_payload_mut(&mut self) -> Option<&mut crate::ErasedHostTensor> {
6530        match &mut self.payload {
6531            TensorPayload::External(payload, _) => Some(payload),
6532            TensorPayload::Native(_) => None,
6533        }
6534    }
6535
6536    pub(crate) fn into_group_parts(self) -> (AllocationGroup, DescriptorSlot) {
6537        match self.payload {
6538            TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.into_group_parts()),
6539            // INVARIANT: a caller-owned payload has no allocation group.
6540            TensorPayload::External(..) => {
6541                unreachable!("an externally defined payload has no allocation group")
6542            }
6543        }
6544    }
6545}
6546
6547/// Dynamic read-only borrowed tensor view.
6548///
6549/// `TensorView` keeps dtype erased while borrowing typed view metadata and
6550/// storage. Use [`TypedTensorView`] directly when the scalar type is statically
6551/// known.
6552///
6553/// # Examples
6554///
6555/// ```
6556/// use tenferro_tensor::{DType, TensorView, TypedTensorView};
6557///
6558/// let data = [1_i32, 2, 3, 4];
6559/// let typed = TypedTensorView::from_slice([2, 2], [1, 2], 0, &data)?;
6560/// let view = TensorView::I32(typed);
6561///
6562/// assert_eq!(view.dtype(), DType::I32);
6563/// assert_eq!(view.shape(), &[2, 2]);
6564/// # Ok::<(), tenferro_tensor::Error>(())
6565/// ```
6566///
6567/// `D` marks the representation the view was proven to borrow, as on
6568/// [`TypedTensorView`]. The default [`Dynamic`] view may borrow host or backend
6569/// storage; a `TensorView<'a, Host>` comes only from
6570/// [`TensorView::try_host`] or [`TensorRead::try_host`], so every arm borrows
6571/// host storage and a consumer reads it without a further placement check.
6572#[derive(Debug)]
6573pub enum TensorView<'a, D: Representation = Dynamic> {
6574    F32(TypedTensorView<'a, f32, DynRank, D>),
6575    F64(TypedTensorView<'a, f64, DynRank, D>),
6576    I32(TypedTensorView<'a, i32, DynRank, D>),
6577    I64(TypedTensorView<'a, i64, DynRank, D>),
6578    Bool(TypedTensorView<'a, bool, DynRank, D>),
6579    C32(TypedTensorView<'a, Complex<f32>, DynRank, D>),
6580    C64(TypedTensorView<'a, Complex<f64>, DynRank, D>),
6581}
6582
6583// Written by hand because the representation markers are not `Clone`: the
6584// derive would demand `D: Clone` although no marker value is ever stored.
6585impl<D: Representation> Clone for TensorView<'_, D> {
6586    fn clone(&self) -> Self {
6587        match self {
6588            Self::F32(view) => Self::F32(view.clone()),
6589            Self::F64(view) => Self::F64(view.clone()),
6590            Self::I32(view) => Self::I32(view.clone()),
6591            Self::I64(view) => Self::I64(view.clone()),
6592            Self::Bool(view) => Self::Bool(view.clone()),
6593            Self::C32(view) => Self::C32(view.clone()),
6594            Self::C64(view) => Self::C64(view.clone()),
6595        }
6596    }
6597}
6598
6599/// Apply one expression to every arm of a [`TensorView`], keeping the arm.
6600macro_rules! map_tensor_view {
6601    ($view:expr, |$typed:ident| $body:expr) => {
6602        match $view {
6603            TensorView::F32($typed) => TensorView::F32($body),
6604            TensorView::F64($typed) => TensorView::F64($body),
6605            TensorView::I32($typed) => TensorView::I32($body),
6606            TensorView::I64($typed) => TensorView::I64($body),
6607            TensorView::Bool($typed) => TensorView::Bool($body),
6608            TensorView::C32($typed) => TensorView::C32($body),
6609            TensorView::C64($typed) => TensorView::C64($body),
6610        }
6611    };
6612}
6613
6614impl<'a> TensorView<'a> {
6615    /// Checked narrowing of a dtype-erased view to the host representation.
6616    ///
6617    /// See [`TypedTensorView::try_host`]: the narrowing succeeds exactly when
6618    /// the view borrows host elements, and a consumer of the
6619    /// `TensorView<'a, Host>` it returns needs no further placement check.
6620    ///
6621    /// # Examples
6622    ///
6623    /// ```rust
6624    /// use tenferro_tensor::{DType, TensorView};
6625    ///
6626    /// let host = TensorView::f64(&[2], &[1.0, 2.0])?.try_host("example")?;
6627    /// assert_eq!(host.dtype(), DType::F64);
6628    /// assert_eq!(host.shape(), &[2]);
6629    /// # Ok::<(), tenferro_tensor::Error>(())
6630    /// ```
6631    ///
6632    /// # Errors
6633    ///
6634    /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
6635    /// borrows backend (device) storage; download the tensor to host first.
6636    pub fn try_host(self, op: &'static str) -> crate::Result<TensorView<'a, Host>> {
6637        Ok(map_tensor_view!(self, |view| view.try_host(op)?))
6638    }
6639}
6640
6641impl<'a> TensorView<'a, Host> {
6642    /// Widen a host-marked view to the runtime union without copying.
6643    ///
6644    /// # Examples
6645    ///
6646    /// ```rust
6647    /// use tenferro_tensor::{DType, TensorView};
6648    ///
6649    /// let host = TensorView::i32(&[2], &[3, 4])?.try_host("example")?;
6650    /// let dynamic = host.into_dynamic();
6651    /// assert_eq!(dynamic.as_slice::<i32>()?, &[3, 4]);
6652    /// # Ok::<(), tenferro_tensor::Error>(())
6653    /// ```
6654    pub fn into_dynamic(self) -> TensorView<'a> {
6655        map_tensor_view!(self, |view| view.into_dynamic())
6656    }
6657
6658    /// The element dtype of this host view.
6659    ///
6660    /// # Examples
6661    ///
6662    /// ```rust
6663    /// use tenferro_tensor::{DType, TensorView};
6664    ///
6665    /// let host = TensorView::i64(&[1], &[7])?.try_host("example")?;
6666    /// assert_eq!(host.dtype(), DType::I64);
6667    /// # Ok::<(), tenferro_tensor::Error>(())
6668    /// ```
6669    pub fn dtype(&self) -> DType {
6670        match self {
6671            Self::F32(_) => DType::F32,
6672            Self::F64(_) => DType::F64,
6673            Self::I32(_) => DType::I32,
6674            Self::I64(_) => DType::I64,
6675            Self::Bool(_) => DType::Bool,
6676            Self::C32(_) => DType::C32,
6677            Self::C64(_) => DType::C64,
6678        }
6679    }
6680
6681    /// The logical shape of this host view.
6682    ///
6683    /// # Examples
6684    ///
6685    /// ```rust
6686    /// use tenferro_tensor::TensorView;
6687    ///
6688    /// let host = TensorView::f32(&[2], &[1.0, 2.0])?.try_host("example")?;
6689    /// assert_eq!(host.shape(), &[2]);
6690    /// # Ok::<(), tenferro_tensor::Error>(())
6691    /// ```
6692    pub fn shape(&self) -> &[usize] {
6693        match self {
6694            Self::F32(view) => view.shape(),
6695            Self::F64(view) => view.shape(),
6696            Self::I32(view) => view.shape(),
6697            Self::I64(view) => view.shape(),
6698            Self::Bool(view) => view.shape(),
6699            Self::C32(view) => view.shape(),
6700            Self::C64(view) => view.shape(),
6701        }
6702    }
6703
6704    /// Whether the view covers its whole host buffer in compact column-major
6705    /// order from offset zero, so it reads exactly like an owned tensor.
6706    ///
6707    /// # Examples
6708    ///
6709    /// ```rust
6710    /// use tenferro_tensor::{Tensor, TensorRead};
6711    ///
6712    /// let tensor = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
6713    /// let host = TensorRead::from_tensor(&tensor).try_host("example")?;
6714    /// assert!(host.is_owned_layout());
6715    /// # Ok::<(), tenferro_tensor::Error>(())
6716    /// ```
6717    pub fn is_owned_layout(&self) -> bool {
6718        fn owned<T: 'static>(view: &TypedTensorView<'_, T, DynRank, Host>) -> bool {
6719            view.offset() == 0
6720                && view.backing_len() == view.n_elements()
6721                && matches!(view.is_col_major_contiguous(), Ok(true))
6722        }
6723        match self {
6724            Self::F32(view) => owned(view),
6725            Self::F64(view) => owned(view),
6726            Self::I32(view) => owned(view),
6727            Self::I64(view) => owned(view),
6728            Self::Bool(view) => owned(view),
6729            Self::C32(view) => owned(view),
6730            Self::C64(view) => owned(view),
6731        }
6732    }
6733}
6734
6735/// Dynamic mutable borrowed tensor view.
6736///
6737/// `TensorViewMut` is the mutable counterpart to [`TensorView`]. It keeps the
6738/// dtype erased while preserving the typed mutable view's shape, strides, and
6739/// offset metadata.
6740///
6741/// # Examples
6742///
6743/// ```
6744/// use tenferro_tensor::{DType, TensorViewMut, TypedTensorViewMut};
6745///
6746/// let mut data = [1.0_f64, 2.0];
6747/// let view = TensorViewMut::F64(TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?);
6748/// assert_eq!(view.dtype(), DType::F64);
6749/// # Ok::<(), tenferro_tensor::Error>(())
6750/// ```
6751///
6752/// `D` marks the representation the view was proven to borrow, as on
6753/// [`TypedTensorViewMut`]. The default [`Dynamic`] view may borrow host or
6754/// backend storage; a `TensorViewMut<'a, Host>` comes only from
6755/// [`TensorViewMut::try_mut_host`] or [`TensorWrite::try_mut_host`], so every
6756/// arm borrows host storage and a consumer writes it without a further
6757/// placement check.
6758#[allow(clippy::large_enum_variant)]
6759#[derive(Debug)]
6760pub enum TensorViewMut<'a, D: Representation = Dynamic> {
6761    F32(TypedTensorViewMut<'a, f32, DynRank, D>),
6762    F64(TypedTensorViewMut<'a, f64, DynRank, D>),
6763    I32(TypedTensorViewMut<'a, i32, DynRank, D>),
6764    I64(TypedTensorViewMut<'a, i64, DynRank, D>),
6765    Bool(TypedTensorViewMut<'a, bool, DynRank, D>),
6766    C32(TypedTensorViewMut<'a, Complex<f32>, DynRank, D>),
6767    C64(TypedTensorViewMut<'a, Complex<f64>, DynRank, D>),
6768}
6769
6770/// Apply one expression to every arm of a [`TensorViewMut`], keeping the arm.
6771macro_rules! map_tensor_view_mut {
6772    ($view:expr, |$typed:ident| $body:expr) => {
6773        match $view {
6774            TensorViewMut::F32($typed) => TensorViewMut::F32($body),
6775            TensorViewMut::F64($typed) => TensorViewMut::F64($body),
6776            TensorViewMut::I32($typed) => TensorViewMut::I32($body),
6777            TensorViewMut::I64($typed) => TensorViewMut::I64($body),
6778            TensorViewMut::Bool($typed) => TensorViewMut::Bool($body),
6779            TensorViewMut::C32($typed) => TensorViewMut::C32($body),
6780            TensorViewMut::C64($typed) => TensorViewMut::C64($body),
6781        }
6782    };
6783}
6784
6785impl<'a> TensorViewMut<'a> {
6786    /// Checked narrowing of a dtype-erased mutable view to the host
6787    /// representation.
6788    ///
6789    /// See [`TypedTensorViewMut::try_mut_host`]: the narrowing succeeds exactly
6790    /// when the view borrows host elements, and a consumer of the
6791    /// `TensorViewMut<'a, Host>` it returns needs no further placement check.
6792    ///
6793    /// # Examples
6794    ///
6795    /// ```rust
6796    /// use tenferro_tensor::{DType, TensorViewMut};
6797    ///
6798    /// let mut data = [1.0_f64, 2.0];
6799    /// let host = TensorViewMut::f64(&[2], &mut data)?.try_mut_host("example")?;
6800    /// assert_eq!(host.dtype(), DType::F64);
6801    /// assert_eq!(host.shape(), &[2]);
6802    /// # Ok::<(), tenferro_tensor::Error>(())
6803    /// ```
6804    ///
6805    /// # Errors
6806    ///
6807    /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
6808    /// borrows backend (device) storage; download the tensor to host first.
6809    pub fn try_mut_host(self, op: &'static str) -> crate::Result<TensorViewMut<'a, Host>> {
6810        Ok(map_tensor_view_mut!(self, |view| view.try_mut_host(op)?))
6811    }
6812}
6813
6814impl<'a> TensorViewMut<'a, Host> {
6815    /// Widen a host-marked mutable view to the runtime union without copying.
6816    ///
6817    /// # Examples
6818    ///
6819    /// ```rust
6820    /// use tenferro_tensor::TensorViewMut;
6821    ///
6822    /// let mut data = [3_i32, 4];
6823    /// let host = TensorViewMut::i32(&[2], &mut data)?.try_mut_host("example")?;
6824    /// let dynamic = host.into_dynamic();
6825    /// assert_eq!(dynamic.as_read_only().as_slice::<i32>()?, &[3, 4]);
6826    /// # Ok::<(), tenferro_tensor::Error>(())
6827    /// ```
6828    pub fn into_dynamic(self) -> TensorViewMut<'a> {
6829        map_tensor_view_mut!(self, |view| view.into_dynamic())
6830    }
6831
6832    /// The element dtype of this host view.
6833    ///
6834    /// # Examples
6835    ///
6836    /// ```rust
6837    /// use tenferro_tensor::{DType, TensorViewMut};
6838    ///
6839    /// let mut data = [7_i64];
6840    /// let host = TensorViewMut::i64(&[1], &mut data)?.try_mut_host("example")?;
6841    /// assert_eq!(host.dtype(), DType::I64);
6842    /// # Ok::<(), tenferro_tensor::Error>(())
6843    /// ```
6844    pub fn dtype(&self) -> DType {
6845        match self {
6846            Self::F32(_) => DType::F32,
6847            Self::F64(_) => DType::F64,
6848            Self::I32(_) => DType::I32,
6849            Self::I64(_) => DType::I64,
6850            Self::Bool(_) => DType::Bool,
6851            Self::C32(_) => DType::C32,
6852            Self::C64(_) => DType::C64,
6853        }
6854    }
6855
6856    /// The logical shape of this host view.
6857    ///
6858    /// # Examples
6859    ///
6860    /// ```rust
6861    /// use tenferro_tensor::TensorViewMut;
6862    ///
6863    /// let mut data = [1.0_f32, 2.0];
6864    /// let host = TensorViewMut::f32(&[2], &mut data)?.try_mut_host("example")?;
6865    /// assert_eq!(host.shape(), &[2]);
6866    /// # Ok::<(), tenferro_tensor::Error>(())
6867    /// ```
6868    pub fn shape(&self) -> &[usize] {
6869        match self {
6870            Self::F32(view) => view.shape(),
6871            Self::F64(view) => view.shape(),
6872            Self::I32(view) => view.shape(),
6873            Self::I64(view) => view.shape(),
6874            Self::Bool(view) => view.shape(),
6875            Self::C32(view) => view.shape(),
6876            Self::C64(view) => view.shape(),
6877        }
6878    }
6879
6880    /// The strides of this host view in element units.
6881    ///
6882    /// # Examples
6883    ///
6884    /// ```rust
6885    /// use tenferro_tensor::TensorViewMut;
6886    ///
6887    /// let mut data = [0.0_f64; 6];
6888    /// let host = TensorViewMut::f64(&[2, 3], &mut data)?.try_mut_host("example")?;
6889    /// assert_eq!(host.strides(), &[1, 2]);
6890    /// # Ok::<(), tenferro_tensor::Error>(())
6891    /// ```
6892    pub fn strides(&self) -> &[isize] {
6893        match self {
6894            Self::F32(view) => view.strides(),
6895            Self::F64(view) => view.strides(),
6896            Self::I32(view) => view.strides(),
6897            Self::I64(view) => view.strides(),
6898            Self::Bool(view) => view.strides(),
6899            Self::C32(view) => view.strides(),
6900            Self::C64(view) => view.strides(),
6901        }
6902    }
6903}
6904
6905/// Read-only tensor input accepted by synchronous eager kernels.
6906///
6907/// `TensorRead` lets kernels accept either an owned tensor reference or a
6908/// borrowed [`TensorView`] without forcing callers to materialize first.
6909/// The `View` variant preserves arbitrary strides and offsets, so kernels that
6910/// support strided reads can consume transposes, slices, and broadcasts directly.
6911///
6912/// `TensorRead` is intentionally borrowed. It is an input-dispatch type, not an
6913/// owned lazy tensor value. APIs that need to store a lazy layout result should
6914/// keep an owned base tensor plus layout metadata, then expose a `TensorRead`
6915/// only for the duration of kernel dispatch.
6916///
6917/// # Examples
6918///
6919/// ```
6920/// use tenferro_tensor::{DType, Tensor, TensorRead};
6921///
6922/// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
6923/// let read = TensorRead::from_tensor(&tensor);
6924///
6925/// assert_eq!(read.dtype(), DType::F64);
6926/// assert_eq!(read.shape(), &[2]);
6927/// ```
6928// Keep borrowed views inline to avoid allocation on read-only tensor dispatch paths.
6929#[allow(clippy::large_enum_variant)]
6930#[derive(Clone, Debug)]
6931pub enum TensorRead<'a> {
6932    Tensor(&'a Tensor),
6933    View(TensorView<'a>),
6934}
6935
6936/// Mutable typed tensor output accepted by synchronous eager kernels.
6937///
6938/// `TypedTensorWrite` is the typed counterpart to [`TensorWrite`]. It accepts
6939/// either an owned compact [`TypedTensor`] or an arbitrary-strided mutable
6940/// [`TypedTensorViewMut`] without erasing the scalar type at the public API
6941/// boundary.
6942///
6943/// # Examples
6944///
6945/// ```
6946/// use tenferro_tensor::{TypedTensorViewMut, TypedTensorWrite};
6947///
6948/// let mut data = [0.0_f64, 1.0, 0.0, 2.0];
6949/// let view = TypedTensorViewMut::from_slice([2], [2], 1, &mut data)?;
6950/// let write = TypedTensorWrite::from_view(view).into_tensor_write();
6951/// assert_eq!(write.shape(), &[2]);
6952/// assert_eq!(write.strides()?, [2]);
6953/// # Ok::<(), tenferro_tensor::Error>(())
6954/// ```
6955#[allow(clippy::large_enum_variant)]
6956#[derive(Debug)]
6957pub enum TypedTensorWrite<'a, T> {
6958    /// An owned compact typed tensor borrowed mutably for the write.
6959    Tensor(&'a mut TypedTensor<T>),
6960    /// An arbitrary-strided mutable typed tensor view.
6961    View(TypedTensorViewMut<'a, T>),
6962}
6963
6964impl<'a, T> TypedTensorWrite<'a, T> {
6965    /// Create a writable target from an owned typed tensor.
6966    ///
6967    /// # Examples
6968    ///
6969    /// ```
6970    /// use tenferro_tensor::{TypedTensor, TypedTensorWrite};
6971    ///
6972    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![0.0])?;
6973    /// let write = TypedTensorWrite::from_tensor(&mut tensor);
6974    /// assert!(matches!(write, TypedTensorWrite::Tensor(_)));
6975    /// # Ok::<(), tenferro_tensor::Error>(())
6976    /// ```
6977    pub fn from_tensor(tensor: &'a mut TypedTensor<T>) -> Self {
6978        Self::Tensor(tensor)
6979    }
6980
6981    /// Create a writable target from a mutable typed tensor view.
6982    ///
6983    /// # Examples
6984    ///
6985    /// ```
6986    /// use tenferro_tensor::{TypedTensorViewMut, TypedTensorWrite};
6987    ///
6988    /// let mut data = [0.0_f64, 1.0];
6989    /// let view = TypedTensorViewMut::from_col_major(&[2], &mut data)?;
6990    /// let write = TypedTensorWrite::from_view(view);
6991    /// assert!(matches!(write, TypedTensorWrite::View(_)));
6992    /// # Ok::<(), tenferro_tensor::Error>(())
6993    /// ```
6994    pub fn from_view(view: TypedTensorViewMut<'a, T>) -> Self {
6995        Self::View(view)
6996    }
6997}
6998
6999impl<'a, T: TensorScalar> TypedTensorWrite<'a, T> {
7000    /// Erase the scalar type while preserving the output layout.
7001    ///
7002    /// # Examples
7003    ///
7004    /// ```
7005    /// use tenferro_tensor::{DType, TypedTensor, TypedTensorWrite};
7006    ///
7007    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![0.0; 2])?;
7008    /// let write = TypedTensorWrite::from_tensor(&mut tensor).into_tensor_write();
7009    /// assert_eq!(write.dtype(), DType::F64);
7010    /// assert_eq!(write.shape(), &[2]);
7011    /// # Ok::<(), tenferro_tensor::Error>(())
7012    /// ```
7013    pub fn into_tensor_write(self) -> TensorWrite<'a> {
7014        match self {
7015            Self::Tensor(tensor) => T::tensor_write(tensor),
7016            Self::View(view) => TensorWrite::from_view(T::tensor_view_mut(view)),
7017        }
7018    }
7019}
7020
7021impl<'a, T> From<&'a mut TypedTensor<T>> for TypedTensorWrite<'a, T> {
7022    fn from(tensor: &'a mut TypedTensor<T>) -> Self {
7023        Self::from_tensor(tensor)
7024    }
7025}
7026
7027impl<'a, T> From<TypedTensorViewMut<'a, T>> for TypedTensorWrite<'a, T> {
7028    fn from(view: TypedTensorViewMut<'a, T>) -> Self {
7029        Self::from_view(view)
7030    }
7031}
7032
7033/// Mutable tensor output accepted by synchronous eager kernels.
7034///
7035/// `TensorWrite` mirrors [`TensorRead`] for output dispatch: it can target an
7036/// owned compact [`Tensor`] or a borrowed mutable [`TensorViewMut`]. The target
7037/// is never resized.
7038///
7039/// # Examples
7040///
7041/// ```
7042/// use tenferro_tensor::{Tensor, TensorWrite};
7043///
7044/// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?;
7045/// let write = TensorWrite::from_tensor(&mut tensor);
7046/// assert_eq!(write.shape(), &[1]);
7047/// # Ok::<(), tenferro_tensor::Error>(())
7048/// ```
7049#[allow(clippy::large_enum_variant)]
7050#[derive(Debug)]
7051pub enum TensorWrite<'a> {
7052    Tensor(&'a mut Tensor),
7053    View(TensorViewMut<'a>),
7054}
7055
7056/// Owned tensor value with one move-only physical owner and metadata-only layout.
7057///
7058/// `TensorValue` is intentionally not cloneable. View transformations consume
7059/// the value and move its existing owner; [`TensorValue::duplicate`] is the
7060/// explicit boundary for creating another physical allocation.
7061///
7062/// # Examples
7063///
7064/// ```
7065/// use tenferro_tensor::{Tensor, TensorValue};
7066/// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7067/// let view = value.transpose_view([1, 0])?;
7068/// assert_eq!(view.strides(), &[2, 1]);
7069/// assert!(view.is_view());
7070/// # Ok::<(), tenferro_tensor::Error>(())
7071/// ```
7072#[derive(Debug)]
7073pub struct TensorValue {
7074    owner: Tensor,
7075    layout: TensorLayout<DynRank>,
7076}
7077
7078/// A consuming view transformation failed while retaining its unchanged owner.
7079///
7080/// # Examples
7081///
7082/// ```
7083/// use tenferro_tensor::{Tensor, TensorValue};
7084/// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7085/// let failure = value.try_reshape_view([3]).unwrap_err();
7086/// let (recovered, cause) = failure.into_parts();
7087/// assert_eq!(recovered.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7088/// assert!(matches!(cause, tenferro_tensor::Error::Validation { .. }));
7089/// # Ok::<(), tenferro_tensor::Error>(())
7090/// ```
7091#[derive(Debug)]
7092pub struct TensorValueViewError {
7093    value: TensorValue,
7094    source: crate::Error,
7095}
7096
7097impl TensorValueViewError {
7098    /// Return the unchanged value and the typed validation/backend error.
7099    ///
7100    /// # Examples
7101    ///
7102    /// ```
7103    /// use tenferro_tensor::{Tensor, TensorValue};
7104    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([1], vec![7.])?);
7105    /// let (value, error) = value.try_reshape_view([2]).unwrap_err().into_parts();
7106    /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[7.]);
7107    /// assert!(matches!(error, tenferro_tensor::Error::Validation { .. }));
7108    /// # Ok::<(), tenferro_tensor::Error>(())
7109    /// ```
7110    pub fn into_parts(self) -> (TensorValue, crate::Error) {
7111        (self.value, self.source)
7112    }
7113
7114    fn new(value: TensorValue, source: crate::Error) -> Self {
7115        Self { value, source }
7116    }
7117}
7118
7119impl std::fmt::Display for TensorValueViewError {
7120    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
7121        std::fmt::Display::fmt(&self.source, formatter)
7122    }
7123}
7124
7125impl std::error::Error for TensorValueViewError {
7126    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
7127        Some(&self.source)
7128    }
7129}
7130
7131impl TensorValue {
7132    /// Explicitly duplicate the physical owner represented by this value.
7133    ///
7134    /// # Examples
7135    ///
7136    /// ```
7137    /// use tenferro_tensor::{Tensor, TensorValue};
7138    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7139    /// let copy = value.duplicate()?.into_tensor()?;
7140    /// assert_eq!(copy.as_slice::<f64>()?, &[3., 4.]);
7141    /// assert_eq!(value.shape(), &[2]);
7142    /// # Ok::<(), tenferro_tensor::Error>(())
7143    /// ```
7144    ///
7145    /// # Errors
7146    ///
7147    /// Returns [`crate::Error::RuntimeState`] or [`crate::Error::Unsupported`]
7148    /// when the backend/storage owner cannot be duplicated.
7149    pub fn duplicate(&self) -> crate::Result<Self> {
7150        let tensor = duplicate_backing_storage(&self.owner)?;
7151        Self::from_parts(
7152            tensor,
7153            self.shape().to_vec(),
7154            self.strides().to_vec(),
7155            self.offset(),
7156        )
7157    }
7158
7159    /// Retain a compact tensor as a move-only value.
7160    ///
7161    /// # Examples
7162    ///
7163    /// ```
7164    /// use tenferro_tensor::{Tensor, TensorValue};
7165    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7166    /// assert!(!value.is_view());
7167    /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7168    /// # Ok::<(), tenferro_tensor::Error>(())
7169    /// ```
7170    pub fn from_tensor(tensor: Tensor) -> Self {
7171        let layout = tensor_layout(&tensor);
7172        Self {
7173            owner: tensor,
7174            layout,
7175        }
7176    }
7177
7178    /// # Errors
7179    ///
7180    /// Returns [`ValidationError::InvalidArgument`] or
7181    /// [`ValidationError::IntegerOverflow`] when the supplied layout is
7182    /// invalid for the tensor's physical buffer.
7183    ///
7184    /// # Examples
7185    ///
7186    /// ```
7187    /// use tenferro_tensor::{Tensor, TensorValue};
7188    /// let tensor = Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
7189    /// let view = TensorValue::from_parts(tensor, vec![2], vec![1], 2)?;
7190    /// assert_eq!(view.shape(), &[2]);
7191    /// assert_eq!(view.offset(), 2);
7192    /// # Ok::<(), tenferro_tensor::Error>(())
7193    /// ```
7194    pub fn from_parts(
7195        tensor: Tensor,
7196        shape: Vec<usize>,
7197        strides: Vec<isize>,
7198        offset: isize,
7199    ) -> crate::Result<Self> {
7200        let layout = TensorLayout::from_parts(
7201            shape_vec(&shape),
7202            stride_vec(&strides),
7203            offset,
7204            tensor_buffer_len(&tensor),
7205        )
7206        .map_err(|err| tensor_layout_error("TensorValue::from_parts", err))?;
7207        Ok(Self {
7208            owner: tensor,
7209            layout,
7210        })
7211    }
7212
7213    // INVARIANT: unchanged-owner recovery is part of the consuming ownership
7214    // contract, so this intentionally carries the large move-only error.
7215    #[doc(hidden)]
7216    /// Move the value's sole physical owner into an allocation group.
7217    ///
7218    /// This preserves metadata-only views without copying. The consumed value
7219    /// always contains one unique owner, so no compatibility fallback exists.
7220    ///
7221    /// # Errors
7222    ///
7223    /// Returns the unchanged value when descriptor publication fails because
7224    /// of [`ValidationError::InvalidArgument`] or
7225    /// [`ValidationError::IntegerOverflow`].
7226    #[allow(clippy::result_large_err)]
7227    pub fn try_into_group_parts(
7228        self,
7229    ) -> std::result::Result<(AllocationGroup, DescriptorSlot, DType, Vec<usize>), Self> {
7230        let Self { owner, layout } = self;
7231        if owner.external_payload().is_some() {
7232            // A caller-owned payload owns no allocation group, so it is returned
7233            // unchanged instead of being forced into one.
7234            return Err(Self { owner, layout });
7235        }
7236        let dtype = owner.dtype();
7237        let shape = layout.shape().to_vec();
7238        let strides = layout.strides().to_vec();
7239        let offset = layout.offset();
7240        let (group, slot) = owner.into_group_parts();
7241        match group.update_descriptor_layout(slot, shape, strides, offset) {
7242            Ok(group) => Ok((group, slot, dtype, layout.shape().to_vec())),
7243            Err((_group, _error)) => {
7244                unreachable!("TensorValue layout was validated before group ownership transfer")
7245            }
7246        }
7247    }
7248
7249    /// Consume a value with its owner's original layout and return that owner.
7250    ///
7251    /// # Examples
7252    ///
7253    /// ```
7254    /// use tenferro_tensor::{Tensor, TensorValue};
7255    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7256    /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7257    /// # Ok::<(), tenferro_tensor::Error>(())
7258    /// ```
7259    ///
7260    /// # Errors
7261    ///
7262    /// Returns [`crate::Error::Unsupported`] when the value's metadata-only
7263    /// view differs from its physical owner's layout.
7264    pub fn into_tensor(self) -> crate::Result<Tensor> {
7265        if self.layout != tensor_layout(&self.owner) {
7266            return Err(crate::Error::unsupported(
7267                "TensorValue::into_tensor",
7268                "a metadata-only view has no compact tensor owner",
7269            ));
7270        }
7271        Ok(self.owner)
7272    }
7273
7274    ///
7275    /// # Examples
7276    ///
7277    /// ```
7278    /// use tenferro_tensor::{Tensor, TensorValue};
7279    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7280    /// assert_eq!(value.as_tensor().unwrap().as_slice::<f64>()?, &[1., 2., 3., 4.]);
7281    /// assert!(value.transpose_view([1, 0])?.as_tensor().is_none());
7282    /// # Ok::<(), tenferro_tensor::Error>(())
7283    /// ```
7284    pub fn as_tensor(&self) -> Option<&Tensor> {
7285        (self.layout == tensor_layout(&self.owner)).then_some(&self.owner)
7286    }
7287
7288    ///
7289    /// # Examples
7290    ///
7291    /// ```
7292    /// use tenferro_tensor::{Tensor, TensorValue};
7293    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7294    /// assert!(!value.is_view());
7295    /// assert!(value.transpose_view([1, 0])?.is_view());
7296    /// # Ok::<(), tenferro_tensor::Error>(())
7297    /// ```
7298    pub fn is_view(&self) -> bool {
7299        self.as_tensor().is_none()
7300    }
7301
7302    ///
7303    /// # Examples
7304    ///
7305    /// ```
7306    /// use tenferro_tensor::{Tensor, TensorValue};
7307    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7308    /// assert_eq!(value.dtype(), tenferro_tensor::DType::F64);
7309    /// # Ok::<(), tenferro_tensor::Error>(())
7310    /// ```
7311    pub fn dtype(&self) -> DType {
7312        self.owner.dtype()
7313    }
7314
7315    ///
7316    /// # Examples
7317    ///
7318    /// ```
7319    /// use tenferro_tensor::{Tensor, TensorValue};
7320    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7321    /// assert_eq!(value.reshape_view([4])?.shape(), &[4]);
7322    /// # Ok::<(), tenferro_tensor::Error>(())
7323    /// ```
7324    pub fn shape(&self) -> &[usize] {
7325        self.layout.shape()
7326    }
7327
7328    ///
7329    /// # Examples
7330    ///
7331    /// ```
7332    /// use tenferro_tensor::{Tensor, TensorValue};
7333    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7334    /// assert_eq!(value.transpose_view([1, 0])?.strides(), &[2, 1]);
7335    /// # Ok::<(), tenferro_tensor::Error>(())
7336    /// ```
7337    pub fn strides(&self) -> &[isize] {
7338        self.layout.strides()
7339    }
7340
7341    ///
7342    /// # Examples
7343    ///
7344    /// ```
7345    /// use tenferro_tensor::{Tensor, TensorValue};
7346    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7347    /// assert_eq!(value.offset(), 0);
7348    /// # Ok::<(), tenferro_tensor::Error>(())
7349    /// ```
7350    pub fn offset(&self) -> isize {
7351        self.layout.offset()
7352    }
7353
7354    /// Borrow this value as a dtype-erased view, or `None` when it holds an
7355    /// externally defined payload.
7356    ///
7357    /// [`TensorView`] has one variant per preset scalar (`F32` ... `C64`) and none
7358    /// for a caller-owned element type, so a value built from
7359    /// [`Tensor::external`] has no view; read it through
7360    /// [`Tensor::external_payload`] instead.
7361    ///
7362    /// # Examples
7363    ///
7364    /// ```
7365    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, Tensor, TensorValue, TypedTensor};
7366    ///
7367    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7368    /// let view = value.tensor_view().ok_or("a preset f64 value has a view")?;
7369    /// assert_eq!(view.shape(), &[2, 2]);
7370    /// assert_eq!(view.dtype(), tenferro_tensor::DType::F64);
7371    ///
7372    /// let payload = ErasedHostTensor::new(
7373    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1., 2.])?,
7374    /// );
7375    /// let external = TensorValue::from_tensor(Tensor::external(payload));
7376    /// assert!(external.tensor_view().is_none());
7377    /// # Ok::<(), Box<dyn std::error::Error>>(())
7378    /// ```
7379    #[must_use]
7380    pub fn tensor_view(&self) -> Option<TensorView<'_>> {
7381        tensor_view_with_layout(&self.owner, self.layout.clone())
7382    }
7383
7384    /// Borrow this value as a [`TensorRead`], or `None` when it is a
7385    /// metadata-only view of an externally defined payload.
7386    ///
7387    /// A value whose layout equals its owner's is borrowed as the owner tensor,
7388    /// whatever its dtype. Any other value is borrowed through
7389    /// [`TensorValue::tensor_view`], which has no variant for a payload built with
7390    /// [`Tensor::external`].
7391    ///
7392    /// # Examples
7393    ///
7394    /// ```
7395    /// use tenferro_tensor::{Tensor, TensorValue};
7396    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7397    /// let read = value.tensor_read().ok_or("a preset f64 value has a read")?;
7398    /// assert_eq!(read.shape(), &[2, 2]);
7399    /// assert_eq!(read.dtype(), tenferro_tensor::DType::F64);
7400    /// # Ok::<(), Box<dyn std::error::Error>>(())
7401    /// ```
7402    #[must_use]
7403    pub fn tensor_read(&self) -> Option<TensorRead<'_>> {
7404        match self.as_tensor() {
7405            Some(tensor) => Some(TensorRead::from_tensor(tensor)),
7406            None => self.tensor_view().map(TensorRead::from_view),
7407        }
7408    }
7409
7410    /// # Errors
7411    ///
7412    /// Returns [`crate::Error::Validation`] with
7413    /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
7414    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
7415    /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
7416    /// not a valid permutation of the value rank.
7417    ///
7418    /// # Examples
7419    ///
7420    /// ```
7421    /// use tenferro_tensor::{Tensor, TensorValue};
7422    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7423    /// let view = value.transpose_view([1, 0])?;
7424    /// assert_eq!(view.strides(), &[2, 1]);
7425    /// assert!(view.is_view());
7426    /// # Ok::<(), tenferro_tensor::Error>(())
7427    /// ```
7428    pub fn transpose_view(self, axes: impl AsRef<[usize]>) -> crate::Result<Self> {
7429        let layout = self
7430            .layout
7431            .transpose_view(axes)
7432            .map_err(|err| tensor_layout_error("TensorValue::transpose_view", err))?;
7433        Ok(Self {
7434            owner: self.owner,
7435            layout,
7436        })
7437    }
7438
7439    // INVARIANT: unchanged-owner recovery is part of the consuming view
7440    // contract, so this intentionally carries the large move-only error.
7441    /// # Errors
7442    ///
7443    /// Returns [`crate::Error::Validation`] with
7444    /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
7445    /// the source is not compact column-major,
7446    /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
7447    /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
7448    /// records the counts) when element counts differ,
7449    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for shape
7450    /// arithmetic overflow, or
7451    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7452    /// reshaped view exceeds the backing buffer.
7453    #[allow(clippy::result_large_err)]
7454    ///
7455    /// # Examples
7456    ///
7457    /// ```
7458    /// use tenferro_tensor::{Tensor, TensorValue};
7459    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7460    /// let (recovered, error) = value.try_reshape_view([3]).unwrap_err().into_parts();
7461    /// assert_eq!(recovered.into_tensor()?.as_slice::<f64>()?, &[1., 2., 3., 4.]);
7462    /// assert!(matches!(error, tenferro_tensor::Error::Validation { .. }));
7463    /// # Ok::<(), tenferro_tensor::Error>(())
7464    /// ```
7465    pub fn try_reshape_view(
7466        self,
7467        shape: impl tenferro_tensor_core::IntoShapeVec,
7468    ) -> std::result::Result<Self, TensorValueViewError> {
7469        let shape = shape.into_shape_vec();
7470        let layout = match reshape_layout_dyn(
7471            &self.layout,
7472            &shape,
7473            tensor_buffer_len(&self.owner),
7474            "TensorValue::reshape_view",
7475        ) {
7476            Ok(layout) => layout,
7477            Err(error) => return Err(TensorValueViewError::new(self, error)),
7478        };
7479        Ok(Self {
7480            owner: self.owner,
7481            layout,
7482        })
7483    }
7484
7485    /// # Errors
7486    ///
7487    /// Returns [`crate::Error::Validation`] with
7488    /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]
7489    /// when the source is not compact, [`tenferro_tensor_core::ValidationError::ShapeMismatch`]
7490    /// when element counts differ, or [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
7491    /// / [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] for invalid
7492    /// target-shape arithmetic or bounds.
7493    ///
7494    /// # Examples
7495    ///
7496    /// ```
7497    /// use tenferro_tensor::{Tensor, TensorValue};
7498    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7499    /// let view = value.reshape_view([4])?;
7500    /// assert_eq!(view.shape(), &[4]);
7501    /// assert_eq!(view.strides(), &[1]);
7502    /// # Ok::<(), tenferro_tensor::Error>(())
7503    /// ```
7504    pub fn reshape_view(
7505        self,
7506        shape: impl tenferro_tensor_core::IntoShapeVec,
7507    ) -> crate::Result<Self> {
7508        self.try_reshape_view(shape).map_err(|error| error.source)
7509    }
7510
7511    /// # Errors
7512    ///
7513    /// Returns [`crate::Error::Validation`] with
7514    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when a slice
7515    /// vector does not match the value rank,
7516    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when a bound
7517    /// or stride cannot be represented or is invalid,
7518    /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
7519    /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for slice
7520    /// parameters, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
7521    /// for slice arithmetic overflow, or
7522    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7523    /// result exceeds the backing buffer.
7524    ///
7525    /// # Examples
7526    ///
7527    /// ```
7528    /// use tenferro_tensor::{Tensor, TensorValue};
7529    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7530    /// let view = value.slice_view(&tenferro_tensor::SliceConfig {
7531    ///    starts: vec![0, 1], limits: vec![2, 2], strides: vec![1, 1],
7532    /// })?;
7533    /// assert_eq!(view.shape(), &[2, 1]);
7534    /// assert_eq!(view.offset(), 2);
7535    /// # Ok::<(), tenferro_tensor::Error>(())
7536    /// ```
7537    pub fn slice_view(self, config: &SliceConfig) -> crate::Result<Self> {
7538        let op = "TensorValue::slice_view";
7539        if config.starts.len() != self.shape().len()
7540            || config.limits.len() != self.shape().len()
7541            || config.strides.len() != self.shape().len()
7542        {
7543            return Err(crate::Error::validation(
7544                op,
7545                ValidationError::RankMismatch {
7546                    expected: self.shape().len(),
7547                    actual: config.starts.len(),
7548                },
7549            ));
7550        }
7551        // The per-axis specs stay inline: a metadata-only slice must not
7552        // allocate its own scratch at rank <= 8 (#2040).
7553        let mut specs = TinyVec::<[CoreSliceSpec; 8]>::with_capacity(self.shape().len());
7554        for (((&start, &limit), &stride), &axis_len) in config
7555            .starts
7556            .iter()
7557            .zip(config.limits.iter())
7558            .zip(config.strides.iter())
7559            .zip(self.shape())
7560        {
7561            let start = isize::try_from(start).map_err(|_| {
7562                crate::Error::invalid_argument(
7563                    op,
7564                    "slice start",
7565                    "slice start does not fit in isize",
7566                )
7567            })?;
7568            let limit = isize::try_from(limit).map_err(|_| {
7569                crate::Error::invalid_argument(
7570                    op,
7571                    "slice limit",
7572                    "slice limit does not fit in isize",
7573                )
7574            })?;
7575            let stride = isize::try_from(stride).map_err(|_| {
7576                crate::Error::invalid_argument(
7577                    op,
7578                    "slice stride",
7579                    "slice stride does not fit in isize",
7580                )
7581            })?;
7582            specs.push(core_slice_spec(
7583                StridedSliceSpec::new(start, Some(limit), stride),
7584                axis_len,
7585                op,
7586            )?);
7587        }
7588        let layout = self
7589            .layout
7590            .slice_view(&specs, tensor_buffer_len(&self.owner))
7591            .map_err(|err| tensor_layout_error(op, err))?;
7592        Ok(Self {
7593            owner: self.owner,
7594            layout,
7595        })
7596    }
7597
7598    /// # Errors
7599    ///
7600    /// Returns [`crate::Error::Validation`] with
7601    /// [`tenferro_tensor_core::ValidationError::RankMismatch`],
7602    /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
7603    /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] for invalid
7604    /// dimension mappings,
7605    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] for
7606    /// incompatible extents,
7607    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7608    /// result exceeds the backing buffer, or
7609    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
7610    /// arithmetic overflow.
7611    ///
7612    /// # Examples
7613    ///
7614    /// ```
7615    /// use tenferro_tensor::{Tensor, TensorValue};
7616    /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7617    /// let view = value.broadcast_in_dim_view([2, 3], [0])?;
7618    /// assert_eq!(view.shape(), &[2, 3]);
7619    /// assert_eq!(view.strides(), &[1, 0]);
7620    /// # Ok::<(), tenferro_tensor::Error>(())
7621    /// ```
7622    pub fn broadcast_in_dim_view(
7623        self,
7624        shape: impl tenferro_tensor_core::IntoShapeVec,
7625        dims: impl AsRef<[usize]>,
7626    ) -> crate::Result<Self> {
7627        let shape = shape.into_shape_vec();
7628        let layout = self
7629            .layout
7630            .broadcast_in_dim_view::<DynRank>(shape, dims, tensor_buffer_len(&self.owner))
7631            .map_err(|err| tensor_layout_error("TensorValue::broadcast_in_dim_view", err))?;
7632        Ok(Self {
7633            owner: self.owner,
7634            layout,
7635        })
7636    }
7637}
7638
7639/// Copy a value's backing storage into a fresh owned tensor carrying `layout`.
7640///
7641/// A value layout is relative to its owner's backing root. For a plain compact
7642/// owner that root is the owner itself, and [`TypedTensor::duplicate`] is
7643/// enough. A root-preserving extraction (#2023) exports only its descriptor
7644/// extent over a wider root, so the copy has to carry the root and be rebased
7645/// onto the same descriptor layout.
7646fn duplicate_backing_storage(tensor: &Tensor) -> crate::Result<Tensor> {
7647    fn typed<T: TensorScalar>(tensor: &TypedTensor<T>) -> crate::Result<Tensor> {
7648        // The owner's descriptor, not the outer value layout: the copy is an
7649        // owner of the same kind, and a value layout may be a strided view over
7650        // it that the owner must not adopt.
7651        let layout = tensor.physical_layout();
7652        // `as_view().host_storage()` reports the whole root for a host owner
7653        // (including one produced by an owning reinterpretation) and refuses a
7654        // backend owner, which `buffer()` cannot express.
7655        let root = tensor.as_view().host_storage()?.to_vec();
7656        let op = "TensorValue::duplicate";
7657        let (group, slot) =
7658            AllocationGroup::from_host_vec::<T, DynRank>(shape_vec(&[root.len()]), root)
7659                .map_err(|error| crate::Error::runtime_state_source(op, error))?;
7660        let group = group
7661            .update_descriptor_layout(
7662                slot,
7663                layout.shape().to_vec(),
7664                layout.strides().to_vec(),
7665                layout.offset(),
7666            )
7667            .map_err(|(_, error)| crate::Error::runtime_state_source(op, error))?;
7668        let allocation = group
7669            .allocation_index(slot)
7670            .unwrap_or_else(|_| unreachable!("the duplicate group carries a live descriptor"));
7671        let descriptor_layout = group
7672            .descriptor_layout(slot)
7673            .unwrap_or_else(|| unreachable!("the duplicate group carries a live descriptor"));
7674        let placement = tensor.placement().clone();
7675        Ok(tensor_from_group(
7676            group,
7677            slot,
7678            allocation,
7679            T::dtype(),
7680            descriptor_layout,
7681            placement,
7682        ))
7683    }
7684
7685    match &tensor.payload {
7686        // A caller-owned payload keeps its existing duplication route: it has no
7687        // allocation group to rebuild.
7688        TensorPayload::External(..) => tensor.duplicate(),
7689        TensorPayload::Native(preset) => with_preset!(preset, |inner| typed(inner)),
7690    }
7691}
7692
7693fn tensor_layout(tensor: &Tensor) -> TensorLayout<DynRank> {
7694    match &tensor.payload {
7695        // A caller-owned payload carries its own view layout, so strides and offset
7696        // come from the payload rather than from a compact assumption.
7697        TensorPayload::External(payload, _) => TensorLayout::<DynRank>::from_parts(
7698            shape_vec(payload.shape()),
7699            stride_vec(payload.strides()),
7700            payload.offset(),
7701            payload.payload_element_count(),
7702        )
7703        .unwrap_or_else(|_| {
7704            // INVARIANT: a payload is built from a validated host tensor, and the
7705            // only layout change is a permutation, so its strides stay inside the
7706            // payload it was created from and this construction cannot fail.
7707            unreachable!("a validated payload yields a layout inside its own storage")
7708        }),
7709        TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.physical_layout()),
7710    }
7711}
7712
7713fn tensor_buffer_len(tensor: &Tensor) -> usize {
7714    match &tensor.payload {
7715        // A caller-owned payload stores its element count directly.
7716        TensorPayload::External(payload, _) => payload.element_count(),
7717        TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.buffer_len()),
7718    }
7719}
7720
7721fn prepare_backend_access<'a, T: 'static, R: TensorRank>(
7722    buffer: &'a dyn BackendStorage<T>,
7723    layout: &'a TensorLayout<R>,
7724    op: &'static str,
7725) -> crate::Result<Box<dyn PreparedDeviceAccess + 'a>> {
7726    let domain = buffer.allocation_domain().ok_or_else(|| {
7727        crate::Error::runtime_state(op, "backend buffer is missing an allocation domain")
7728    })?;
7729    let allocation_id = buffer.allocation_id().ok_or_else(|| {
7730        crate::Error::runtime_state(op, "backend buffer is missing an allocation identity")
7731    })?;
7732    let byte_len = buffer
7733        .len()
7734        .checked_mul(size_of::<T>())
7735        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
7736    let request = DeviceAccessRequest::new(
7737        domain,
7738        allocation_id,
7739        byte_len,
7740        size_of::<T>(),
7741        layout.shape(),
7742        layout.strides(),
7743        layout.offset(),
7744    );
7745    buffer
7746        .prepare_device_access(request)
7747        .map_err(|error| crate::Error::runtime_state_source(op, error))
7748}
7749
7750fn cast_view_slice<S: 'static, T: TensorScalar>(source: &[S]) -> crate::Result<&[T]> {
7751    if size_of::<S>() != size_of::<T>() || align_of::<S>() != align_of::<T>() {
7752        return Err(crate::Error::invalid_argument(
7753            "TensorView::as_slice",
7754            "dtype",
7755            "matching dtypes must have identical scalar layout",
7756        ));
7757    }
7758    // SAFETY: the dtype check above is exhaustive over the sealed scalar set;
7759    // equal size/alignment preserve the element boundaries and the source
7760    // slice remains borrowed for the returned lifetime.
7761    Ok(unsafe { std::slice::from_raw_parts(source.as_ptr().cast::<T>(), source.len()) })
7762}
7763
7764/// Re-layout a borrowed typed view while keeping its buffer, retained root and
7765/// placement.
7766///
7767/// #2143 item 1: an eager implicit broadcast is a metadata change, so the view
7768/// keeps reading the same storage through zero strides instead of copying the
7769/// broadcast tensor into a fresh allocation.
7770fn broadcast_typed_view<'a, T: 'static, R: TensorRank>(
7771    view: TypedTensorView<'a, T, R>,
7772    shape: &[usize],
7773    dims: &[usize],
7774) -> crate::Result<TypedTensorView<'a, T, R>> {
7775    let shape = R::shape_from_vec(shape_vec(shape))
7776        .map_err(|err| tensor_layout_error("TensorRead::broadcast_in_dim_view", err))?;
7777    let layout = view
7778        .layout()
7779        .broadcast_in_dim_view::<R>(shape, dims, view.backing_len())
7780        .map_err(|err| tensor_layout_error("TensorRead::broadcast_in_dim_view", err))?;
7781    Ok(TypedTensorView {
7782        buffer: view.buffer,
7783        root: view.root,
7784        layout,
7785        placement: view.placement,
7786        _representation: std::marker::PhantomData,
7787    })
7788}
7789
7790/// Borrow `tensor` as a preset-scalar view with `layout`, or `None` for an
7791/// externally defined payload: `TensorView` has one variant per preset scalar and
7792/// none for a caller-owned element type, and [`Tensor::external`] is public, so
7793/// that case is reachable and is answered rather than asserted away (#2486).
7794fn tensor_view_with_layout(
7795    tensor: &Tensor,
7796    layout: TensorLayout<DynRank>,
7797) -> Option<TensorView<'_>> {
7798    Some(match tensor.dtype() {
7799        DType::F32 => TensorView::F32(typed_view_with_layout(
7800            tensor
7801                .as_typed::<f32>()
7802                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7803            layout,
7804        )),
7805        DType::F64 => TensorView::F64(typed_view_with_layout(
7806            tensor
7807                .as_typed::<f64>()
7808                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7809            layout,
7810        )),
7811        DType::I32 => TensorView::I32(typed_view_with_layout(
7812            tensor
7813                .as_typed::<i32>()
7814                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7815            layout,
7816        )),
7817        DType::I64 => TensorView::I64(typed_view_with_layout(
7818            tensor
7819                .as_typed::<i64>()
7820                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7821            layout,
7822        )),
7823        DType::Bool => TensorView::Bool(typed_view_with_layout(
7824            tensor
7825                .as_typed::<bool>()
7826                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7827            layout,
7828        )),
7829        DType::C32 => TensorView::C32(typed_view_with_layout(
7830            tensor
7831                .as_typed::<Complex<f32>>()
7832                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7833            layout,
7834        )),
7835        DType::C64 => TensorView::C64(typed_view_with_layout(
7836            tensor
7837                .as_typed::<Complex<f64>>()
7838                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7839            layout,
7840        )),
7841        DType::External(_) => return None,
7842    })
7843}
7844
7845fn typed_view_with_layout<T: TensorScalar + 'static>(
7846    tensor: &TypedTensor<T>,
7847    layout: TensorLayout<DynRank>,
7848) -> TypedTensorView<'_, T> {
7849    match &tensor.storage {
7850        DynamicStorage::Host(HostStorage { data }) => TypedTensorView {
7851            buffer: TensorStorageRef::Host(data.as_slice()),
7852            root: None,
7853            layout,
7854            placement: tensor.placement.clone(),
7855            _representation: std::marker::PhantomData,
7856        },
7857        DynamicStorage::Group(core) => {
7858            let root = core.group.view::<T>().unwrap_or_else(|error| {
7859                unreachable!("typed tensor group descriptor mismatch: {error}")
7860            });
7861            let buffer = if let Some(allocation) = root.backend_allocation() {
7862                TensorStorageRef::Root(allocation)
7863            } else {
7864                TensorStorageRef::Host(tensor.group_host_slice())
7865            };
7866            TypedTensorView {
7867                buffer,
7868                root: Some(root),
7869                layout,
7870                placement: tensor.placement.clone(),
7871                _representation: std::marker::PhantomData,
7872            }
7873        }
7874    }
7875}
7876
7877pub(crate) fn tensor_view_from_group<'a, T: TensorScalar>(
7878    view: GroupReadView<'a, T, DynRank>,
7879) -> crate::Result<TensorView<'a>> {
7880    let buffer = if let Some(allocation) = view.backend_allocation() {
7881        TensorStorageRef::Root(allocation)
7882    } else {
7883        let storage = view.storage_buffer();
7884        match storage {
7885            Some(StorageBuffer::Host(data)) => TensorStorageRef::Host(data),
7886            Some(StorageBuffer::Backend(buffer)) => TensorStorageRef::Backend(buffer.as_ref()),
7887            // A sealed representation reinterpretation changes the descriptor's
7888            // dtype while the host root keeps its own, so the typed downcast
7889            // above cannot see it.
7890            None => match view.host_root_slice() {
7891                Some(data) => TensorStorageRef::Host(data),
7892                None => {
7893                    return Err(crate::Error::runtime_state(
7894                        "AllocationGroup::tensor_read",
7895                        "group descriptor has no backing storage",
7896                    ));
7897                }
7898            },
7899        }
7900    };
7901    let layout = view.descriptor().layout().clone();
7902    let placement = view.descriptor().placement().clone();
7903    let typed = TypedTensorView {
7904        buffer,
7905        root: Some(view.clone()),
7906        layout,
7907        placement,
7908        _representation: std::marker::PhantomData,
7909    };
7910    Ok(T::tensor_view(typed))
7911}
7912
7913pub(crate) fn tensor_from_group(
7914    group: AllocationGroup,
7915    slot: DescriptorSlot,
7916    allocation_index: AllocationSlot,
7917    dtype: DType,
7918    layout: TensorLayout<DynRank>,
7919    placement: Placement,
7920) -> Tensor {
7921    fn typed<T: TensorScalar>(
7922        group: AllocationGroup,
7923        slot: DescriptorSlot,
7924        allocation_index: AllocationSlot,
7925        layout: TensorLayout<DynRank>,
7926        placement: Placement,
7927    ) -> TypedTensor<T> {
7928        let descriptor_dtype = group
7929            .descriptor_dtype(slot)
7930            .unwrap_or_else(|| unreachable!("tensor_from_group requires a live typed descriptor"));
7931        assert_eq!(
7932            descriptor_dtype,
7933            T::dtype(),
7934            "managed typed owner must match its descriptor dtype",
7935        );
7936        let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
7937        TypedTensor {
7938            shape: shape_vec(layout.shape()),
7939            placement,
7940            layout: stride_vec(layout.strides()),
7941            storage: DynamicStorage::Group(GroupStorage {
7942                group: Box::new(OwnedTensorGroup {
7943                    group,
7944                    slot,
7945                    allocation_index,
7946                    host_ptr,
7947                    host_byte_len,
7948                    _rank: PhantomData,
7949                }),
7950            }),
7951        }
7952    }
7953
7954    match dtype {
7955        DType::F32 => <f32 as TensorScalar>::typed_tensor_into_tensor(typed::<f32>(
7956            group,
7957            slot,
7958            allocation_index,
7959            layout,
7960            placement,
7961        )),
7962        DType::F64 => <f64 as TensorScalar>::typed_tensor_into_tensor(typed::<f64>(
7963            group,
7964            slot,
7965            allocation_index,
7966            layout,
7967            placement,
7968        )),
7969        DType::I32 => <i32 as TensorScalar>::typed_tensor_into_tensor(typed::<i32>(
7970            group,
7971            slot,
7972            allocation_index,
7973            layout,
7974            placement,
7975        )),
7976        DType::I64 => <i64 as TensorScalar>::typed_tensor_into_tensor(typed::<i64>(
7977            group,
7978            slot,
7979            allocation_index,
7980            layout,
7981            placement,
7982        )),
7983        DType::Bool => <bool as TensorScalar>::typed_tensor_into_tensor(typed::<bool>(
7984            group,
7985            slot,
7986            allocation_index,
7987            layout,
7988            placement,
7989        )),
7990        DType::C32 => <Complex<f32> as TensorScalar>::typed_tensor_into_tensor(
7991            typed::<Complex<f32>>(group, slot, allocation_index, layout, placement),
7992        ),
7993        DType::C64 => <Complex<f64> as TensorScalar>::typed_tensor_into_tensor(
7994            typed::<Complex<f64>>(group, slot, allocation_index, layout, placement),
7995        ),
7996        // INVARIANT: an allocation group is created from a sealed preset scalar,
7997        // so it can never carry an externally defined one. External payloads are
7998        // caller-owned and do not enter a group.
7999        DType::External(_) => unreachable!("allocation groups are preset-typed"),
8000    }
8001}
8002
8003/// Wrap an `f64` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8004///
8005/// # Examples
8006///
8007/// ```
8008/// use tenferro_tensor::{Tensor, TypedTensor};
8009///
8010/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
8011/// let tensor: Tensor = typed.into();
8012/// assert_eq!(tensor.shape(), &[2]);
8013/// ```
8014impl From<TypedTensor<f64>> for Tensor {
8015    fn from(t: TypedTensor<f64>) -> Self {
8016        Tensor::from_typed(t)
8017    }
8018}
8019
8020/// Wrap an `f32` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8021///
8022/// # Examples
8023///
8024/// ```
8025/// use tenferro_tensor::{Tensor, TypedTensor};
8026///
8027/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f32, 2.0]).unwrap();
8028/// let tensor: Tensor = typed.into();
8029/// assert_eq!(tensor.shape(), &[2]);
8030/// ```
8031impl From<TypedTensor<f32>> for Tensor {
8032    fn from(t: TypedTensor<f32>) -> Self {
8033        Tensor::from_typed(t)
8034    }
8035}
8036
8037/// Wrap an `i64` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8038///
8039/// # Examples
8040///
8041/// ```
8042/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8043///
8044/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i64, 2]).unwrap();
8045/// let tensor: Tensor = typed.into();
8046/// assert_eq!(tensor.dtype(), DType::I64);
8047/// assert_eq!(tensor.shape(), &[2]);
8048/// ```
8049impl From<TypedTensor<i64>> for Tensor {
8050    fn from(t: TypedTensor<i64>) -> Self {
8051        Tensor::from_typed(t)
8052    }
8053}
8054
8055/// Wrap an `i32` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8056///
8057/// # Examples
8058///
8059/// ```
8060/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8061///
8062/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i32, 2]).unwrap();
8063/// let tensor: Tensor = typed.into();
8064/// assert_eq!(tensor.dtype(), DType::I32);
8065/// assert_eq!(tensor.shape(), &[2]);
8066/// ```
8067impl From<TypedTensor<i32>> for Tensor {
8068    fn from(t: TypedTensor<i32>) -> Self {
8069        Tensor::from_typed(t)
8070    }
8071}
8072
8073/// Wrap a `bool` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8074///
8075/// # Examples
8076///
8077/// ```
8078/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8079///
8080/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![true, false]).unwrap();
8081/// let tensor: Tensor = typed.into();
8082/// assert_eq!(tensor.dtype(), DType::Bool);
8083/// assert_eq!(tensor.shape(), &[2]);
8084/// ```
8085impl From<TypedTensor<bool>> for Tensor {
8086    fn from(t: TypedTensor<bool>) -> Self {
8087        Tensor::from_typed(t)
8088    }
8089}
8090
8091/// Wrap a [`Complex64`] [`TypedTensor`] into the corresponding [`Tensor`]
8092/// variant.
8093///
8094/// # Examples
8095///
8096/// ```
8097/// use num_complex::Complex64;
8098/// use tenferro_tensor::{Tensor, TypedTensor};
8099///
8100/// let typed = TypedTensor::from_vec_col_major(
8101///     vec![1],
8102///     vec![Complex64::new(1.0, 2.0)],
8103/// ).unwrap();
8104/// let tensor: Tensor = typed.into();
8105/// assert_eq!(tensor.shape(), &[1]);
8106/// ```
8107impl From<TypedTensor<Complex<f64>>> for Tensor {
8108    fn from(t: TypedTensor<Complex<f64>>) -> Self {
8109        Tensor::from_typed(t)
8110    }
8111}
8112
8113/// Wrap a [`Complex32`] [`TypedTensor`] into the corresponding [`Tensor`]
8114/// variant.
8115///
8116/// # Examples
8117///
8118/// ```
8119/// use num_complex::Complex32;
8120/// use tenferro_tensor::{Tensor, TypedTensor};
8121///
8122/// let typed = TypedTensor::from_vec_col_major(
8123///     vec![1],
8124///     vec![Complex32::new(1.0, 2.0)],
8125/// ).unwrap();
8126/// let tensor: Tensor = typed.into();
8127/// assert_eq!(tensor.shape(), &[1]);
8128/// ```
8129impl From<TypedTensor<Complex<f32>>> for Tensor {
8130    fn from(t: TypedTensor<Complex<f32>>) -> Self {
8131        Tensor::from_typed(t)
8132    }
8133}
8134
8135impl<'a> TensorView<'a> {
8136    /// Create a dynamic `f32` view over compact column-major host data.
8137    ///
8138    /// # Examples
8139    ///
8140    /// ```
8141    /// use tenferro_tensor::{DType, TensorView};
8142    ///
8143    /// let data = [1.0_f32, 2.0];
8144    /// let view = TensorView::f32(&[2], &data)?;
8145    /// assert_eq!(view.dtype(), DType::F32);
8146    /// # Ok::<(), tenferro_tensor::Error>(())
8147    /// ```
8148    /// # Errors
8149    ///
8150    /// Returns [`crate::Error::Validation`] with
8151    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8152    /// shape or offset arithmetic overflow, or
8153    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8154    /// compact shape reaches beyond `data`.
8155    pub fn f32(shape: &'a [usize], data: &'a [f32]) -> crate::Result<Self> {
8156        Ok(Self::F32(TypedTensorView::from_col_major(shape, data)?))
8157    }
8158
8159    /// Create a dynamic `f64` view over compact column-major host data.
8160    ///
8161    /// # Examples
8162    ///
8163    /// ```
8164    /// use tenferro_tensor::{DType, TensorView};
8165    ///
8166    /// let data = [1.0_f64, 2.0];
8167    /// let view = TensorView::f64(&[2], &data)?;
8168    /// assert_eq!(view.dtype(), DType::F64);
8169    /// # Ok::<(), tenferro_tensor::Error>(())
8170    /// ```
8171    /// # Errors
8172    ///
8173    /// Returns [`crate::Error::Validation`] with
8174    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8175    /// shape or offset arithmetic overflow, or
8176    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8177    /// compact shape reaches beyond `data`.
8178    pub fn f64(shape: &'a [usize], data: &'a [f64]) -> crate::Result<Self> {
8179        Ok(Self::F64(TypedTensorView::from_col_major(shape, data)?))
8180    }
8181
8182    /// Create a dynamic `i64` view over compact column-major host data.
8183    ///
8184    /// # Examples
8185    ///
8186    /// ```
8187    /// use tenferro_tensor::{DType, TensorView};
8188    ///
8189    /// let data = [1_i64, 2];
8190    /// let view = TensorView::i64(&[2], &data)?;
8191    /// assert_eq!(view.dtype(), DType::I64);
8192    /// # Ok::<(), tenferro_tensor::Error>(())
8193    /// ```
8194    /// # Errors
8195    ///
8196    /// Returns [`crate::Error::Validation`] with
8197    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8198    /// shape or offset arithmetic overflow, or
8199    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8200    /// compact shape reaches beyond `data`.
8201    pub fn i64(shape: &'a [usize], data: &'a [i64]) -> crate::Result<Self> {
8202        Ok(Self::I64(TypedTensorView::from_col_major(shape, data)?))
8203    }
8204
8205    /// Create a dynamic `i32` view over compact column-major host data.
8206    ///
8207    /// # Examples
8208    ///
8209    /// ```
8210    /// use tenferro_tensor::{DType, TensorView};
8211    ///
8212    /// let data = [1_i32, 2];
8213    /// let view = TensorView::i32(&[2], &data)?;
8214    /// assert_eq!(view.dtype(), DType::I32);
8215    /// # Ok::<(), tenferro_tensor::Error>(())
8216    /// ```
8217    /// # Errors
8218    ///
8219    /// Returns [`crate::Error::Validation`] with
8220    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8221    /// shape or offset arithmetic overflow, or
8222    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8223    /// compact shape reaches beyond `data`.
8224    pub fn i32(shape: &'a [usize], data: &'a [i32]) -> crate::Result<Self> {
8225        Ok(Self::I32(TypedTensorView::from_col_major(shape, data)?))
8226    }
8227
8228    /// Create a dynamic `bool` view over compact column-major host data.
8229    ///
8230    /// # Examples
8231    ///
8232    /// ```
8233    /// use tenferro_tensor::{DType, TensorView};
8234    ///
8235    /// let data = [true, false];
8236    /// let view = TensorView::bool(&[2], &data)?;
8237    /// assert_eq!(view.dtype(), DType::Bool);
8238    /// # Ok::<(), tenferro_tensor::Error>(())
8239    /// ```
8240    /// # Errors
8241    ///
8242    /// Returns [`crate::Error::Validation`] with
8243    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8244    /// shape or offset arithmetic overflow, or
8245    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8246    /// compact shape reaches beyond `data`.
8247    pub fn bool(shape: &'a [usize], data: &'a [bool]) -> crate::Result<Self> {
8248        Ok(Self::Bool(TypedTensorView::from_col_major(shape, data)?))
8249    }
8250
8251    /// Create a dynamic `Complex32` view over compact column-major host data.
8252    ///
8253    /// # Examples
8254    ///
8255    /// ```
8256    /// use num_complex::Complex32;
8257    /// use tenferro_tensor::{DType, TensorView};
8258    ///
8259    /// let data = [Complex32::new(1.0, 2.0)];
8260    /// let view = TensorView::c32(&[1], &data)?;
8261    /// assert_eq!(view.dtype(), DType::C32);
8262    /// # Ok::<(), tenferro_tensor::Error>(())
8263    /// ```
8264    /// # Errors
8265    ///
8266    /// Returns [`crate::Error::Validation`] with
8267    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8268    /// shape or offset arithmetic overflow, or
8269    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8270    /// compact shape reaches beyond `data`.
8271    pub fn c32(shape: &'a [usize], data: &'a [Complex32]) -> crate::Result<Self> {
8272        Ok(Self::C32(TypedTensorView::from_col_major(shape, data)?))
8273    }
8274
8275    /// Create a dynamic `Complex64` view over compact column-major host data.
8276    ///
8277    /// # Examples
8278    ///
8279    /// ```
8280    /// use num_complex::Complex64;
8281    /// use tenferro_tensor::{DType, TensorView};
8282    ///
8283    /// let data = [Complex64::new(1.0, 2.0)];
8284    /// let view = TensorView::c64(&[1], &data)?;
8285    /// assert_eq!(view.dtype(), DType::C64);
8286    /// # Ok::<(), tenferro_tensor::Error>(())
8287    /// ```
8288    /// # Errors
8289    ///
8290    /// Returns [`crate::Error::Validation`] with
8291    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8292    /// shape or offset arithmetic overflow, or
8293    /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8294    /// compact shape reaches beyond `data`.
8295    pub fn c64(shape: &'a [usize], data: &'a [Complex64]) -> crate::Result<Self> {
8296        Ok(Self::C64(TypedTensorView::from_col_major(shape, data)?))
8297    }
8298
8299    /// Return the element dtype of this borrowed view.
8300    ///
8301    /// # Examples
8302    ///
8303    /// ```
8304    /// use tenferro_tensor::{DType, TensorView};
8305    ///
8306    /// let view = TensorView::f64(&[2], &[1.0, 2.0])?;
8307    /// assert_eq!(view.dtype(), DType::F64);
8308    /// # Ok::<(), tenferro_tensor::Error>(())
8309    /// ```
8310    pub fn dtype(&self) -> DType {
8311        match self {
8312            Self::F32(_) => DType::F32,
8313            Self::F64(_) => DType::F64,
8314            Self::I32(_) => DType::I32,
8315            Self::I64(_) => DType::I64,
8316            Self::Bool(_) => DType::Bool,
8317            Self::C32(_) => DType::C32,
8318            Self::C64(_) => DType::C64,
8319        }
8320    }
8321
8322    /// Return the logical shape of this borrowed view.
8323    ///
8324    /// # Examples
8325    ///
8326    /// ```
8327    /// use tenferro_tensor::TensorView;
8328    ///
8329    /// let view = TensorView::i32(&[2, 1], &[1, 2])?;
8330    /// assert_eq!(view.shape(), &[2, 1]);
8331    /// # Ok::<(), tenferro_tensor::Error>(())
8332    /// ```
8333    pub fn shape(&self) -> &[usize] {
8334        match self {
8335            Self::F32(t) => t.shape(),
8336            Self::F64(t) => t.shape(),
8337            Self::I32(t) => t.shape(),
8338            Self::I64(t) => t.shape(),
8339            Self::Bool(t) => t.shape(),
8340            Self::C32(t) => t.shape(),
8341            Self::C64(t) => t.shape(),
8342        }
8343    }
8344
8345    /// Borrow a contiguous host slice when the requested scalar matches this view's dtype.
8346    ///
8347    /// Backend buffers and non-contiguous views return an explicit error. No
8348    /// download or materialization is performed.
8349    ///
8350    /// # Errors
8351    ///
8352    /// Returns [`ValidationError::DTypeMismatch`] when `T` does not match the
8353    /// view dtype, [`ValidationError::NonContiguousViewAsSlice`] for a
8354    /// non-contiguous layout, or [`crate::Error::HostAccess`] for unavailable
8355    /// backend host access.
8356    pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&'a [T]> {
8357        if self.dtype() != T::dtype() {
8358            return Err(crate::Error::validation(
8359                "TensorView::as_slice",
8360                ValidationError::DTypeMismatch {
8361                    expected: T::dtype(),
8362                    actual: self.dtype(),
8363                },
8364            ));
8365        }
8366        match self {
8367            Self::F32(view) => cast_view_slice(view.as_slice()?),
8368            Self::F64(view) => cast_view_slice(view.as_slice()?),
8369            Self::I32(view) => cast_view_slice(view.as_slice()?),
8370            Self::I64(view) => cast_view_slice(view.as_slice()?),
8371            Self::Bool(view) => cast_view_slice(view.as_slice()?),
8372            Self::C32(view) => cast_view_slice(view.as_slice()?),
8373            Self::C64(view) => cast_view_slice(view.as_slice()?),
8374        }
8375    }
8376
8377    /// Reinterpret a complex view as its sealed real representation.
8378    ///
8379    /// # Examples
8380    ///
8381    /// ```
8382    /// use tenferro_tensor::{Complex64, DType, TensorView};
8383    ///
8384    /// let data = [Complex64::new(1.0, 2.0)];
8385    /// let real = TensorView::c64(&[1], &data)?.as_real_view()?;
8386    /// assert_eq!(real.dtype(), DType::F64);
8387    /// assert_eq!(real.as_slice::<f64>()?, &[1.0, 2.0]);
8388    /// # Ok::<(), tenferro_tensor::Error>(())
8389    /// ```
8390    ///
8391    /// # Errors
8392    ///
8393    /// Returns [`crate::Error::Unsupported`] for the wrong dtype pair and
8394    /// [`ValidationError::InvalidArgument`] or
8395    /// [`ValidationError::ViewOutOfBounds`] for invalid layout metadata.
8396    pub fn as_real_view(&self) -> crate::Result<Self> {
8397        match self {
8398            Self::C32(t) => t.as_real_view().map(Self::F32),
8399            Self::C64(t) => t.as_real_view().map(Self::F64),
8400            _ => Err(crate::Error::unsupported(
8401                "TensorView::as_real_view",
8402                "only complex views have a sealed real representation",
8403            )),
8404        }
8405    }
8406
8407    /// Reinterpret a real view as its sealed complex representation.
8408    ///
8409    /// # Examples
8410    ///
8411    /// ```
8412    /// use tenferro_tensor::{Complex64, DType, TensorView};
8413    ///
8414    /// let data = [1.0_f64, 2.0];
8415    /// let complex = TensorView::f64(&[2, 1], &data)?.as_complex_view()?;
8416    /// assert_eq!(complex.dtype(), DType::C64);
8417    /// assert_eq!(complex.as_slice::<Complex64>()?, &[Complex64::new(1.0, 2.0)]);
8418    /// # Ok::<(), tenferro_tensor::Error>(())
8419    /// ```
8420    ///
8421    /// # Errors
8422    ///
8423    /// Returns [`crate::Error::Unsupported`] for the wrong dtype pair and
8424    /// [`ValidationError::InvalidArgument`] or
8425    /// [`ValidationError::ViewOutOfBounds`] for invalid layout metadata.
8426    pub fn as_complex_view(&self) -> crate::Result<Self> {
8427        match self {
8428            Self::F32(t) => t.as_complex_view().map(Self::C32),
8429            Self::F64(t) => t.as_complex_view().map(Self::C64),
8430            _ => Err(crate::Error::unsupported(
8431                "TensorView::as_complex_view",
8432                "only real views have a sealed complex representation",
8433            )),
8434        }
8435    }
8436
8437    /// Return the placement metadata carried by this borrowed view.
8438    ///
8439    /// # Examples
8440    ///
8441    /// ```
8442    /// use tenferro_tensor::{MemoryKind, TensorView};
8443    ///
8444    /// let view = TensorView::f64(&[1], &[1.0])?;
8445    /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
8446    /// # Ok::<(), tenferro_tensor::Error>(())
8447    /// ```
8448    pub fn placement(&self) -> &Placement {
8449        match self {
8450            Self::F32(t) => t.placement(),
8451            Self::F64(t) => t.placement(),
8452            Self::I32(t) => t.placement(),
8453            Self::I64(t) => t.placement(),
8454            Self::Bool(t) => t.placement(),
8455            Self::C32(t) => t.placement(),
8456            Self::C64(t) => t.placement(),
8457        }
8458    }
8459
8460    /// Return the physical backend family, when this view is backend-owned.
8461    ///
8462    /// # Examples
8463    ///
8464    /// ```rust
8465    /// use tenferro_tensor::TensorView;
8466    ///
8467    /// let view = TensorView::f64(&[1], &[1.0])?;
8468    /// assert_eq!(view.backend_family(), None);
8469    /// # Ok::<(), tenferro_tensor::Error>(())
8470    /// ```
8471    pub fn backend_family(&self) -> Option<&'static str> {
8472        match self {
8473            Self::F32(t) => t.backend_family(),
8474            Self::F64(t) => t.backend_family(),
8475            Self::I32(t) => t.backend_family(),
8476            Self::I64(t) => t.backend_family(),
8477            Self::Bool(t) => t.backend_family(),
8478            Self::C32(t) => t.backend_family(),
8479            Self::C64(t) => t.backend_family(),
8480        }
8481    }
8482
8483    /// Return whether this view borrows host-addressed memory.
8484    ///
8485    /// See [`TypedTensorView::is_host_memory`]; the borrowed payload answers,
8486    /// not the placement label.
8487    ///
8488    /// # Examples
8489    ///
8490    /// ```rust
8491    /// use tenferro_tensor::TensorView;
8492    ///
8493    /// let view = TensorView::f64(&[1], &[1.0])?;
8494    /// assert!(view.is_host_memory());
8495    /// # Ok::<(), tenferro_tensor::Error>(())
8496    /// ```
8497    pub fn is_host_memory(&self) -> bool {
8498        match self {
8499            Self::F32(t) => t.is_host_memory(),
8500            Self::F64(t) => t.is_host_memory(),
8501            Self::I32(t) => t.is_host_memory(),
8502            Self::I64(t) => t.is_host_memory(),
8503            Self::Bool(t) => t.is_host_memory(),
8504            Self::C32(t) => t.is_host_memory(),
8505            Self::C64(t) => t.is_host_memory(),
8506        }
8507    }
8508
8509    /// Return the shared allocation domain, when this view has one.
8510    ///
8511    /// # Examples
8512    ///
8513    /// ```
8514    /// use tenferro_tensor::TensorView;
8515    ///
8516    /// let view = TensorView::f64(&[1], &[1.0])?;
8517    /// assert_eq!(view.allocation_domain(), None);
8518    /// # Ok::<(), tenferro_tensor::Error>(())
8519    /// ```
8520    pub fn allocation_domain(&self) -> Option<AllocationDomainId> {
8521        match self {
8522            Self::F32(t) => t.allocation_domain(),
8523            Self::F64(t) => t.allocation_domain(),
8524            Self::I32(t) => t.allocation_domain(),
8525            Self::I64(t) => t.allocation_domain(),
8526            Self::Bool(t) => t.allocation_domain(),
8527            Self::C32(t) => t.allocation_domain(),
8528            Self::C64(t) => t.allocation_domain(),
8529        }
8530    }
8531
8532    /// Return strides in element units.
8533    ///
8534    /// # Examples
8535    ///
8536    /// ```
8537    /// use tenferro_tensor::TensorView;
8538    ///
8539    /// let data = [0.0_f64; 6];
8540    /// let view = TensorView::f64(&[2, 3], &data)?;
8541    /// assert_eq!(view.strides(), &[1, 2]);
8542    /// # Ok::<(), tenferro_tensor::Error>(())
8543    /// ```
8544    pub fn strides(&self) -> &[isize] {
8545        match self {
8546            Self::F32(t) => t.strides(),
8547            Self::F64(t) => t.strides(),
8548            Self::I32(t) => t.strides(),
8549            Self::I64(t) => t.strides(),
8550            Self::Bool(t) => t.strides(),
8551            Self::C32(t) => t.strides(),
8552            Self::C64(t) => t.strides(),
8553        }
8554    }
8555
8556    /// Return the physical element offset.
8557    pub fn offset(&self) -> isize {
8558        match self {
8559            Self::F32(t) => t.offset(),
8560            Self::F64(t) => t.offset(),
8561            Self::I32(t) => t.offset(),
8562            Self::I64(t) => t.offset(),
8563            Self::Bool(t) => t.offset(),
8564            Self::C32(t) => t.offset(),
8565            Self::C64(t) => t.offset(),
8566        }
8567    }
8568
8569    /// Compute the physical element offset for a logical index.
8570    /// # Errors
8571    ///
8572    /// Returns [`crate::Error::Validation`] with
8573    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
8574    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
8575    /// when an index is outside its axis extent, or
8576    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
8577    /// arithmetic overflows.
8578    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
8579        match self {
8580            Self::F32(t) => t.layout_linear_offset(indices),
8581            Self::F64(t) => t.layout_linear_offset(indices),
8582            Self::I32(t) => t.layout_linear_offset(indices),
8583            Self::I64(t) => t.layout_linear_offset(indices),
8584            Self::Bool(t) => t.layout_linear_offset(indices),
8585            Self::C32(t) => t.layout_linear_offset(indices),
8586            Self::C64(t) => t.layout_linear_offset(indices),
8587        }
8588    }
8589
8590    /// Return whether this view is compact column-major.
8591    /// # Errors
8592    ///
8593    /// Returns [`crate::Error::Validation`] with
8594    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8595    /// compactness arithmetic overflows.
8596    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
8597        match self {
8598            Self::F32(t) => t.is_col_major_contiguous(),
8599            Self::F64(t) => t.is_col_major_contiguous(),
8600            Self::I32(t) => t.is_col_major_contiguous(),
8601            Self::I64(t) => t.is_col_major_contiguous(),
8602            Self::Bool(t) => t.is_col_major_contiguous(),
8603            Self::C32(t) => t.is_col_major_contiguous(),
8604            Self::C64(t) => t.is_col_major_contiguous(),
8605        }
8606    }
8607
8608    /// Return a compact string summary of this view's layout metadata.
8609    pub fn layout_summary(&self) -> String {
8610        layout_summary(self.shape(), self.strides(), self.offset())
8611    }
8612
8613    /// Assert this view is compact column-major.
8614    /// # Errors
8615    ///
8616    /// Returns [`crate::Error::Validation`] with
8617    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8618    /// compactness arithmetic overflows, or
8619    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8620    /// view is not compact column-major.
8621    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
8622        assert_layout_col_major_contiguous(
8623            self.is_col_major_contiguous()?,
8624            self.shape(),
8625            self.strides(),
8626            self.offset(),
8627            "TensorView::assert_col_major_contiguous",
8628        )
8629    }
8630
8631    /// Explicitly duplicate a compact host view into a fresh tensor.
8632    ///
8633    /// Backend views and non-contiguous layouts return a typed error; this
8634    /// operation never downloads or silently canonicalizes a view.
8635    ///
8636    /// # Examples
8637    ///
8638    /// ```
8639    /// use tenferro_tensor::{TensorView, TypedTensorView};
8640    ///
8641    /// let data = [1_i32, 2];
8642    /// let view = TensorView::I32(TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?);
8643    /// let copy = view.duplicate()?;
8644    /// assert_eq!(copy.shape(), &[2]);
8645    /// # Ok::<(), tenferro_tensor::Error>(())
8646    /// ```
8647    ///
8648    /// # Errors
8649    ///
8650    /// Returns [`crate::Error::HostAccess`] for backend-owned views,
8651    /// [`ValidationError::NonContiguousViewAsSlice`] for non-contiguous views,
8652    /// or [`ValidationError::InvalidArgument`] for invalid layout metadata.
8653    pub fn duplicate(&self) -> crate::Result<Tensor> {
8654        fn duplicate_typed<T: TensorScalar>(
8655            view: &TypedTensorView<'_, T>,
8656        ) -> crate::Result<TypedTensor<T>> {
8657            let mut tensor = TypedTensor::<T>::from_vec_col_major(
8658                view.shape().to_vec(),
8659                view.as_slice()?.to_vec(),
8660            )?;
8661            tensor.set_placement(view.placement().clone())?;
8662            Ok(tensor)
8663        }
8664
8665        match self {
8666            Self::F32(view) => duplicate_typed(view).map(Tensor::from_typed),
8667            Self::F64(view) => duplicate_typed(view).map(Tensor::from_typed),
8668            Self::I32(view) => duplicate_typed(view).map(Tensor::from_typed),
8669            Self::I64(view) => duplicate_typed(view).map(Tensor::from_typed),
8670            Self::Bool(view) => duplicate_typed(view).map(Tensor::from_typed),
8671            Self::C32(view) => duplicate_typed(view).map(Tensor::from_typed),
8672            Self::C64(view) => duplicate_typed(view).map(Tensor::from_typed),
8673        }
8674    }
8675}
8676
8677macro_rules! tensor_view_mut_constructor {
8678    ($name:ident, $variant:ident, $scalar:ty) => {
8679        /// Create a dynamic mutable view over compact column-major host data.
8680        ///
8681        /// # Errors
8682        ///
8683        /// Returns [`crate::Error::Validation`] with
8684        /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8685        /// compact layout arithmetic overflows, or
8686        /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8687        /// requested shape exceeds `data`.
8688        pub fn $name(shape: &'a [usize], data: &'a mut [$scalar]) -> crate::Result<Self> {
8689            Ok(Self::$variant(TypedTensorViewMut::from_col_major(
8690                shape, data,
8691            )?))
8692        }
8693    };
8694}
8695
8696impl<'a> TensorViewMut<'a> {
8697    tensor_view_mut_constructor!(f32, F32, f32);
8698    tensor_view_mut_constructor!(f64, F64, f64);
8699    tensor_view_mut_constructor!(i32, I32, i32);
8700    tensor_view_mut_constructor!(i64, I64, i64);
8701    tensor_view_mut_constructor!(bool, Bool, bool);
8702    tensor_view_mut_constructor!(c32, C32, Complex32);
8703    tensor_view_mut_constructor!(c64, C64, Complex64);
8704
8705    pub fn dtype(&self) -> DType {
8706        match self {
8707            Self::F32(_) => DType::F32,
8708            Self::F64(_) => DType::F64,
8709            Self::I32(_) => DType::I32,
8710            Self::I64(_) => DType::I64,
8711            Self::Bool(_) => DType::Bool,
8712            Self::C32(_) => DType::C32,
8713            Self::C64(_) => DType::C64,
8714        }
8715    }
8716
8717    pub fn shape(&self) -> &[usize] {
8718        match self {
8719            Self::F32(t) => t.shape(),
8720            Self::F64(t) => t.shape(),
8721            Self::I32(t) => t.shape(),
8722            Self::I64(t) => t.shape(),
8723            Self::Bool(t) => t.shape(),
8724            Self::C32(t) => t.shape(),
8725            Self::C64(t) => t.shape(),
8726        }
8727    }
8728
8729    /// Return strides in element units.
8730    ///
8731    /// # Examples
8732    ///
8733    /// ```
8734    /// use tenferro_tensor::TensorViewMut;
8735    ///
8736    /// let mut data = [0.0_f64; 6];
8737    /// let view = TensorViewMut::f64(&[2, 3], &mut data)?;
8738    /// assert_eq!(view.strides(), &[1, 2]);
8739    /// # Ok::<(), tenferro_tensor::Error>(())
8740    /// ```
8741    pub fn strides(&self) -> &[isize] {
8742        match self {
8743            Self::F32(t) => t.strides(),
8744            Self::F64(t) => t.strides(),
8745            Self::I32(t) => t.strides(),
8746            Self::I64(t) => t.strides(),
8747            Self::Bool(t) => t.strides(),
8748            Self::C32(t) => t.strides(),
8749            Self::C64(t) => t.strides(),
8750        }
8751    }
8752
8753    pub fn offset(&self) -> isize {
8754        match self {
8755            Self::F32(t) => t.offset(),
8756            Self::F64(t) => t.offset(),
8757            Self::I32(t) => t.offset(),
8758            Self::I64(t) => t.offset(),
8759            Self::Bool(t) => t.offset(),
8760            Self::C32(t) => t.offset(),
8761            Self::C64(t) => t.offset(),
8762        }
8763    }
8764
8765    /// Return whether this mutable view writes host-addressed memory.
8766    ///
8767    /// See [`TypedTensorViewMut::is_host_memory`]; it is the same answer
8768    /// [`Self::try_mut_host`] acts on.
8769    ///
8770    /// # Examples
8771    ///
8772    /// ```rust
8773    /// use tenferro_tensor::TensorViewMut;
8774    ///
8775    /// let mut data = [1.0_f64, 2.0];
8776    /// let view = TensorViewMut::f64(&[2], &mut data)?;
8777    /// assert!(view.is_host_memory());
8778    /// # Ok::<(), tenferro_tensor::Error>(())
8779    /// ```
8780    pub fn is_host_memory(&self) -> bool {
8781        match self {
8782            Self::F32(t) => t.is_host_memory(),
8783            Self::F64(t) => t.is_host_memory(),
8784            Self::I32(t) => t.is_host_memory(),
8785            Self::I64(t) => t.is_host_memory(),
8786            Self::Bool(t) => t.is_host_memory(),
8787            Self::C32(t) => t.is_host_memory(),
8788            Self::C64(t) => t.is_host_memory(),
8789        }
8790    }
8791
8792    /// Compute the physical element offset for a logical index.
8793    ///
8794    /// # Errors
8795    ///
8796    /// Returns [`crate::Error::Validation`] with
8797    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
8798    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
8799    /// when an index is outside its axis extent, or
8800    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
8801    /// arithmetic overflows.
8802    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
8803        match self {
8804            Self::F32(t) => t.layout_linear_offset(indices),
8805            Self::F64(t) => t.layout_linear_offset(indices),
8806            Self::I32(t) => t.layout_linear_offset(indices),
8807            Self::I64(t) => t.layout_linear_offset(indices),
8808            Self::Bool(t) => t.layout_linear_offset(indices),
8809            Self::C32(t) => t.layout_linear_offset(indices),
8810            Self::C64(t) => t.layout_linear_offset(indices),
8811        }
8812    }
8813
8814    /// Return whether this view is compact column-major.
8815    ///
8816    /// # Errors
8817    ///
8818    /// Returns [`crate::Error::Validation`] with
8819    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8820    /// compactness arithmetic overflows.
8821    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
8822        match self {
8823            Self::F32(t) => t.is_col_major_contiguous(),
8824            Self::F64(t) => t.is_col_major_contiguous(),
8825            Self::I32(t) => t.is_col_major_contiguous(),
8826            Self::I64(t) => t.is_col_major_contiguous(),
8827            Self::Bool(t) => t.is_col_major_contiguous(),
8828            Self::C32(t) => t.is_col_major_contiguous(),
8829            Self::C64(t) => t.is_col_major_contiguous(),
8830        }
8831    }
8832
8833    pub fn layout_summary(&self) -> String {
8834        layout_summary(self.shape(), self.strides(), self.offset())
8835    }
8836
8837    /// Assert this view is compact column-major.
8838    ///
8839    /// # Errors
8840    ///
8841    /// Returns [`crate::Error::Validation`] with
8842    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8843    /// compactness arithmetic overflows, or
8844    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8845    /// view is not compact column-major.
8846    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
8847        assert_layout_col_major_contiguous(
8848            self.is_col_major_contiguous()?,
8849            self.shape(),
8850            self.strides(),
8851            self.offset(),
8852            "TensorViewMut::assert_col_major_contiguous",
8853        )
8854    }
8855
8856    /// Explicitly duplicate the compact host data visible through this
8857    /// mutable view into a new tensor owner.
8858    ///
8859    /// # Examples
8860    ///
8861    /// ```
8862    /// use tenferro_tensor::{TensorViewMut, TypedTensorViewMut};
8863    ///
8864    /// let mut data = [1_i32, 2];
8865    /// let view = TensorViewMut::I32(TypedTensorViewMut::from_slice(
8866    ///     vec![2], vec![1], 0, &mut data,
8867    /// )?);
8868    /// let copy = view.duplicate()?;
8869    /// assert_eq!(copy.shape(), &[2]);
8870    /// # Ok::<(), tenferro_tensor::Error>(())
8871    /// ```
8872    ///
8873    /// # Errors
8874    ///
8875    /// Returns [`crate::Error::HostAccess`] for backend-owned views,
8876    /// [`ValidationError::NonContiguousViewAsSlice`] for non-contiguous views,
8877    /// or [`ValidationError::InvalidArgument`] for invalid layout metadata.
8878    pub fn duplicate(&self) -> crate::Result<Tensor> {
8879        self.as_read_only().duplicate()
8880    }
8881
8882    /// Borrow this mutable view as a read-only dtype-erased view.
8883    ///
8884    /// # Examples
8885    ///
8886    /// ```
8887    /// use tenferro_tensor::TensorViewMut;
8888    ///
8889    /// let mut data = [1.0_f64, 2.0];
8890    /// let view = TensorViewMut::f64(&[2], &mut data)?;
8891    /// assert_eq!(view.as_read_only().as_slice::<f64>()?, &[1.0, 2.0]);
8892    /// # Ok::<(), tenferro_tensor::Error>(())
8893    /// ```
8894    pub fn as_read_only(&self) -> TensorView<'_> {
8895        match self {
8896            Self::F32(t) => TensorView::F32(t.as_read_only()),
8897            Self::F64(t) => TensorView::F64(t.as_read_only()),
8898            Self::I32(t) => TensorView::I32(t.as_read_only()),
8899            Self::I64(t) => TensorView::I64(t.as_read_only()),
8900            Self::Bool(t) => TensorView::Bool(t.as_read_only()),
8901            Self::C32(t) => TensorView::C32(t.as_read_only()),
8902            Self::C64(t) => TensorView::C64(t.as_read_only()),
8903        }
8904    }
8905}
8906
8907impl<'a> TensorRead<'a> {
8908    /// Checked narrowing of a read target to a host-marked view.
8909    ///
8910    /// This is the boundary a CPU entry point crosses once: an owned tensor is
8911    /// borrowed without copying, an existing view keeps its layout, and the
8912    /// result is a [`TensorView<'a, Host>`](TensorView) whose consumers read
8913    /// host elements without re-checking placement. `op` names the operation
8914    /// in the error, as the per-entry checks it replaces did.
8915    ///
8916    /// # Examples
8917    ///
8918    /// ```rust
8919    /// use tenferro_tensor::{DType, Tensor, TensorRead};
8920    ///
8921    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8922    /// let host = TensorRead::from_tensor(&tensor).try_host("cholesky")?;
8923    /// assert_eq!(host.dtype(), DType::F64);
8924    /// # Ok::<(), tenferro_tensor::Error>(())
8925    /// ```
8926    ///
8927    /// # Errors
8928    ///
8929    /// Returns [`crate::Error::UnsupportedDType`] attributed to `op` for a
8930    /// tensor built with [`Tensor::external`], which has no preset-scalar view,
8931    /// and [`crate::Error::RuntimeState`] attributed to `op` when the read
8932    /// borrows backend (device) storage; download the tensor to host first.
8933    pub fn try_host(self, op: &'static str) -> crate::Result<TensorView<'a, Host>> {
8934        let dtype = self.dtype();
8935        self.tensor_view()
8936            .ok_or_else(|| {
8937                crate::Error::unsupported_dtype(
8938                    op,
8939                    dtype,
8940                    "an externally defined payload has no host tensor view",
8941                )
8942            })?
8943            .try_host(op)
8944    }
8945}
8946
8947impl<'a> TensorRead<'a> {
8948    /// Borrow an owned tensor as a read target without copying it.
8949    ///
8950    /// # Examples
8951    ///
8952    /// ```
8953    /// use tenferro_tensor::{Tensor, TensorRead};
8954    ///
8955    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8956    /// let read = TensorRead::from_tensor(&tensor);
8957    /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
8958    /// # Ok::<(), tenferro_tensor::Error>(())
8959    /// ```
8960    pub fn from_tensor(tensor: &'a Tensor) -> Self {
8961        Self::Tensor(tensor)
8962    }
8963
8964    /// Wrap a borrowed dtype-erased view as a read target.
8965    ///
8966    /// # Examples
8967    ///
8968    /// ```
8969    /// use tenferro_tensor::{TensorRead, TensorView};
8970    ///
8971    /// let read = TensorRead::from_view(TensorView::i32(&[2], &[3, 4])?);
8972    /// assert_eq!(read.as_slice::<i32>()?, &[3, 4]);
8973    /// assert!(read.as_tensor().is_none());
8974    /// # Ok::<(), tenferro_tensor::Error>(())
8975    /// ```
8976    #[inline]
8977    pub fn from_view(view: TensorView<'a>) -> Self {
8978        Self::View(view)
8979    }
8980
8981    /// Convert this read target into a dtype-erased tensor view, or `None` when
8982    /// it borrows a tensor with an externally defined payload.
8983    ///
8984    /// Owned tensors are borrowed without copying their storage. Existing
8985    /// views are returned as is, preserving their layout and placement metadata.
8986    /// [`TensorView`] has one variant per preset scalar (`F32` ... `C64`) and none
8987    /// for a caller-owned element type, so a tensor built from
8988    /// [`Tensor::external`] has no view; read it through
8989    /// [`Tensor::external_payload`] instead.
8990    ///
8991    /// # Examples
8992    ///
8993    /// ```rust
8994    /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, Tensor, TensorRead, TypedTensor};
8995    ///
8996    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8997    /// let view = TensorRead::from_tensor(&tensor)
8998    ///     .tensor_view()
8999    ///     .ok_or("a preset f64 tensor has a view")?;
9000    /// assert_eq!(view.shape(), &[2]);
9001    /// assert_eq!(view.as_slice::<f64>()?, &[1.0, 2.0]);
9002    ///
9003    /// let payload = ErasedHostTensor::new(
9004    ///     TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?,
9005    /// );
9006    /// let external = Tensor::external(payload);
9007    /// assert!(TensorRead::from_tensor(&external).tensor_view().is_none());
9008    /// # Ok::<(), Box<dyn std::error::Error>>(())
9009    /// ```
9010    #[must_use]
9011    pub fn tensor_view(self) -> Option<TensorView<'a>> {
9012        match self {
9013            Self::Tensor(tensor) => tensor_view_with_layout(tensor, tensor_layout(tensor)),
9014            Self::View(view) => Some(view),
9015        }
9016    }
9017
9018    /// Build a metadata-only stride-0 broadcast of this read.
9019    ///
9020    /// An owned preset is borrowed and an existing view keeps its buffer,
9021    /// retained root and placement, so the result copies no elements and
9022    /// allocates no storage. A caller that can consume a read-only operand
9023    /// should use this instead of the materializing session
9024    /// `broadcast_in_dim_read`.
9025    ///
9026    /// # Examples
9027    ///
9028    /// ```
9029    /// use tenferro_tensor::{Tensor, TensorRead};
9030    ///
9031    /// let tensor = Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?;
9032    /// let read = TensorRead::from_tensor(&tensor).broadcast_in_dim_view(&[2, 3], &[1])?;
9033    /// assert_eq!(read.shape(), &[2, 3]);
9034    /// assert_eq!(read.strides()?, vec![0, 1]);
9035    /// # Ok::<(), tenferro_tensor::Error>(())
9036    /// ```
9037    ///
9038    /// # Errors
9039    ///
9040    /// Returns [`crate::Error::UnsupportedDType`] for a caller-owned payload,
9041    /// which has no borrowed view, or a validation error when `dims` does not
9042    /// map this read's layout into `shape`.
9043    #[doc(hidden)]
9044    pub fn broadcast_in_dim_view(self, shape: &[usize], dims: &[usize]) -> crate::Result<Self> {
9045        let dtype = self.dtype();
9046        let view = self.tensor_view().ok_or_else(|| {
9047            crate::Error::unsupported_dtype(
9048                "TensorRead::broadcast_in_dim_view",
9049                dtype,
9050                "a caller-owned payload has no borrowed broadcast view",
9051            )
9052        })?;
9053        Ok(Self::View(match view {
9054            TensorView::F32(view) => TensorView::F32(broadcast_typed_view(view, shape, dims)?),
9055            TensorView::F64(view) => TensorView::F64(broadcast_typed_view(view, shape, dims)?),
9056            TensorView::I32(view) => TensorView::I32(broadcast_typed_view(view, shape, dims)?),
9057            TensorView::I64(view) => TensorView::I64(broadcast_typed_view(view, shape, dims)?),
9058            TensorView::Bool(view) => TensorView::Bool(broadcast_typed_view(view, shape, dims)?),
9059            TensorView::C32(view) => TensorView::C32(broadcast_typed_view(view, shape, dims)?),
9060            TensorView::C64(view) => TensorView::C64(broadcast_typed_view(view, shape, dims)?),
9061        }))
9062    }
9063
9064    /// Borrow this read target as a typed compact host slice without allocation.
9065    ///
9066    /// This delegates to [`TensorView::as_slice`]. Cloning a `TensorRead` is a
9067    /// shallow clone of its borrowed reference or view metadata, so the returned
9068    /// slice retains the original `'a` storage lifetime and never outlives the
9069    /// storage borrowed by this read target. This method does not materialize,
9070    /// transfer, or otherwise canonicalize the input.
9071    ///
9072    /// # Errors
9073    ///
9074    /// Returns [`ValidationError::DTypeMismatch`] when `T` does not match the
9075    /// input dtype, [`ValidationError::NonContiguousViewAsSlice`] for a
9076    /// noncompact view, a typed runtime-state host-access error for
9077    /// backend-owned storage, or [`crate::Error::UnsupportedDType`] for a
9078    /// tensor built with [`Tensor::external`], which has no preset-scalar view.
9079    /// Backend-owned inputs are never downloaded implicitly.
9080    ///
9081    /// # Examples
9082    ///
9083    /// ```
9084    /// use tenferro_tensor::{Tensor, TensorRead};
9085    ///
9086    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9087    /// let read = TensorRead::from_tensor(&tensor);
9088    /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
9089    /// # Ok::<(), tenferro_tensor::Error>(())
9090    /// ```
9091    pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&'a [T]> {
9092        self.clone()
9093            .tensor_view()
9094            .ok_or_else(|| {
9095                crate::Error::unsupported_dtype(
9096                    "TensorRead::as_slice",
9097                    self.dtype(),
9098                    "a caller-owned payload has no preset-scalar host slice; read it through Tensor::external_payload",
9099                )
9100            })?
9101            .as_slice()
9102    }
9103
9104    /// Return the element dtype of this read target.
9105    ///
9106    /// # Examples
9107    ///
9108    /// ```
9109    /// use tenferro_tensor::{DType, Tensor, TensorRead};
9110    ///
9111    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1_i64])?;
9112    /// assert_eq!(TensorRead::from_tensor(&tensor).dtype(), DType::I64);
9113    /// # Ok::<(), tenferro_tensor::Error>(())
9114    /// ```
9115    pub fn dtype(&self) -> DType {
9116        match self {
9117            Self::Tensor(tensor) => tensor.dtype(),
9118            Self::View(view) => view.dtype(),
9119        }
9120    }
9121
9122    /// Return the logical shape of this read target.
9123    ///
9124    /// # Examples
9125    ///
9126    /// ```
9127    /// use tenferro_tensor::{Tensor, TensorRead};
9128    ///
9129    /// let tensor = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
9130    /// assert_eq!(TensorRead::from_tensor(&tensor).shape(), &[2, 1]);
9131    /// # Ok::<(), tenferro_tensor::Error>(())
9132    /// ```
9133    pub fn shape(&self) -> &[usize] {
9134        match self {
9135            Self::Tensor(tensor) => tensor.shape(),
9136            Self::View(view) => view.shape(),
9137        }
9138    }
9139
9140    /// Return the placement metadata carried by this read target.
9141    ///
9142    /// # Examples
9143    ///
9144    /// ```
9145    /// use tenferro_tensor::{MemoryKind, Tensor, TensorRead};
9146    ///
9147    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9148    /// let read = TensorRead::from_tensor(&tensor);
9149    /// assert_eq!(read.placement().memory_kind, MemoryKind::UnpinnedHost);
9150    /// # Ok::<(), tenferro_tensor::Error>(())
9151    /// ```
9152    pub fn placement(&self) -> &Placement {
9153        match self {
9154            Self::Tensor(tensor) => tensor.placement(),
9155            Self::View(view) => view.placement(),
9156        }
9157    }
9158
9159    /// Return whether this read target borrows host-addressed memory.
9160    ///
9161    /// The one host/device answer a CPU entry point needs, decided by the
9162    /// payload and never by [`Placement::memory_kind`]; it is the same answer
9163    /// [`Self::try_host`] acts on, and the same one
9164    /// [`TypedTensor::is_host_memory`] gives for an owner.
9165    ///
9166    /// # Examples
9167    ///
9168    /// ```rust
9169    /// use tenferro_tensor::{Tensor, TensorRead};
9170    ///
9171    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9172    /// assert!(TensorRead::from_tensor(&tensor).is_host_memory());
9173    /// # Ok::<(), tenferro_tensor::Error>(())
9174    /// ```
9175    pub fn is_host_memory(&self) -> bool {
9176        match self {
9177            Self::Tensor(tensor) => tensor.is_host_memory(),
9178            Self::View(view) => view.is_host_memory(),
9179        }
9180    }
9181
9182    /// Return the physical backend family of this read target, when backend-owned.
9183    ///
9184    /// # Examples
9185    ///
9186    /// ```
9187    /// use tenferro_tensor::{Tensor, TensorRead};
9188    ///
9189    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9190    /// assert_eq!(TensorRead::from_tensor(&tensor).backend_family(), None);
9191    /// # Ok::<(), tenferro_tensor::Error>(())
9192    /// ```
9193    pub fn backend_family(&self) -> Option<&'static str> {
9194        match self {
9195            Self::Tensor(tensor) => match tensor.dtype() {
9196                // A caller-owned payload is host memory without backend family.
9197                DType::External(_) => None,
9198                DType::F32 => tensor.as_typed::<f32>().and_then(|t| t.backend_family()),
9199                DType::F64 => tensor.as_typed::<f64>().and_then(|t| t.backend_family()),
9200                DType::I32 => tensor.as_typed::<i32>().and_then(|t| t.backend_family()),
9201                DType::I64 => tensor.as_typed::<i64>().and_then(|t| t.backend_family()),
9202                DType::Bool => tensor.as_typed::<bool>().and_then(|t| t.backend_family()),
9203                DType::C32 => tensor
9204                    .as_typed::<Complex<f32>>()
9205                    .and_then(|t| t.backend_family()),
9206                DType::C64 => tensor
9207                    .as_typed::<Complex<f64>>()
9208                    .and_then(|t| t.backend_family()),
9209            },
9210            Self::View(view) => view.backend_family(),
9211        }
9212    }
9213
9214    /// Return the shared allocation domain of this read target, when present.
9215    ///
9216    /// # Examples
9217    ///
9218    /// ```
9219    /// use tenferro_tensor::{Tensor, TensorRead};
9220    ///
9221    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9222    /// assert_eq!(TensorRead::from_tensor(&tensor).allocation_domain(), None);
9223    /// # Ok::<(), tenferro_tensor::Error>(())
9224    /// ```
9225    pub fn allocation_domain(&self) -> Option<AllocationDomainId> {
9226        match self {
9227            Self::Tensor(tensor) => match tensor.dtype() {
9228                // A caller-owned payload has no allocation domain.
9229                DType::External(_) => None,
9230                DType::F32 => tensor.as_typed::<f32>().and_then(|t| t.allocation_domain()),
9231                DType::F64 => tensor.as_typed::<f64>().and_then(|t| t.allocation_domain()),
9232                DType::I32 => tensor.as_typed::<i32>().and_then(|t| t.allocation_domain()),
9233                DType::I64 => tensor.as_typed::<i64>().and_then(|t| t.allocation_domain()),
9234                DType::Bool => tensor
9235                    .as_typed::<bool>()
9236                    .and_then(|t| t.allocation_domain()),
9237                DType::C32 => tensor
9238                    .as_typed::<Complex<f32>>()
9239                    .and_then(|t| t.allocation_domain()),
9240                DType::C64 => tensor
9241                    .as_typed::<Complex<f64>>()
9242                    .and_then(|t| t.allocation_domain()),
9243            },
9244            Self::View(view) => view.allocation_domain(),
9245        }
9246    }
9247
9248    /// Return strides in element units; owned tensors report compact column-major strides.
9249    ///
9250    /// # Examples
9251    ///
9252    /// ```
9253    /// use tenferro_tensor::{Tensor, TensorRead};
9254    ///
9255    /// let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9256    /// assert_eq!(TensorRead::from_tensor(&tensor).strides()?, vec![1, 2]);
9257    /// # Ok::<(), tenferro_tensor::Error>(())
9258    /// ```
9259    ///
9260    /// # Errors
9261    ///
9262    /// Returns [`crate::Error::Validation`] with
9263    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9264    /// column-major stride arithmetic overflows.
9265    pub fn strides(&self) -> crate::Result<Vec<isize>> {
9266        match self {
9267            Self::Tensor(tensor) => Ok(col_major_strides(tensor.shape())?.into_vec()),
9268            Self::View(view) => Ok(view.strides().to_vec()),
9269        }
9270    }
9271
9272    /// Return the physical element offset; owned tensors always start at `0`.
9273    ///
9274    /// # Examples
9275    ///
9276    /// ```
9277    /// use tenferro_tensor::{TensorRead, TensorView, TypedTensorView};
9278    ///
9279    /// let data = [1.0_f64, 2.0, 3.0];
9280    /// let view = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![1], 1, &data)?);
9281    /// assert_eq!(TensorRead::from_view(view).offset(), 1);
9282    /// # Ok::<(), tenferro_tensor::Error>(())
9283    /// ```
9284    pub fn offset(&self) -> isize {
9285        match self {
9286            Self::Tensor(_) => 0,
9287            Self::View(view) => view.offset(),
9288        }
9289    }
9290
9291    /// Compute the physical element offset for a logical index.
9292    ///
9293    /// # Examples
9294    ///
9295    /// ```
9296    /// use tenferro_tensor::{Tensor, TensorRead};
9297    ///
9298    /// let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9299    /// let read = TensorRead::from_tensor(&tensor);
9300    /// assert_eq!(read.layout_linear_offset(&[1, 2])?, 5);
9301    /// assert!(read.layout_linear_offset(&[2, 0]).is_err());
9302    /// # Ok::<(), tenferro_tensor::Error>(())
9303    /// ```
9304    ///
9305    /// # Errors
9306    ///
9307    /// Returns [`crate::Error::Validation`] with
9308    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
9309    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
9310    /// when an index is outside its axis extent, or
9311    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
9312    /// arithmetic overflows.
9313    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
9314        match self {
9315            Self::Tensor(tensor) => tensor.layout_linear_offset(indices),
9316            Self::View(view) => view.layout_linear_offset(indices),
9317        }
9318    }
9319
9320    /// Return whether this read target is compact column-major.
9321    ///
9322    /// # Examples
9323    ///
9324    /// ```
9325    /// use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
9326    ///
9327    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9328    /// assert!(TensorRead::from_tensor(&tensor).is_col_major_contiguous()?);
9329    /// let data = [1.0_f64, 2.0, 3.0];
9330    /// let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
9331    /// assert!(!TensorRead::from_view(strided).is_col_major_contiguous()?);
9332    /// # Ok::<(), tenferro_tensor::Error>(())
9333    /// ```
9334    ///
9335    /// # Errors
9336    ///
9337    /// Returns [`crate::Error::Validation`] with
9338    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9339    /// compactness arithmetic overflows.
9340    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
9341        match self {
9342            Self::Tensor(tensor) => tensor.is_col_major_contiguous(),
9343            Self::View(view) => view.is_col_major_contiguous(),
9344        }
9345    }
9346
9347    /// Return a compact string summary of this read target's layout metadata.
9348    ///
9349    /// # Examples
9350    ///
9351    /// ```
9352    /// use tenferro_tensor::{Tensor, TensorRead};
9353    ///
9354    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9355    /// assert_eq!(
9356    ///     TensorRead::from_tensor(&tensor).layout_summary(),
9357    ///     "shape=[2] strides=[1] offset=0"
9358    /// );
9359    /// # Ok::<(), tenferro_tensor::Error>(())
9360    /// ```
9361    pub fn layout_summary(&self) -> String {
9362        let strides = match self.strides() {
9363            Ok(strides) => strides,
9364            Err(err) => return format!("layout unavailable: {err}"),
9365        };
9366        layout_summary(self.shape(), &strides, self.offset())
9367    }
9368
9369    /// Assert this read target is compact column-major.
9370    ///
9371    /// # Examples
9372    ///
9373    /// ```
9374    /// use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
9375    ///
9376    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9377    /// TensorRead::from_tensor(&tensor).assert_col_major_contiguous()?;
9378    /// let data = [1.0_f64, 2.0, 3.0];
9379    /// let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
9380    /// assert!(TensorRead::from_view(strided).assert_col_major_contiguous().is_err());
9381    /// # Ok::<(), tenferro_tensor::Error>(())
9382    /// ```
9383    ///
9384    /// # Errors
9385    ///
9386    /// Returns [`crate::Error::Validation`] with
9387    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9388    /// compactness arithmetic overflows, or
9389    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
9390    /// view is not compact column-major.
9391    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
9392        let strides = self.strides()?;
9393        assert_layout_col_major_contiguous(
9394            self.is_col_major_contiguous()?,
9395            self.shape(),
9396            &strides,
9397            self.offset(),
9398            "TensorRead::assert_col_major_contiguous",
9399        )
9400    }
9401
9402    /// Return the borrowed owned tensor, or `None` when this read target is a view.
9403    ///
9404    /// # Examples
9405    ///
9406    /// ```
9407    /// use tenferro_tensor::{Tensor, TensorRead, TensorView};
9408    ///
9409    /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9410    /// assert!(TensorRead::from_tensor(&tensor).as_tensor().is_some());
9411    /// assert!(TensorRead::from_view(TensorView::f64(&[1], &[1.0])?).as_tensor().is_none());
9412    /// # Ok::<(), tenferro_tensor::Error>(())
9413    /// ```
9414    pub fn as_tensor(&self) -> Option<&'a Tensor> {
9415        match self {
9416            Self::Tensor(tensor) => Some(*tensor),
9417            Self::View(_) => None,
9418        }
9419    }
9420}
9421
9422impl<'a> TensorWrite<'a> {
9423    /// Checked narrowing of a write target to a host-marked mutable view.
9424    ///
9425    /// The write counterpart of [`TensorRead::try_host`]: an owned tensor is
9426    /// borrowed mutably without copying, an existing view keeps its layout, and
9427    /// the result is a [`TensorViewMut<'a, Host>`](TensorViewMut) whose
9428    /// consumers write host elements without re-checking placement. `op` names
9429    /// the operation in the error.
9430    ///
9431    /// # Examples
9432    ///
9433    /// ```rust
9434    /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9435    ///
9436    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![0.0_f64; 2])?;
9437    /// let host = TensorWrite::from_tensor(&mut tensor).try_mut_host("solve_read_into")?;
9438    /// assert_eq!(host.dtype(), DType::F64);
9439    /// assert_eq!(host.shape(), &[2]);
9440    /// # Ok::<(), tenferro_tensor::Error>(())
9441    /// ```
9442    ///
9443    /// # Errors
9444    ///
9445    /// Returns [`crate::Error::UnsupportedDType`] attributed to `op` for a
9446    /// tensor built with [`Tensor::external`], which has no preset-scalar view,
9447    /// and [`crate::Error::RuntimeState`] attributed to `op` when the target
9448    /// borrows backend (device) storage; download the tensor to host first.
9449    pub fn try_mut_host(self, op: &'static str) -> crate::Result<TensorViewMut<'a, Host>> {
9450        match self {
9451            Self::Tensor(tensor) => {
9452                let dtype = tensor.dtype();
9453                tensor_view_mut_of(tensor).ok_or_else(|| {
9454                    crate::Error::unsupported_dtype(
9455                        op,
9456                        dtype,
9457                        "an externally defined payload has no host tensor view",
9458                    )
9459                })?
9460            }
9461            Self::View(view) => view,
9462        }
9463        .try_mut_host(op)
9464    }
9465}
9466
9467/// Mutably borrow an owned tensor as a dtype-erased view, or `None` when it
9468/// holds an externally defined payload ([`TensorViewMut`] has no arm for it).
9469fn tensor_view_mut_of(tensor: &mut Tensor) -> Option<TensorViewMut<'_>> {
9470    Some(match tensor.dtype() {
9471        DType::F32 => TensorViewMut::F32(tensor.as_typed_mut::<f32>()?.as_view_mut()),
9472        DType::F64 => TensorViewMut::F64(tensor.as_typed_mut::<f64>()?.as_view_mut()),
9473        DType::I32 => TensorViewMut::I32(tensor.as_typed_mut::<i32>()?.as_view_mut()),
9474        DType::I64 => TensorViewMut::I64(tensor.as_typed_mut::<i64>()?.as_view_mut()),
9475        DType::Bool => TensorViewMut::Bool(tensor.as_typed_mut::<bool>()?.as_view_mut()),
9476        DType::C32 => TensorViewMut::C32(tensor.as_typed_mut::<Complex32>()?.as_view_mut()),
9477        DType::C64 => TensorViewMut::C64(tensor.as_typed_mut::<Complex64>()?.as_view_mut()),
9478        DType::External(_) => return None,
9479    })
9480}
9481
9482impl<'a> TensorWrite<'a> {
9483    /// Borrow an owned tensor as a writable target without copying it.
9484    ///
9485    /// # Examples
9486    ///
9487    /// ```
9488    /// use tenferro_tensor::{Tensor, TensorWrite};
9489    ///
9490    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9491    /// let write = TensorWrite::from_tensor(&mut tensor);
9492    /// assert_eq!(write.shape(), &[2]);
9493    /// # Ok::<(), tenferro_tensor::Error>(())
9494    /// ```
9495    pub fn from_tensor(tensor: &'a mut Tensor) -> Self {
9496        Self::Tensor(tensor)
9497    }
9498
9499    /// Wrap a borrowed mutable dtype-erased view as a writable target.
9500    ///
9501    /// # Examples
9502    ///
9503    /// ```
9504    /// use tenferro_tensor::{DType, TensorViewMut, TensorWrite};
9505    ///
9506    /// let mut data = [1.0_f64, 2.0];
9507    /// let write = TensorWrite::from_view(TensorViewMut::f64(&[2], &mut data)?);
9508    /// assert_eq!(write.dtype(), DType::F64);
9509    /// assert_eq!(write.as_read().as_slice::<f64>()?, &[1.0, 2.0]);
9510    /// # Ok::<(), tenferro_tensor::Error>(())
9511    /// ```
9512    pub fn from_view(view: TensorViewMut<'a>) -> Self {
9513        Self::View(view)
9514    }
9515
9516    /// Borrow this writable target as a read-only tensor input.
9517    ///
9518    /// This is useful for explicit read-modify-write kernels such as
9519    /// accumulation updates. The returned view borrows through `&self`, so it
9520    /// cannot outlive the current read-only borrow of the writable target.
9521    ///
9522    /// # Examples
9523    ///
9524    /// ```rust
9525    /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9526    ///
9527    /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?;
9528    /// let write = TensorWrite::from_tensor(&mut tensor);
9529    /// let read = write.as_read();
9530    /// assert_eq!(read.dtype(), DType::F64);
9531    /// # Ok::<(), tenferro_tensor::Error>(())
9532    /// ```
9533    pub fn as_read(&self) -> TensorRead<'_> {
9534        match self {
9535            Self::Tensor(tensor) => TensorRead::from_tensor(tensor),
9536            Self::View(view) => TensorRead::from_view(view.as_read_only()),
9537        }
9538    }
9539
9540    /// Return the element dtype of this writable target.
9541    ///
9542    /// # Examples
9543    ///
9544    /// ```
9545    /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9546    ///
9547    /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![1_i32])?;
9548    /// assert_eq!(TensorWrite::from_tensor(&mut tensor).dtype(), DType::I32);
9549    /// # Ok::<(), tenferro_tensor::Error>(())
9550    /// ```
9551    pub fn dtype(&self) -> DType {
9552        match self {
9553            Self::Tensor(tensor) => tensor.dtype(),
9554            Self::View(view) => view.dtype(),
9555        }
9556    }
9557
9558    /// Return the logical shape of this writable target.
9559    ///
9560    /// # Examples
9561    ///
9562    /// ```
9563    /// use tenferro_tensor::{Tensor, TensorWrite};
9564    ///
9565    /// let mut tensor = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
9566    /// assert_eq!(TensorWrite::from_tensor(&mut tensor).shape(), &[2, 1]);
9567    /// # Ok::<(), tenferro_tensor::Error>(())
9568    /// ```
9569    pub fn shape(&self) -> &[usize] {
9570        match self {
9571            Self::Tensor(tensor) => tensor.shape(),
9572            Self::View(view) => view.shape(),
9573        }
9574    }
9575
9576    /// Return strides in element units; owned tensors report compact column-major strides.
9577    ///
9578    /// # Examples
9579    ///
9580    /// ```
9581    /// use tenferro_tensor::{Tensor, TensorWrite};
9582    ///
9583    /// let mut tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9584    /// assert_eq!(TensorWrite::from_tensor(&mut tensor).strides()?, vec![1, 2]);
9585    /// # Ok::<(), tenferro_tensor::Error>(())
9586    /// ```
9587    ///
9588    /// # Errors
9589    ///
9590    /// Returns [`crate::Error::Validation`] with
9591    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9592    /// column-major stride arithmetic overflows.
9593    pub fn strides(&self) -> crate::Result<Vec<isize>> {
9594        match self {
9595            Self::Tensor(tensor) => Ok(col_major_strides(tensor.shape())?.into_vec()),
9596            Self::View(view) => Ok(view.strides().to_vec()),
9597        }
9598    }
9599
9600    /// Return whether this write target writes host-addressed memory.
9601    ///
9602    /// The one host/device answer for an output, decided by the payload and
9603    /// never by [`Placement::memory_kind`]. It is the same answer
9604    /// [`Self::try_mut_host`] acts on.
9605    ///
9606    /// # Examples
9607    ///
9608    /// ```rust
9609    /// use tenferro_tensor::{Tensor, TensorWrite};
9610    ///
9611    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![0.0_f64; 2])?;
9612    /// assert!(TensorWrite::from_tensor(&mut tensor).is_host_memory());
9613    /// # Ok::<(), tenferro_tensor::Error>(())
9614    /// ```
9615    pub fn is_host_memory(&self) -> bool {
9616        match self {
9617            Self::Tensor(tensor) => tensor.is_host_memory(),
9618            Self::View(view) => view.is_host_memory(),
9619        }
9620    }
9621
9622    /// Return the physical element offset; owned tensors always start at `0`.
9623    ///
9624    /// # Examples
9625    ///
9626    /// ```
9627    /// use tenferro_tensor::{TensorViewMut, TensorWrite, TypedTensorViewMut};
9628    ///
9629    /// let mut data = [1.0_f64, 2.0, 3.0];
9630    /// let view = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![1], 1, &mut data)?);
9631    /// assert_eq!(TensorWrite::from_view(view).offset(), 1);
9632    /// # Ok::<(), tenferro_tensor::Error>(())
9633    /// ```
9634    pub fn offset(&self) -> isize {
9635        match self {
9636            Self::Tensor(_) => 0,
9637            Self::View(view) => view.offset(),
9638        }
9639    }
9640
9641    /// Compute the physical element offset for a logical index.
9642    ///
9643    /// # Examples
9644    ///
9645    /// ```
9646    /// use tenferro_tensor::{Tensor, TensorWrite};
9647    ///
9648    /// let mut tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9649    /// let write = TensorWrite::from_tensor(&mut tensor);
9650    /// assert_eq!(write.layout_linear_offset(&[1, 2])?, 5);
9651    /// assert!(write.layout_linear_offset(&[0]).is_err());
9652    /// # Ok::<(), tenferro_tensor::Error>(())
9653    /// ```
9654    ///
9655    /// # Errors
9656    ///
9657    /// Returns [`crate::Error::Validation`] with
9658    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
9659    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
9660    /// when an index is outside its axis extent, or
9661    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
9662    /// arithmetic overflows.
9663    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
9664        match self {
9665            Self::Tensor(tensor) => tensor.layout_linear_offset(indices),
9666            Self::View(view) => view.layout_linear_offset(indices),
9667        }
9668    }
9669
9670    /// Return whether this writable target is compact column-major.
9671    ///
9672    /// # Examples
9673    ///
9674    /// ```
9675    /// use tenferro_tensor::{Tensor, TensorViewMut, TensorWrite, TypedTensorViewMut};
9676    ///
9677    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9678    /// assert!(TensorWrite::from_tensor(&mut tensor).is_col_major_contiguous()?);
9679    /// let mut data = [1.0_f64, 2.0, 3.0];
9680    /// let strided = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![2], 0, &mut data)?);
9681    /// assert!(!TensorWrite::from_view(strided).is_col_major_contiguous()?);
9682    /// # Ok::<(), tenferro_tensor::Error>(())
9683    /// ```
9684    ///
9685    /// # Errors
9686    ///
9687    /// Returns [`crate::Error::Validation`] with
9688    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9689    /// compactness arithmetic overflows.
9690    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
9691        match self {
9692            Self::Tensor(tensor) => tensor.is_col_major_contiguous(),
9693            Self::View(view) => view.is_col_major_contiguous(),
9694        }
9695    }
9696
9697    /// Return a compact string summary of this writable target's layout metadata.
9698    ///
9699    /// # Examples
9700    ///
9701    /// ```
9702    /// use tenferro_tensor::{Tensor, TensorWrite};
9703    ///
9704    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9705    /// assert_eq!(
9706    ///     TensorWrite::from_tensor(&mut tensor).layout_summary(),
9707    ///     "shape=[2] strides=[1] offset=0"
9708    /// );
9709    /// # Ok::<(), tenferro_tensor::Error>(())
9710    /// ```
9711    pub fn layout_summary(&self) -> String {
9712        let strides = match self.strides() {
9713            Ok(strides) => strides,
9714            Err(err) => return format!("layout unavailable: {err}"),
9715        };
9716        layout_summary(self.shape(), &strides, self.offset())
9717    }
9718
9719    /// Assert this writable target is compact column-major.
9720    ///
9721    /// # Examples
9722    ///
9723    /// ```
9724    /// use tenferro_tensor::{Tensor, TensorViewMut, TensorWrite, TypedTensorViewMut};
9725    ///
9726    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9727    /// TensorWrite::from_tensor(&mut tensor).assert_col_major_contiguous()?;
9728    /// let mut data = [1.0_f64, 2.0, 3.0];
9729    /// let strided = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![2], 0, &mut data)?);
9730    /// assert!(TensorWrite::from_view(strided).assert_col_major_contiguous().is_err());
9731    /// # Ok::<(), tenferro_tensor::Error>(())
9732    /// ```
9733    ///
9734    /// # Errors
9735    ///
9736    /// Returns [`crate::Error::Validation`] with
9737    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9738    /// compactness arithmetic overflows, or
9739    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
9740    /// view is not compact column-major.
9741    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
9742        let strides = self.strides()?;
9743        assert_layout_col_major_contiguous(
9744            self.is_col_major_contiguous()?,
9745            self.shape(),
9746            &strides,
9747            self.offset(),
9748            "TensorWrite::assert_col_major_contiguous",
9749        )
9750    }
9751}
9752
9753/// Column-major strides derived from a shape.
9754///
9755/// # Examples
9756///
9757/// ```rust
9758/// use tenferro_tensor::col_major_strides;
9759///
9760/// assert_eq!(col_major_strides(&[2, 3])?.as_slice(), &[1, 2]);
9761/// # Ok::<(), tenferro_tensor::Error>(())
9762/// ```
9763/// # Errors
9764///
9765/// Returns [`crate::Error::Validation`] with
9766/// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when a
9767/// column-major stride product overflows.
9768pub fn col_major_strides(shape: &[usize]) -> crate::Result<StrideVec> {
9769    // Inline for common ranks: every compact destination on the CPU and CUDA
9770    // paths derives its strides here, so the heap is off this path entirely.
9771    let mut strides = StrideVec::with_capacity(shape.len());
9772    let mut stride = 1isize;
9773    for &extent in shape {
9774        strides.push(stride);
9775        let extent = isize::try_from(extent).map_err(|_| {
9776            crate::Error::validation("col_major_strides", ValidationError::IntegerOverflow)
9777        })?;
9778        stride = stride.checked_mul(extent).ok_or_else(|| {
9779            crate::Error::validation("col_major_strides", ValidationError::IntegerOverflow)
9780        })?;
9781    }
9782    Ok(strides)
9783}
9784
9785fn try_linear_offset_for_shape(
9786    shape: &[usize],
9787    indices: &[usize],
9788    op: &'static str,
9789) -> crate::Result<usize> {
9790    if indices.len() != shape.len() {
9791        return Err(crate::Error::validation(
9792            op,
9793            ValidationError::RankMismatch {
9794                expected: shape.len(),
9795                actual: indices.len(),
9796            },
9797        ));
9798    }
9799    let mut offset = 0usize;
9800    let mut stride = 1usize;
9801    for (axis, (&idx, &extent)) in indices.iter().zip(shape).enumerate() {
9802        if idx >= extent {
9803            return Err(crate::Error::invalid_argument(
9804                op,
9805                "index",
9806                format!("index {idx} out of bounds for axis {axis} extent {extent}"),
9807            ));
9808        }
9809        offset =
9810            offset
9811                .checked_add(idx.checked_mul(stride).ok_or_else(|| {
9812                    crate::Error::validation(op, ValidationError::IntegerOverflow)
9813                })?)
9814                .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
9815        stride = stride
9816            .checked_mul(extent)
9817            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
9818    }
9819    Ok(offset)
9820}
9821
9822fn checked_view_offset_result(
9823    shape: &[usize],
9824    strides: &[isize],
9825    base_offset: isize,
9826    indices: &[usize],
9827    op: &'static str,
9828) -> crate::Result<usize> {
9829    if indices.len() != shape.len() {
9830        return Err(crate::Error::validation(
9831            op,
9832            ValidationError::RankMismatch {
9833                expected: shape.len(),
9834                actual: indices.len(),
9835            },
9836        ));
9837    }
9838    for (axis, (&index, &extent)) in indices.iter().zip(shape).enumerate() {
9839        if index >= extent {
9840            return Err(crate::Error::invalid_argument(
9841                op,
9842                "index",
9843                format!("index {index} out of bounds for axis {axis} extent {extent}"),
9844            ));
9845        }
9846    }
9847    checked_view_offset(shape, strides, base_offset, indices)
9848        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9849}
9850
9851fn layout_summary(shape: &[usize], strides: &[isize], offset: isize) -> String {
9852    format!("shape={shape:?} strides={strides:?} offset={offset}")
9853}
9854
9855fn assert_layout_col_major_contiguous(
9856    is_contiguous: bool,
9857    shape: &[usize],
9858    strides: &[isize],
9859    offset: isize,
9860    op: &'static str,
9861) -> crate::Result<()> {
9862    if is_contiguous {
9863        Ok(())
9864    } else {
9865        Err(crate::Error::invalid_argument(
9866            op,
9867            "layout",
9868            format!(
9869                "expected compact column-major layout, got {}",
9870                layout_summary(shape, strides, offset)
9871            ),
9872        ))
9873    }
9874}
9875
9876fn try_shape_product(shape: &[usize], op: &'static str) -> crate::Result<usize> {
9877    shape.iter().try_fold(1usize, |acc, &dim| {
9878        acc.checked_mul(dim)
9879            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9880    })
9881}
9882
9883fn try_checked_shape_len(shape: &[usize], data_len: usize, op: &'static str) -> crate::Result<()> {
9884    let n = try_shape_product(shape, op)?;
9885    if data_len != n {
9886        return Err(crate::Error::validation(
9887            op,
9888            ValidationError::ShapeDataLengthMismatch {
9889                expected: n,
9890                actual: data_len,
9891            },
9892        ));
9893    }
9894    Ok(())
9895}
9896
9897fn try_compact_layout<R: TensorRank>(
9898    shape: impl tenferro_tensor_core::IntoRankShape<R>,
9899    op: &'static str,
9900) -> crate::Result<TensorLayout<R>> {
9901    let shape = shape
9902        .into_rank_shape()
9903        .map_err(|err| tensor_layout_error(op, err))?;
9904    TensorLayout::compact(shape).map_err(|err| tensor_layout_error(op, err))
9905}
9906
9907fn tensor_layout_error(
9908    op: &'static str,
9909    err: tenferro_tensor_core::ValidationError,
9910) -> crate::Error {
9911    crate::Error::validation(op, err)
9912}
9913
9914fn checked_view_element_count(shape: &[usize], op: &'static str) -> crate::Result<usize> {
9915    if shape.contains(&0) {
9916        return Ok(0);
9917    }
9918    shape.iter().try_fold(1usize, |product, &dim| {
9919        product
9920            .checked_mul(dim)
9921            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9922    })
9923}
9924
9925fn checked_view_offset(
9926    shape: &[usize],
9927    strides: &[isize],
9928    base_offset: isize,
9929    indices: &[usize],
9930) -> Option<usize> {
9931    if indices.len() != shape.len() {
9932        return None;
9933    }
9934
9935    let mut offset = base_offset;
9936    for ((&index, &extent), &stride) in indices.iter().zip(shape).zip(strides) {
9937        if index >= extent {
9938            return None;
9939        }
9940        let index = isize::try_from(index).ok()?;
9941        let delta = index.checked_mul(stride)?;
9942        offset = offset.checked_add(delta)?;
9943    }
9944
9945    usize::try_from(offset).ok()
9946}
9947
9948fn reachable_layout_span(
9949    shape: &[usize],
9950    strides: &[isize],
9951    offset: isize,
9952) -> crate::Result<Option<(usize, usize)>> {
9953    if shape.contains(&0) {
9954        return Ok(None);
9955    }
9956
9957    let mut min_offset = offset;
9958    let mut max_offset = offset;
9959    for (&extent, &stride) in shape.iter().zip(strides) {
9960        let steps = isize::try_from(extent.saturating_sub(1)).map_err(|_| {
9961            crate::Error::validation(
9962                "TypedTensorViewMut::try_multi_slice_mut",
9963                ValidationError::IntegerOverflow,
9964            )
9965        })?;
9966        let end = stride.checked_mul(steps).ok_or_else(|| {
9967            crate::Error::validation(
9968                "TypedTensorViewMut::try_multi_slice_mut",
9969                ValidationError::IntegerOverflow,
9970            )
9971        })?;
9972        let (axis_min, axis_max) = if end < 0 { (end, 0) } else { (0, end) };
9973        min_offset = min_offset.checked_add(axis_min).ok_or_else(|| {
9974            crate::Error::validation(
9975                "TypedTensorViewMut::try_multi_slice_mut",
9976                ValidationError::IntegerOverflow,
9977            )
9978        })?;
9979        max_offset = max_offset.checked_add(axis_max).ok_or_else(|| {
9980            crate::Error::validation(
9981                "TypedTensorViewMut::try_multi_slice_mut",
9982                ValidationError::IntegerOverflow,
9983            )
9984        })?;
9985    }
9986
9987    let min_offset = usize::try_from(min_offset).map_err(|_| {
9988        crate::Error::invalid_argument(
9989            "TypedTensorViewMut::try_multi_slice_mut",
9990            "layout",
9991            "minimum reachable offset is negative",
9992        )
9993    })?;
9994    let max_offset = usize::try_from(max_offset).map_err(|_| {
9995        crate::Error::invalid_argument(
9996            "TypedTensorViewMut::try_multi_slice_mut",
9997            "layout",
9998            "maximum reachable offset is negative",
9999        )
10000    })?;
10001    Ok(Some((min_offset, max_offset)))
10002}
10003
10004fn split_two_mut_ranges<T>(
10005    data: &mut [T],
10006    first: (usize, usize),
10007    second: (usize, usize),
10008) -> Option<(&mut [T], &mut [T])> {
10009    if first.1 < second.0 {
10010        let (_, after_first_start) = data.split_at_mut(first.0);
10011        let (first_slice, after_first) = after_first_start.split_at_mut(first.1 - first.0 + 1);
10012        let (_, after_gap) = after_first.split_at_mut(second.0 - first.1 - 1);
10013        let (second_slice, _) = after_gap.split_at_mut(second.1 - second.0 + 1);
10014        Some((first_slice, second_slice))
10015    } else if second.1 < first.0 {
10016        let (_, after_second_start) = data.split_at_mut(second.0);
10017        let (second_slice, after_second) = after_second_start.split_at_mut(second.1 - second.0 + 1);
10018        let (_, after_gap) = after_second.split_at_mut(first.0 - second.1 - 1);
10019        let (first_slice, _) = after_gap.split_at_mut(first.1 - first.0 + 1);
10020        Some((first_slice, second_slice))
10021    } else {
10022        None
10023    }
10024}
10025
10026fn adjusted_view_offset(offset: isize, span_start: usize) -> crate::Result<isize> {
10027    let span_start = isize::try_from(span_start).map_err(|_| {
10028        crate::Error::validation(
10029            "TypedTensorViewMut::try_multi_slice_mut",
10030            ValidationError::IntegerOverflow,
10031        )
10032    })?;
10033    offset.checked_sub(span_start).ok_or_else(|| {
10034        crate::Error::validation(
10035            "TypedTensorViewMut::try_multi_slice_mut",
10036            ValidationError::IntegerOverflow,
10037        )
10038    })
10039}
10040
10041fn view_mut_from_layout_and_slice<'a, T: 'static, R: TensorRank>(
10042    layout: &TensorLayout<R>,
10043    offset: isize,
10044    data: &'a mut [T],
10045    placement: Placement,
10046) -> crate::Result<TypedTensorViewMut<'a, T, R>> {
10047    let shape = R::shape_from_vec(shape_vec(layout.shape()))
10048        .map_err(|err| tensor_layout_error("TypedTensorViewMut::try_multi_slice_mut", err))?;
10049    let strides = R::strides_from_vec(stride_vec(layout.strides()))
10050        .map_err(|err| tensor_layout_error("TypedTensorViewMut::try_multi_slice_mut", err))?;
10051    TypedTensorViewMut::from_buffer_ref_mut(
10052        shape,
10053        strides,
10054        offset,
10055        TensorStorageRefMut::Host(data),
10056        placement,
10057        "TypedTensorViewMut::try_multi_slice_mut",
10058    )
10059}
10060
10061fn contiguous_layout_slice<'a, T, R: TensorRank>(
10062    layout: &TensorLayout<R>,
10063    data: &'a [T],
10064    op: &'static str,
10065) -> crate::Result<&'a [T]> {
10066    if !layout
10067        .is_compact_col_major()
10068        .map_err(|err| tensor_layout_error(op, err))?
10069    {
10070        return Err(crate::Error::validation(
10071            op,
10072            ValidationError::NonContiguousViewAsSlice,
10073        ));
10074    }
10075    let len = checked_view_element_count(layout.shape(), op)?;
10076    let start = usize::try_from(layout.offset())
10077        .map_err(|_| crate::Error::invalid_argument(op, "layout", "view offset is negative"))?;
10078    let end = start
10079        .checked_add(len)
10080        .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10081    data.get(start..end)
10082        .ok_or_else(|| crate::Error::validation(op, ValidationError::ViewOutOfBounds))
10083}
10084
10085fn relaxed_col_major_contiguous(
10086    shape: &[usize],
10087    strides: &[isize],
10088    op: &'static str,
10089) -> crate::Result<bool> {
10090    if shape.contains(&0) {
10091        return Ok(true);
10092    }
10093
10094    let mut expected = 1isize;
10095    for (&extent, &stride) in shape.iter().zip(strides) {
10096        if extent <= 1 {
10097            continue;
10098        }
10099        if stride != expected {
10100            return Ok(false);
10101        }
10102        let extent = isize::try_from(extent)
10103            .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10104        expected = expected
10105            .checked_mul(extent)
10106            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10107    }
10108    Ok(true)
10109}
10110
10111fn reshape_layout_dyn<R: TensorRank>(
10112    layout: &TensorLayout<R>,
10113    shape: &[usize],
10114    buffer_len: usize,
10115    op: &'static str,
10116) -> crate::Result<TensorLayout<DynRank>> {
10117    match layout.reshape_view_as::<DynRank>(shape_vec(shape), buffer_len) {
10118        Ok(layout) => Ok(layout),
10119        Err(err) => {
10120            if !relaxed_col_major_contiguous(layout.shape(), layout.strides(), op)? {
10121                return Err(tensor_layout_error(op, err));
10122            }
10123            let from = checked_view_element_count(layout.shape(), op)?;
10124            let to = checked_view_element_count(shape, op)?;
10125            if from != to {
10126                return Err(tensor_layout_error(
10127                    op,
10128                    tenferro_tensor_core::ShapeMismatch::ReshapeElementCount { from, to }.into(),
10129                ));
10130            }
10131            TensorLayout::<DynRank>::compact(shape_vec(shape))
10132                .and_then(|compact| {
10133                    TensorLayout::from_parts(
10134                        shape_vec(compact.shape()),
10135                        stride_vec(compact.strides()),
10136                        layout.offset(),
10137                        buffer_len,
10138                    )
10139                })
10140                .map_err(|err| tensor_layout_error(op, err))
10141        }
10142    }
10143}
10144
10145fn core_slice_specs(
10146    slices: &[StridedSliceSpec],
10147    shape: &[usize],
10148    op: &'static str,
10149) -> crate::Result<TinyVec<[CoreSliceSpec; 8]>> {
10150    if slices.len() != shape.len() {
10151        return Err(crate::Error::validation(
10152            op,
10153            ValidationError::RankMismatch {
10154                expected: shape.len(),
10155                actual: slices.len(),
10156            },
10157        ));
10158    }
10159
10160    let mut specs = TinyVec::<[CoreSliceSpec; 8]>::with_capacity(slices.len());
10161    for (slice, &axis_len) in slices.iter().zip(shape) {
10162        specs.push(core_slice_spec(*slice, axis_len, op)?);
10163    }
10164    Ok(specs)
10165}
10166
10167fn core_slice_spec(
10168    slice: StridedSliceSpec,
10169    axis_len: usize,
10170    op: &'static str,
10171) -> crate::Result<CoreSliceSpec> {
10172    if slice.step() == 0 {
10173        return Err(crate::Error::validation(
10174            op,
10175            ValidationError::InvalidSliceStep { step: slice.step() },
10176        ));
10177    }
10178
10179    let start = normalize_strided_bound(slice.start(), axis_len, op, "slice start")?;
10180    let end = match slice.end() {
10181        Some(end) => normalize_strided_bound(end, axis_len, op, "slice end")?,
10182        None => isize::try_from(axis_len)
10183            .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10184    };
10185
10186    if slice.step() > 0 {
10187        return Ok(CoreSliceSpec {
10188            start,
10189            end,
10190            step: slice.step(),
10191        });
10192    }
10193
10194    if start >= end {
10195        // `core`'s negative-step contract requires the inclusive `start` to
10196        // point at an element (`start < axis_len`). An empty selection is
10197        // step-sign independent, so encode the `start == axis_len` boundary at
10198        // the last element instead of re-encoding it verbatim (which `core`
10199        // would reject as out of bounds).
10200        let empty_start = if axis_len == 0 {
10201            start
10202        } else {
10203            start.min(axis_len as isize - 1)
10204        };
10205        return Ok(CoreSliceSpec {
10206            start: empty_start,
10207            end: empty_start,
10208            step: slice.step(),
10209        });
10210    }
10211
10212    Ok(CoreSliceSpec {
10213        start: end
10214            .checked_sub(1)
10215            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10216        end: start
10217            .checked_sub(1)
10218            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10219        step: slice.step(),
10220    })
10221}
10222
10223fn normalize_strided_bound(
10224    bound: isize,
10225    axis_len: usize,
10226    op: &'static str,
10227    role: &'static str,
10228) -> crate::Result<isize> {
10229    let original_axis_len = axis_len;
10230    let axis_len = isize::try_from(axis_len)
10231        .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10232    let bound = if bound < 0 {
10233        axis_len
10234            .checked_add(bound)
10235            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?
10236    } else {
10237        bound
10238    };
10239    if !(0..=axis_len).contains(&bound) {
10240        let (start, end) = if role == "slice start" {
10241            (bound, bound)
10242        } else {
10243            (0, bound)
10244        };
10245        return Err(crate::Error::validation(
10246            op,
10247            ValidationError::InvalidSliceBounds {
10248                start,
10249                end,
10250                axis_len: original_axis_len,
10251            },
10252        ));
10253    }
10254    Ok(bound)
10255}
10256
10257fn slice_axis_specs(
10258    rank: usize,
10259    axis: usize,
10260    slice: StridedSliceSpec,
10261    op: &'static str,
10262) -> crate::Result<Vec<StridedSliceSpec>> {
10263    if axis >= rank {
10264        return Err(crate::Error::validation(
10265            op,
10266            ValidationError::AxisOutOfBounds {
10267                axis: isize::try_from(axis).unwrap_or(isize::MAX),
10268                rank,
10269            },
10270        ));
10271    }
10272
10273    let mut slices = vec![StridedSliceSpec::all(); rank];
10274    slices[axis] = slice;
10275    Ok(slices)
10276}
10277
10278pub(crate) fn default_placement() -> Placement {
10279    Placement {
10280        memory_kind: MemoryKind::UnpinnedHost,
10281        device: None,
10282        cpu_affinity: None,
10283    }
10284}
10285
10286/// Refuse a label a payload demonstrably contradicts.
10287///
10288/// One fact has one owner: the payload. A plain host payload is a Rust slice, so
10289/// `MemoryKind::Device` or `Managed` on one names memory it definitely does not
10290/// have; that is the contradiction this check refuses, and it is what keeps
10291/// "host memory labelled device-resident" out of the workspace.
10292///
10293/// The opposite direction stays legal on purpose. A backend payload is an opaque
10294/// [`BackendAllocation`](crate::BackendAllocation), so this crate cannot decide
10295/// whether the handle is device memory or host-mapped; the runtime labels such a
10296/// payload with the caller's storage class, and `MemoryKind::Other` is likewise
10297/// unmodelled. Refusing those would turn a routing key into an unrepresentable
10298/// state without removing a single alias risk.
10299///
10300/// Enforced where an owned tensor is built with an explicit placement and in
10301/// [`TypedTensor::set_placement`], the only two ways a payload and a label meet.
10302fn validate_placement_for_payload(
10303    op: &'static str,
10304    payload_is_host: bool,
10305    placement: &Placement,
10306) -> crate::Result<()> {
10307    let contradicts = payload_is_host
10308        && matches!(
10309            placement.memory_kind,
10310            MemoryKind::Device | MemoryKind::Managed
10311        );
10312    if contradicts {
10313        return Err(crate::Error::runtime_state(
10314            op,
10315            format!(
10316                "the placement says {:?} but the payload is plain host memory; a host payload cannot be device memory",
10317                placement.memory_kind
10318            ),
10319        ));
10320    }
10321    Ok(())
10322}
10323
10324fn typed_tensor_from_vec_col_major<T, R: TensorRank>(
10325    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10326    data: Vec<T>,
10327    op: &'static str,
10328) -> crate::Result<TypedTensor<T, R>> {
10329    try_typed_tensor_from_vec_col_major(shape, data, op)
10330}
10331
10332fn try_typed_tensor_from_vec_col_major<T, R: TensorRank>(
10333    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10334    data: Vec<T>,
10335    op: &'static str,
10336) -> crate::Result<TypedTensor<T, R>> {
10337    let shape = shape
10338        .into_rank_shape()
10339        .map_err(|err| tensor_layout_error(op, err))?;
10340    let layout = tenferro_tensor_core::col_major_strides(shape.as_ref())
10341        .map_err(|err| tensor_layout_error(op, err))?;
10342    try_checked_shape_len(shape.as_ref(), data.len(), op)?;
10343    Ok(TypedTensor {
10344        shape,
10345        placement: default_placement(),
10346        layout,
10347        storage: DynamicStorage::Host(HostStorage {
10348            data: HostData::new(data),
10349        }),
10350    })
10351}
10352
10353fn typed_tensor_zeros<T: TensorScalar + Zero, R: TensorRank>(
10354    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10355) -> crate::Result<TypedTensor<T, R>> {
10356    try_typed_tensor_zeros(shape)
10357}
10358
10359fn try_typed_tensor_zeros<T: TensorScalar + Clone + Zero, R: TensorRank>(
10360    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10361) -> crate::Result<TypedTensor<T, R>> {
10362    let layout = try_compact_layout(shape, "zeros")?;
10363    let n = try_shape_product(layout.shape(), "zeros")?;
10364    typed_tensor_from_vec_col_major(
10365        R::shape_from_vec(shape_vec(layout.shape()))
10366            .map_err(|err| tensor_layout_error("zeros", err))?,
10367        vec![T::zero(); n],
10368        "zeros",
10369    )
10370}
10371
10372fn typed_tensor_ones<T: TensorScalar + One + Zero, R: TensorRank>(
10373    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10374) -> crate::Result<TypedTensor<T, R>> {
10375    try_typed_tensor_ones(shape)
10376}
10377
10378fn try_typed_tensor_ones<T: TensorScalar + Clone + One + Zero, R: TensorRank>(
10379    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10380) -> crate::Result<TypedTensor<T, R>> {
10381    let layout = try_compact_layout(shape, "ones")?;
10382    let n = try_shape_product(layout.shape(), "ones")?;
10383    typed_tensor_from_vec_col_major(
10384        R::shape_from_vec(shape_vec(layout.shape()))
10385            .map_err(|err| tensor_layout_error("ones", err))?,
10386        vec![T::one(); n],
10387        "ones",
10388    )
10389}
10390
10391fn typed_tensor_from_buffer_col_major<T: TensorScalar + Send + Sync + 'static, R: TensorRank>(
10392    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10393    buffer: StorageBuffer<T>,
10394    placement: Placement,
10395) -> crate::Result<TypedTensor<T, R>> {
10396    try_typed_tensor_from_buffer_col_major(shape, buffer, placement)
10397}
10398
10399#[doc(hidden)]
10400fn typed_tensor_from_backend_allocation<T: TensorScalar + Send + Sync + 'static, R: TensorRank>(
10401    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10402    allocation: Box<dyn crate::BackendAllocation>,
10403    placement: Placement,
10404) -> crate::Result<TypedTensor<T, R>> {
10405    let layout = try_compact_layout(shape, "from_backend_allocation")?;
10406    let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
10407        .map_err(|err| tensor_layout_error("from_backend_allocation", err))?;
10408    let shape = group_shape.clone();
10409    let (mut group, slot) =
10410        AllocationGroup::from_backend_allocation::<T, R>(group_shape, allocation)
10411            .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10412    group
10413        .set_descriptor_placement(slot, placement.clone())
10414        .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10415    let allocation_index = group
10416        .allocation_index(slot)
10417        .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10418    let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
10419    Ok(TypedTensor {
10420        shape,
10421        placement,
10422        layout: stride_vec(layout.strides()),
10423        storage: DynamicStorage::Group(GroupStorage {
10424            group: Box::new(OwnedTensorGroup {
10425                group,
10426                slot,
10427                allocation_index,
10428                host_ptr,
10429                host_byte_len,
10430                _rank: PhantomData,
10431            }),
10432        }),
10433    })
10434}
10435
10436fn try_typed_tensor_from_buffer_col_major<
10437    T: TensorScalar + Send + Sync + 'static,
10438    R: TensorRank,
10439>(
10440    shape: impl tenferro_tensor_core::IntoRankShape<R>,
10441    buffer: StorageBuffer<T>,
10442    placement: Placement,
10443) -> crate::Result<TypedTensor<T, R>> {
10444    let layout = try_compact_layout(shape, "from_buffer_col_major")?;
10445    let len = buffer.len();
10446    try_checked_shape_len(layout.shape(), len, "from_buffer_col_major")?;
10447    let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
10448        .map_err(|err| tensor_layout_error("from_buffer_col_major", err))?;
10449    match buffer {
10450        StorageBuffer::Host(data) => {
10451            validate_placement_for_payload("from_buffer_col_major", true, &placement)?;
10452            Ok(TypedTensor {
10453                shape: group_shape,
10454                placement,
10455                layout: stride_vec(layout.strides()),
10456                storage: DynamicStorage::Host(HostStorage {
10457                    data: HostData::new(data),
10458                }),
10459            })
10460        }
10461        StorageBuffer::Backend(buffer) => {
10462            let group = OwnedTensorGroup::from_backend_buffer(
10463                group_shape.clone(),
10464                StorageBuffer::Backend(buffer),
10465                placement.clone(),
10466            )?;
10467            Ok(TypedTensor {
10468                shape: group_shape,
10469                placement,
10470                layout: stride_vec(layout.strides()),
10471                storage: DynamicStorage::Group(GroupStorage {
10472                    group: Box::new(group),
10473                }),
10474            })
10475        }
10476    }
10477}
10478
10479impl<T: TensorScalar + Zero, R: TensorRank> TypedTensor<T, R> {
10480    /// Allocate a zero-filled tensor.
10481    ///
10482    /// # Examples
10483    ///
10484    /// ```rust
10485    /// use tenferro_tensor::TypedTensor;
10486    ///
10487    /// let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
10488    /// assert_eq!(t.n_elements(), 6);
10489    /// ```
10490    /// # Errors
10491    ///
10492    /// Returns [`crate::Error::Validation`] with
10493    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
10494    /// product or compact-stride arithmetic overflows.
10495    /// A vector or slice with a different static rank returns
10496    /// [`tenferro_tensor_core::ValidationError::RankMismatch`].
10497    pub fn zeros(shape: impl tenferro_tensor_core::IntoRankShape<R>) -> crate::Result<Self> {
10498        typed_tensor_zeros(shape)
10499    }
10500}
10501
10502impl<T: TensorScalar + One + Zero, R: TensorRank> TypedTensor<T, R> {
10503    /// Allocate a one-filled tensor.
10504    ///
10505    /// # Examples
10506    ///
10507    /// ```rust
10508    /// use tenferro_tensor::TypedTensor;
10509    ///
10510    /// let t = TypedTensor::<f64>::ones(vec![2]).unwrap();
10511    /// assert_eq!(t.host_data().unwrap(), &[1.0, 1.0]);
10512    /// ```
10513    /// # Errors
10514    ///
10515    /// Returns [`crate::Error::Validation`] with
10516    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
10517    /// product or compact-stride arithmetic overflows.
10518    /// A vector or slice with a different static rank returns
10519    /// [`tenferro_tensor_core::ValidationError::RankMismatch`].
10520    pub fn ones(shape: impl tenferro_tensor_core::IntoRankShape<R>) -> crate::Result<Self> {
10521        typed_tensor_ones(shape)
10522    }
10523}
10524
10525impl<T, R: TensorRank> TypedTensor<T, R> {
10526    /// Adopt a column-major host `Vec<T>` with no scalar, copy or thread-safety bound.
10527    ///
10528    /// # Examples
10529    /// ```
10530    /// use tenferro_tensor::{Rank, TypedTensor};
10531    /// struct Custom(String);
10532    /// let tensor = TypedTensor::<Custom, Rank<2>>::from_vec_col_major(
10533    ///     [1, 2], vec![Custom("a".into()), Custom("b".into())],
10534    /// )?;
10535    /// assert_eq!(tensor.get(&[0, 1])?.0.as_str(), "b");
10536    /// # Ok::<(), tenferro_tensor::Error>(())
10537    /// ```
10538    /// # Errors
10539    /// Returns [`crate::Error::Validation`] for a rank mismatch, shape/data
10540    /// length mismatch or shape/stride arithmetic overflow.
10541    pub fn from_vec_col_major(
10542        shape: impl tenferro_tensor_core::IntoRankShape<R>,
10543        data: Vec<T>,
10544    ) -> crate::Result<Self> {
10545        typed_tensor_from_vec_col_major(shape, data, "from_vec_col_major")
10546    }
10547
10548    /// Explicitly import row-major host values into column-major storage.
10549    ///
10550    /// Clones each input element once; no backend or scalar registration is used.
10551    ///
10552    /// # Examples
10553    /// ```
10554    /// use tenferro_tensor::{Rank, TypedTensor};
10555    /// let tensor = TypedTensor::<i32, Rank<2>>::from_vec_row_major(
10556    ///     [2, 3], vec![1, 2, 3, 4, 5, 6],
10557    /// )?;
10558    /// assert_eq!(tensor.get(&[1, 0])?, &4);
10559    /// assert_eq!(tensor.get(&[0, 2])?, &3);
10560    /// # Ok::<(), tenferro_tensor::Error>(())
10561    /// ```
10562    /// # Errors
10563    /// Returns [`crate::Error::Validation`] for a rank, shape-length or stride overflow,
10564    /// or when the shape product disagrees with the input length.
10565    pub fn from_vec_row_major(
10566        shape: impl tenferro_tensor_core::IntoRankShape<R>,
10567        data: Vec<T>,
10568    ) -> crate::Result<Self>
10569    where
10570        T: Clone,
10571    {
10572        let op = "from_vec_row_major";
10573        let (shape, reordered) = row_major_reorder(shape, data, op)?;
10574        typed_tensor_from_vec_col_major(shape, reordered, op)
10575    }
10576
10577    /// Consume this compact tensor and return the original host `Vec<T>`.
10578    ///
10579    /// # Examples
10580    ///
10581    /// ```
10582    /// use tenferro_tensor::TypedTensor;
10583    /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
10584    /// let data = tensor.into_host_vec().map_err(|failure| failure.into_parts().1)?;
10585    /// assert_eq!(data, vec![1, 2]);
10586    /// # Ok::<(), tenferro_tensor::Error>(())
10587    /// ```
10588    ///
10589    /// # Errors
10590    /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10591    /// storage is device-only, the managed root cannot export a host vector, or
10592    /// a group-backed descriptor is not compact column-major
10593    /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
10594    pub fn into_host_vec(self) -> std::result::Result<Vec<T>, ReinterpretError<Self>>
10595    where
10596        T: 'static,
10597    {
10598        let TypedTensor {
10599            shape,
10600            placement,
10601            layout,
10602            storage,
10603        } = self;
10604        match storage {
10605            DynamicStorage::Host(HostStorage { data }) => Ok(data.into_vec()),
10606            DynamicStorage::Group(GroupStorage { group }) => {
10607                let range = match group_logical_range(&group, "TypedTensor::into_host_vec") {
10608                    Ok(range) => range,
10609                    Err(error) => {
10610                        return Err(ReinterpretError::new(
10611                            TypedTensor {
10612                                shape,
10613                                placement,
10614                                layout,
10615                                storage: DynamicStorage::Group(GroupStorage { group }),
10616                            },
10617                            error,
10618                        ))
10619                    }
10620                };
10621                match group.into_host_vec::<T>() {
10622                    Ok(mut data) => {
10623                        // INVARIANT: the live descriptor's compact logical range
10624                        // was validated inside its root span, so the exported
10625                        // vector covers it.
10626                        debug_assert!(range.end <= data.len(), "descriptor range exceeds its root");
10627                        data.truncate(range.end);
10628                        data.drain(..range.start);
10629                        // The exported vector represents the logical extent only,
10630                        // so it must not retain the root's capacity.
10631                        data.shrink_to_fit();
10632                        Ok(data)
10633                    }
10634                    Err((group, error)) => Err(ReinterpretError::new(
10635                        TypedTensor {
10636                            shape,
10637                            placement,
10638                            layout,
10639                            storage: DynamicStorage::Group(GroupStorage {
10640                                group: Box::new(group),
10641                            }),
10642                        },
10643                        error,
10644                    )),
10645                }
10646            }
10647        }
10648    }
10649
10650    /// Consume the original host vector along with its column-major shape.
10651    ///
10652    /// # Examples
10653    ///
10654    /// ```
10655    /// use tenferro_tensor::TypedTensor;
10656    /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2, 1], vec![1, 2])?;
10657    /// let (shape, data) = tensor.into_vec_col_major().map_err(|failure| failure.into_parts().1)?;
10658    /// assert_eq!(shape, vec![2, 1]);
10659    /// assert_eq!(data, vec![1, 2]);
10660    /// # Ok::<(), tenferro_tensor::Error>(())
10661    /// ```
10662    ///
10663    /// # Errors
10664    /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10665    /// storage is device-only, the managed root cannot export a host vector, or
10666    /// a group-backed descriptor is not compact column-major
10667    /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
10668    pub fn into_vec_col_major(
10669        self,
10670    ) -> std::result::Result<(Vec<usize>, Vec<T>), ReinterpretError<Self>>
10671    where
10672        T: 'static,
10673    {
10674        let shape = self.shape().to_vec();
10675        match self.into_host_vec() {
10676            Ok(data) => Ok((shape, data)),
10677            Err(failure) => Err(failure),
10678        }
10679    }
10680
10681    /// Borrow the plain host values of this tensor.
10682    ///
10683    /// A group-backed owner extracted from a larger root exposes only its
10684    /// logical, compact values; [`Self::as_view`] retains the whole backing
10685    /// root when a caller needs to inspect elements outside the extent.
10686    ///
10687    /// # Examples
10688    ///
10689    /// ```
10690    /// use tenferro_tensor::TypedTensor;
10691    /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
10692    /// assert_eq!(tensor.host_data()?, &[1.0, 2.0]);
10693    /// # Ok::<(), tenferro_tensor::Error>(())
10694    /// ```
10695    ///
10696    /// # Errors
10697    /// Returns [`crate::Error::RuntimeState`] for device-only storage and the
10698    /// non-compact-descriptor validation error for a strided owner.
10699    pub fn host_data(&self) -> crate::Result<&[T]> {
10700        match &self.storage {
10701            DynamicStorage::Host(HostStorage { data }) => Ok(data.as_slice()),
10702            DynamicStorage::Group(core) => {
10703                let data = core.group.host_slice::<T>()?;
10704                let range = group_logical_range(&core.group, "TypedTensor::host_data")?;
10705                data.get(range).ok_or_else(|| {
10706                    crate::Error::validation(
10707                        "TypedTensor::host_data",
10708                        ValidationError::ViewOutOfBounds,
10709                    )
10710                })
10711            }
10712        }
10713    }
10714
10715    /// Borrow the logical host values as a flat column-major slice without
10716    /// copying.
10717    ///
10718    /// This is the value view of [`Self::host_data`]: a root-preserving
10719    /// extraction exposes only its compact logical slice, never the root prefix
10720    /// and never elements outside its extent.
10721    ///
10722    /// # Examples
10723    /// ```
10724    /// use tenferro_tensor::TypedTensor;
10725    /// let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
10726    /// assert_eq!(tensor.as_slice()?, &["a", "b"]);
10727    /// # Ok::<(), tenferro_tensor::Error>(())
10728    /// ```
10729    /// # Errors
10730    /// Device-only storage returns [`crate::Error::RuntimeState`].
10731    pub fn as_slice(&self) -> crate::Result<&[T]> {
10732        self.host_data()
10733    }
10734
10735    /// Mutably borrow the plain host values of this tensor.
10736    ///
10737    /// The exclusive borrow covers exactly the logical, compact values of a
10738    /// root-preserving owner, so writes cannot reach elements outside its
10739    /// extent.
10740    ///
10741    /// # Examples
10742    ///
10743    /// ```
10744    /// use tenferro_tensor::TypedTensor;
10745    /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
10746    /// tensor.host_data_mut()?[0] = 5.0;
10747    /// assert_eq!(tensor.host_data()?, &[5.0, 2.0]);
10748    /// # Ok::<(), tenferro_tensor::Error>(())
10749    /// ```
10750    ///
10751    /// # Errors
10752    /// Returns [`crate::Error::RuntimeState`] for device-only storage and the
10753    /// non-compact-descriptor validation error for a strided owner.
10754    pub fn host_data_mut(&mut self) -> crate::Result<&mut [T]> {
10755        match &mut self.storage {
10756            DynamicStorage::Host(HostStorage { data }) => Ok(data.as_mut_slice()),
10757            DynamicStorage::Group(core) => {
10758                let range = group_logical_range(&core.group, "TypedTensor::host_data_mut")?;
10759                let data = core.group.host_slice_mut::<T>()?;
10760                data.get_mut(range).ok_or_else(|| {
10761                    crate::Error::validation(
10762                        "TypedTensor::host_data_mut",
10763                        ValidationError::ViewOutOfBounds,
10764                    )
10765                })
10766            }
10767        }
10768    }
10769
10770    /// Borrow an element by checked column-major multi-index.
10771    ///
10772    /// # Examples
10773    /// ```
10774    /// use tenferro_tensor::TypedTensor;
10775    /// let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
10776    /// assert_eq!(tensor.get(&[1])?, "b");
10777    /// # Ok::<(), tenferro_tensor::Error>(())
10778    /// ```
10779    /// # Errors
10780    /// Invalid rank, coordinates or offset return [`crate::Error::Validation`];
10781    /// device-only storage returns [`crate::Error::RuntimeState`].
10782    pub fn get(&self, indices: &[usize]) -> crate::Result<&T> {
10783        let offset = self.linear_offset(indices)?;
10784        self.host_data()?.get(offset).ok_or_else(|| {
10785            crate::Error::validation("TypedTensor::get", ValidationError::ViewOutOfBounds)
10786        })
10787    }
10788
10789    /// Exclusively borrow an element by checked column-major multi-index.
10790    ///
10791    /// # Examples
10792    /// ```
10793    /// use tenferro_tensor::TypedTensor;
10794    /// let mut tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
10795    /// *tensor.get_mut(&[0])? = "b".into();
10796    /// assert_eq!(tensor.get(&[0])?, "b");
10797    /// # Ok::<(), tenferro_tensor::Error>(())
10798    /// ```
10799    /// # Errors
10800    /// Invalid rank, coordinates or offset return [`crate::Error::Validation`];
10801    /// device-only storage returns [`crate::Error::RuntimeState`].
10802    pub fn get_mut(&mut self, indices: &[usize]) -> crate::Result<&mut T> {
10803        let offset = self.linear_offset(indices)?;
10804        self.host_data_mut()?.get_mut(offset).ok_or_else(|| {
10805            crate::Error::validation("TypedTensor::get_mut", ValidationError::ViewOutOfBounds)
10806        })
10807    }
10808
10809    /// Make an explicit independent host copy with the same shape and placement.
10810    ///
10811    /// The dynamic `TypedTensor` does not implement [`Clone`] (only the
10812    /// host-only representation does): the copy reads host data, rejects
10813    /// device-only storage, and creates a new owner, so it is fallible. See
10814    /// [`Tensor::duplicate`] for the sharing alternatives.
10815    ///
10816    /// # Examples
10817    /// ```
10818    /// use tenferro_tensor::TypedTensor;
10819    /// let tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
10820    /// assert_eq!(tensor.duplicate()?.get(&[0])?, "a");
10821    /// # Ok::<(), tenferro_tensor::Error>(())
10822    /// ```
10823    /// # Errors
10824    /// Device-only storage returns [`crate::Error::RuntimeState`]; invalid
10825    /// host metadata returns [`crate::Error::Validation`].
10826    pub fn duplicate(&self) -> crate::Result<Self>
10827    where
10828        T: Clone,
10829    {
10830        let mut copy = Self::from_vec_col_major(
10831            R::shape_from_vec(shape_vec(self.shape()))
10832                .map_err(|err| tensor_layout_error("TypedTensor::duplicate", err))?,
10833            self.host_data()?.to_vec(),
10834        )?;
10835        copy.set_placement(self.placement().clone())?;
10836        Ok(copy)
10837    }
10838
10839    /// Create a tensor from an existing buffer and compact column-major layout.
10840    ///
10841    /// This preserves the owned tensor invariant that layout metadata is
10842    /// compact column-major, including for backend-owned buffers.
10843    ///
10844    /// # Examples
10845    ///
10846    /// ```
10847    /// use tenferro_tensor::{StorageBuffer, Placement, TypedTensor};
10848    ///
10849    /// let tensor = TypedTensor::<f64>::from_buffer_col_major(
10850    ///     vec![2],
10851    ///     StorageBuffer::Host(vec![1.0, 2.0]),
10852    ///     Placement {
10853    ///         memory_kind: tenferro_tensor::MemoryKind::UnpinnedHost,
10854    ///         device: None,
10855    ///         cpu_affinity: None,
10856    ///     },
10857    /// )
10858    /// .unwrap();
10859    /// assert_eq!(tensor.shape(), &[2]);
10860    /// ```
10861    /// # Errors
10862    ///
10863    /// Returns [`crate::Error::Validation`] with
10864    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
10865    /// the shape product differs from the buffer length,
10866    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape or
10867    /// stride arithmetic overflows, or
10868    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when a supplied
10869    /// rank-specific shape cannot be represented.
10870    pub fn from_buffer_col_major(
10871        shape: impl tenferro_tensor_core::IntoRankShape<R>,
10872        buffer: StorageBuffer<T>,
10873        placement: Placement,
10874    ) -> crate::Result<Self>
10875    where
10876        T: TensorScalar + Send + Sync + 'static,
10877    {
10878        typed_tensor_from_buffer_col_major(shape, buffer, placement)
10879    }
10880
10881    /// Consume a scalar-independent provider root into one compact tensor.
10882    #[doc(hidden)]
10883    pub fn from_backend_allocation(
10884        shape: impl tenferro_tensor_core::IntoRankShape<R>,
10885        allocation: Box<dyn crate::BackendAllocation>,
10886        placement: Placement,
10887    ) -> crate::Result<Self>
10888    where
10889        T: TensorScalar + Send + Sync + 'static,
10890    {
10891        typed_tensor_from_backend_allocation(shape, allocation, placement)
10892    }
10893
10894    /// Convert this tensor into static rank metadata after validating its rank.
10895    ///
10896    /// The buffer and placement are preserved. This method changes only the
10897    /// compile-time rank marker on the owned compact column-major tensor.
10898    ///
10899    /// # Examples
10900    ///
10901    /// ```
10902    /// use tenferro_tensor::{Rank, TypedTensor};
10903    ///
10904    /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![1.0; 6]).unwrap();
10905    /// let Ok(ranked) = tensor.try_into_rank::<2>() else {
10906    ///     panic!("a rank-2 tensor converts to two axes")
10907    /// };
10908    /// assert_eq!(ranked.shape(), &[2, 3]);
10909    /// # Ok::<(), tenferro_tensor::Error>(())
10910    /// ```
10911    /// # Errors
10912    ///
10913    /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10914    /// typed rank does not match the existing shape, with
10915    /// [`crate::Error::Validation`] and
10916    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] as the cause,
10917    /// or when the compact rank layout overflows.
10918    pub fn try_into_rank<const N: usize>(
10919        self,
10920    ) -> std::result::Result<TypedTensor<T, Rank<N>>, ReinterpretError<Self>> {
10921        let op = "TypedTensor::try_into_rank";
10922        let actual = self.shape().len();
10923        let shape: [usize; N] = match self.shape().try_into() {
10924            Ok(shape) => shape,
10925            Err(_) => {
10926                return Err(ReinterpretError::new(
10927                    self,
10928                    tensor_layout_error(
10929                        op,
10930                        ValidationError::RankMismatch {
10931                            expected: N,
10932                            actual,
10933                        },
10934                    ),
10935                ))
10936            }
10937        };
10938        let layout = match TensorLayout::<Rank<N>>::compact(shape) {
10939            Ok(layout) => layout,
10940            Err(error) => return Err(ReinterpretError::new(self, tensor_layout_error(op, error))),
10941        };
10942        let TypedTensor {
10943            placement, storage, ..
10944        } = self;
10945        let storage = match storage {
10946            DynamicStorage::Host(host) => DynamicStorage::Host(host),
10947            DynamicStorage::Group(GroupStorage { group }) => DynamicStorage::Group(GroupStorage {
10948                group: Box::new(OwnedTensorGroup {
10949                    group: group.group,
10950                    slot: group.slot,
10951                    allocation_index: group.allocation_index,
10952                    host_ptr: group.host_ptr,
10953                    host_byte_len: group.host_byte_len,
10954                    _rank: PhantomData,
10955                }),
10956            }),
10957        };
10958        Ok(TypedTensor {
10959            shape,
10960            placement,
10961            layout: stride_vec(layout.strides()),
10962            storage,
10963        })
10964    }
10965
10966    /// Return the storage backing this tensor.
10967    ///
10968    /// This is an explicit storage-inspection API for backend glue and tests.
10969    /// Host value inspection should prefer [`TypedTensor::host_data`] when the
10970    /// caller requires host storage.
10971    ///
10972    /// # Panics
10973    ///
10974    /// Panics only if the typed descriptor and its single group owner are
10975    /// internally inconsistent.
10976    ///
10977    /// # Examples
10978    ///
10979    /// ```
10980    /// use tenferro_tensor::{StorageBuffer, TypedTensor};
10981    ///
10982    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
10983    /// assert!(matches!(t.buffer(), StorageBuffer::Host(_)));
10984    /// ```
10985    pub fn buffer(&self) -> &StorageBuffer<T>
10986    where
10987        T: 'static,
10988    {
10989        match &self.storage {
10990            DynamicStorage::Host(HostStorage { data }) => &data.buffer,
10991            DynamicStorage::Group(core) => core
10992                .group
10993                .host_buffer::<T>()
10994                .or_else(|| core.group.backend_buffer::<T>())
10995                .unwrap_or_else(|| unreachable!("typed tensor group storage mismatch")),
10996        }
10997    }
10998
10999    /// Return the provider family for this tensor when backend-owned.
11000    #[doc(hidden)]
11001    pub fn backend_family(&self) -> Option<&'static str>
11002    where
11003        T: TensorScalar + 'static,
11004    {
11005        self.as_view().backend_family()
11006    }
11007
11008    /// Return the opaque backend buffer for backend-owned tensors.
11009    #[doc(hidden)]
11010    pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>>
11011    where
11012        T: 'static,
11013    {
11014        match &self.storage {
11015            DynamicStorage::Host(..) => None,
11016            DynamicStorage::Group(core) => match core.group.backend_buffer::<T>() {
11017                Some(StorageBuffer::Backend(buffer)) => Some(buffer.as_ref()),
11018                Some(StorageBuffer::Host(_)) | None => None,
11019            },
11020        }
11021    }
11022
11023    /// Return the mutable backend buffer for an exclusive owner borrow.
11024    #[doc(hidden)]
11025    pub fn backend_buffer_mut(&mut self) -> Option<&mut dyn BackendStorage<T>>
11026    where
11027        T: 'static,
11028    {
11029        let DynamicStorage::Group(core) = &mut self.storage else {
11030            return None;
11031        };
11032        match core.group.backend_buffer_mut::<T>()? {
11033            StorageBuffer::Host(_) => None,
11034            StorageBuffer::Backend(buffer) => Some(buffer.as_mut()),
11035        }
11036    }
11037
11038    /// Prepare this backend tensor for one provider-native read binding.
11039    #[doc(hidden)]
11040    pub fn prepare_device_read(
11041        &self,
11042        op: &'static str,
11043    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
11044    where
11045        T: TensorScalar + 'static,
11046    {
11047        let DynamicStorage::Group(core) = &self.storage else {
11048            return Err(crate::Error::runtime_state_source(
11049                op,
11050                crate::AccessError::Unsupported { backend: "host" },
11051            ));
11052        };
11053        let layout = self.physical_layout();
11054        core.group
11055            .prepare_device_read_for_layout::<T>(&layout)
11056            .map_err(|error| crate::Error::runtime_state_source(op, error))
11057    }
11058
11059    /// Prepare this backend tensor for one provider-native write binding.
11060    #[doc(hidden)]
11061    pub fn prepare_device_write(
11062        &mut self,
11063        op: &'static str,
11064    ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
11065    where
11066        T: TensorScalar + 'static,
11067    {
11068        let layout = self.physical_layout();
11069        let DynamicStorage::Group(core) = &mut self.storage else {
11070            return Err(crate::Error::runtime_state_source(
11071                op,
11072                crate::AccessError::Unsupported { backend: "host" },
11073            ));
11074        };
11075        core.group
11076            .prepare_device_write_for_layout::<T>(&layout)
11077            .map_err(|error| crate::Error::runtime_state_source(op, error))
11078    }
11079
11080    /// Element count of the tensor's backing storage.
11081    ///
11082    /// A root-preserving owner reports its whole backing root, not just the
11083    /// logical view extent, so layout validation for views and reshapes bounds
11084    /// against the real allocation.
11085    pub(crate) fn buffer_len(&self) -> usize
11086    where
11087        T: 'static,
11088    {
11089        match &self.storage {
11090            DynamicStorage::Host(HostStorage { data }) => data.as_slice().len(),
11091            DynamicStorage::Group(core) => core
11092                .group
11093                .group
11094                .descriptor_backing_len(core.group.slot)
11095                .unwrap_or_else(|| unreachable!("typed tensor group descriptor mismatch")),
11096        }
11097    }
11098
11099    /// Return the shared-allocation domain carried by the backend buffer.
11100    ///
11101    /// # Examples
11102    ///
11103    /// ```rust
11104    /// use tenferro_tensor::TypedTensor;
11105    ///
11106    /// let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
11107    /// assert_eq!(tensor.allocation_domain(), None);
11108    /// # Ok::<(), tenferro_tensor::Error>(())
11109    /// ```
11110    pub fn allocation_domain(&self) -> Option<AllocationDomainId>
11111    where
11112        T: 'static,
11113    {
11114        match &self.storage {
11115            DynamicStorage::Host(..) => None,
11116            DynamicStorage::Group(core) => core
11117                .group
11118                .group
11119                .backend_identity(core.group.slot)
11120                .map(|(domain, _)| domain),
11121        }
11122    }
11123
11124    /// Return the stable physical backend allocation identity.
11125    ///
11126    /// # Examples
11127    ///
11128    /// ```rust
11129    /// use tenferro_tensor::TypedTensor;
11130    ///
11131    /// let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
11132    /// assert_eq!(tensor.allocation_id(), None);
11133    /// # Ok::<(), tenferro_tensor::Error>(())
11134    /// ```
11135    pub fn allocation_id(&self) -> Option<AllocationId>
11136    where
11137        T: 'static,
11138    {
11139        match &self.storage {
11140            DynamicStorage::Host(..) => None,
11141            DynamicStorage::Group(core) => core
11142                .group
11143                .group
11144                .backend_identity(core.group.slot)
11145                .map(|(_, allocation)| allocation),
11146        }
11147    }
11148
11149    /// Borrow this tensor as a typed view preserving rank and layout metadata.
11150    ///
11151    /// The view carries the descriptor's physical layout, so a root-preserving
11152    /// extraction exposes its full backing allocation with the logical slice at
11153    /// the descriptor offset.
11154    ///
11155    /// # Panics
11156    ///
11157    /// Panics only if the typed descriptor and its single group owner are
11158    /// internally inconsistent.
11159    ///
11160    /// # Examples
11161    ///
11162    /// ```rust
11163    /// use tenferro_tensor::{Rank, TypedTensor};
11164    ///
11165    /// let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
11166    /// let view = tensor.as_view();
11167    /// assert_eq!(view.strides(), &[1, 2]);
11168    /// ```
11169    pub fn as_view(&self) -> TypedTensorView<'_, T, R>
11170    where
11171        T: 'static,
11172    {
11173        let layout = self.physical_layout();
11174        let placement = self.placement.clone();
11175        match &self.storage {
11176            DynamicStorage::Host(HostStorage { data }) => TypedTensorView {
11177                buffer: TensorStorageRef::Host(data.as_slice()),
11178                root: None,
11179                layout,
11180                placement,
11181                _representation: std::marker::PhantomData,
11182            },
11183            DynamicStorage::Group(core) => {
11184                // Managed owners are constructed only with their matching preset T.
11185                let root = core
11186                    .group
11187                    .group
11188                    .view_raw::<T, R>(core.group.slot)
11189                    .unwrap_or_else(|error| {
11190                        unreachable!("typed tensor group descriptor mismatch: {error}")
11191                    });
11192                let buffer = if let Some(allocation) = root.backend_allocation() {
11193                    TensorStorageRef::Root(allocation)
11194                } else {
11195                    TensorStorageRef::Host(core.group.host_slice::<T>().unwrap_or_default())
11196                };
11197                TypedTensorView {
11198                    buffer,
11199                    root: Some(root),
11200                    layout,
11201                    placement,
11202                    _representation: std::marker::PhantomData,
11203                }
11204            }
11205        }
11206    }
11207
11208    /// Mutably borrow this tensor as a typed view preserving rank and layout metadata.
11209    ///
11210    /// # Panics
11211    ///
11212    /// Panics only if the typed descriptor and its single group owner are
11213    /// internally inconsistent.
11214    ///
11215    /// # Examples
11216    ///
11217    /// ```rust
11218    /// use tenferro_tensor::TypedTensor;
11219    ///
11220    /// let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![1]).unwrap();
11221    /// *tensor.as_view_mut().get_mut(&[0]).unwrap() = 2;
11222    /// assert_eq!(tensor.as_slice().unwrap(), &[2]);
11223    /// ```
11224    pub fn as_view_mut(&mut self) -> TypedTensorViewMut<'_, T, R>
11225    where
11226        T: TensorScalar + 'static,
11227    {
11228        let layout = self.physical_layout();
11229        let placement = self.placement.clone();
11230        match &mut self.storage {
11231            DynamicStorage::Host(HostStorage { data }) => TypedTensorViewMut {
11232                buffer: TensorStorageRefMut::Host(data.as_mut_slice()),
11233                root: None,
11234                layout,
11235                placement,
11236                _representation: std::marker::PhantomData,
11237            },
11238            DynamicStorage::Group(core) => {
11239                let mut root = core.group.view_mut::<T>().unwrap_or_else(|error| {
11240                    unreachable!("typed tensor group descriptor mismatch: {error}")
11241                });
11242                let buffer = if let Some(StorageBuffer::Backend(buffer)) = root.backend_buffer_mut()
11243                {
11244                    TensorStorageRefMut::Backend(buffer.as_mut())
11245                } else {
11246                    TensorStorageRefMut::Host(root.host_slice_mut().unwrap_or_else(|error| {
11247                        unreachable!("typed tensor group descriptor is not host-backed: {error}")
11248                    }))
11249                };
11250                TypedTensorViewMut {
11251                    buffer,
11252                    root: Some(root),
11253                    layout,
11254                    placement,
11255                    _representation: std::marker::PhantomData,
11256                }
11257            }
11258        }
11259    }
11260
11261    /// Borrow a read-only strided region view over this tensor's backend
11262    /// (device) buffer from explicit layout metadata.
11263    ///
11264    /// This is a metadata-only view: no data is copied or transferred. The
11265    /// layout's reachable element span is validated against the backend
11266    /// buffer's physical length. Host-backed tensors are rejected with an
11267    /// explicit backend error; host regions are expressed with
11268    /// [`TypedTensorView::from_slice`] over host storage instead.
11269    ///
11270    /// # Examples
11271    ///
11272    /// ```rust
11273    /// use tenferro_tensor::TypedTensor;
11274    ///
11275    /// // Host tensors are rejected: this constructor is for backend buffers.
11276    /// let host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
11277    /// let err = host.backend_region_view(vec![2, 2], vec![1, 2], 0).unwrap_err();
11278    /// assert!(err.to_string().contains("backend"));
11279    /// ```
11280    /// # Errors
11281    ///
11282    /// Returns [`crate::Error::RuntimeState`] when this tensor is host-backed;
11283    /// backend region views require a backend buffer. It returns
11284    /// [`crate::Error::Validation`] with
11285    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for incompatible
11286    /// shape/stride ranks, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
11287    /// when the region exceeds the backend buffer, or
11288    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
11289    /// arithmetic overflow.
11290    pub fn backend_region_view(
11291        &self,
11292        shape: Vec<usize>,
11293        strides: Vec<isize>,
11294        offset: isize,
11295    ) -> crate::Result<TypedTensorView<'_, T, DynRank>>
11296    where
11297        T: TensorScalar + 'static,
11298    {
11299        let op = "TypedTensor::backend_region_view";
11300        let DynamicStorage::Group(core) = &self.storage else {
11301            return Err(crate::Error::runtime_state(op, "expected a backend (device) allocation; host tensors use TypedTensorView::from_slice over host storage"));
11302        };
11303        let root = core.group.view_dyn::<T>()?;
11304        let Some(allocation) = root.backend_allocation() else {
11305            return Err(crate::Error::runtime_state(
11306                op,
11307                "expected a backend (device) allocation; host tensors use \
11308                 TypedTensorView::from_slice over host storage",
11309            ));
11310        };
11311        let element_len = allocation
11312            .root_extent()
11313            .byte_len()
11314            .checked_div(size_of::<T>())
11315            .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
11316        let layout =
11317            TensorLayout::from_parts(shape_vec(&shape), stride_vec(&strides), offset, element_len)
11318                .map_err(|err| tensor_layout_error(op, err))?;
11319        Ok(TypedTensorView {
11320            buffer: TensorStorageRef::Root(allocation),
11321            root: Some(root),
11322            layout,
11323            placement: self.placement.clone(),
11324            _representation: std::marker::PhantomData,
11325        })
11326    }
11327
11328    /// Borrow a mutable strided region view over this tensor's backend
11329    /// (device) buffer from explicit layout metadata.
11330    ///
11331    /// This is the mutable counterpart of
11332    /// [`TypedTensor::backend_region_view`]. The layout's reachable element
11333    /// span is validated against the backend buffer's physical length, and
11334    /// layouts whose logical elements alias the same physical element are
11335    /// rejected. Host-backed tensors are rejected with an explicit backend
11336    /// error; mutable host regions must go through
11337    /// [`TypedTensorViewMut::try_multi_slice_mut`] or host constructors.
11338    ///
11339    /// The returned view borrows the tensor's backend owner exclusively for its
11340    /// lifetime. This keeps write authority tied to the owner; a second mutable
11341    /// region view must be created only after the first borrow ends.
11342    ///
11343    /// # Examples
11344    ///
11345    /// ```rust
11346    /// use tenferro_tensor::TypedTensor;
11347    ///
11348    /// // Host tensors are rejected: this constructor is for backend buffers.
11349    /// let mut host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
11350    /// let err = host.backend_region_view_mut(vec![2, 2], vec![1, 2], 0).unwrap_err();
11351    /// assert!(err.to_string().contains("backend"));
11352    /// ```
11353    /// # Errors
11354    ///
11355    /// Returns [`crate::Error::RuntimeState`] when this tensor is host-backed;
11356    /// mutable backend region views require a backend buffer. It returns
11357    /// [`crate::Error::Validation`] with
11358    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for incompatible
11359    /// shape/stride ranks, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
11360    /// when the region exceeds the backend buffer,
11361    /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
11362    /// logical elements alias, or
11363    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
11364    /// arithmetic overflow.
11365    pub fn backend_region_view_mut(
11366        &mut self,
11367        shape: Vec<usize>,
11368        strides: Vec<isize>,
11369        offset: isize,
11370    ) -> crate::Result<TypedTensorViewMut<'_, T, DynRank>>
11371    where
11372        T: TensorScalar + 'static,
11373    {
11374        let op = "TypedTensor::backend_region_view_mut";
11375        let placement = self.placement.clone();
11376        let DynamicStorage::Group(core) = &mut self.storage else {
11377            return Err(crate::Error::runtime_state(op, "expected a backend (device) buffer; mutable host regions use TypedTensorViewMut host constructors or try_multi_slice_mut"));
11378        };
11379        let mut root = core.group.view_mut_dyn::<T>()?;
11380        let Some(StorageBuffer::Backend(buffer)) = root.backend_buffer_mut() else {
11381            return Err(crate::Error::runtime_state(
11382                op,
11383                "expected a backend (device) buffer; mutable host regions use \
11384                 TypedTensorViewMut host constructors or try_multi_slice_mut",
11385            ));
11386        };
11387        let layout = TensorLayout::from_parts(
11388            shape_vec(&shape),
11389            stride_vec(&strides),
11390            offset,
11391            buffer.len(),
11392        )
11393        .map_err(|err| tensor_layout_error(op, err))?;
11394        layout
11395            .validate_mutable_no_overlap()
11396            .map_err(|err| tensor_layout_error(op, err))?;
11397        Ok(TypedTensorViewMut {
11398            buffer: TensorStorageRefMut::Backend(buffer.as_mut()),
11399            root: Some(root),
11400            layout,
11401            placement,
11402            _representation: std::marker::PhantomData,
11403        })
11404    }
11405
11406    /// Consume this tensor and return its logical host storage, layout, and
11407    /// placement.
11408    ///
11409    /// A root-preserving owner exports only its compact logical values, exactly
11410    /// like [`TypedTensor::into_host_vec`].
11411    ///
11412    /// # Examples
11413    ///
11414    /// ```
11415    /// use tenferro_tensor::{StorageBuffer, TypedTensor};
11416    ///
11417    /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
11418    /// let Ok((buffer, layout, placement)) = t.into_parts() else {
11419    ///     panic!("a plain host owner extracts")
11420    /// };
11421    /// assert!(matches!(buffer, StorageBuffer::Host(_)));
11422    /// assert_eq!(layout.shape(), &[2]);
11423    /// assert!(placement.device.is_none());
11424    /// # Ok::<(), tenferro_tensor::Error>(())
11425    /// ```
11426    ///
11427    /// # Errors
11428    ///
11429    /// Returns [`ReinterpretError`] carrying the unchanged tensor when it uses
11430    /// backend storage (download it before extracting host storage) or when a
11431    /// group-backed descriptor is not compact column-major
11432    /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
11433    pub fn into_parts(
11434        self,
11435    ) -> std::result::Result<(StorageBuffer<T>, TensorLayout<R>, Placement), ReinterpretError<Self>>
11436    where
11437        T: TensorScalar,
11438    {
11439        let placement = self.placement().clone();
11440        let layout = TensorLayout::<R>::compact(
11441            R::shape_from_vec(shape_vec(self.shape()))
11442                .unwrap_or_else(|err| unreachable!("validated owned shape: {err:?}")),
11443        )
11444        .unwrap_or_else(|err| unreachable!("validated owned shape: {err}"));
11445        // The export contract is identical to `into_host_vec`; reuse it rather
11446        // than repeating the descriptor rebase and its failure recovery.
11447        match self.into_host_vec() {
11448            Ok(data) => Ok((StorageBuffer::Host(data), layout, placement)),
11449            Err(error) => Err(error),
11450        }
11451    }
11452}
11453
11454impl<T: TensorScalar, R: TensorRank> TypedTensor<T, R> {
11455    fn into_managed(self) -> Self {
11456        let TypedTensor {
11457            shape,
11458            placement,
11459            layout,
11460            storage,
11461        } = self;
11462        match storage {
11463            DynamicStorage::Host(HostStorage { data }) => {
11464                let group = promote_host_group::<T, R>(shape.clone(), data)
11465                    .unwrap_or_else(|err| unreachable!("a validated host owner promotes: {err}"));
11466                Self {
11467                    shape,
11468                    placement,
11469                    layout,
11470                    storage: DynamicStorage::Group(GroupStorage {
11471                        group: Box::new(group),
11472                    }),
11473                }
11474            }
11475            DynamicStorage::Group(core) => Self {
11476                shape,
11477                placement,
11478                layout,
11479                storage: DynamicStorage::Group(core),
11480            },
11481        }
11482    }
11483
11484    fn into_group_parts(self) -> (AllocationGroup, DescriptorSlot) {
11485        let TypedTensor {
11486            placement, storage, ..
11487        } = self.into_managed();
11488        let DynamicStorage::Group(GroupStorage { group }) = storage else {
11489            unreachable!("explicit group promotion produces managed storage")
11490        };
11491        let (mut group, slot) = group.into_parts();
11492        group.publish_live_descriptor_placement(slot, placement);
11493        (group, slot)
11494    }
11495
11496    /// Construct a backend-pooled host tensor with weak final-owner reclamation.
11497    /// Explicit Vec extraction disarms reclamation; aliases and retained groups
11498    /// keep the original root alive. The recycler must not acquire session locks.
11499    ///
11500    /// # Errors
11501    /// Returns validation errors for invalid shape/length and runtime-state errors
11502    /// if the freshly created host root cannot attach its recycler.
11503    #[doc(hidden)]
11504    pub fn from_vec_col_major_with_recycler(
11505        shape: impl tenferro_tensor_core::IntoRankShape<R>,
11506        data: Vec<T>,
11507        recycler: std::sync::Weak<dyn crate::HostBufferRecycler<T>>,
11508    ) -> crate::Result<Self> {
11509        let mut tensor = Self::from_vec_col_major(shape, data)?;
11510        if let DynamicStorage::Host(HostStorage { data }) = &mut tensor.storage {
11511            data.recycler = Some(recycler);
11512        }
11513        Ok(tensor)
11514    }
11515
11516    /// Borrow compact host-visible storage through one synchronization guard.
11517    #[doc(hidden)]
11518    pub fn with_host_read<U>(&self, f: impl FnOnce(&[T]) -> U) -> crate::Result<U>
11519    where
11520        T: TensorScalar + 'static,
11521    {
11522        self.as_view().with_host_read(f)
11523    }
11524
11525    /// Borrow compact host-visible storage through one exclusive write guard.
11526    #[doc(hidden)]
11527    pub fn with_host_write<U>(&mut self, f: impl FnOnce(&mut [T]) -> U) -> crate::Result<U>
11528    where
11529        T: TensorScalar + 'static,
11530    {
11531        match &mut self.storage {
11532            DynamicStorage::Host(HostStorage { data }) => Ok(f(data.as_mut_slice())),
11533            DynamicStorage::Group(core) => {
11534                let slot = core.group.slot;
11535                let mut view = core
11536                    .group
11537                    .group
11538                    .view_mut::<T, R>(slot)
11539                    .map_err(|error| group_error("TypedTensor::with_host_write", error))?;
11540                let mut prepared = view.prepare_host_write().map_err(|error| {
11541                    crate::Error::runtime_state("TypedTensor::with_host_write", error.to_string())
11542                })?;
11543                let slice = prepared.as_slice_mut().ok_or_else(|| {
11544                    crate::Error::unsupported(
11545                        "TypedTensor::with_host_write",
11546                        "host guard access requires a compact descriptor",
11547                    )
11548                })?;
11549                Ok(f(slice))
11550            }
11551        }
11552    }
11553
11554    /// Whole backing host buffer, including bytes outside a root-preserving
11555    /// extraction's logical extent (#2023).
11556    ///
11557    /// A mutable reinterpretation rebases the descriptor over the whole root,
11558    /// so it must borrow that root rather than the exported logical slice.
11559    fn backing_host_slice_mut(&mut self) -> crate::Result<&mut [T]> {
11560        match &mut self.storage {
11561            DynamicStorage::Host(HostStorage { data }) => Ok(data.as_mut_slice()),
11562            DynamicStorage::Group(core) => core.group.host_slice_mut::<T>(),
11563        }
11564    }
11565
11566    fn group_host_slice(&self) -> &[T] {
11567        let DynamicStorage::Group(core) = &self.storage else {
11568            return &[];
11569        };
11570        core.group
11571            .view::<T>()
11572            .ok()
11573            .and_then(|view| view.host_slice().ok())
11574            .unwrap_or_default()
11575    }
11576}
11577
11578/// Layout builder used by an owning representation reinterpretation.
11579type ReinterpretLayoutFn =
11580    fn(&[usize], &[isize], isize, usize, &'static str) -> crate::Result<TensorLayout<DynRank>>;
11581
11582fn reinterpret_owned<S: TensorScalar, U: TensorScalar, R: TensorRank>(
11583    owner: TypedTensor<S, R>,
11584    from: DType,
11585    to: DType,
11586    make_layout: ReinterpretLayoutFn,
11587    op: &'static str,
11588) -> Result<TypedTensor<U>, ReinterpretError<TypedTensor<S, R>>> {
11589    if let Err(error) = validate_representation_pair(op, from, to) {
11590        return Err(ReinterpretError::new(owner, error));
11591    }
11592    if matches!(to, DType::C32 | DType::C64) && !owner.buffer_len().is_multiple_of(2) {
11593        return Err(ReinterpretError::new(
11594            owner,
11595            crate::Error::invalid_argument(
11596                op,
11597                "buffer",
11598                "the owned real buffer must contain an even number of elements",
11599            ),
11600        ));
11601    }
11602    let source_layout = owner.physical_layout();
11603    let target_layout = match make_layout(
11604        source_layout.shape(),
11605        source_layout.strides(),
11606        source_layout.offset(),
11607        owner.buffer_len(),
11608        op,
11609    ) {
11610        Ok(layout) => layout,
11611        Err(error) => return Err(ReinterpretError::new(owner, error)),
11612    };
11613    // Only an explicit owning representation conversion promotes a plain owner;
11614    // borrowed session dispatch never passes through a group.
11615    let TypedTensor {
11616        shape,
11617        placement,
11618        layout,
11619        storage,
11620    } = owner.into_managed();
11621    let DynamicStorage::Group(GroupStorage { group }) = storage else {
11622        unreachable!("explicit group promotion produces managed storage")
11623    };
11624    match group.reinterpret::<S, U>(
11625        target_layout.shape().to_vec(),
11626        target_layout.strides().to_vec(),
11627        target_layout.offset(),
11628    ) {
11629        Ok(group) => Ok(TypedTensor {
11630            shape: shape_vec(target_layout.shape()),
11631            placement,
11632            layout: stride_vec(target_layout.strides()),
11633            storage: DynamicStorage::Group(GroupStorage {
11634                group: Box::new(group),
11635            }),
11636        }),
11637        Err((group, error)) => Err(ReinterpretError::new(
11638            TypedTensor {
11639                shape,
11640                placement,
11641                layout,
11642                storage: DynamicStorage::Group(GroupStorage {
11643                    group: Box::new(group),
11644                }),
11645            },
11646            error,
11647        )),
11648    }
11649}
11650
11651impl<R: TensorRank> TypedTensor<Complex32, R> {
11652    /// Borrow this tensor as an interleaved `f32` view without copying.
11653    ///
11654    /// # Errors
11655    ///
11656    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11657    /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11658    /// invalid tensor layout.
11659    pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'_, f32, DynRank>> {
11660        self.as_view().as_real_view()
11661    }
11662
11663    /// Borrow this tensor mutably as an interleaved `f32` view without copying.
11664    ///
11665    /// # Errors
11666    ///
11667    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11668    /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11669    /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11670    /// invalid representation metadata.
11671    pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f32, DynRank>> {
11672        let op = "TypedTensor::as_real_view_mut";
11673        validate_representation_pair(op, DType::C32, DType::F32)?;
11674        let source_layout = self.physical_layout();
11675        let layout = reinterpret_complex_to_real_layout(
11676            self.shape(),
11677            source_layout.strides(),
11678            source_layout.offset(),
11679            self.buffer_len(),
11680            op,
11681        )?;
11682        layout
11683            .validate_mutable_no_overlap()
11684            .map_err(|err| tensor_layout_error(op, err))?;
11685        if self.backend_buffer().is_some() {
11686            return Err(crate::Error::unsupported(
11687                op,
11688                "backend representation reinterpretation is enabled by the provider phases",
11689            ));
11690        }
11691        let placement = self.placement().clone();
11692        let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex32, f32>(
11693            self.backing_host_slice_mut()?,
11694            op,
11695        )?);
11696        Ok(TypedTensorViewMut {
11697            buffer,
11698            root: None,
11699            layout,
11700            placement,
11701            _representation: std::marker::PhantomData,
11702        })
11703    }
11704
11705    /// Consume this tensor and reinterpret its owner as `f32` without copying.
11706    ///
11707    /// A failed operation returns the unchanged owner through
11708    /// [`ReinterpretError::into_owner`].
11709    ///
11710    /// # Errors
11711    ///
11712    /// Returns [`ReinterpretError::error`] containing
11713    /// [`ValidationError::InvalidArgument`] or
11714    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11715    /// owner.
11716    pub fn into_real(self) -> Result<TypedTensor<f32, DynRank>, ReinterpretError<Self>> {
11717        reinterpret_owned(
11718            self,
11719            DType::C32,
11720            DType::F32,
11721            reinterpret_complex_to_real_layout,
11722            "TypedTensor::into_real",
11723        )
11724    }
11725}
11726
11727impl<R: TensorRank> TypedTensor<Complex64, R> {
11728    /// Borrow this tensor as an interleaved `f64` view without copying.
11729    ///
11730    /// # Errors
11731    ///
11732    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11733    /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11734    /// invalid tensor layout.
11735    pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'_, f64, DynRank>> {
11736        self.as_view().as_real_view()
11737    }
11738
11739    /// Borrow this tensor mutably as an interleaved `f64` view without copying.
11740    ///
11741    /// # Errors
11742    ///
11743    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11744    /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11745    /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11746    /// invalid representation metadata.
11747    pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f64, DynRank>> {
11748        let op = "TypedTensor::as_real_view_mut";
11749        validate_representation_pair(op, DType::C64, DType::F64)?;
11750        let source_layout = self.physical_layout();
11751        let layout = reinterpret_complex_to_real_layout(
11752            self.shape(),
11753            source_layout.strides(),
11754            source_layout.offset(),
11755            self.buffer_len(),
11756            op,
11757        )?;
11758        layout
11759            .validate_mutable_no_overlap()
11760            .map_err(|err| tensor_layout_error(op, err))?;
11761        if self.backend_buffer().is_some() {
11762            return Err(crate::Error::unsupported(
11763                op,
11764                "backend representation reinterpretation is enabled by the provider phases",
11765            ));
11766        }
11767        let placement = self.placement().clone();
11768        let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex64, f64>(
11769            self.backing_host_slice_mut()?,
11770            op,
11771        )?);
11772        Ok(TypedTensorViewMut {
11773            buffer,
11774            root: None,
11775            layout,
11776            placement,
11777            _representation: std::marker::PhantomData,
11778        })
11779    }
11780
11781    /// Consume this tensor and reinterpret its owner as `f64` without copying.
11782    ///
11783    /// A failed operation returns the unchanged owner through
11784    /// [`ReinterpretError::into_owner`].
11785    ///
11786    /// # Errors
11787    ///
11788    /// Returns [`ReinterpretError::error`] containing
11789    /// [`ValidationError::InvalidArgument`] or
11790    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11791    /// owner.
11792    pub fn into_real(self) -> Result<TypedTensor<f64, DynRank>, ReinterpretError<Self>> {
11793        reinterpret_owned(
11794            self,
11795            DType::C64,
11796            DType::F64,
11797            reinterpret_complex_to_real_layout,
11798            "TypedTensor::into_real",
11799        )
11800    }
11801}
11802
11803impl<R: TensorRank> TypedTensor<f32, R> {
11804    /// Borrow this tensor as a complex view without copying.
11805    ///
11806    /// # Errors
11807    ///
11808    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11809    /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11810    /// invalid tensor layout.
11811    pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'_, Complex32, DynRank>> {
11812        self.as_view().as_complex_view()
11813    }
11814
11815    /// Borrow this tensor mutably as a complex view without copying.
11816    ///
11817    /// # Errors
11818    ///
11819    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11820    /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11821    /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11822    /// invalid representation metadata.
11823    pub fn as_complex_view_mut(
11824        &mut self,
11825    ) -> crate::Result<TypedTensorViewMut<'_, Complex32, DynRank>> {
11826        let op = "TypedTensor::as_complex_view_mut";
11827        validate_representation_pair(op, DType::F32, DType::C32)?;
11828        let source_layout = self.physical_layout();
11829        let layout = reinterpret_real_to_complex_layout(
11830            self.shape(),
11831            source_layout.strides(),
11832            source_layout.offset(),
11833            self.buffer_len(),
11834            op,
11835        )?;
11836        layout
11837            .validate_mutable_no_overlap()
11838            .map_err(|err| tensor_layout_error(op, err))?;
11839        if self.backend_buffer().is_some() {
11840            return Err(crate::Error::unsupported(
11841                op,
11842                "backend representation reinterpretation is enabled by the provider phases",
11843            ));
11844        }
11845        let placement = self.placement().clone();
11846        let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f32, Complex32>(
11847            self.backing_host_slice_mut()?,
11848            op,
11849        )?);
11850        Ok(TypedTensorViewMut {
11851            buffer,
11852            root: None,
11853            layout,
11854            placement,
11855            _representation: std::marker::PhantomData,
11856        })
11857    }
11858
11859    /// Consume this tensor and reinterpret its owner as `Complex32` without copying.
11860    ///
11861    /// The compact source must have an even physical element count. A failed
11862    /// operation returns the unchanged owner through
11863    /// [`ReinterpretError::into_owner`].
11864    ///
11865    /// # Errors
11866    ///
11867    /// Returns [`ReinterpretError::error`] containing
11868    /// [`ValidationError::InvalidArgument`] or
11869    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11870    /// owner.
11871    pub fn into_complex(self) -> Result<TypedTensor<Complex32, DynRank>, ReinterpretError<Self>> {
11872        reinterpret_owned(
11873            self,
11874            DType::F32,
11875            DType::C32,
11876            reinterpret_real_to_complex_layout,
11877            "TypedTensor::into_complex",
11878        )
11879    }
11880}
11881
11882impl<R: TensorRank> TypedTensor<f64, R> {
11883    /// Borrow this tensor as a complex view without copying.
11884    ///
11885    /// # Errors
11886    ///
11887    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11888    /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11889    /// invalid tensor layout.
11890    pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'_, Complex64, DynRank>> {
11891        self.as_view().as_complex_view()
11892    }
11893
11894    /// Borrow this tensor mutably as a complex view without copying.
11895    ///
11896    /// # Errors
11897    ///
11898    /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11899    /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11900    /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11901    /// invalid representation metadata.
11902    pub fn as_complex_view_mut(
11903        &mut self,
11904    ) -> crate::Result<TypedTensorViewMut<'_, Complex64, DynRank>> {
11905        let op = "TypedTensor::as_complex_view_mut";
11906        validate_representation_pair(op, DType::F64, DType::C64)?;
11907        let source_layout = self.physical_layout();
11908        let layout = reinterpret_real_to_complex_layout(
11909            self.shape(),
11910            source_layout.strides(),
11911            source_layout.offset(),
11912            self.buffer_len(),
11913            op,
11914        )?;
11915        layout
11916            .validate_mutable_no_overlap()
11917            .map_err(|err| tensor_layout_error(op, err))?;
11918        if self.backend_buffer().is_some() {
11919            return Err(crate::Error::unsupported(
11920                op,
11921                "backend representation reinterpretation is enabled by the provider phases",
11922            ));
11923        }
11924        let placement = self.placement().clone();
11925        let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f64, Complex64>(
11926            self.backing_host_slice_mut()?,
11927            op,
11928        )?);
11929        Ok(TypedTensorViewMut {
11930            buffer,
11931            root: None,
11932            layout,
11933            placement,
11934            _representation: std::marker::PhantomData,
11935        })
11936    }
11937
11938    /// Consume this tensor and reinterpret its owner as `Complex64` without copying.
11939    ///
11940    /// The compact source must have an even physical element count. A failed
11941    /// operation returns the unchanged owner through
11942    /// [`ReinterpretError::into_owner`].
11943    ///
11944    /// # Errors
11945    ///
11946    /// Returns [`ReinterpretError::error`] containing
11947    /// [`ValidationError::InvalidArgument`] or
11948    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11949    /// owner.
11950    pub fn into_complex(self) -> Result<TypedTensor<Complex64, DynRank>, ReinterpretError<Self>> {
11951        reinterpret_owned(
11952            self,
11953            DType::F64,
11954            DType::C64,
11955            reinterpret_real_to_complex_layout,
11956            "TypedTensor::into_complex",
11957        )
11958    }
11959}
11960
11961impl Tensor {
11962    /// Borrow a complex tensor as its sealed interleaved real representation.
11963    ///
11964    /// # Errors
11965    ///
11966    /// Returns [`crate::Error::Unsupported`] for a non-complex dtype and
11967    /// [`ValidationError::ViewOutOfBounds`] or
11968    /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
11969    pub fn as_real_view(&self) -> crate::Result<TensorView<'_>> {
11970        match self.dtype() {
11971            DType::C32 => self
11972                .as_typed::<Complex<f32>>()
11973                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
11974                .as_real_view()
11975                .map(TensorView::F32),
11976            DType::C64 => self
11977                .as_typed::<Complex<f64>>()
11978                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
11979                .as_real_view()
11980                .map(TensorView::F64),
11981            other => Err(crate::Error::unsupported_dtype_conversion(
11982                "Tensor::as_real_view",
11983                other,
11984                DType::F32,
11985                "only complex tensors have a sealed real representation view",
11986            )),
11987        }
11988    }
11989
11990    /// Borrow a complex tensor mutably as its sealed interleaved real representation.
11991    ///
11992    /// # Errors
11993    ///
11994    /// Returns [`crate::Error::Unsupported`] for a non-complex dtype and
11995    /// [`ValidationError::ViewOutOfBounds`] or
11996    /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
11997    pub fn as_real_view_mut(&mut self) -> crate::Result<TensorViewMut<'_>> {
11998        match self.dtype() {
11999            DType::C32 => self
12000                .as_typed_mut::<Complex<f32>>()
12001                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12002                .as_real_view_mut()
12003                .map(TensorViewMut::F32),
12004            DType::C64 => self
12005                .as_typed_mut::<Complex<f64>>()
12006                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12007                .as_real_view_mut()
12008                .map(TensorViewMut::F64),
12009            other => Err(crate::Error::unsupported_dtype_conversion(
12010                "Tensor::as_real_view_mut",
12011                other,
12012                DType::F32,
12013                "only complex tensors have a sealed real representation view",
12014            )),
12015        }
12016    }
12017
12018    /// Consume a complex tensor and reinterpret its owner as real without copying.
12019    ///
12020    /// # Errors
12021    ///
12022    /// Returns [`ReinterpretError::error`] containing
12023    /// [`ValidationError::InvalidArgument`] or
12024    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
12025    /// owner.
12026    pub fn into_real(self) -> Result<Self, ReinterpretError<Self>> {
12027        let dtype = self.dtype();
12028        match dtype {
12029            DType::C32 => {
12030                let tensor = <Complex<f32> as TensorScalar>::into_typed(self)
12031                    .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12032                tensor
12033                    .into_real()
12034                    .map(Tensor::from_typed::<f32>)
12035                    .map_err(|error| {
12036                        let (owner, error) = error.into_parts();
12037                        ReinterpretError::new(Tensor::from_typed::<Complex<f32>>(owner), error)
12038                    })
12039            }
12040            DType::C64 => {
12041                let tensor = <Complex<f64> as TensorScalar>::into_typed(self)
12042                    .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12043                tensor
12044                    .into_real()
12045                    .map(Tensor::from_typed::<f64>)
12046                    .map_err(|error| {
12047                        let (owner, error) = error.into_parts();
12048                        ReinterpretError::new(Tensor::from_typed::<Complex<f64>>(owner), error)
12049                    })
12050            }
12051            _ => Err(ReinterpretError::new(
12052                self,
12053                crate::Error::unsupported(
12054                    "Tensor::into_real",
12055                    "only complex tensors have a sealed real representation",
12056                ),
12057            )),
12058        }
12059    }
12060
12061    /// Borrow an interleaved real tensor as its sealed complex representation.
12062    ///
12063    /// # Errors
12064    ///
12065    /// Returns [`crate::Error::Unsupported`] for a non-real dtype and
12066    /// [`ValidationError::ViewOutOfBounds`] or
12067    /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
12068    pub fn as_complex_view(&self) -> crate::Result<TensorView<'_>> {
12069        match self.dtype() {
12070            DType::F32 => self
12071                .as_typed::<f32>()
12072                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12073                .as_complex_view()
12074                .map(TensorView::C32),
12075            DType::F64 => self
12076                .as_typed::<f64>()
12077                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12078                .as_complex_view()
12079                .map(TensorView::C64),
12080            other => Err(crate::Error::unsupported_dtype_conversion(
12081                "Tensor::as_complex_view",
12082                other,
12083                DType::C32,
12084                "only real tensors can have a sealed complex representation view",
12085            )),
12086        }
12087    }
12088
12089    /// Borrow an interleaved real tensor mutably as its sealed complex representation.
12090    ///
12091    /// # Errors
12092    ///
12093    /// Returns [`crate::Error::Unsupported`] for a non-real dtype and
12094    /// [`ValidationError::ViewOutOfBounds`] or
12095    /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
12096    pub fn as_complex_view_mut(&mut self) -> crate::Result<TensorViewMut<'_>> {
12097        match self.dtype() {
12098            DType::F32 => self
12099                .as_typed_mut::<f32>()
12100                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12101                .as_complex_view_mut()
12102                .map(TensorViewMut::C32),
12103            DType::F64 => self
12104                .as_typed_mut::<f64>()
12105                .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12106                .as_complex_view_mut()
12107                .map(TensorViewMut::C64),
12108            other => Err(crate::Error::unsupported_dtype_conversion(
12109                "Tensor::as_complex_view_mut",
12110                other,
12111                DType::C32,
12112                "only real tensors can have a sealed complex representation view",
12113            )),
12114        }
12115    }
12116
12117    /// Consume a real tensor and reinterpret its owner as complex without copying.
12118    ///
12119    /// # Errors
12120    ///
12121    /// Returns [`ReinterpretError::error`] containing
12122    /// [`ValidationError::InvalidArgument`] or
12123    /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
12124    /// owner.
12125    pub fn into_complex(self) -> Result<Self, ReinterpretError<Self>> {
12126        let dtype = self.dtype();
12127        match dtype {
12128            DType::F32 => {
12129                let tensor = <f32 as TensorScalar>::into_typed(self)
12130                    .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12131                tensor
12132                    .into_complex()
12133                    .map(Tensor::from_typed::<Complex<f32>>)
12134                    .map_err(|error| {
12135                        let (owner, error) = error.into_parts();
12136                        ReinterpretError::new(Tensor::from_typed::<f32>(owner), error)
12137                    })
12138            }
12139            DType::F64 => {
12140                let tensor = <f64 as TensorScalar>::into_typed(self)
12141                    .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12142                tensor
12143                    .into_complex()
12144                    .map(Tensor::from_typed::<Complex<f64>>)
12145                    .map_err(|error| {
12146                        let (owner, error) = error.into_parts();
12147                        ReinterpretError::new(Tensor::from_typed::<f64>(owner), error)
12148                    })
12149            }
12150            _ => Err(ReinterpretError::new(
12151                self,
12152                crate::Error::unsupported(
12153                    "Tensor::into_complex",
12154                    "only real tensors have a sealed complex representation",
12155                ),
12156            )),
12157        }
12158    }
12159
12160    /// Make an explicit owning copy of this dtype-erased tensor.
12161    ///
12162    /// `Tensor` deliberately does not implement [`Clone`]: copying can fail
12163    /// (device-only storage is rejected) and allocates a new, independent
12164    /// owner, so it is an explicit fallible call rather than an infallible
12165    /// `clone()`. The copy shares nothing with `self`; mutating one never
12166    /// affects the other. To share one tensor between several users without
12167    /// copying, wrap it in [`std::sync::Arc`] or borrow views of it.
12168    ///
12169    /// # Examples
12170    ///
12171    /// ```
12172    /// use std::sync::Arc;
12173    /// use tenferro_tensor::Tensor;
12174    ///
12175    /// let weights = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12176    /// // Two independent owners of the same values.
12177    /// let copy = weights.duplicate()?;
12178    /// assert_eq!(copy.as_slice::<f64>()?, weights.as_slice::<f64>()?);
12179    ///
12180    /// // A shared, read-only handle instead of a copy.
12181    /// let shared = Arc::new(weights);
12182    /// let other = Arc::clone(&shared);
12183    /// assert_eq!(other.shape(), &[2]);
12184    /// # Ok::<(), tenferro_tensor::Error>(())
12185    /// ```
12186    ///
12187    /// # Errors
12188    ///
12189    /// Returns [`crate::Error::RuntimeState`] or [`crate::Error::Unsupported`]
12190    /// when the selected backend/storage owner cannot be duplicated.
12191    pub fn duplicate(&self) -> crate::Result<Self> {
12192        match &self.payload {
12193            // A caller-owned payload is copied through its own entry point, which
12194            // keeps its element type and its view; sharing the payload instead
12195            // would alias the caller's storage.
12196            TensorPayload::External(payload, placement) => Ok(Self {
12197                payload: TensorPayload::External(payload.duplicate(), placement.clone()),
12198            }),
12199            TensorPayload::Native(_) => match self.dtype() {
12200                DType::F32 => self.duplicate_typed::<f32>(),
12201                DType::F64 => self.duplicate_typed::<f64>(),
12202                DType::I32 => self.duplicate_typed::<i32>(),
12203                DType::I64 => self.duplicate_typed::<i64>(),
12204                DType::Bool => self.duplicate_typed::<bool>(),
12205                DType::C32 => self.duplicate_typed::<Complex<f32>>(),
12206                DType::C64 => self.duplicate_typed::<Complex<f64>>(),
12207                DType::External(_) => unreachable!("a native payload carries a preset dtype"),
12208            },
12209        }
12210    }
12211
12212    /// Duplicate a preset tensor through its typed owner.
12213    fn duplicate_typed<T: TensorScalar>(&self) -> crate::Result<Self> {
12214        self.as_typed::<T>()
12215            .unwrap_or_else(|| unreachable!("the caller selected this arm from the dtype"))
12216            .duplicate()
12217            .map(Self::from_typed)
12218    }
12219
12220    /// Create a tensor from a shape and column-major flat data.
12221    ///
12222    /// This is the `Tensor`-level equivalent of
12223    /// `TypedTensor::<T>::from_vec_col_major`.
12224    ///
12225    /// # Examples
12226    ///
12227    /// ```
12228    /// use tenferro_tensor::Tensor;
12229    ///
12230    /// let t = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 3.0, 2.0, 4.0]).unwrap();
12231    /// assert_eq!(t.shape(), &[2, 2]);
12232    /// assert_eq!(t.as_slice::<f64>().unwrap(), &[1.0, 3.0, 2.0, 4.0]);
12233    /// ```
12234    /// # Errors
12235    ///
12236    /// Returns [`crate::Error::Validation`] with
12237    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
12238    /// the shape product differs from `data.len()`, or
12239    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
12240    /// arithmetic overflows.
12241    pub fn from_vec_col_major<T: TensorScalar>(
12242        shape: impl tenferro_tensor_core::IntoShapeVec,
12243        data: Vec<T>,
12244    ) -> crate::Result<Self> {
12245        // Build the typed owner once and wrap it: routing the shape through
12246        // `T::into_tensor(Vec<usize>, _)` costs an exact-size `Vec` per construction
12247        // that the destination cannot keep, because the erased payload stores the
12248        // inline shape the typed constructor already produces (#2177).
12249        Ok(Self::from_typed(TypedTensor::<T>::from_vec_col_major(
12250            shape, data,
12251        )?))
12252    }
12253
12254    /// Create a tensor from a shape and row-major (C-order) flat data.
12255    ///
12256    /// The values are reordered once into tenferro's column-major storage;
12257    /// no row-major owner is created. Use this for buffers authored in
12258    /// PyTorch/NumPy/C order instead of passing them to
12259    /// [`Self::from_vec_col_major`], which would reinterpret them silently.
12260    /// This is the `Tensor`-level equivalent of
12261    /// `TypedTensor::<T>::from_vec_row_major`.
12262    ///
12263    /// # Examples
12264    ///
12265    /// ```
12266    /// use tenferro_tensor::Tensor;
12267    ///
12268    /// // Row-major [[1, 2, 3], [4, 5, 6]].
12269    /// let t = Tensor::from_vec_row_major(vec![2, 3], vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0])?;
12270    /// assert_eq!(t.shape(), &[2, 3]);
12271    /// assert_eq!(t.as_slice::<f64>()?, &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);
12272    /// # Ok::<(), tenferro_tensor::Error>(())
12273    /// ```
12274    /// # Errors
12275    ///
12276    /// Returns [`crate::Error::Validation`] with
12277    /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
12278    /// the shape product differs from `data.len()`, or
12279    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
12280    /// arithmetic overflows.
12281    pub fn from_vec_row_major<T: TensorScalar>(
12282        shape: impl tenferro_tensor_core::IntoShapeVec,
12283        data: Vec<T>,
12284    ) -> crate::Result<Self> {
12285        // The reorder keeps its own `op` name, and the shape comes back as the inline
12286        // vector the typed constructor takes, so neither `.to_vec()` in the erased
12287        // route is needed (#2177).
12288        let (shape, reordered) = row_major_reorder::<T, tenferro_tensor_core::DynRank>(
12289            shape,
12290            data,
12291            "Tensor::from_vec_row_major",
12292        )?;
12293        Ok(Self::from_typed(TypedTensor::<T>::from_vec_col_major(
12294            shape, reordered,
12295        )?))
12296    }
12297
12298    /// Tensor shape.
12299    ///
12300    /// # Examples
12301    ///
12302    /// ```rust
12303    /// use tenferro_tensor::{Tensor, TypedTensor};
12304    ///
12305    /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap());
12306    /// assert_eq!(t.shape(), &[2]);
12307    /// ```
12308    pub fn shape(&self) -> &[usize] {
12309        match &self.payload {
12310            TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.shape()),
12311            // The payload keeps its shape from construction.
12312            TensorPayload::External(payload, _) => payload.shape(),
12313        }
12314    }
12315
12316    /// Tensor dtype tag.
12317    ///
12318    /// # Examples
12319    ///
12320    /// ```rust
12321    /// use tenferro_tensor::{DType, Tensor, TypedTensor};
12322    ///
12323    /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![], vec![1.0]).unwrap());
12324    /// assert_eq!(t.dtype(), DType::F64);
12325    /// ```
12326    pub fn dtype(&self) -> DType {
12327        match &self.payload {
12328            TensorPayload::Native(preset) => match preset {
12329                PresetTensor::F32(_) => DType::F32,
12330                PresetTensor::F64(_) => DType::F64,
12331                PresetTensor::I32(_) => DType::I32,
12332                PresetTensor::I64(_) => DType::I64,
12333                PresetTensor::Bool(_) => DType::Bool,
12334                PresetTensor::C32(_) => DType::C32,
12335                PresetTensor::C64(_) => DType::C64,
12336            },
12337            // The payload carries its own element identity.
12338            TensorPayload::External(payload, _) => DType::External(payload.element_type_id()),
12339        }
12340    }
12341
12342    /// Return placement metadata for this dtype-erased tensor.
12343    ///
12344    /// # Examples
12345    ///
12346    /// ```rust
12347    /// use tenferro_tensor::{MemoryKind, Tensor};
12348    ///
12349    /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
12350    /// assert_eq!(t.placement().memory_kind, MemoryKind::UnpinnedHost);
12351    /// ```
12352    pub fn placement(&self) -> &Placement {
12353        match &self.payload {
12354            TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.placement()),
12355            // The placement is stored with the payload.
12356            TensorPayload::External(_, placement) => placement,
12357        }
12358    }
12359
12360    /// Return whether this tensor is backed by backend-native storage.
12361    ///
12362    /// # Examples
12363    ///
12364    /// ```rust
12365    /// use tenferro_tensor::Tensor;
12366    ///
12367    /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
12368    /// assert!(!t.is_backend_buffer());
12369    /// ```
12370    pub fn is_backend_buffer(&self) -> bool {
12371        match &self.payload {
12372            TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12373                matches!(&typed.storage, DynamicStorage::Group(core) if core.group.is_backend_buffer())
12374            }),
12375            // A caller-owned payload is host memory, never a backend buffer.
12376            TensorPayload::External(..) => false,
12377        }
12378    }
12379
12380    /// Return whether this tensor's payload is host-addressed memory.
12381    ///
12382    /// The one host/device answer, decided by the payload and never by
12383    /// [`Placement::memory_kind`]: the same answer
12384    /// [`TypedTensor::is_host_memory`] gives for a typed owner and
12385    /// [`TensorRead::is_host_memory`] for a read target. A caller-owned payload
12386    /// holds host bytes, so it is host memory; erasing its dtype, not its
12387    /// placement, is what makes a preset-scalar view unavailable.
12388    ///
12389    /// # Examples
12390    ///
12391    /// ```rust
12392    /// use tenferro_tensor::{Tensor, TensorRead};
12393    ///
12394    /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
12395    /// assert!(t.is_host_memory());
12396    /// assert!(TensorRead::from_tensor(&t).is_host_memory());
12397    /// # Ok::<(), tenferro_tensor::Error>(())
12398    /// ```
12399    pub fn is_host_memory(&self) -> bool {
12400        match &self.payload {
12401            TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.is_host_memory()),
12402            TensorPayload::External(..) => true,
12403        }
12404    }
12405
12406    /// Compute the physical element offset for a logical index.
12407    ///
12408    /// # Examples
12409    ///
12410    /// ```rust
12411    /// use tenferro_tensor::Tensor;
12412    ///
12413    /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12414    /// assert_eq!(t.layout_linear_offset(&[1])?, 1);
12415    /// # Ok::<(), tenferro_tensor::Error>(())
12416    /// ```
12417    /// # Errors
12418    ///
12419    /// Returns [`crate::Error::Validation`] with
12420    /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
12421    /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
12422    /// when an index is outside its axis extent, or
12423    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
12424    /// arithmetic overflows.
12425    pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
12426        match &self.payload {
12427            TensorPayload::Native(_) => {
12428                let layout = tensor_layout(self);
12429                checked_view_offset_result(
12430                    layout.shape(),
12431                    layout.strides(),
12432                    layout.offset(),
12433                    indices,
12434                    "Tensor::layout_linear_offset",
12435                )
12436            }
12437            // A caller-owned payload's owner resolves its own offsets.
12438            TensorPayload::External(..) => Err(crate::Error::unsupported_dtype(
12439                "layout_linear_offset",
12440                self.dtype(),
12441                "an externally defined payload resolves its own offsets",
12442            )),
12443        }
12444    }
12445
12446    /// Return whether this tensor is compact column-major.
12447    ///
12448    /// # Examples
12449    ///
12450    /// ```rust
12451    /// use tenferro_tensor::Tensor;
12452    ///
12453    /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12454    /// assert!(t.is_col_major_contiguous()?);
12455    /// # Ok::<(), tenferro_tensor::Error>(())
12456    /// ```
12457    /// # Errors
12458    ///
12459    /// Returns [`crate::Error::Validation`] with
12460    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
12461    /// compactness arithmetic overflows.
12462    pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
12463        match &self.payload {
12464            TensorPayload::Native(_) => tensor_layout(self)
12465                .is_compact_col_major()
12466                .map_err(|err| tensor_layout_error("Tensor::is_col_major_contiguous", err)),
12467            // The payload is a compact column-major host tensor by construction.
12468            TensorPayload::External(..) => Ok(true),
12469        }
12470    }
12471
12472    /// Return a compact string summary of this tensor's layout metadata.
12473    ///
12474    /// # Examples
12475    ///
12476    /// ```rust
12477    /// use tenferro_tensor::Tensor;
12478    ///
12479    /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12480    /// assert!(t.layout_summary().contains("shape=[2]"));
12481    /// # Ok::<(), tenferro_tensor::Error>(())
12482    /// ```
12483    pub fn layout_summary(&self) -> String {
12484        let layout = tensor_layout(self);
12485        layout_summary(layout.shape(), layout.strides(), layout.offset())
12486    }
12487
12488    /// Assert this tensor is compact column-major.
12489    ///
12490    /// # Examples
12491    ///
12492    /// ```rust
12493    /// use tenferro_tensor::Tensor;
12494    ///
12495    /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12496    /// t.assert_col_major_contiguous()?;
12497    /// # Ok::<(), tenferro_tensor::Error>(())
12498    /// ```
12499    /// # Errors
12500    ///
12501    /// Returns [`crate::Error::Validation`] with
12502    /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
12503    /// compactness arithmetic overflows, or
12504    /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
12505    /// tensor is not compact column-major.
12506    pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
12507        let layout = tensor_layout(self);
12508        assert_layout_col_major_contiguous(
12509            self.is_col_major_contiguous()?,
12510            layout.shape(),
12511            layout.strides(),
12512            layout.offset(),
12513            "Tensor::assert_col_major_contiguous",
12514        )
12515    }
12516
12517    /// Try to borrow the host data as a typed slice.
12518    ///
12519    /// Returns an error if the tensor dtype does not match `T`.
12520    ///
12521    /// # Examples
12522    ///
12523    /// ```
12524    /// use tenferro_tensor::{Tensor, TypedTensor};
12525    ///
12526    /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![3], vec![1.0, 2.0, 3.0]).unwrap());
12527    /// assert_eq!(t.as_slice::<f64>().unwrap(), [1.0, 2.0, 3.0].as_slice());
12528    /// assert!(t.as_slice::<f32>().is_err());
12529    /// ```
12530    /// # Errors
12531    ///
12532    /// Returns [`crate::Error::Validation`] with
12533    /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `T` does
12534    /// not match the tensor dtype, or [`crate::Error::RuntimeState`] when the
12535    /// matching tensor uses backend storage that has not been downloaded.
12536    pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&[T]> {
12537        T::as_slice(self)
12538    }
12539
12540    /// Borrow the typed tensor when the requested scalar matches this tensor's dtype.
12541    ///
12542    /// This is the accessor tag-based dispatch needs: it recovers the typed tensor — and with it the
12543    /// device buffer — from a value whose element type is only known at run time, so a caller can
12544    /// dispatch on [`Tensor::dtype`] instead of matching every variant. An externally defined scalar
12545    /// is not a typed tensor, so it returns `None` rather than guessing a representation.
12546    ///
12547    /// # Examples
12548    ///
12549    /// ```
12550    /// use tenferro_tensor::Tensor;
12551    ///
12552    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12553    /// assert!(tensor.as_typed::<f64>().is_some());
12554    /// assert!(tensor.as_typed::<f32>().is_none());
12555    /// assert_eq!(tensor.as_typed::<f64>().unwrap().shape(), &[2]);
12556    /// # Ok::<(), tenferro_tensor::Error>(())
12557    /// ```
12558    #[must_use]
12559    pub fn as_typed<T: TensorScalar>(&self) -> Option<&TypedTensor<T>> {
12560        if self.dtype() != T::dtype() {
12561            return None;
12562        }
12563        match &self.payload {
12564            TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12565                (typed as &dyn Any).downcast_ref::<TypedTensor<T>>()
12566            }),
12567            TensorPayload::External(..) => None,
12568        }
12569    }
12570
12571    /// Mutably borrow the typed tensor when the requested scalar matches this tensor's dtype.
12572    ///
12573    /// This is the mutable half of [`Tensor::as_typed`], for the tables whose arm calls a method that
12574    /// needs `&mut`, such as marking a freshly allocated output with its placement. An externally
12575    /// defined scalar is not a typed tensor, so it returns `None` for the same reason.
12576    ///
12577    /// # Examples
12578    ///
12579    /// ```
12580    /// use tenferro_tensor::Tensor;
12581    ///
12582    /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12583    /// assert!(tensor.as_typed_mut::<f64>().is_some());
12584    /// assert!(tensor.as_typed_mut::<f32>().is_none());
12585    /// # Ok::<(), tenferro_tensor::Error>(())
12586    /// ```
12587    #[must_use]
12588    pub fn as_typed_mut<T: TensorScalar>(&mut self) -> Option<&mut TypedTensor<T>> {
12589        if self.dtype() != T::dtype() {
12590            return None;
12591        }
12592        match &mut self.payload {
12593            TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12594                (typed as &mut dyn Any).downcast_mut::<TypedTensor<T>>()
12595            }),
12596            TensorPayload::External(..) => None,
12597        }
12598    }
12599
12600    /// Consume this tensor and return the owned typed tensor when the dtype matches.
12601    ///
12602    /// This is the consuming counterpart of [`Tensor::as_typed`], for the tables whose arm hands the typed
12603    /// tensor to a function that takes it by value — reusing its buffer rather than copying it.
12604    ///
12605    /// # Examples
12606    ///
12607    /// ```
12608    /// use tenferro_tensor::Tensor;
12609    ///
12610    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12611    /// assert!(tensor.into_typed::<f64>().is_ok());
12612    ///
12613    /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f32, 2.0])?;
12614    /// assert!(tensor.into_typed::<f64>().is_err());
12615    /// # Ok::<(), tenferro_tensor::Error>(())
12616    /// ```
12617    /// # Errors
12618    ///
12619    /// Returns [`ReinterpretError`] carrying the unchanged tensor when `T` is
12620    /// not this tensor's dtype, with [`crate::Error::Validation`] and
12621    /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] as the cause.
12622    /// A matching tensor is handed over as it is, including one whose storage
12623    /// lives in a backend buffer.
12624    pub fn into_typed<T: TensorScalar>(
12625        self,
12626    ) -> std::result::Result<TypedTensor<T>, ReinterpretError<Self>> {
12627        T::into_typed(self)
12628    }
12629
12630    /// Consume this tensor and return its owned column-major buffer when the
12631    /// dtype matches.
12632    ///
12633    /// # Examples
12634    ///
12635    /// ```
12636    /// use tenferro_tensor::Tensor;
12637    ///
12638    /// let t = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
12639    /// assert_eq!(t.into_vec_col_major::<f64>().unwrap().1, vec![2.0]);
12640    /// ```
12641    /// # Errors
12642    ///
12643    /// Returns [`ReinterpretError`] carrying the unchanged tensor when `T` does
12644    /// not match the tensor dtype or when the matching tensor uses backend
12645    /// storage that has not been downloaded.
12646    pub fn into_vec_col_major<T: TensorScalar>(
12647        self,
12648    ) -> std::result::Result<(Vec<usize>, Vec<T>), ReinterpretError<Self>> {
12649        let typed = T::into_typed(self)?;
12650        match typed.into_vec_col_major() {
12651            Ok(parts) => Ok(parts),
12652            Err(failure) => {
12653                let (owner, error) = failure.into_parts();
12654                Err(ReinterpretError::new(Tensor::from_typed(owner), error))
12655            }
12656        }
12657    }
12658}
12659
12660// INVARIANT: retained for crate-local layout tests while tensor indexing
12661// helpers remain split across the tensor and CPU crates.
12662#[allow(dead_code)]
12663pub(crate) fn flat_to_multi(mut flat: usize, shape: &[usize], out: &mut [usize]) {
12664    for i in 0..shape.len() {
12665        if shape[i] == 0 {
12666            out[i] = 0;
12667        } else {
12668            out[i] = flat % shape[i];
12669            flat /= shape[i];
12670        }
12671    }
12672}