edgefirst_tensor/

lib.rs

// SPDX-FileCopyrightText: Copyright 2025 Au-Zone Technologies
// SPDX-License-Identifier: Apache-2.0

/*!
EdgeFirst HAL - Tensor Module

The `edgefirst_tensor` crate provides a unified interface for managing multi-dimensional arrays (tensors)
across four memory backends: the platform's native zero-copy GPU buffer, POSIX shared memory, the system
heap, and an OpenGL Pixel Buffer Object. The crate defines traits and structures for creating, reshaping,
and mapping tensors into memory.

## Examples
```rust
use edgefirst_tensor::{Error, Tensor, TensorMemory, TensorTrait};
# fn main() -> Result<(), Error> {
let tensor = Tensor::<f32>::new(&[2, 3, 4], Some(TensorMemory::Mem), Some("test_tensor"))?;
assert_eq!(tensor.memory(), TensorMemory::Mem);
assert_eq!(tensor.name(), "test_tensor");
#    Ok(())
# }
```

## Overview
The main structures and traits provided by the `edgefirst_tensor` crate are [`TensorTrait`] and
[`TensorMapTrait`], which define the behavior of Tensors and their memory mappings, respectively.
The [`Tensor<T>`] struct wraps a backend-specific storage with optional image format metadata
([`PixelFormat`]); mapping a tensor yields a [`HostView`], which implements
[`TensorMapTrait`] and derefs to the underlying elements. The
[`TensorDyn`] type-erased enum wraps `Tensor<T>` for runtime element-type dispatch.

[`TensorMemory::DmaBuf`] is one variant with three implementations behind it — a Linux DMA-heap DMA-BUF,
a macOS/iOS `IOSurfaceRef`, or an Android `AHardwareBuffer`. Callers ask for `Dma` and get whichever
the platform provides, so portable code never branches on the mechanism.

## Image tensors
Images go through [`Tensor::image`] (or [`Tensor::image_desc`] for the full-featured request) rather
than [`Tensor::new`]. Two things set them apart:

- They take a required [`CpuAccess`] declaration. Hardware access — GPU, NPU, ISP, codec — is always
  implied; what the CPU intends is the one thing the allocator cannot guess. Mapping beyond the
  declaration is best-effort and always counted by [`unplanned_cpu_access_count`].
- DMA-backed images carry a 64-byte-aligned row stride in every layout, because Mali and Vivante
  reject an EGLImage import at an unaligned pitch. Read the real pitch from
  [`Tensor::effective_row_stride`]; don't assume `width * bpp`.
 */
#[cfg(all(feature = "static", feature = "dynamic"))]
compile_error!(
    "edgefirst-tensor: `static` and `dynamic` are mutually exclusive. \
     A consumer building the C-API leaves wants `--no-default-features \
     --features dynamic`; everything else wants the default."
);

// The workspace declares `default-features = false` for this crate, so
// nothing arrives here by accident anymore -- every consumer names a
// backend explicitly. Before that change `static` was always a default and
// this state was unreachable; now a manifest that forgot to ask for either
// backend back builds an empty `tensor_dyn` module and fails on confusing
// `E0432: unresolved import` errors instead of a message that names the
// actual problem.
#[cfg(not(any(feature = "static", feature = "dynamic")))]
compile_error!(
    "edgefirst-tensor: exactly one backend must be enabled. This crate has \
     `default-features = false` at the workspace level, so every consumer \
     must name one explicitly: `features = [\"static\"]` for Rust consumers, \
     or `[\"dynamic\"]` for the C-API leaves."
);

// `static`-only: every constructor/accessor here is reached exclusively
// through `TensorStorage`'s `AHardwareBuffer` variant (`impl<T> Tensor<T>`,
// gated `#[cfg(feature = "static")]`); under `dynamic` nothing calls into
// it, which clippy's dead-code lint on Android correctly flags without this
// gate. Not `#[allow]`-ed: an `allow` here would hide the next real
// dead-code signal in this module, the opposite of what a gate does.
#[cfg(all(target_os = "android", feature = "static"))]
mod ahardwarebuffer;
// Pure AHardwareBuffer layout logic (format table, descriptor geometry,
// overflow-checked shape math) — cfg-free so it compiles and unit-tests
// on every host; the android module above consumes it.
#[allow(dead_code)]
mod ahardwarebuffer_layout;
pub mod colorimetry;
#[cfg(feature = "tracing")]
pub mod trace;

pub mod covguard;
mod cuda;
mod detect;
// `static`-gated as well as Linux-gated. `DmaTensor` is storage, and only
// the `static` backend has storage -- `TensorStorage` itself is already
// `#[cfg(feature = "static")]`, and the `dynamic` backend reaches a
// DMA-BUF's fd through `ef_tensor_plane_at` instead of ever constructing
// one. Until task P2b's F3, this module was kept alive under `dynamic` by a
// single always-`None` `Tensor::as_dma` whose signature named `DmaTensor`;
// removing that stub revealed the whole module (the tensor, the sync
// ioctls, the DRM PRIME helpers, the mmap owner) as dead code there --
// twenty-six dead-code warnings' worth. It was always dead; one method
// hid it.
#[cfg(all(target_os = "linux", feature = "static"))]
mod dma;
#[cfg(all(target_os = "linux", feature = "static"))]
mod dmabuf;
mod error;
mod format;
// Layout table is backend-agnostic (pure DXGI-format math), same reasoning
// as `iosurface_layout` below: compiled on every platform so it is
// unit-tested on every CI lane. The allocator that consumes it
// (`crate::d3d11`) is Windows-only.
#[cfg(target_os = "windows")]
pub mod d3d11;
pub mod d3d11_layout;
// Layout table is backend-agnostic (pure FourCC math). Storage
// (`IoSurfaceTensor`) is `static`-only; `dynamic` reads IOSurface handles
// through `ef_tensor_*`.
#[cfg(any(target_os = "macos", target_os = "ios"))]
mod iosurface_layout;
// `static`-only, same reasoning as `ahardwarebuffer` above: reached only
// through `TensorStorage`'s `IoSurface` variant.
#[cfg(all(any(target_os = "macos", target_os = "ios"), feature = "static"))]
mod iosurface;
pub mod lens;
// `static`-only: `MemTensor` backs `TensorStorage::Mem`, `impl<T> Tensor<T>`
// only. `dynamic`'s host-memory allocation goes through `ef_tensor_new`/
// `ef_tensor_builder_alloc` in `libedgefirst_tensor.so` instead -- there is
// no local `MemTensor` under `dynamic` to be dead code, so the whole module
// gates rather than an internal `#[allow]`.
#[cfg(feature = "static")]
mod mem;
mod pbo;
pub mod pin;
pub mod protocol;
// `static`-only, same reasoning as `mem` above: `ShmTensor` backs
// `TensorStorage::Shm`, `impl<T> Tensor<T>` only.
#[cfg(all(unix, feature = "static"))]
mod shm;
mod tensor_dyn;
#[cfg(test)]
mod test_support;
pub mod view;
mod vocabulary;
pub use colorimetry::{
    ColorEncoding, ColorRange, ColorSpace, ColorTransfer, Colorimetry, MatrixWeights, RangeScaling,
};

/// Retained constructor: installs the coverage flush-on-abort handler for this
/// crate's instrumented test binary. See `covguard`. Only present under
/// coverage on Linux (`.init_array` is ELF-only; the i.MX flush is Linux-only).
#[cfg(all(coverage, target_os = "linux"))]
#[used]
#[link_section = ".init_array"]
static __EDGEFIRST_COV_INSTALL: extern "C" fn() = {
    extern "C" fn ctor() {
        crate::covguard::install();
    }
    ctor
};

// Backing tensor/map types are internal implementation details: callers
// allocate `Tensor<T>` / `TensorDyn` and map them, never naming the per-memory
// backing types directly. They are `pub(crate)` so they stay nameable for the
// `TensorStorage` / `TensorMap` enums without leaking into the public API.
// Exceptions kept public: `Pbo*` is a GL extension point implemented by the
// image crate, and `image_iosurface_layout` is a public helper.
#[cfg(all(target_os = "android", feature = "static"))]
pub use crate::ahardwarebuffer::image_ahardwarebuffer_layout;
#[cfg(all(target_os = "android", feature = "static"))]
pub(crate) use crate::ahardwarebuffer::AHardwareBufferTensor;
#[cfg(all(target_os = "linux", feature = "static"))]
pub(crate) use crate::dma::DmaTensor;
#[cfg(all(any(target_os = "macos", target_os = "ios"), feature = "static"))]
pub(crate) use crate::iosurface::IoSurfaceTensor;
// The two geometry helpers are compiled for both backends: three of the four
// surfaces that read a raw texture's geometry (the Python bindings, and the
// protocol and blob imports) link `dynamic`, and only the C ABI links
// `static`. See `crate::d3d11::geometry`.
#[cfg(target_os = "windows")]
pub use crate::d3d11::geometry::{d3d11_shared_handle_geometry, d3d11_texture_geometry};
#[cfg(any(target_os = "macos", target_os = "ios"))]
pub use crate::iosurface_layout::image_iosurface_layout;
#[cfg(feature = "static")]
pub(crate) use crate::mem::MemTensor;
pub use crate::pbo::{
    client_state_pbo_ops, read_pbo_vtable_parts, EfClientState, EfPboMapFn, EfPboUnmapFn,
    PboClientParts, PboMapping, PboOps, PboOpsVtableParts, PboTensor,
};
#[cfg(all(unix, feature = "static"))]
pub(crate) use crate::shm::ShmTensor;
pub use cuda::{
    gl_map_resource, gl_register_buffer, gl_unmap_resource, gl_unregister_resource,
    is_cuda_available, memcpy_device_to_host, memcpy_host_to_device,
    runtime_path as cuda_runtime_path, stream_create, stream_destroy, stream_synchronize,
    CudaGlOps, CudaHandle, CudaMap, CudaStream,
};
pub use detect::{unletter_norm, BoundingBox, DetectBox, ProtoData, ProtoLayout, Segmentation};
pub use error::{Error, Result};
// Static-backend-implementation code: backs `tensor-capi`'s own
// `ef_tensor_export`/`ef_tensor_import` (the static cdylib's `TensorDyn`
// serialization), the one caller in the whole workspace. It calls
// `TensorDyn::new`/`from_fd` and reads fields (`.quantization()`,
// `.colorimetry()`, `.pin_host()`, ...) that only the `static` backend's
// richer `TensorDyn` surface has, so it never compiled under `dynamic` in
// fact even though nothing gated it -- see `PRIMITIVE-INVENTORY.md`'s
// "structural findings".
#[cfg(feature = "static")]
pub mod blob;
#[cfg(feature = "static")]
pub use blob::{
    BlobError, BlobHeader, BlobPlane, BlobStrings, BlobView, Regions, TransportMode, HEADER_LEN,
    PLANE_RECORD_LEN,
};
pub use format::{ChromaLayout, PixelFormat, PixelLayout, PlaneGeometry};
pub use lens::Element;
use num_traits::Num;
pub use pin::HostPin;
pub use protocol::{
    dtype as tensor_dtype, dtype_to_dtype, format as tensor_format, format_from_code,
    kind as tensor_kind, SendPtr, TensorDesc, ABI_VERSION,
};
use serde::{Deserialize, Serialize};
#[cfg(unix)]
use std::os::fd::OwnedFd;
use std::{
    fmt,
    sync::{
        atomic::{AtomicU64, Ordering},
        Arc, Weak,
    },
};
// `static`'s `Tensor<T>` is declared directly above, in this file; there is
// nothing to re-export for it. `dynamic`'s lives in `tensor_dyn` (see that
// module's docs) and is re-exported here under the same crate-root name so
// both backends present the same `edgefirst_tensor::Tensor` to callers.
#[cfg(feature = "dynamic")]
pub use tensor_dyn::Tensor;
pub use tensor_dyn::{Raw, TensorDyn};
pub use view::HostView;
pub use vocabulary::vocabulary_demo;

/// Opaque keep-alive handle for a foreign-memory tensor (see
/// [`Tensor::from_foreign`] / [`TensorDyn::from_foreign_ptr`]).
///
/// The HAL borrows the foreign buffer without owning it; this handle co-owns
/// the *source* so the borrowed memory stays valid for the tensor's life. Its
/// `Drop` releases the source — e.g. a small struct that calls `cudaFreeHost`,
/// or a `Py<PyAny>` that decrements a NumPy array's refcount. Wrapping it in an
/// `Arc` (then boxing each clone) makes the release fire exactly once, after
/// the last sharing tensor/view/map drops, regardless of drop order.
pub type ForeignOwner = Box<dyn std::any::Any + Send + Sync>;

/// Re-export of `half::f16` so downstream crates can write
/// `Tensor::<edgefirst_tensor::f16>::from_iosurface(…)` without
/// adding `half` to their own dependency list. The version stays in
/// lockstep with the `half` workspace dep.
pub use half::f16;

// =============================================================================
// RGBA16F packed-layout geometry — single source of truth
//
// A `PlanarRgb` [3,H,W] or `PlanarRgba` [4,H,W] f16 tensor is represented
// on the GPU as an RGBA16F surface (the only float format accepted by the
// ANGLE IOSurface extension). Four contiguous f16 elements are packed into
// each 8-byte RGBA16F texel, yielding a `(W/4, C*H)` surface.
//
// All call sites that need these dimensions must use `packed_rgba16f_layout`
// so the rule lives in exactly one place. Currently consumed by:
//  - `crates/tensor/src/iosurface.rs` `new_image` (macOS IOSurface alloc)
//  - `crates/image/src/gl/iosurface_import.rs` (macOS GL IOSurface import)
//  - `crates/image/src/gl/processor/float.rs` (Linux GL float render — PBO
//    readback and DMA-BUF, also via the `dma_f16_packed_layout` wrapper)
// =============================================================================

/// Geometry of the RGBA16F-packed surface backing a planar F16 image tensor.
///
/// ANGLE only supports one float `(type, internal_format)` pair for IOSurface
/// import: `(GL_HALF_FLOAT, GL_RGBA)` = RGBA16F (8 bytes/texel). To map a
/// `[C, H, W]` f16 planar tensor onto such a surface, 4 contiguous f16
/// elements are packed into each RGBA16F texel, yielding a surface of
/// `(W/4, C*H)` texels at 8 bytes/texel. The byte stream is identical to a
/// (nonexistent) R16F `(W, C*H)` surface and can be consumed as `&[f16]`
/// with shape `[1, C, H, W]` without rearrangement.
///
/// Obtain via [`packed_rgba16f_layout`] — never construct directly.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PackedRgba16fLayout {
    /// Surface width in texels (`width / 4`).
    pub surface_w: usize,
    /// Surface height in texels (`planes * height`).
    pub surface_h: usize,
    /// Bytes per RGBA16F texel (always 8).
    pub bytes_per_texel: usize,
    /// Row pitch in bytes (`surface_w * 8`).
    pub pitch: usize,
}

/// Canonical geometry for the RGBA16F-packed surface backing a planar F16
/// image tensor.
///
/// Returns `Some(layout)` only when **all** of the following hold:
///
/// - `dtype == DType::F16`
/// - `format` is `PixelFormat::PlanarRgb` (3 planes) or
///   `PixelFormat::PlanarRgba` (4 planes)
/// - `width % 4 == 0`
///
/// Returns `None` for any other `(format, dtype)` combination, misaligned
/// width, or when the surface geometry would overflow `usize` — callers
/// must fall back to a non-packed path or return a context-appropriate
/// error.
///
/// # Examples
///
/// ```rust
/// use edgefirst_tensor::{packed_rgba16f_layout, PixelFormat, DType};
///
/// let layout = packed_rgba16f_layout(PixelFormat::PlanarRgb, DType::F16, 640, 480).unwrap();
/// assert_eq!(layout.surface_w, 160);
/// assert_eq!(layout.surface_h, 1440);
/// assert_eq!(layout.bytes_per_texel, 8);
/// assert_eq!(layout.pitch, 1280);
/// ```
pub fn packed_rgba16f_layout(
    format: PixelFormat,
    dtype: DType,
    width: usize,
    height: usize,
) -> Option<PackedRgba16fLayout> {
    if dtype != DType::F16 {
        return None;
    }
    let planes: usize = match format {
        PixelFormat::PlanarRgb => 3,
        PixelFormat::PlanarRgba => 4,
        _ => return None,
    };
    if !width.is_multiple_of(4) {
        return None;
    }
    let surface_w = width / 4;
    // Checked arithmetic: a degenerate (height, width) could otherwise wrap
    // and yield an under-sized layout, which downstream allocators trust for
    // GPU/CPU buffer sizing. Overflow → None (handled like any other
    // unsupported geometry).
    let surface_h = planes.checked_mul(height)?;
    let bytes_per_texel = 8;
    let pitch = surface_w.checked_mul(bytes_per_texel)?;
    Some(PackedRgba16fLayout {
        surface_w,
        surface_h,
        bytes_per_texel,
        pitch,
    })
}

/// Geometry of the RGBA8888-packed surface backing a packed RGB u8/i8 image
/// tensor.
///
/// GPUs have no 3-channel renderable format, so the GL engine's two-pass
/// packed-RGB shader writes the tight `[H, W, 3]` byte stream into an
/// RGBA8888 surface: each texel carries 4 consecutive RGB bytes, giving a
/// `(W*3/4, H)` surface at 4 bytes/texel whose rows are byte-identical to
/// tight RGB — consumable flat as `[H, W, 3]` with no rearrangement (the
/// u8/i8 analog of [`packed_rgba16f_layout`]; i8 shares the layout since
/// INT8 quantization is a per-byte `^0x80` bias, not a format change).
///
/// Returns `Some(layout)` only when `width % 4 == 0` (so `W*3` bytes divide
/// into whole texels) and the geometry does not overflow `usize`.
///
/// # Examples
///
/// ```rust
/// use edgefirst_tensor::packed_rgb888_layout;
///
/// let layout = packed_rgb888_layout(640, 480).unwrap();
/// assert_eq!(layout.surface_w, 480); // 640*3/4
/// assert_eq!(layout.surface_h, 480);
/// assert_eq!(layout.bytes_per_texel, 4);
/// assert_eq!(layout.pitch, 1920); // 640*3
/// assert!(packed_rgb888_layout(641, 480).is_none());
/// ```
pub fn packed_rgb888_layout(width: usize, height: usize) -> Option<PackedRgb888Layout> {
    if !width.is_multiple_of(4) {
        return None;
    }
    let row_bytes = width.checked_mul(3)?;
    let surface_w = row_bytes / 4;
    Some(PackedRgb888Layout {
        surface_w,
        surface_h: height,
        bytes_per_texel: 4,
        pitch: row_bytes,
    })
}

/// Geometry of the RGBA8888 surface backing a packed RGB u8/i8 image tensor.
///
/// Obtain via [`packed_rgb888_layout`] — never construct directly.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PackedRgb888Layout {
    /// Surface width in texels (`width * 3 / 4`).
    pub surface_w: usize,
    /// Surface height in texels (`height`).
    pub surface_h: usize,
    /// Bytes per RGBA8888 texel (always 4).
    pub bytes_per_texel: usize,
    /// Row pitch in bytes (`surface_w * 4` = `width * 3`).
    pub pitch: usize,
}

/// The logical `(width, height)` an **allocation** shape describes for
/// `format` -- the inverse of [`PixelFormat::allocation_shape`].
///
/// Used wherever a tensor arrives carrying a shape and a format but not its
/// dimensions: the C constructors, the Python bindings and the cross-package
/// protocol import.
///
/// # The input is the allocation shape, not the addressing shape
///
/// [`PixelFormat::allocation_shape`] is what [`Tensor::image`] allocates from
/// and what `descriptor_pinned` emits from `shape()`, so that is what this
/// inverts. [`PixelFormat::addressing_shape`] is a different, smaller grid,
/// and for a semi-planar format the two collide: NV12's addressing shape is
/// `[h, w]` and its allocation shape is `[combined_h, w]`, both rank 2. Handed
/// an addressing shape this cannot tell -- NV12 `[480, 640]` reads as a
/// combined height of 480 and answers `(640, 320)`, silently. Nothing in the
/// shape distinguishes them, so callers must pass the allocation shape.
///
/// A D3D11 import is the one place this cannot bite: the constructors check
/// the derived size against the texture description, so a mismatch fails with
/// [`Error::InvalidArgument`] naming both. On Windows, prefer
/// `d3d11_texture_geometry` and `d3d11_shared_handle_geometry`, which read the
/// dimensions off the texture itself and leave the shape as a consistency
/// check -- except for a semi-planar texture, whose width is its row stride
/// rather than the image width, so those helpers take the width from the shape
/// they are given and refuse to answer without one.
///
/// The rank is part of the format's contract, so a shape of the wrong rank is
/// an error rather than an interpretation of whatever dimensions are present:
///
/// | Layout | Shape | Result |
/// |--------|-------|--------|
/// | Packed | `[h, w, c]` | `(shape[1], shape[0])` |
/// | Planar | `[c, h, w]` | `(shape[2], shape[1])` |
/// | SemiPlanar | `[combined_h, w]` | `(shape[1], image height)` |
///
/// A semi-planar shape carries the *combined* plane height, so the logical
/// height is recovered through
/// [`PixelFormat::image_height_from_combined`], which rejects a combined
/// height no image height produces (721 for NV12, say) instead of rounding to
/// a nearby one.
///
/// # Errors
///
/// [`Error::InvalidShape`] for a shape of the wrong rank, or a semi-planar
/// combined height with no image height behind it.
///
/// # Example
///
/// ```
/// use edgefirst_tensor::{image_dims_from_shape, PixelFormat};
/// assert_eq!(image_dims_from_shape(PixelFormat::Rgba, &[480, 640, 4]).unwrap(), (640, 480));
/// assert_eq!(image_dims_from_shape(PixelFormat::PlanarRgb, &[3, 480, 640]).unwrap(), (640, 480));
/// assert_eq!(image_dims_from_shape(PixelFormat::Nv12, &[722, 640]).unwrap(), (640, 481));
/// assert!(image_dims_from_shape(PixelFormat::Nv12, &[721, 640]).is_err());
/// ```
pub fn image_dims_from_shape(format: PixelFormat, shape: &[usize]) -> Result<(usize, usize)> {
    let wrong_rank = |expected: usize| {
        Error::InvalidShape(format!(
            "image_dims_from_shape: {format:?} describes a rank-{expected} allocation \
             shape, got rank {} ({shape:?})",
            shape.len()
        ))
    };
    match format.layout() {
        PixelLayout::Packed => {
            if shape.len() != 3 {
                return Err(wrong_rank(3));
            }
            Ok((shape[1], shape[0]))
        }
        PixelLayout::Planar => {
            if shape.len() != 3 {
                return Err(wrong_rank(3));
            }
            Ok((shape[2], shape[1]))
        }
        PixelLayout::SemiPlanar => {
            if shape.len() != 2 {
                return Err(wrong_rank(2));
            }
            let height = format.image_height_from_combined(shape[0]).ok_or_else(|| {
                Error::InvalidShape(format!(
                    "image_dims_from_shape: no {format:?} image height has combined plane \
                     height {} (shape {shape:?})",
                    shape[0]
                ))
            })?;
            Ok((shape[1], height))
        }
    }
}

/// Per-plane DMA-BUF descriptor for external buffer import.
///
/// Owns a duplicated file descriptor plus optional stride and offset metadata.
/// The fd is duplicated eagerly in [`new()`](Self::new) so that a bad fd is
/// caught immediately. `import_image` consumes the descriptor and takes
/// ownership of the duped fd — no further cleanup is needed by the caller.
///
/// # Examples
///
/// ```rust,no_run
/// use edgefirst_tensor::PlaneDescriptor;
/// use std::os::fd::BorrowedFd;
///
/// // SAFETY: fd 42 is hypothetical; real code must pass a valid fd.
/// let pd = unsafe { PlaneDescriptor::new(BorrowedFd::borrow_raw(42)) }
///     .unwrap()
///     .with_stride(2048)
///     .with_offset(0);
/// ```
#[cfg(unix)]
pub struct PlaneDescriptor {
    fd: OwnedFd,
    stride: Option<usize>,
    offset: Option<usize>,
}

#[cfg(unix)]
impl PlaneDescriptor {
    /// Create a new plane descriptor by duplicating the given file descriptor.
    ///
    /// The fd is duped immediately — a bad fd fails here rather than inside
    /// `import_image`. The caller retains ownership of the original fd.
    ///
    /// # Errors
    ///
    /// Returns an error if the `dup()` syscall fails (e.g. invalid fd or
    /// fd limit reached).
    pub fn new(fd: std::os::fd::BorrowedFd<'_>) -> Result<Self> {
        let owned = fd.try_clone_to_owned()?;
        Ok(Self {
            fd: owned,
            stride: None,
            offset: None,
        })
    }

    /// Set the row stride in bytes (consuming builder).
    pub fn with_stride(mut self, stride: usize) -> Self {
        self.stride = Some(stride);
        self
    }

    /// Set the plane offset in bytes (consuming builder).
    pub fn with_offset(mut self, offset: usize) -> Self {
        self.offset = Some(offset);
        self
    }

    /// Consume the descriptor and return the owned file descriptor.
    pub fn into_fd(self) -> OwnedFd {
        self.fd
    }

    /// Row stride in bytes, if set.
    pub fn stride(&self) -> Option<usize> {
        self.stride
    }

    /// Plane offset in bytes, if set.
    pub fn offset(&self) -> Option<usize> {
        self.offset
    }
}

/// A rectangular sub-region of a tensor's leading spatial frame, in pixels.
///
/// `Region` is the single rectangle type in the workspace: the argument to
/// [`Tensor::view`], the source sampling window in the image crate's `Crop`,
/// and the geometry the image backend lowers to a `glViewport` (a destination
/// tile) or a sampling rectangle (a source). Coordinates are pixel/element
/// units of the leading spatial axes; byte addressing is derived from the
/// parent's row stride, not stored here.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Region {
    pub x: usize,
    pub y: usize,
    pub width: usize,
    pub height: usize,
}

impl Region {
    /// Create a region at `(x, y)` spanning `width` × `height` pixels.
    pub fn new(x: usize, y: usize, width: usize, height: usize) -> Self {
        Self {
            x,
            y,
            width,
            height,
        }
    }

    /// True when the region lies fully within a `width` × `height` frame.
    pub fn fits_within(&self, width: usize, height: usize) -> bool {
        self.x.saturating_add(self.width) <= width && self.y.saturating_add(self.height) <= height
    }
}

/// The parent image a [`view`](Tensor::view)/[`batch`](Tensor::batch) sub-region
/// was carved from, snapshotted at the time the view was created.
///
/// A view shares the parent's `BufferIdentity` and addresses a sub-rectangle of
/// it. The GL backend keys its EGLImage import on the **parent** geometry (so all
/// sibling views of one buffer collapse to a single import) and renders each
/// view as a `glViewport`+`glScissor` ROI at `(x, y, width, height)` within that
/// parent — the view is render state, never a distinct import. `parent_width`/
/// `parent_height` are the parent's logical pixel dimensions; `x`/`y` are this
/// view's top-left origin within the parent (pixels). Nested views compose:
/// the snapshot always names the **root** parent, with offsets accumulated.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ViewOrigin {
    /// Logical width of the root parent image, in pixels.
    pub parent_width: usize,
    /// Logical height of the root parent image, in pixels. For a `batch(n)` view
    /// of an `[N, H, W, C]` tensor this is `N * H` (the tiles stack vertically in
    /// the shared buffer).
    pub parent_height: usize,
    /// The parent's row stride in **bytes**. The GL backend keys its EGLImage
    /// import/cache and pitch on this — NOT on the view's own `row_stride`, which
    /// a single-row view sets tight (for map-span safety). Using the parent
    /// stride keeps the import pitch parent-consistent so single-row and
    /// multi-row sibling views collapse onto the same parent import.
    pub parent_row_stride: usize,
    /// This view's top-left x origin within the root parent, in pixels.
    pub x: usize,
    /// This view's top-left y origin within the root parent, in pixels.
    pub y: usize,
}

// Declared through `ef_vocabulary!` (see `vocabulary.rs`): `.code()` is this
// crate's wire numbering, mirrored by `protocol::dtype` and the C ABI's
// `hal_dtype`. Both surfaces are generated from the same per-variant literal
// below rather than re-typed by hand, and `dtype_codes_are_unchanged_by_the_macro`
// in `tests/vocabulary.rs` pins them against the values already shipping.
crate::ef_vocabulary! {
    /// Element type discriminant for runtime type identification.
    #[derive(Serialize, Deserialize)]
    #[non_exhaustive]
    pub enum DType {
        U8 = 0, "u8", U8,
        I8 = 1, "i8", I8,
        U16 = 2, "u16", U16,
        I16 = 3, "i16", I16,
        U32 = 4, "u32", U32,
        I32 = 5, "i32", I32,
        U64 = 6, "u64", U64,
        I64 = 7, "i64", I64,
        F16 = 8, "f16", F16,
        F32 = 9, "f32", F32,
        F64 = 10, "f64", F64,
    }
    // `#[doc(hidden)]`: this module has to be `pub` for `protocol::dtype`'s
    // `pub use` re-export below to compile, but it is emission plumbing, not
    // a second documented API for the same eleven codes -- `protocol::dtype`
    // is the canonical, documented path.
    #[doc(hidden)]
    pub mod dtype_wire;
}

impl DType {
    /// Size of one element in bytes.
    pub const fn size(&self) -> usize {
        match self {
            Self::U8 | Self::I8 => 1,
            Self::U16 | Self::I16 | Self::F16 => 2,
            Self::U32 | Self::I32 | Self::F32 => 4,
            Self::U64 | Self::I64 | Self::F64 => 8,
        }
    }

    /// Short type name (e.g., "u8", "f32", "f16"). Identical to
    /// [`DType::as_str`]; kept as its own method for existing callers.
    pub fn name(&self) -> &'static str {
        self.as_str()
    }
}

impl fmt::Display for DType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// Map a static numeric type `T` to its `DType` discriminant, returning
/// `None` for types that do not have a `DType` representation (e.g.
/// user-defined wrappers in tests).
///
/// Runtime dtype of a static `Tensor<T>` element type — a safe `TypeId`
/// allowlist of HAL's primitive numeric types (`Some` for `u8`..`i64` /
/// `f16` / `f32` / `f64`, `None` otherwise). Used by the macOS IOSurface
/// image constructors (FourCC / pixel-format lookup) and by the `Mem`
/// backing's `alloc_zeroed` fast path (these types' `T::zero()` is the
/// all-zeros bit pattern), so it is compiled on every target -- but only
/// under `static`: every call site lives in `impl<T> Tensor<T>`, itself
/// `#[cfg(feature = "static")]`.
#[cfg(feature = "static")]
pub(crate) fn dtype_of<T: 'static>() -> Option<DType> {
    use std::any::TypeId;
    let id = TypeId::of::<T>();
    if id == TypeId::of::<u8>() {
        Some(DType::U8)
    } else if id == TypeId::of::<i8>() {
        Some(DType::I8)
    } else if id == TypeId::of::<u16>() {
        Some(DType::U16)
    } else if id == TypeId::of::<i16>() {
        Some(DType::I16)
    } else if id == TypeId::of::<u32>() {
        Some(DType::U32)
    } else if id == TypeId::of::<i32>() {
        Some(DType::I32)
    } else if id == TypeId::of::<u64>() {
        Some(DType::U64)
    } else if id == TypeId::of::<i64>() {
        Some(DType::I64)
    } else if id == TypeId::of::<half::f16>() {
        Some(DType::F16)
    } else if id == TypeId::of::<f32>() {
        Some(DType::F32)
    } else if id == TypeId::of::<f64>() {
        Some(DType::F64)
    } else {
        None
    }
}

// =============================================================================
// Quantization metadata — type-gated to integer element types via sealed
// `IntegerType` trait. Accessors on `Tensor<T>` only compile when `T` is
// an integer type; calling them on `Tensor<f32>` / `Tensor<f16>` etc. is a
// compile error, not a runtime one.
// =============================================================================

mod sealed {
    pub trait Sealed {}
    impl Sealed for u8 {}
    impl Sealed for i8 {}
    impl Sealed for u16 {}
    impl Sealed for i16 {}
    impl Sealed for u32 {}
    impl Sealed for i32 {}
    impl Sealed for u64 {}
    impl Sealed for i64 {}
    // f16 / f32 / f64 are sealed too (crate::lens::Element covers all
    // eleven element types), but deliberately NOT given `IntegerType` below.
    impl Sealed for half::f16 {}
    impl Sealed for f32 {}
    impl Sealed for f64 {}
}

/// Integer element types that may carry quantization metadata.
///
/// Sealed trait: implemented for `u8`, `i8`, `u16`, `i16`, `u32`, `i32`,
/// `u64`, `i64`. Cannot be implemented downstream. Float element types
/// (`half::f16`, `f32`, `f64`) are explicitly excluded — quantization
/// metadata does not apply to float tensors per the edgefirst.json spec.
pub trait IntegerType: sealed::Sealed {}
impl IntegerType for u8 {}
impl IntegerType for i8 {}
impl IntegerType for u16 {}
impl IntegerType for i16 {}
impl IntegerType for u32 {}
impl IntegerType for i32 {}
impl IntegerType for u64 {}
impl IntegerType for i64 {}

/// Quantization parameters for an integer tensor.
///
/// Covers all four modes the edgefirst.json spec defines:
///
/// | Mode | `scale.len()` | `zero_point` | `axis` |
/// |---|---|---|---|
/// | Per-tensor symmetric | 1 | `None` | `None` |
/// | Per-tensor asymmetric | 1 | `Some(len == 1)` | `None` |
/// | Per-channel symmetric | >1 | `None` | `Some(c)` |
/// | Per-channel asymmetric | >1 | `Some(len == scale.len())` | `Some(c)` |
///
/// The quantized storage type is carried on the parent [`Tensor<T>`]; this
/// struct does not duplicate it. Construct via the four named constructors
/// (the only public entry points); direct field mutation is not allowed so
/// invalid combinations cannot be represented.
///
/// Dequantization formula:
///
/// ```text
///   real_value = scale[c] × (quantized_value[c] - zero_point[c])
/// ```
///
/// where `c` is the channel index (always `0` for per-tensor).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Quantization {
    /// Per-tensor: `vec![scale]`. Per-channel: `vec![scale_0, scale_1, ...]`.
    #[serde(deserialize_with = "deserialize_scalar_or_vec_f32")]
    scale: Vec<f32>,

    /// `None` means symmetric (zero-point is 0). `Some(vec)` must have the
    /// same length as `scale`.
    #[serde(
        default,
        deserialize_with = "deserialize_opt_scalar_or_vec_i32",
        skip_serializing_if = "Option::is_none"
    )]
    zero_point: Option<Vec<i32>>,

    /// Channel axis for per-channel quantization. `Some(_)` iff
    /// `scale.len() > 1`. Validated against the parent tensor's shape at
    /// `set_quantization()` time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    axis: Option<usize>,
}

/// Semantic mode discriminant for hot-path kernel dispatch.
///
/// Obtain via [`Quantization::mode`] once at kernel entry; never inside a
/// pixel-level loop. The enum is borrow-based so the hot kernel receives
/// the scales / zero-points as slices without reallocation.
#[derive(Debug, Clone, Copy)]
pub enum QuantMode<'a> {
    PerTensorSymmetric {
        scale: f32,
    },
    PerTensor {
        scale: f32,
        zero_point: i32,
    },
    PerChannelSymmetric {
        scales: &'a [f32],
        axis: usize,
    },
    PerChannel {
        scales: &'a [f32],
        zero_points: &'a [i32],
        axis: usize,
    },
}

impl Quantization {
    /// Per-tensor symmetric (zero_point = 0).
    pub fn per_tensor_symmetric(scale: f32) -> Self {
        Self {
            scale: vec![scale],
            zero_point: None,
            axis: None,
        }
    }

    /// Per-tensor asymmetric — the most common runtime shape.
    pub fn per_tensor(scale: f32, zero_point: i32) -> Self {
        Self {
            scale: vec![scale],
            zero_point: Some(vec![zero_point]),
            axis: None,
        }
    }

    /// Per-channel symmetric. Errors on empty `scales`.
    pub fn per_channel_symmetric(scales: Vec<f32>, axis: usize) -> Result<Self> {
        if scales.is_empty() {
            return Err(Error::QuantizationInvalid {
                field: "scale.len",
                expected: "non-empty per-channel scales".to_string(),
                got: "length 0".to_string(),
            });
        }
        Ok(Self {
            scale: scales,
            zero_point: None,
            axis: Some(axis),
        })
    }

    /// Per-channel asymmetric. Errors on length mismatch between `scales`
    /// and `zero_points`, or empty arrays.
    pub fn per_channel(scales: Vec<f32>, zero_points: Vec<i32>, axis: usize) -> Result<Self> {
        if scales.is_empty() {
            return Err(Error::QuantizationInvalid {
                field: "scale.len",
                expected: "non-empty per-channel scales".to_string(),
                got: "length 0".to_string(),
            });
        }
        if scales.len() != zero_points.len() {
            return Err(Error::QuantizationInvalid {
                field: "zero_point.len",
                expected: format!("length matches scale ({})", scales.len()),
                got: format!("length {}", zero_points.len()),
            });
        }
        Ok(Self {
            scale: scales,
            zero_point: Some(zero_points),
            axis: Some(axis),
        })
    }

    /// Borrow-based dispatch view. Match once at kernel entry.
    pub fn mode(&self) -> QuantMode<'_> {
        match (self.scale.len(), self.zero_point.as_deref(), self.axis) {
            (1, None, _) => QuantMode::PerTensorSymmetric {
                scale: self.scale[0],
            },
            (1, Some(zps), _) => QuantMode::PerTensor {
                scale: self.scale[0],
                zero_point: zps.first().copied().unwrap_or(0),
            },
            (_, None, Some(axis)) => QuantMode::PerChannelSymmetric {
                scales: &self.scale,
                axis,
            },
            (_, Some(zps), Some(axis)) => QuantMode::PerChannel {
                scales: &self.scale,
                zero_points: zps,
                axis,
            },
            // The `validate()` path prevents constructing a
            // per-channel Quantization without an axis, so the remaining
            // pattern is unreachable in practice. Fall back to
            // per-tensor symmetric using scale[0] to avoid panicking in
            // release; debug builds assert.
            _ => {
                debug_assert!(
                    false,
                    "Quantization::mode: per-channel without axis is unreachable"
                );
                QuantMode::PerTensorSymmetric {
                    scale: self.scale.first().copied().unwrap_or(1.0),
                }
            }
        }
    }

    /// Returns `true` for per-tensor quantization (`scale.len() == 1`).
    pub fn is_per_tensor(&self) -> bool {
        self.scale.len() == 1
    }

    /// Returns `true` for per-channel quantization (`scale.len() > 1`).
    pub fn is_per_channel(&self) -> bool {
        self.scale.len() > 1
    }

    /// Returns `true` for symmetric quantization (no zero-point, or
    /// zero-point vector of all zeros).
    pub fn is_symmetric(&self) -> bool {
        match &self.zero_point {
            None => true,
            Some(zps) => zps.iter().all(|&z| z == 0),
        }
    }

    /// Borrow the scale array. Length 1 for per-tensor; `num_channels` for
    /// per-channel.
    pub fn scale(&self) -> &[f32] {
        &self.scale
    }

    /// Borrow the zero-point array. `None` for symmetric.
    pub fn zero_point(&self) -> Option<&[i32]> {
        self.zero_point.as_deref()
    }

    /// Channel axis for per-channel quantization. `None` for per-tensor.
    pub fn axis(&self) -> Option<usize> {
        self.axis
    }

    /// Validate against a target tensor shape. Runs in
    /// `Tensor::set_quantization()`. Catches:
    ///   - empty `scale` (reject — must declare at least one factor)
    ///   - `zero_point` length inconsistent with `scale` (reject —
    ///     per-tensor must have len 1, per-channel must match `scale.len`)
    ///   - `axis >= shape.len()` (axis out of range)
    ///   - `scale.len() != shape[axis]` for per-channel
    ///   - per-channel without axis (reject)
    ///   - per-tensor with redundant axis (reject)
    ///
    /// `static`-only: `Tensor::set_quantization` is `impl<T> Tensor<T>`,
    /// itself `#[cfg(feature = "static")]`. `dynamic`'s
    /// `TensorDyn::set_quantization` (`dynamic_backend.rs`) sends the raw
    /// scale/zero-point/axis over FFI and lets `libedgefirst_tensor.so`
    /// validate them on its own (`static`) side instead of calling this
    /// method locally.
    #[cfg(feature = "static")]
    pub(crate) fn validate(&self, shape: &[usize]) -> Result<()> {
        // `Quantization` is `Deserialize`, so malformed JSON like
        // `{"scale": [], "zero_point": []}` could otherwise produce an
        // ill-defined value that confuses `mode()` selection and the
        // per-channel kernels' indexing.
        if self.scale.is_empty() {
            return Err(Error::QuantizationInvalid {
                field: "scale.len",
                expected: ">= 1".to_string(),
                got: "0".to_string(),
            });
        }
        if let Some(zps) = self.zero_point.as_ref() {
            // Per-tensor: scale.len() == 1 and zero_point.len() must == 1.
            // Per-channel: zero_point.len() must == scale.len().
            let expected = if self.scale.len() == 1 {
                1
            } else {
                self.scale.len()
            };
            if zps.len() != expected {
                return Err(Error::QuantizationInvalid {
                    field: "zero_point.len",
                    expected: format!(
                        "{expected} (matching {})",
                        if self.scale.len() == 1 {
                            "per-tensor scale"
                        } else {
                            "per-channel scale.len"
                        }
                    ),
                    got: format!("length {}", zps.len()),
                });
            }
        }

        match (self.scale.len(), self.axis) {
            (1, None) => Ok(()),
            (1, Some(_)) => Err(Error::QuantizationInvalid {
                field: "per_tensor_redundant_axis",
                expected: "axis=None for per-tensor quantization".to_string(),
                got: format!("axis={:?}", self.axis),
            }),
            (_, None) => Err(Error::QuantizationInvalid {
                field: "per_channel_requires_axis",
                expected: format!(
                    "axis=Some(_) for per-channel quantization (scale.len={})",
                    self.scale.len()
                ),
                got: "axis=None".to_string(),
            }),
            (n, Some(axis)) => {
                if axis >= shape.len() {
                    return Err(Error::QuantizationInvalid {
                        field: "axis",
                        expected: format!("axis < tensor rank ({})", shape.len()),
                        got: format!("axis={axis}"),
                    });
                }
                if shape[axis] != n {
                    return Err(Error::QuantizationInvalid {
                        field: "scale.len",
                        expected: format!("length matches shape[{axis}] ({})", shape[axis]),
                        got: format!("length {n}"),
                    });
                }
                Ok(())
            }
        }
    }
}

impl From<(f32, i32)> for Quantization {
    /// Convenience construction from a `(scale, zero_point)` tuple. Matches
    /// the legacy `QuantTuple` / `Quantization::new` calling convention so
    /// existing `(0.1, -128).into()` sites keep working.
    fn from((scale, zero_point): (f32, i32)) -> Self {
        Self::per_tensor(scale, zero_point)
    }
}

fn deserialize_scalar_or_vec_f32<'de, D: serde::Deserializer<'de>>(
    de: D,
) -> std::result::Result<Vec<f32>, D::Error> {
    use serde::de::{self, Visitor};
    struct V;
    impl<'de> Visitor<'de> for V {
        type Value = Vec<f32>;
        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
            f.write_str("f32 or array of f32")
        }
        fn visit_f64<E: de::Error>(self, v: f64) -> std::result::Result<Self::Value, E> {
            Ok(vec![v as f32])
        }
        #[allow(clippy::cast_possible_truncation)]
        fn visit_i64<E: de::Error>(self, v: i64) -> std::result::Result<Self::Value, E> {
            Ok(vec![v as f32])
        }
        #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
        fn visit_u64<E: de::Error>(self, v: u64) -> std::result::Result<Self::Value, E> {
            Ok(vec![v as f32])
        }
        fn visit_seq<A: de::SeqAccess<'de>>(
            self,
            mut seq: A,
        ) -> std::result::Result<Self::Value, A::Error> {
            let mut out = Vec::with_capacity(seq.size_hint().unwrap_or(1));
            while let Some(x) = seq.next_element::<f32>()? {
                out.push(x);
            }
            Ok(out)
        }
    }
    de.deserialize_any(V)
}

fn deserialize_opt_scalar_or_vec_i32<'de, D: serde::Deserializer<'de>>(
    de: D,
) -> std::result::Result<Option<Vec<i32>>, D::Error> {
    use serde::de::{self, Visitor};
    struct V;
    impl<'de> Visitor<'de> for V {
        type Value = Option<Vec<i32>>;
        fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
            f.write_str("null, i32, or array of i32")
        }
        fn visit_none<E: de::Error>(self) -> std::result::Result<Self::Value, E> {
            Ok(None)
        }
        fn visit_unit<E: de::Error>(self) -> std::result::Result<Self::Value, E> {
            Ok(None)
        }
        fn visit_some<D2: serde::Deserializer<'de>>(
            self,
            de: D2,
        ) -> std::result::Result<Self::Value, D2::Error> {
            struct Inner;
            impl<'de> Visitor<'de> for Inner {
                type Value = Vec<i32>;
                fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                    f.write_str("i32 or array of i32")
                }
                #[allow(clippy::cast_possible_truncation)]
                fn visit_i64<E: de::Error>(self, v: i64) -> std::result::Result<Self::Value, E> {
                    Ok(vec![v as i32])
                }
                #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
                fn visit_u64<E: de::Error>(self, v: u64) -> std::result::Result<Self::Value, E> {
                    Ok(vec![v as i32])
                }
                fn visit_seq<A: de::SeqAccess<'de>>(
                    self,
                    mut seq: A,
                ) -> std::result::Result<Self::Value, A::Error> {
                    let mut out = Vec::with_capacity(seq.size_hint().unwrap_or(1));
                    while let Some(x) = seq.next_element::<i32>()? {
                        out.push(x);
                    }
                    Ok(out)
                }
            }
            de.deserialize_any(Inner).map(Some)
        }
        #[allow(clippy::cast_possible_truncation)]
        fn visit_i64<E: de::Error>(self, v: i64) -> std::result::Result<Self::Value, E> {
            Ok(Some(vec![v as i32]))
        }
        #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
        fn visit_u64<E: de::Error>(self, v: u64) -> std::result::Result<Self::Value, E> {
            Ok(Some(vec![v as i32]))
        }
        fn visit_seq<A: de::SeqAccess<'de>>(
            self,
            mut seq: A,
        ) -> std::result::Result<Self::Value, A::Error> {
            let mut out = Vec::with_capacity(seq.size_hint().unwrap_or(1));
            while let Some(x) = seq.next_element::<i32>()? {
                out.push(x);
            }
            Ok(Some(out))
        }
    }
    de.deserialize_option(V)
}

/// Count of tensor maps requested beyond the buffer's declared
/// [`CpuAccess`] (including any CPU map of a `CpuAccess::None` buffer).
/// Undeclared CPU access is a pipeline smell: it forfeits layout
/// optimizations (write-combined mappings, tile compression) and may be
/// slow or refused on Android. Read via [`unplanned_cpu_access_count`];
/// each offending buffer also logs one warning.
static UNPLANNED_CPU_ACCESS: AtomicU64 = AtomicU64::new(0);

/// Number of tensor maps that exceeded the buffer's declared
/// [`CpuAccess`] since process start. A pipeline that declares its CPU
/// access correctly holds this flat; see [`CpuAccess`] for the contract.
pub fn unplanned_cpu_access_count() -> u64 {
    UNPLANNED_CPU_ACCESS.load(Ordering::Relaxed)
}

/// Record an unplanned CPU access on `identity_id`, warning once per
/// buffer (a steady-state pipeline maps the same buffer every frame — a
/// per-map warn would flood the log; repeats count silently).
///
/// `static`-only: the sole caller is `impl<T> TensorMapTrait<T> for
/// Tensor<T>` in `lib.rs`, itself `#[cfg(feature = "static")]`.
/// [`unplanned_cpu_access_count`] stays available under `dynamic` too --
/// it just always reads 0 there, honestly reflecting that this backend
/// produces no such telemetry.
#[cfg(feature = "static")]
pub(crate) fn note_unplanned_cpu_access(identity_id: u64, backend: &str, detail: &str) {
    UNPLANNED_CPU_ACCESS.fetch_add(1, Ordering::Relaxed);
    static WARNED: std::sync::OnceLock<std::sync::Mutex<std::collections::HashSet<u64>>> =
        std::sync::OnceLock::new();
    let warned = WARNED.get_or_init(Default::default);
    if warned.lock().is_ok_and(|mut s| s.insert(identity_id)) {
        log::warn!(
            "unplanned CPU access on {backend} buffer (identity {identity_id}): {detail} — \
             declare the intent at allocation (CpuAccess::Read/Write/ReadWrite) to make \
             this a planned, optimized mapping"
        );
    }
}

/// Uniform guard for mutable access through a read-only map. Every
/// `TensorMap` backend calls this from `as_mut_slice`/`deref_mut` so a
/// `map_read()` misuse fails identically on all platforms instead of
/// passing on tolerant ones and exploding only on Android.
#[inline]
pub(crate) fn assert_map_writable(writable: bool, backend: &str) {
    assert!(
        writable,
        "{backend} map is read-only (obtained via map_read()/CpuAccess::Read) — \
         use map_mut() or map_write() for mutable access"
    );
}

/// Declared CPU involvement for an image tensor, chosen at allocation.
///
/// The HAL assumes buffers are produced and consumed by hardware (ISP,
/// codec, GPU, NPU) — hardware access needs no declaration. CPU access is
/// the opt-in: it selects the CPU usage/mapping mode at allocation
/// (write-combined for `Write`, cached for `Read`) and, on Android, pins
/// the layout linear (vendor tile compression requires `None`).
///
/// Mapping beyond the declared access is best-effort, never silent: it
/// may be refused ([`Error::NotImplemented`]) or take a slow path, and it
/// always increments [`unplanned_cpu_access_count`] with a once-per-buffer
/// warning.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CpuAccess {
    /// Hardware-only buffer (the default): no CPU mapping declared.
    /// Compression-eligible on platforms with vendor tile layouts.
    #[default]
    None,
    /// CPU reads (verification, CPU consumers) — cached mapping.
    Read,
    /// CPU writes (decode targets) — write-combined mapping where the
    /// platform supports it; reading through a `Write` map is undeclared.
    Write,
    /// CPU reads and writes — the pre-CpuAccess implicit behavior.
    ReadWrite,
}

impl CpuAccess {
    /// Whether this declaration includes CPU reads.
    pub fn reads(self) -> bool {
        matches!(self, CpuAccess::Read | CpuAccess::ReadWrite)
    }

    /// Whether this declaration includes CPU writes.
    pub fn writes(self) -> bool {
        matches!(self, CpuAccess::Write | CpuAccess::ReadWrite)
    }

    /// Whether this declaration covers `requested` (every direction the
    /// request needs is declared).
    pub fn covers(self, requested: CpuAccess) -> bool {
        (!requested.reads() || self.reads()) && (!requested.writes() || self.writes())
    }
}

/// Requested tile-compression behavior for an image allocation (set via
/// [`ImageDesc::with_compression`]).
///
/// Vendor GPUs store textures in proprietary compressed tile layouts
/// (UBWC, AFBC, PVRIC, DCC) that cut memory bandwidth; eligibility
/// requires a hardware-only buffer ([`CpuAccess::None`]) because CPU
/// mapping pins the layout linear. The request records best knowledge on
/// the tensor ([`Tensor::compression`]); it never changes what bytes a
/// consumer sees through the GPU/NPU.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Compression {
    /// Let the platform use its native scheme when the format is
    /// eligible; otherwise allocate linear and count the fallback
    /// ([`compression_fallback_count`]). The right default for pipelines
    /// that want the bandwidth win without portability failures.
    Any,
    /// Require one specific scheme: allocation fails with
    /// [`Error::InvalidArgument`] when the device's scheme differs and
    /// [`Error::NotImplemented`] on platforms without vendor tile
    /// compression. For consumers whose ABI names a layout (e.g. a
    /// QNN context binary declaring UBWC inputs).
    Scheme(CompressionScheme),
}

// Declared through `ef_vocabulary!` (see `vocabulary.rs`). This vocabulary
// gained a wire numbering when `ef_tensor_compression` was added: the
// dynamic backend reads a scheme back across the C boundary, so the enum
// needs codes that cannot drift from the C enumerators. Hand-writing that
// mapping in `edgefirst-tensor-capi` was the alternative and it is strictly
// worse -- `#[non_exhaustive]` makes a cross-crate `match` require a
// wildcard arm, so a scheme added here would silently map to "linear"
// there. Generated from one declaration, it cannot.
//
// Code 0 is deliberately unassigned and reserved for "linear" -- the state
// this crate spells `Option::None`, which has no variant to carry a code of
// its own. The C side names it `EF_COMPRESSION_NONE`.
crate::ef_vocabulary! {
    /// Vendor tile-compression schemes the HAL recognizes and records.
    ///
    /// Unrecognized platforms record `None` (linear) — there is deliberately
    /// no `Unknown` variant; a scheme is only recorded when the vendor is
    /// positively identified.
    #[non_exhaustive]
    pub enum CompressionScheme {
        /// Qualcomm Adreno Universal Bandwidth Compression.
        Ubwc = 1, "ubwc", UBWC,
        /// Arm Mali/Immortalis Framebuffer Compression.
        Afbc = 2, "afbc", AFBC,
        /// Imagination PowerVR Image Compression (Google Tensor G5+).
        Pvric = 3, "pvric", PVRIC,
        /// Samsung Xclipse (AMD RDNA) Delta Color Compression.
        Dcc = 4, "dcc", DCC,
    }
    // `#[doc(hidden)]` for the same reason `dtype_wire` is: emission
    // plumbing for `const`-only consumers, not a second documented API.
    #[doc(hidden)]
    pub mod compression_wire;
}

/// Count of image allocations that requested [`Compression::Any`] but
/// resolved to a linear layout (ineligible format/dtype, unrecognized
/// vendor, or a platform without vendor tile compression). Read via
/// [`compression_fallback_count`].
static COMPRESSION_FALLBACKS: AtomicU64 = AtomicU64::new(0);

/// Number of [`Compression::Any`] requests since process start that
/// resolved to a linear layout instead of a vendor tile scheme. A
/// steady-state pipeline holds this flat after warmup; growth means an
/// allocation path keeps requesting compression it never gets.
pub fn compression_fallback_count() -> u64 {
    COMPRESSION_FALLBACKS.load(Ordering::Relaxed)
}

/// Record a `Compression::Any` request resolving linear.
///
/// `static`-only: the sole caller is `Tensor::image_desc` (`impl<T>
/// Tensor<T>`), itself `#[cfg(feature = "static")]`.
/// [`compression_fallback_count`] stays available under `dynamic` too --
/// it just always reads 0 there.
#[cfg(feature = "static")]
pub(crate) fn note_compression_fallback(detail: &str) {
    COMPRESSION_FALLBACKS.fetch_add(1, Ordering::Relaxed);
    log::debug!("compression request fell back to linear: {detail}");
}

/// Whether this platform can allocate `(format, dtype)` images in a
/// vendor tile-compressed layout. `true` requires an Android build, an
/// eligible format (RGBA8888 `u8`/`i8` initially), and a positively
/// identified GPU vendor; everywhere else the answer is `false` and
/// [`Compression::Any`] requests fall back to linear.
pub fn compression_support(format: PixelFormat, dtype: DType) -> bool {
    #[cfg(target_os = "android")]
    {
        crate::ahardwarebuffer_layout::compression_eligible(format, dtype)
            && crate::ahardwarebuffer::device_compression_scheme().is_some()
    }
    #[cfg(not(target_os = "android"))]
    {
        let _ = (format, dtype);
        false
    }
}

/// Declarative image-allocation request — the full-featured front door
/// for image tensors ([`TensorDyn::image_desc`] and the image crate's
/// `ImageProcessor::create_image_desc`).
///
/// The classic constructors (`image`, `create_image`) cover the common
/// cases; the desc carries the optional requests — today the
/// [`Compression`] request — without another constructor-parameter
/// sweep. Fields are private and the builders consume/return by value,
/// so future options are non-breaking.
///
/// ```
/// use edgefirst_tensor::{Compression, CpuAccess, DType, ImageDesc, PixelFormat};
/// let desc = ImageDesc::new(640, 640, PixelFormat::Rgba, DType::U8)
///     .with_access(CpuAccess::None)
///     .with_compression(Compression::Any);
/// ```
#[derive(Debug, Clone)]
pub struct ImageDesc {
    width: usize,
    height: usize,
    format: PixelFormat,
    dtype: DType,
    memory: Option<TensorMemory>,
    access: CpuAccess,
    compression: Option<Compression>,
}

impl ImageDesc {
    /// A new image request: auto-selected memory, [`CpuAccess::None`]
    /// (hardware-only), no compression request.
    pub fn new(width: usize, height: usize, format: PixelFormat, dtype: DType) -> Self {
        Self {
            width,
            height,
            format,
            dtype,
            memory: None,
            access: CpuAccess::None,
            compression: None,
        }
    }

    /// Request a specific memory backing (`None` = auto-select).
    pub fn with_memory(mut self, memory: Option<TensorMemory>) -> Self {
        self.memory = memory;
        self
    }

    /// Declare the CPU access (see [`CpuAccess`]). Any declaration other
    /// than `None` makes a compression request invalid.
    pub fn with_access(mut self, access: CpuAccess) -> Self {
        self.access = access;
        self
    }

    /// Request a tile-compressed layout (see [`Compression`]).
    pub fn with_compression(mut self, compression: Compression) -> Self {
        self.compression = Some(compression);
        self
    }

    /// Requested width in pixels.
    pub fn width(&self) -> usize {
        self.width
    }

    /// Requested height in pixels.
    pub fn height(&self) -> usize {
        self.height
    }

    /// Requested pixel format.
    pub fn format(&self) -> PixelFormat {
        self.format
    }

    /// Requested element type.
    pub fn dtype(&self) -> DType {
        self.dtype
    }

    /// Requested memory backing (`None` = auto-select).
    pub fn memory(&self) -> Option<TensorMemory> {
        self.memory
    }

    /// Declared CPU access.
    pub fn access(&self) -> CpuAccess {
        self.access
    }

    /// The compression request, if any.
    pub fn compression(&self) -> Option<Compression> {
        self.compression
    }
}

/// What kind of system key an identity was derived from. Participates in the
/// id so that, say, inode 7 and IOSurfaceID 7 cannot collide.
///
/// Invariant every variant must uphold: the key passed to
/// [`BufferIdentity::derived`] is unique among live buffers of that kind
/// **that own an allocation**. There is no "no identity" case — where no
/// system-wide key exists a process-local one does (a pointer, a GL name),
/// and a process-local key is exactly as sound as a system-wide one:
/// pointer/name reuse after free is the same ABA hazard as inode reuse, and
/// is mitigated the same way, by the retaining cache (see the design spec's
/// Task 6).
///
/// The allocation qualifier is load-bearing, not a hedge. A zero-element
/// tensor (`[0, num_protos]`, the tracker's "no detections this frame"
/// sentinel — see [`crate::mem`]) owns no allocation, so its `Vec` yields the
/// dangling well-aligned pointer `align_of::<T>()`. Every zero-element
/// `Tensor<f32>` in a process therefore shares one identity, and can even
/// collide across kinds with a small integer key from another variant.
///
/// That is safe rather than tolerated: an identity exists to answer "are
/// these the same bytes?", and buffers with no bytes have nothing to alias.
/// Nor can they reach an import cache. There are four GPU import paths —
/// a dma-buf fd on Linux, an IOSurface ref on macOS, an `AHardwareBuffer` on
/// Android, and an `ID3D11Texture2D` on Windows — and each takes only its own
/// object, so a tensor with no allocation reaches none of them. The Windows
/// path additionally keys on the texture the import itself holds a reference
/// to, and `edgefirst-image` **refuses** any texture whose identity is not
/// `D3d11Texture` over that same pointer — in every build, and on every
/// import including one served from its cache
/// (`GlPlatform::validate_import_identity`). That refusal exists because the
/// rule was once only written
/// down: the dynamic backend handed the image crate `HostPtr` identities over
/// recyclable handle addresses, and converts silently rendered into dropped
/// textures. Do not "fix" the zero-element case by minting a distinct id per
/// empty tensor: that reintroduces a counter, which is the state this whole
/// design exists to remove.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IdentityKind {
    /// `(st_dev, st_ino)` of a dma-buf or memfd. Survives `dup`, and is the
    /// same value in every process that holds the buffer.
    DmaBuf,
    Shm,
    /// `IOSurfaceGetID`.
    IoSurface,
    /// `AHardwareBuffer_getId`, API 31+.
    AHardwareBufferId,
    /// The `AHardwareBuffer*` pointer, pre-API-31 where no id exists.
    /// Process-local: unique among live buffers here, meaningless elsewhere.
    AHardwareBufferPtr,
    /// An `ID3D11Texture2D*`. Process-local, like `AHardwareBufferPtr`, and
    /// the same pointer for every kind of texture tensor: one the HAL
    /// allocated, one wrapped from a caller's pointer, and one opened from a
    /// shared NT handle all key on the texture object they hold.
    ///
    /// **Both backends derive it from the same pointer, so their ids are
    /// equal byte for byte.** The static backend reads the `ComPtr` it owns
    /// (`d3d11::texture::tex_key`); the dynamic backend reads the same
    /// pointer back across the ABI with `ef_tensor_d3d11_texture`
    /// (`TensorDyn::derive_identity`). That equality is the point, not a
    /// coincidence: [`BufferIdentity::derived`] exists so two independently
    /// linked copies of this crate name one buffer identically, and
    /// `edgefirst-image` links the dynamic backend inside every `-capi` leaf
    /// while its own tests link the static one.
    ///
    /// **An `ef_tensor` handle's address must never be the key.** It is not a
    /// buffer at all, nothing the cache holds keeps it alive, and this
    /// library's allocator hands a freed handle's address to the very next
    /// one it mints — measured at 400 texture handles over 4 distinct
    /// addresses. The dynamic backend did exactly that on Windows until
    /// 2026-09-04, and a convert whose destination key collided rendered into
    /// the dropped texture while returning success.
    ///
    /// A handle import therefore does **not** compare equal to the tensor it
    /// was exported from, nor to a second import of the same handle:
    /// `OpenSharedResource1` mints a fresh `ID3D11Texture2D` per open. Keying
    /// on a handle value would make those compare equal, and would be unsound:
    /// Windows recycles a closed handle value straight into the next
    /// `DuplicateHandle`, so a consumer that caches on this id past the
    /// producing tensor's lifetime -- as the image crate's EGLImage cache
    /// does -- could serve one texture's entry for a later, unrelated import.
    /// A COM object's address cannot be recycled that way: a cache that holds
    /// a reference to the texture keeps the address taken for as long as its
    /// entry can be found. The cost is a cache miss per re-import instead of
    /// a wrong image.
    D3d11Texture,
    /// A host mapping address. Process-local.
    HostPtr,
    /// A GL buffer name. Valid only in the context that created it.
    Pbo,
}

/// Unique identity for a tensor's underlying buffer.
///
/// Created fresh on every buffer allocation or import. The `id` is a cache
/// key, `kind` records what system key (if any) it was derived from, and the
/// `guard` is an `Arc<()>` whose weak references allow downstream caches to
/// detect when the buffer has been dropped.
#[derive(Debug, Clone)]
pub struct BufferIdentity {
    id: u64,
    kind: IdentityKind,
    guard: Arc<()>,
}

impl BufferIdentity {
    /// Derive an identity from a key the operating system already guarantees.
    ///
    /// Deliberately NOT a counter: two independently-linked copies of this
    /// crate must derive the same id for the same buffer, or a consumer's
    /// import cache misses every frame. See the design spec, "The core finding".
    pub fn derived(kind: IdentityKind, key: u64) -> Self {
        // Mix the discriminant into the high bits so different kinds with the
        // same numeric key never collide.
        let id = ((kind as u64) << 56) ^ key;
        Self {
            id,
            kind,
            guard: Arc::new(()),
        }
    }

    /// Unique identifier for this buffer. Changes when the buffer changes.
    pub fn id(&self) -> u64 {
        self.id
    }

    /// What kind of system key this identity was derived from.
    pub fn kind(&self) -> IdentityKind {
        self.kind
    }

    /// Returns a weak reference to the buffer guard. Goes dead when the
    /// owning Tensor is dropped (and no clones remain).
    pub fn weak(&self) -> Weak<()> {
        Arc::downgrade(&self.guard)
    }
}

// `static`-only from here through `fs_magic` below: every use site lives in
// `impl<T> TensorStorage<T>` (`from_fd`'s DMA-BUF-vs-tmpfs classification),
// itself `#[cfg(feature = "static")]`. `dynamic`'s `from_fd`
// (`dynamic_backend.rs`) drives `ef_tensor_builder_wrap` instead, which
// does this same classification inside `libedgefirst_tensor.so`.
#[cfg(all(target_os = "linux", feature = "static"))]
use nix::sys::stat::{major, minor};

/// Filesystem magic of the internal `dma_buf` mount, from
/// `include/uapi/linux/magic.h` (`DMA_BUF_MAGIC`, "DMAB").
///
/// This is stable UAPI and is the only reliable way to recognize a DMA-BUF
/// fd — see [`TensorStorage::from_fd`] for why `st_dev` cannot be used.
#[cfg(all(target_os = "linux", feature = "static"))]
const DMA_BUF_MAGIC: u32 = 0x444d_4142;

/// Filesystem magic of tmpfs, from `include/uapi/linux/magic.h`
/// (`TMPFS_MAGIC`). Covers both POSIX `shm_open` segments under `/dev/shm`
/// and anonymous `memfd_create` files.
#[cfg(all(target_os = "linux", feature = "static"))]
const TMPFS_MAGIC: u32 = 0x0102_1994;

/// Normalize a raw `fstatfs` `f_type` to the 32-bit unsigned magic that
/// `include/uapi/linux/magic.h` documents.
///
/// The width and signedness of `f_type` are target-dependent: `__fsword_t`
/// on Linux/gnu (`i64` on 64-bit, `i32` on 32-bit targets such as armv7,
/// i686 and aarch64-ilp32), `c_int` on uclibc, `c_ulong` on musl, and
/// `c_uint` on s390x. Where it is signed and 32 bits wide, widening it
/// sign-extends every magic with bit 31 set — hugetlbfs (`0x958458f6`),
/// btrfs (`0x9123683e`), f2fs (`0xf2f52010`) — which would make the value
/// reported by [`Error::UnknownBufferType`] impossible to find in the
/// header the docs point callers at.
///
/// Every magic is a 32-bit quantity, so truncating back to `u32` recovers
/// the true value from all four representations and loses nothing.
#[cfg(all(target_os = "linux", feature = "static"))]
const fn fs_magic(raw: i64) -> u32 {
    raw as u32
}

/// The operations every memory backend implements.
///
/// This is the seam that lets [`Tensor<T>`] hide which backend is in play.
/// The implementors are `DmaTensor` (Linux DMA-BUF), `IoSurfaceTensor`
/// (macOS/iOS), `AHardwareBufferTensor` (Android), `ShmTensor`, `MemTensor`,
/// and [`PboTensor`]; `TensorStorage<T>` dispatches to whichever is active.
/// Backend types are not public — allocate a [`Tensor<T>`] or [`TensorDyn`]
/// and call these methods through it.
///
/// Import the trait to get `shape`, `size`, `map`, `clone_fd`,
/// `buffer_identity`, and the zero-copy sub-region `view` on a tensor value.
/// `Tensor::view` and `Tensor::batch` route through [`TensorTrait::view`], so
/// each backend's identity-sharing rule lives in exactly one place.
///
/// [`TensorDyn`]: crate::TensorDyn
pub trait TensorTrait<T>: Send + Sync
where
    T: Num + Clone + fmt::Debug,
{
    /// Create a new tensor with the given shape and optional name. If no name
    /// is given, a random name will be generated.
    fn new(shape: &[usize], name: Option<&str>) -> Result<Self>
    where
        Self: Sized;

    #[cfg(unix)]
    /// Import an existing buffer as a tensor, taking ownership of its file
    /// descriptor. The buffer is adopted in place — no bytes are copied.
    ///
    /// The backend is **detected**, not chosen: the fd already belongs to a
    /// buffer type, and this call's job is to recognize which. On Linux that
    /// is decided by the fd's filesystem magic, which is stable UAPI
    /// (`include/uapi/linux/magic.h`):
    ///
    /// | Filesystem | Magic | Resulting [`TensorMemory`] |
    /// |------------|-------|----------------------------|
    /// | `dma_buf` | `DMA_BUF_MAGIC` (`0x444d4142`) | [`TensorMemory::DmaBuf`] |
    /// | `tmpfs` (`/dev/shm` **and** `memfd`) | `TMPFS_MAGIC` (`0x01021994`) | [`TensorMemory::Shm`] |
    /// | anything else | — | *rejected* — see Errors |
    ///
    /// Both supported types are identified **positively**. An unrecognized
    /// filesystem is an error, never a fallback to shared memory: the wrong
    /// branch does not fail loudly (a DMA-BUF is mmap-able, so it would
    /// import as a perfectly functional tensor that merely isn't DMA, and a
    /// pipe would import as a zero-length one), so guessing would trade a
    /// clear error here for silent loss of zero-copy far downstream.
    ///
    /// The device number is deliberately **not** consulted. `dma_buf` files
    /// live on an internal kernel mount whose `st_dev` comes from
    /// `get_anon_bdev()` — an IDA shared with every other anonymous
    /// pseudo-filesystem and allocated in boot order — so the minor a
    /// DMA-BUF lands on varies by kernel build and is not part of any ABI.
    ///
    /// On non-Linux Unix (macOS/iOS/Android) there is no fd-based DMA import;
    /// the fd is always adopted as [`TensorMemory::Shm`].
    ///
    /// # Arguments
    ///
    /// * `fd` - Owned descriptor for the buffer to import. Ownership
    ///   transfers to the returned tensor and the fd is closed on drop; pass
    ///   [`clone_fd`](TensorTrait::clone_fd) output to keep your own handle.
    /// * `shape` - Logical shape to interpret the buffer with. Must describe
    ///   no more elements than the buffer holds.
    /// * `name` - Optional name; a random one is generated when `None`.
    ///
    /// # Returns
    ///
    /// A tensor sharing the imported buffer's memory, whose
    /// [`memory()`](TensorTrait::memory) reports the detected backend.
    ///
    /// # Errors
    ///
    /// * [`Error::UnknownBufferType`] - the fd is on a filesystem that is
    ///   neither `dma_buf` nor `tmpfs`, so its buffer type cannot be
    ///   determined. Carries the observed `fstatfs` magic as a `u32`,
    ///   normalized so it can be looked up in `magic.h` directly on both
    ///   32- and 64-bit targets. Typical causes: a regular file, a pipe or
    ///   socket, or a `MFD_HUGETLB` memfd (hugetlbfs, not tmpfs). Linux only.
    /// * [`Error::UnknownDeviceType`] - the fd's `st_dev` major is non-zero,
    ///   i.e. it lives on a real block device rather than an anonymous or
    ///   in-memory filesystem. Linux only.
    /// * [`Error::InvalidSize`] - `shape` is empty or describes zero
    ///   elements.
    /// * [`Error::NixError`] - `fstat`, `fstatfs`, or `mmap` failed on the
    ///   descriptor.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use edgefirst_tensor::{Tensor, TensorMemory, TensorTrait};
    ///
    /// # fn main() -> edgefirst_tensor::Result<()> {
    /// let src = Tensor::<u8>::new(&[480, 640, 3], Some(TensorMemory::DmaBuf), None)?;
    ///
    /// // Round-tripping a DMA-BUF fd preserves the backend — the import is
    /// // still zero-copy, and still eligible for GPU/NPU paths.
    /// let imported = Tensor::<u8>::from_fd(src.clone_fd()?, src.shape(), None)?;
    /// assert_eq!(imported.memory(), TensorMemory::DmaBuf);
    /// # Ok(())
    /// # }
    /// ```
    fn from_fd(fd: std::os::fd::OwnedFd, shape: &[usize], name: Option<&str>) -> Result<Self>
    where
        Self: Sized;

    #[cfg(unix)]
    /// Clone the file descriptor associated with this tensor.
    fn clone_fd(&self) -> Result<std::os::fd::OwnedFd>;

    /// Get the memory type of this tensor.
    fn memory(&self) -> TensorMemory;

    /// Get the name of this tensor.
    fn name(&self) -> String;

    /// Get the number of elements in this tensor.
    fn len(&self) -> usize {
        self.shape().iter().product()
    }

    /// Check if the tensor is empty.
    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Get the size in bytes of this tensor.
    fn size(&self) -> usize {
        self.len() * std::mem::size_of::<T>()
    }

    /// Get the shape of this tensor.
    fn shape(&self) -> &[usize];

    /// Reshape this tensor to the given shape. The total number of elements
    /// must remain the same.
    fn reshape(&mut self, shape: &[usize]) -> Result<()>;

    /// Bytes of the underlying allocation (>= the current logical `size()`).
    /// Defaults to the logical size for storages without spare capacity.
    fn capacity_bytes(&self) -> usize {
        self.size()
    }

    /// Set the logical shape to any shape whose byte size fits the allocation
    /// capacity, without the equal-size constraint of `reshape`.
    fn set_logical_shape(&mut self, shape: &[usize]) -> Result<()> {
        self.reshape(shape)
    }

    /// Map the tensor into memory with the given access direction and
    /// return a TensorMap for accessing the data.
    ///
    /// `access` selects the platform mapping mode (read-only IOSurface
    /// lock, dma-buf sync direction, AHardwareBuffer lock usage) and the
    /// map's mutability: a map obtained with [`CpuAccess::Read`] rejects
    /// `as_mut_slice`. [`CpuAccess::None`] is not a mappable direction
    /// and returns [`Error::InvalidArgument`].
    ///
    /// Prefer the typed wrappers [`map_read`](Self::map_read) /
    /// [`map_write`](Self::map_write) / [`map_mut`](Self::map_mut).
    /// Map for CPU access.
    ///
    /// Like [`pin_host`](Tensor::pin_host), `'a` bounds how long the backing
    /// allocation lives rather than borrowing the tensor: the returned view
    /// shares ownership through the pin's keepalive, so a map can coexist with
    /// a `&mut` on the same tensor.
    ///
    /// # Windows D3D11 textures: no write-only map of a partial window
    ///
    /// A [`CpuAccess::Write`] map is not refreshed from the texture and
    /// publishes the whole texture when it unmaps, so the bytes the caller
    /// leaves untouched are undefined. That is a contract a whole-tensor map
    /// can meet and a sub-view cannot: the window spans its own rows only.
    /// A write-only map of a tensor whose window is shorter than its backing
    /// -- a [`view`](Tensor::view), or a shape narrowed with
    /// `set_logical_shape` -- is therefore refused with
    /// [`Error::InvalidArgument`] naming [`CpuAccess::ReadWrite`], which is
    /// the same window with the refresh that makes the untouched rows
    /// well-defined.
    fn map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a;

    /// Map the tensor read-write (equivalent to
    /// `map_with(CpuAccess::ReadWrite)` — the historical `map()`
    /// behavior).
    fn map<'a>(&self) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_with(CpuAccess::ReadWrite)
    }

    /// Map the tensor for CPU reading only. The returned map rejects
    /// `as_mut_slice`; on macOS this takes the read-only IOSurface lock
    /// (skips the unlock flush), on Linux the dma-buf read-direction
    /// sync.
    fn map_read<'a>(&self) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_with(CpuAccess::Read)
    }

    /// Map the tensor for CPU writing (fill-only: reading through a
    /// write map may see write-combined memory — do not read the slice).
    fn map_write<'a>(&self) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_with(CpuAccess::Write)
    }

    /// Map the tensor read-write (alias of [`map`](Self::map) with the
    /// intent spelled out).
    fn map_mut<'a>(&self) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_with(CpuAccess::ReadWrite)
    }

    /// Non-blocking [`map_with`](Self::map_with): returns
    /// `Err(Error::IoError(WouldBlock))` while a GPU copy the map depends on
    /// is still in flight, and makes progress on a retry.
    ///
    /// Backings with no such copy (host memory, shared memory, dma-buf,
    /// IOSurface, AHardwareBuffer, PBO) alias `map_with`, so a caller can use
    /// this unconditionally and only ever see `WouldBlock` where the wait is
    /// real -- today the Windows D3D11 texture's staging refresh.
    ///
    /// A retry loop must yield or sleep between attempts. On the WARP
    /// software adapter the CPU threads are the GPU, so a tight loop starves
    /// the very copy it is waiting for.
    ///
    /// [`CpuAccess::Write`] is refused on a Windows D3D11 texture tensor whose
    /// window is shorter than its backing, exactly as it is for
    /// [`map_with`](Self::map_with); see that method.
    fn try_map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_with(access)
    }

    /// Non-blocking [`map`](Self::map): read-write, and `WouldBlock` rather
    /// than a stall. See [`try_map_with`](Self::try_map_with).
    fn try_map<'a>(&self) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.try_map_with(CpuAccess::ReadWrite)
    }

    /// Get the buffer identity for cache keying and liveness tracking.
    fn buffer_identity(&self) -> &BufferIdentity;

    /// Create a zero-copy sub-region view of this backing that shares the
    /// underlying allocation **and** [`BufferIdentity`].
    ///
    /// The window is `[offset_bytes, offset_bytes + shape.product() *
    /// size_of::<T>())` measured from this tensor's own logical start, so a
    /// sub-view of a sub-view composes by adding offsets. Sharing the parent's
    /// identity is the contract that lets identity-keyed caches (e.g. the GL
    /// EGLImage import cache) treat offset-distinct windows as one buffer rather
    /// than unrelated allocations — `view` must never mint a fresh identity.
    ///
    /// Defaults to [`Error::NotImplemented`]; every backend that supports
    /// sub-views overrides it (`Mem`, `Shm`, Linux DMA, macOS IOSurface, `Pbo`).
    fn view(&self, offset_bytes: usize, shape: &[usize]) -> Result<Self>
    where
        Self: Sized,
    {
        let _ = (offset_bytes, shape);
        Err(Error::NotImplemented(
            "view (zero-copy sub-region) is not supported for this tensor backend".to_owned(),
        ))
    }
}

pub trait TensorMapTrait<T>
where
    T: Num + Clone + fmt::Debug,
{
    /// Get the shape of this tensor map.
    fn shape(&self) -> &[usize];

    /// Unmap the tensor from memory.
    fn unmap(&mut self);

    /// Get the number of elements in this tensor map.
    fn len(&self) -> usize {
        self.shape().iter().product()
    }

    /// Check if the tensor map is empty.
    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Get the size in bytes of this tensor map.
    fn size(&self) -> usize {
        self.len() * std::mem::size_of::<T>()
    }

    /// Get a slice to the data in this tensor map.
    fn as_slice(&self) -> &[T];

    /// Get a mutable slice to the data in this tensor map.
    fn as_mut_slice(&mut self) -> &mut [T];

    /// Whether this mapping permits writes -- i.e. whether the coherency
    /// bracket it holds will flush on release.
    ///
    /// The single source of truth for a binding that has to advertise
    /// mutability to a foreign consumer (the Python buffer protocol's
    /// `readonly` flag, say). Deriving that from the access a caller
    /// *requested* instead would leave the advertisement agreeing with the
    /// request while both disagreed with the mapping actually taken.
    fn is_writable(&self) -> bool;

    #[cfg(feature = "ndarray")]
    /// Get an ndarray ArrayView of the tensor data.
    fn view(&'_ self) -> Result<ndarray::ArrayView<'_, T, ndarray::Dim<ndarray::IxDynImpl>>> {
        Ok(ndarray::ArrayView::from_shape(
            self.shape(),
            self.as_slice(),
        )?)
    }

    #[cfg(feature = "ndarray")]
    /// Get an ndarray ArrayViewMut of the tensor data.
    fn view_mut(
        &'_ mut self,
    ) -> Result<ndarray::ArrayViewMut<'_, T, ndarray::Dim<ndarray::IxDynImpl>>> {
        let shape = self.shape().to_vec();
        Ok(ndarray::ArrayViewMut::from_shape(
            shape,
            self.as_mut_slice(),
        )?)
    }
}

// Declared through `ef_vocabulary!` (see `vocabulary.rs`). Before this, the
// same four backings were numbered three different ways -- Rust's implicit
// discriminants (`Dma=0, Shm=1, Mem=2, Pbo=3`), the C ABI's
// `hal_tensor_memory` (`MEM=0, DMA=1, SHM=2, PBO=3`), and Python's
// `PyTensorMemory`, which had no explicit discriminants at all and a
// `#[cfg(unix)]` variant in the middle of the list, so its numbering
// depended on the target OS. The canonical assignment below is the one all
// of them converge on; `hal_tensor_memory` is the single explicitly-mapped
// outlier that keeps its own released values (see `to_hal_tensor_memory` in
// the capi crate).
//
// Note this is NOT `protocol::kind`, which is a genuinely different
// vocabulary and stays so: `kind` describes what a `TensorDesc`'s `handle`
// and `ptr` fields MEAN to an importer, and both `Mem` and `Shm` mean the
// same thing there (`kind::HOST`, host-addressable pointer, no handle). A
// vocabulary that collapses two variants into one cannot also be the
// vocabulary that distinguishes them. `kind_of()` in `protocol.rs` is the
// mapping between them.
crate::ef_vocabulary! {
    /// Which memory backend a tensor is (or should be) allocated from.
    ///
    /// Pass `Some(..)` to a constructor to pin the backend, or `None` to
    /// auto-select. Auto-selection differs by constructor: [`Tensor::new`]
    /// tries `DmaBuf` → `Mem`, while the image constructors try `DmaBuf` →
    /// `Mem` and skip `Shm`. `EDGEFIRST_TENSOR_FORCE_MEM=1` short-circuits
    /// either chain to `Mem`, which is how tests run on hosts without
    /// DMA-heap permissions.
    ///
    /// A pinned request has no fallback: if the backend cannot serve it, the
    /// constructor fails rather than quietly giving you something slower.
    /// [`TensorTrait::memory`] reports what a tensor actually ended up with.
    ///
    /// # Every variant exists on every platform
    ///
    /// This is a namespace of codes, not a list of what this build can
    /// allocate -- [`TensorMemory::is_available`] answers the latter, at
    /// runtime. `Shm` used to be `#[cfg(unix)]`, which shifted every
    /// variant declared after it on a non-unix build and made the
    /// numbering a compile-time detail of the host. It also made a
    /// cross-platform recording unreadable: a blob captured on Linux
    /// carries `"dmabuf"`, and a macOS consumer has to be able to NAME
    /// that backing in order to report "cannot materialise here" instead
    /// of failing with an unrecognised code.
    ///
    /// # `#[non_exhaustive]`
    ///
    /// Match this with a wildcard arm. The variant list is expected to
    /// keep growing -- `IoSurface` and `Cuda` were added here, Windows
    /// backings and a real CUDA device backing are named as coming -- and
    /// this attribute is what keeps a closed-source consumer's
    /// `match memory { .. }` compiling across those additions. It protects
    /// DOWNSTREAM, not this crate: inside `edgefirst-tensor` the matches
    /// stay exhaustive and compile-enforced. Same rule as [`DType`],
    /// [`Compression`] and [`PixelFormat`], which `TensorMemory` was the
    /// lone exception to.
    #[non_exhaustive]
    pub enum TensorMemory {
        /// Regular system memory allocation. Available everywhere; the
        /// floor every auto-selection chain ends on.
        Mem = 0, "mem", MEM,
        /// POSIX Shared Memory allocation. Suitable for inter-process
        /// communication, but not for hardware acceleration. Only
        /// allocatable on unix; nameable everywhere.
        Shm = 1, "shm", SHM,
        /// Platform-native zero-copy GPU buffer.
        ///
        /// On Linux this is a DMA-BUF (`DmaTensor` in
        /// `crates/tensor/src/dma.rs`) allocated via the DRM/dma-heap
        /// subsystem. On macOS/iOS it is currently also this variant that
        /// yields an IOSurface, and on Android an AHardwareBuffer: they
        /// share the `TensorStorage::Dma` slot at the trait level, and the
        /// public C API discriminant (`HAL_TENSOR_MEMORY_DMA = 1`) covers
        /// all three with no ABI break. `IoSurface` below is the code for
        /// naming that backing specifically; no backend reports it yet.
        ///
        /// Allows hardware-accelerated paths (OpenGL backend on Linux via
        /// `EGL_EXT_image_dma_buf_import`; macOS via
        /// `EGL_ANGLE_iosurface_client_buffer`). CPU access via `map()`
        /// incurs cache-coherency overhead on Linux DMA-BUF and is similar
        /// in cost on IOSurface; SHM/Mem are cheaper for CPU-only workloads.
        ///
        /// On Windows it is an `ID3D11Texture2D` on the process D3D11 device
        /// (`crates/tensor/src/d3d11/`), allocated only through
        /// [`Tensor::image`](crate::Tensor::image); CPU access goes through a
        /// staging copy. The first such allocation creates the process
        /// device, so a host supplying its own device must call
        /// `d3d11::use_external_device` before it -- and before
        /// [`crate::is_gpu_buffer_available`], which creates the device too.
        DmaBuf = 2, "dmabuf", DMABUF,
        /// Apple IOSurface, named specifically rather than through the
        /// portable `DmaBuf` spelling.
        ///
        /// Defined as a code so a descriptor or recording that names an
        /// IOSurface is parseable on every platform. **No backend produces
        /// or accepts it yet** -- macOS/iOS allocate and report `DmaBuf`.
        /// Pinning a request to it fails with `NotImplemented`.
        IoSurface = 3, "iosurface", IOSURFACE,
        /// OpenGL Pixel Buffer Object memory. Created by `ImageProcessor`
        /// when DMA-buf is unavailable but OpenGL is present -- never by
        /// [`Tensor::new`], which has no GL context to create it in.
        Pbo = 4, "pbo", PBO,
        /// CUDA device memory: a device pointer, not host-addressable.
        ///
        /// Defined as a code for the same reason as `IoSurface`. **No
        /// backend produces or accepts it yet**; pinning a request to it
        /// fails with `NotImplemented`.
        Cuda = 5, "cuda", CUDA,
    }
    // `#[doc(hidden)]`: `pub` so the const-only form is reachable by an FFI
    // or cbindgen consumer, but it is emission plumbing rather than a second
    // documented API -- `TensorMemory::code()` is the documented path, and
    // the two are generated from the same literal.
    #[doc(hidden)]
    pub mod tensor_memory_wire;
}

impl TensorMemory {
    /// Whether this backing can actually be allocated in this process, now.
    ///
    /// A runtime question, not a compile-time one, which is why it is a
    /// method on the vocabulary rather than a `cfg` on the variant:
    /// `DmaBuf` needs `/dev/dma_heap` to exist *and* this process to have
    /// permission on it (a container, a user outside the `video`/`render`
    /// groups, and a stock desktop give three different answers on the same
    /// kernel), and `Shm` needs a writable `/dev/shm`. Each probe allocates
    /// once and caches.
    ///
    /// Reports what can be *allocated*, which is not the same as what can be
    /// *named*: every variant is nameable on every platform (that is the
    /// point of the vocabulary), and the ones this build cannot serve say so
    /// here rather than by being absent from the enum.
    ///
    /// Three variants answer `false` unconditionally today, for reasons
    /// worth stating rather than hiding behind a probe that cannot fail:
    ///
    /// * `IoSurface` -- no backend produces or accepts it yet; macOS/iOS
    ///   serve IOSurface under the `DmaBuf` spelling, so `DmaBuf` is the
    ///   variant that answers `true` there.
    /// * `Pbo` -- PBO tensors are created by `ImageProcessor::create_image`
    ///   with a GL context current, never by [`Tensor::new`]. This crate
    ///   holds no GL context and cannot see one; ask the image crate
    ///   whether a GL backend is live.
    /// * `Cuda` -- there is no CUDA backing in this crate at all. Probing
    ///   for `libcuda` would answer `true` on a Jetson while every
    ///   allocation still failed, which is worse than answering `false`.
    ///
    /// One variant answers `true` for a narrower constructor than the rest:
    /// on Windows `DmaBuf` is an `ID3D11Texture2D`, which is image-formatted,
    /// so `true` there means [`Tensor::image`] can serve it and
    /// [`Tensor::new`] with `Some(DmaBuf)` still answers `NotImplemented`.
    /// [`is_gpu_buffer_available`](crate::is_gpu_buffer_available), which this
    /// forwards to, states the same split.
    pub fn is_available(self) -> bool {
        match self {
            // Always: the fallback every constructor chain ends on. If this
            // could fail, allocation would have no floor left.
            TensorMemory::Mem => true,
            TensorMemory::Shm => is_shm_available(),
            // Today `DmaBuf` is the portable spelling of "platform-native
            // zero-copy GPU buffer", so it is the portable probe that
            // answers for it -- true on macOS/iOS (IOSurface) and Android
            // (AHardwareBuffer) as well as Linux.
            TensorMemory::DmaBuf => is_gpu_buffer_available(),
            TensorMemory::IoSurface | TensorMemory::Pbo | TensorMemory::Cuda => false,
        }
    }

    /// The error to return when a caller pins a request to a backing this
    /// build knows the name of but cannot serve.
    ///
    /// Deliberately not `unreachable!()`. `IoSurface` and `Cuda` are
    /// unreachable *today* only because no backend reports them yet; the
    /// day one does, an `unreachable!()` written now becomes a panic in
    /// library code reached from an ordinary caller request. A "this build
    /// cannot do that" error is the same information without the crash, and
    /// it is what every other unservable request here already returns.
    ///
    /// `static`-only: every call site is inside `impl<T> TensorStorage<T>`
    /// (`TensorStorage::new`), itself `#[cfg(feature = "static")]`.
    #[cfg(feature = "static")]
    pub(crate) fn unsupported_here(self) -> Error {
        let reason = match self {
            // Not reachable: `Mem` is servable on every target. Stated
            // rather than panicked on, for the reason above.
            TensorMemory::Mem => "Mem is servable on every platform, so this should not happen",
            TensorMemory::Shm => "POSIX shared memory is unix-only",
            TensorMemory::DmaBuf => {
                "this target has no platform GPU-buffer allocator (DMA-BUF is Linux, \
                 IOSurface macOS/iOS, AHardwareBuffer Android, D3D11 textures on \
                 Windows)"
            }
            TensorMemory::IoSurface => {
                "no backend produces or accepts IOSurface under its own code yet -- \
                 macOS/iOS allocate and report TensorMemory::DmaBuf"
            }
            TensorMemory::Pbo => {
                "PBO tensors are created by ImageProcessor::create_image with a GL \
                 context current, never by Tensor::new"
            }
            TensorMemory::Cuda => "there is no CUDA backing in this build",
        };
        Error::NotImplemented(format!(
            "TensorMemory::{self:?} is not supported by this build: {reason}"
        ))
    }
}

impl From<TensorMemory> for String {
    /// The wire string, via [`TensorMemory::as_str`] -- one spelling, not a
    /// second one maintained alongside it.
    ///
    /// `DmaBuf` renders as `"dmabuf"`, not the `"dma"` this impl used to
    /// emit. `TryFrom<&str>` still accepts `"dma"` so anything that
    /// persisted the old spelling keeps parsing; the benchmark result keys
    /// in `.github/scripts` spell it `"dma"` but build that string
    /// themselves and never went through this impl.
    fn from(memory: TensorMemory) -> Self {
        memory.as_str().to_owned()
    }
}

impl TryFrom<&str> for TensorMemory {
    type Error = Error;

    /// Parses [`TensorMemory::as_str`]'s spelling, plus the legacy `"dma"`
    /// alias for `DmaBuf`.
    fn try_from(s: &str) -> Result<Self> {
        TensorMemory::from_str_code(s)
            .or(if s == "dma" {
                Some(TensorMemory::DmaBuf)
            } else {
                None
            })
            .ok_or_else(|| Error::InvalidMemoryType(s.to_owned()))
    }
}

// Everything from here through the end of `impl<T> TensorTrait<T> for
// Tensor<T>` below is the `static` backend's storage-owning `Tensor<T>`:
// `TensorStorage<T>` (the per-memory-backend enum) and the `Tensor<T>`
// struct that wraps it. `dynamic`'s `Tensor<T>` is a different, much
// smaller type -- a typed lens over `TensorDyn` with no storage of its
// own -- defined in `tensor_dyn/dynamic_tensor.rs` and re-exported below.
#[cfg(feature = "static")]
#[derive(Debug)]
#[allow(dead_code)] // Variants are constructed by downstream crates via pub(crate) helpers
pub(crate) enum TensorStorage<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// Platform-native zero-copy GPU buffer. Inner type differs per
    /// target: `DmaTensor` on Linux (DMA-BUF fd), `IoSurfaceTensor` on
    /// macOS (CFRetained IOSurface). The shared variant name keeps the
    /// public `TensorMemory::DmaBuf` discriminant stable across platforms.
    #[cfg(target_os = "linux")]
    Dma(DmaTensor<T>),
    #[cfg(any(target_os = "macos", target_os = "ios"))]
    Dma(IoSurfaceTensor<T>),
    #[cfg(target_os = "android")]
    Dma(AHardwareBufferTensor<T>),
    #[cfg(target_os = "windows")]
    Dma(crate::d3d11::texture::D3d11TextureTensor<T>),
    #[cfg(unix)]
    Shm(ShmTensor<T>),
    Mem(MemTensor<T>),
    Pbo(PboTensor<T>),
}

#[cfg(feature = "static")]
impl<T> TensorStorage<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// The backing allocation's intrinsic physical row pitch in bytes, if it
    /// has one that is fixed independent of the logical shape. macOS IOSurface
    /// reports its 64-aligned `bytesPerRow`; other backings (Linux DMA, SHM,
    /// Mem, PBO) have no fixed pitch beyond the logical shape and return `None`.
    ///
    /// Used by `configure_image` to preserve the physical pitch when a reused
    /// pool tensor is reconfigured to a smaller logical image — so the decode
    /// writes rows at the surface's real stride and the GPU samples them with
    /// the same stride (the physical-grid / logical-ROI decoupling).
    pub(crate) fn backing_row_stride(&self) -> Option<usize> {
        match self {
            // Only genuine image-formatted IOSurfaces (height > 1) carry a real
            // per-row pitch; a generic byte-bag (height == 1) returns `None` so
            // `configure_image` does not adopt its whole-buffer "row" as a stride.
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(t) => t.image_backing_row_stride(),
            // Android AHardwareBuffer: same rule — only genuine 2D
            // image-formatted buffers (height > 1) carry a real row pitch.
            #[cfg(target_os = "android")]
            TensorStorage::Dma(t) => t.image_backing_row_stride(),
            // Windows D3D11: the driver's staging row pitch. `None` when the
            // tensor has no staging (write-only or hardware-only), whose host
            // buffer has tight rows -- except for a semi-planar tensor, whose
            // texture is allocated as wide as that pitch for every access, so
            // it always has one to report.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(t) => t.image_backing_row_stride(),
            _ => None,
        }
    }

    /// Create a new tensor storage with the given shape, memory type, and
    /// optional name. If no name is given, a random name will be generated.
    /// If no memory type is given, the best available memory type will be
    /// chosen based on the platform and environment variables.
    fn new(shape: &[usize], memory: Option<TensorMemory>, name: Option<&str>) -> Result<Self> {
        match memory {
            #[cfg(target_os = "linux")]
            Some(TensorMemory::DmaBuf) => {
                DmaTensor::<T>::new(shape, name).map(TensorStorage::Dma)
            }
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            Some(TensorMemory::DmaBuf) => {
                IoSurfaceTensor::<T>::new(shape, name).map(TensorStorage::Dma)
            }
            #[cfg(target_os = "android")]
            Some(TensorMemory::DmaBuf) => {
                AHardwareBufferTensor::<T>::new(shape, name).map(TensorStorage::Dma)
            }
            // Windows has a DmaBuf backing, but it is a D3D11 texture: an image
            // layout, not a byte bag, so a shape alone cannot describe one.
            // Name the constructor that can, rather than quietly handing back
            // host memory the caller did not ask for.
            #[cfg(target_os = "windows")]
            Some(TensorMemory::DmaBuf) => Err(crate::error::Error::NotImplemented(
                "D3D11 texture tensors are image-formatted; use Tensor::image with \
                 TensorMemory::DmaBuf"
                    .to_owned(),
            )),
            #[cfg(not(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            )))]
            Some(TensorMemory::DmaBuf) => Err(crate::error::Error::NotImplemented(
                "TensorMemory::DmaBuf is only available on Linux (DMA-BUF), macOS/iOS (IOSurface), \
                 Android (AHardwareBuffer), and Windows (D3D11 textures, via Tensor::image)"
                    .to_owned(),
            )),
            #[cfg(unix)]
            Some(TensorMemory::Shm) => {
                ShmTensor::<T>::new(shape, name).map(TensorStorage::Shm)
            }
            #[cfg(not(unix))]
            Some(m @ TensorMemory::Shm) => Err(m.unsupported_here()),
            Some(TensorMemory::Mem) => {
                MemTensor::<T>::new(shape, name).map(TensorStorage::Mem)
            }
            Some(TensorMemory::Pbo) => Err(crate::error::Error::NotImplemented(
                "PboTensor cannot be created via Tensor::new() — use ImageProcessor::create_image()".to_owned(),
            )),
            // Defined codes with no backing behind them yet. An error, not
            // an `unreachable!()` -- see `unsupported_here`.
            Some(m @ (TensorMemory::IoSurface | TensorMemory::Cuda)) => Err(m.unsupported_here()),
            None => {
                if std::env::var("EDGEFIRST_TENSOR_FORCE_MEM")
                    .is_ok_and(|x| x != "0" && x.to_lowercase() != "false")
                {
                    MemTensor::<T>::new(shape, name).map(TensorStorage::Mem)
                } else {
                    // Auto-select priority: Dma > Mem. Shm is intentionally NOT
                    // auto-selected — it offers no advantage over Mem for an
                    // in-process tensor and Mem always succeeds, so Shm below Mem
                    // is effectively never reached. Request Shm explicitly via
                    // `TensorMemory::Shm` when cross-process sharing is needed.
                    // (PBO sits between Dma and Mem but is GL-backed and created
                    // only via `ImageProcessor::create_image`.)
                    #[cfg(target_os = "linux")]
                    {
                        // Linux: Try DMA -> Mem
                        match DmaTensor::<T>::new(shape, name) {
                            Ok(tensor) => Ok(TensorStorage::Dma(tensor)),
                            Err(_) => MemTensor::<T>::new(shape, name).map(TensorStorage::Mem),
                        }
                    }
                    #[cfg(any(target_os = "macos", target_os = "ios"))]
                    {
                        // macOS/iOS: Try IOSurface -> Mem. IOSurface is the
                        // GPU-shareable backend (zero-copy via ANGLE), filling the
                        // same role as DMA-BUF on Linux.
                        match IoSurfaceTensor::<T>::new(shape, name) {
                            Ok(tensor) => Ok(TensorStorage::Dma(tensor)),
                            Err(_) => MemTensor::<T>::new(shape, name).map(TensorStorage::Mem),
                        }
                    }
                    #[cfg(target_os = "android")]
                    {
                        // Android: Mem. Unlike macOS (where a byte-bag
                        // IOSurface is still GL-importable as R8) a generic
                        // BLOB AHardwareBuffer cannot back a GPU texture, so
                        // auto-selecting it buys nothing and costs plenty: a
                        // gralloc allocator-HAL ioctl per allocation (orders
                        // slower than malloc, ≥1 page + a dmabuf fd even for
                        // tiny tensors) and a lock/unlock cache-maintenance
                        // round trip on every map(). Zero-copy image tensors
                        // come from `Tensor::image(..)`; callers that want a
                        // BLOB (NNAPI handoff) request `TensorMemory::DmaBuf`
                        // explicitly.
                        MemTensor::<T>::new(shape, name).map(TensorStorage::Mem)
                    }
                    #[cfg(all(
                        unix,
                        not(any(
                            target_os = "linux",
                            target_os = "macos",
                            target_os = "ios",
                            target_os = "android"
                        ))
                    ))]
                    {
                        // Other Unix (BSD): Mem only (no DMA; Shm is explicit-only)
                        MemTensor::<T>::new(shape, name).map(TensorStorage::Mem)
                    }
                    #[cfg(not(unix))]
                    {
                        // Windows/other: Mem only
                        MemTensor::<T>::new(shape, name).map(TensorStorage::Mem)
                    }
                }
            }
        }
    }

    /// Create a DMA-backed tensor storage with an explicit byte size that
    /// may exceed `shape.product() * sizeof(T)`. Used for image tensors
    /// with row-padded layouts (see `DmaTensor::new_with_byte_size`).
    ///
    /// This is intentionally DMA-only: padding is only meaningful for
    /// buffers that will be imported as GPU textures via EGLImage. PBO,
    /// Shm, and Mem storage doesn't benefit from pitch alignment and
    /// shouldn't pay the memory cost.
    #[cfg(target_os = "linux")]
    pub(crate) fn new_dma_with_byte_size(
        shape: &[usize],
        byte_size: usize,
        name: Option<&str>,
    ) -> Result<Self> {
        DmaTensor::<T>::new_with_byte_size(shape, byte_size, name).map(TensorStorage::Dma)
    }

    // No non-Linux stub: the only caller (`Tensor::image_with_stride`)
    // returns `NotImplemented` directly on non-Linux without ever
    // reaching the storage layer, so defining a stub here would be
    // dead code and fail the `-D warnings` clippy gate on macOS CI.

    /// Create a Mem-backed tensor storage with an explicit byte size that may
    /// exceed `shape.product() * sizeof(T)`.  Used for image tensors with
    /// 64-byte-aligned row strides (see `MemTensor::with_capacity_bytes`).
    pub(crate) fn new_mem_with_byte_size(
        shape: &[usize],
        byte_size: usize,
        name: Option<&str>,
    ) -> Result<Self>
    where
        T: 'static,
    {
        MemTensor::<T>::with_capacity_bytes(shape, byte_size, name).map(TensorStorage::Mem)
    }

    /// Create a Shm-backed tensor storage with an explicit byte size that may
    /// exceed `shape.product() * sizeof(T)`.  Used for image tensors with
    /// 64-byte-aligned row strides (see `ShmTensor::new_with_byte_size`).
    #[cfg(unix)]
    pub(crate) fn new_shm_with_byte_size(
        shape: &[usize],
        byte_size: usize,
        name: Option<&str>,
    ) -> Result<Self> {
        ShmTensor::<T>::new_with_byte_size(shape, byte_size, name).map(TensorStorage::Shm)
    }

    /// Allocate an image-formatted IOSurface-backed storage (macOS).
    ///
    /// Used by `Tensor::image()` when the caller requests
    /// `TensorMemory::DmaBuf` and the format has an IOSurface FourCC
    /// mapping (YUYV, RGBA, BGRA today). Falls back to `new_with_byte_size`
    /// otherwise.
    #[cfg(any(target_os = "macos", target_os = "ios"))]
    pub(crate) fn new_image_iosurface(
        width: usize,
        height: usize,
        format: PixelFormat,
        dtype: DType,
        shape: &[usize],
        name: Option<&str>,
    ) -> Result<Self> {
        IoSurfaceTensor::<T>::new_image(width, height, format, dtype, shape, name)
            .map(TensorStorage::Dma)
    }

    /// Allocate an image-formatted AHardwareBuffer-backed storage (Android).
    ///
    /// Used by `Tensor::image()` when the caller requests
    /// `TensorMemory::DmaBuf` and the format has an AHardwareBuffer format
    /// mapping (RGBA8 and the RGBA16F float paths today). Falls back to
    /// `new_with_byte_size` otherwise.
    #[cfg(target_os = "android")]
    pub(crate) fn new_image_ahardwarebuffer(
        width: usize,
        height: usize,
        format: PixelFormat,
        dtype: DType,
        shape: &[usize],
        name: Option<&str>,
        access: CpuAccess,
    ) -> Result<Self> {
        AHardwareBufferTensor::<T>::new_image(width, height, format, dtype, shape, name, access)
            .map(TensorStorage::Dma)
    }

    /// Allocate an image-formatted D3D11 texture storage (Windows).
    ///
    /// Used by `Tensor::image()` when the caller requests
    /// `TensorMemory::DmaBuf`. Unlike the IOSurface and AHardwareBuffer
    /// constructors there is no byte-bag fallback: a format with no texture
    /// layout is an error, because a texture is the only thing this backing
    /// can be.
    #[cfg(target_os = "windows")]
    pub(crate) fn new_image_d3d11(
        width: usize,
        height: usize,
        format: PixelFormat,
        dtype: DType,
        shape: &[usize],
        name: Option<&str>,
        access: CpuAccess,
    ) -> Result<Self> {
        crate::d3d11::texture::D3d11TextureTensor::<T>::new_image(
            width, height, format, dtype, shape, name, access,
        )
        .map(TensorStorage::Dma)
    }

    /// Create a new tensor storage using the given file descriptor, shape,
    /// and optional name.
    #[cfg(unix)]
    fn from_fd(fd: OwnedFd, shape: &[usize], name: Option<&str>) -> Result<Self> {
        #[cfg(target_os = "linux")]
        {
            use nix::sys::stat::fstat;
            use nix::sys::statfs::fstatfs;

            let stat = fstat(&fd)?;
            let major = major(stat.st_dev);
            let minor = minor(stat.st_dev);

            if major != 0 {
                // Dma and Shm tensors are expected to have major number 0
                return Err(Error::UnknownDeviceType(major, minor));
            }

            // Classify by filesystem magic, never by the st_dev minor.
            //
            // dma_buf files live on an internal kernel mount (`dma_buf_mnt`,
            // created with `kern_mount`) whose superblock draws its device
            // number from `get_anon_bdev()` — an IDA allocated first-come,
            // first-served during boot, shared with every other anonymous
            // pseudo-filesystem (pipefs, sockfs, anon_inodefs, nsfs, bdev,
            // tracefs, ...). The minor a DMA-BUF lands on is therefore a
            // function of which pseudo-filesystems registered first on that
            // kernel build: it moves with kernel config, driver load order,
            // initramfs use, and kernel version. It is not part of any ABI.
            //
            // Observed values for a genuine DMA-BUF: 12 on x86 desktop, 8 on
            // the ADIS Verdin. An earlier revision hardcoded `9 | 10` here,
            // which silently imported real DMA-BUFs as shared memory
            // everywhere else.
            //
            // The filesystem magic, by contrast, is stable UAPI
            // (include/uapi/linux/magic.h). Both branches are identified
            // positively; anything else is genuinely unknown and is rejected
            // rather than guessed at. Falling back to SHM would "work" — a
            // DMA-BUF is mmap-able, and even a pipe imports as a zero-length
            // tensor — which is exactly why it must not be the default.
            let magic = fs_magic(fstatfs(&fd)?.filesystem_type().0 as i64);

            log::debug!(
                "Creating tensor from fd: major={major}, minor={minor}, magic={magic:#010x}"
            );

            match magic {
                DMA_BUF_MAGIC => DmaTensor::<T>::from_fd(fd, shape, name).map(TensorStorage::Dma),
                TMPFS_MAGIC => ShmTensor::<T>::from_fd(fd, shape, name).map(TensorStorage::Shm),
                other => Err(Error::UnknownBufferType(other)),
            }
        }
        #[cfg(all(unix, not(target_os = "linux")))]
        {
            // On macOS/iOS/BSD, always use SHM (no DMA-BUF fd import)
            ShmTensor::<T>::from_fd(fd, shape, name).map(TensorStorage::Shm)
        }
    }
}

#[cfg(feature = "static")]
impl<T> TensorTrait<T> for TensorStorage<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    fn new(shape: &[usize], name: Option<&str>) -> Result<Self> {
        Self::new(shape, None, name)
    }

    #[cfg(unix)]
    fn from_fd(fd: OwnedFd, shape: &[usize], name: Option<&str>) -> Result<Self> {
        Self::from_fd(fd, shape, name)
    }

    #[cfg(unix)]
    fn clone_fd(&self) -> Result<OwnedFd> {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android"
            ))]
            TensorStorage::Dma(t) => t.clone_fd(),
            TensorStorage::Shm(t) => t.clone_fd(),
            TensorStorage::Mem(t) => t.clone_fd(),
            TensorStorage::Pbo(t) => t.clone_fd(),
        }
    }

    fn memory(&self) -> TensorMemory {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(_) => TensorMemory::DmaBuf,
            #[cfg(unix)]
            TensorStorage::Shm(_) => TensorMemory::Shm,
            TensorStorage::Mem(_) => TensorMemory::Mem,
            TensorStorage::Pbo(_) => TensorMemory::Pbo,
        }
    }

    fn name(&self) -> String {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.name(),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.name(),
            TensorStorage::Mem(t) => t.name(),
            TensorStorage::Pbo(t) => t.name(),
        }
    }

    fn shape(&self) -> &[usize] {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.shape(),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.shape(),
            TensorStorage::Mem(t) => t.shape(),
            TensorStorage::Pbo(t) => t.shape(),
        }
    }

    fn reshape(&mut self, shape: &[usize]) -> Result<()> {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.reshape(shape),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.reshape(shape),
            TensorStorage::Mem(t) => t.reshape(shape),
            TensorStorage::Pbo(t) => t.reshape(shape),
        }
    }

    fn capacity_bytes(&self) -> usize {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.capacity_bytes(),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.capacity_bytes(),
            TensorStorage::Mem(t) => t.capacity_bytes(),
            TensorStorage::Pbo(t) => t.capacity_bytes(),
        }
    }

    fn set_logical_shape(&mut self, shape: &[usize]) -> Result<()> {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.set_logical_shape(shape),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.set_logical_shape(shape),
            TensorStorage::Mem(t) => t.set_logical_shape(shape),
            TensorStorage::Pbo(t) => t.set_logical_shape(shape),
        }
    }

    fn map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.map_with(access),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.map_with(access),
            TensorStorage::Mem(t) => t.map_with(access),
            TensorStorage::Pbo(t) => t.map_with(access),
        }
    }

    fn try_map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.try_map_with(access),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.try_map_with(access),
            TensorStorage::Mem(t) => t.try_map_with(access),
            TensorStorage::Pbo(t) => t.try_map_with(access),
        }
    }

    fn buffer_identity(&self) -> &BufferIdentity {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.buffer_identity(),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.buffer_identity(),
            TensorStorage::Mem(t) => t.buffer_identity(),
            TensorStorage::Pbo(t) => t.buffer_identity(),
        }
    }

    /// Forward a sub-region view to the active backend, re-wrapping the
    /// backend's view (which shares the parent's allocation and
    /// [`BufferIdentity`]) back into the matching `TensorStorage` variant. Each
    /// backend's `view` is its own `TensorTrait::view` override; this single
    /// match is the only per-variant dispatch (`Tensor::subview` calls through
    /// here rather than matching the storage itself).
    fn view(&self, offset_bytes: usize, shape: &[usize]) -> Result<Self> {
        match self {
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            TensorStorage::Dma(t) => t.view(offset_bytes, shape).map(TensorStorage::Dma),
            #[cfg(unix)]
            TensorStorage::Shm(t) => t.view(offset_bytes, shape).map(TensorStorage::Shm),
            TensorStorage::Mem(t) => t.view(offset_bytes, shape).map(TensorStorage::Mem),
            TensorStorage::Pbo(t) => t.view(offset_bytes, shape).map(TensorStorage::Pbo),
        }
    }
}

/// Multi-backend tensor with optional image format metadata.
///
/// When `format` is `Some`, this tensor represents an image. Width, height,
/// and channels are derived from `shape` + `format`. When `format` is `None`,
/// this is a raw tensor (identical to the pre-refactoring behavior).
///
/// This is the `static` backend's `Tensor<T>` -- it owns its storage. See
/// `tensor_dyn/dynamic_tensor.rs` for `dynamic`'s `Tensor<T>`, a typed lens
/// with no storage of its own.
#[cfg(feature = "static")]
#[derive(Debug)]
pub struct Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// CUDA registration for this tensor, if any. Set after creation by
    /// the image crate once a PBO is registered with CUDA interop.
    ///
    /// MUST be declared before `storage`: CUDA must unregister the GL buffer
    /// before storage's Drop deletes it (cudaGraphicsUnregisterResource before
    /// glDeleteBuffers). Rust drops fields in declaration order.
    cuda: Option<crate::cuda::CudaHandle>,
    pub(crate) storage: TensorStorage<T>,
    format: Option<PixelFormat>,
    chroma: Option<Box<Tensor<T>>>,
    /// Row stride in bytes for externally allocated buffers with row padding.
    /// `None` means tightly packed (stride == width * bytes_per_pixel).
    row_stride: Option<usize>,
    /// Byte offset within the DMA-BUF where image data starts.
    /// `None` means offset 0 (data starts at the beginning of the buffer).
    plane_offset: Option<usize>,
    /// Quantization metadata for integer-typed tensors. Public access is
    /// gated by the `IntegerType` trait — `Tensor<f32>` etc. carry the
    /// field for layout uniformity but have no way to read or write it.
    pub(crate) quantization: Option<Quantization>,
    /// Optional colorimetry metadata. `None` = undefined; never auto-filled.
    colorimetry: Option<crate::Colorimetry>,
    /// Declared CPU access (see [`CpuAccess`]). Image constructors set it
    /// from their `access` parameter; non-image tensors (`new`, imports,
    /// numpy) default to `ReadWrite` — they are CPU-centric by nature.
    /// `map_with` counts requests beyond this declaration as unplanned.
    cpu_access: CpuAccess,
    /// Recorded vendor tile-compression scheme — best knowledge from
    /// allocation time (see [`Compression`]). `Some` only for Android
    /// hardware-only AHardwareBuffers whose allocation requested
    /// compression on an eligible format with a recognized vendor. When
    /// set, the row-stride accessors describe no meaningful linear
    /// layout. `configure_image` preserves it (physical layout, unlike
    /// colorimetry); views inherit it.
    compression: Option<CompressionScheme>,
    /// Parent-image snapshot when this tensor is a [`view`](Self::view)/
    /// [`batch`](Self::batch) sub-region; `None` for a whole tensor. Lets the GL
    /// backend key its import on the parent and render the view as a
    /// `glViewport`/`glScissor` ROI. See [`ViewOrigin`].
    view_origin: Option<ViewOrigin>,
}

#[cfg(feature = "static")]
impl<T> Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// Wrap a TensorStorage in a Tensor with no image metadata.
    pub(crate) fn wrap(storage: TensorStorage<T>) -> Self {
        Self {
            storage,
            format: None,
            chroma: None,
            row_stride: None,
            plane_offset: None,
            quantization: None,
            cuda: None,
            colorimetry: None,
            cpu_access: CpuAccess::ReadWrite,
            compression: None,
            view_origin: None,
        }
    }

    /// Construct a tensor from a row-major element slice + shape. Allocates a
    /// new buffer (`TensorMemory::Mem`) and memcpys the contents; caller
    /// retains ownership of the input slice.
    ///
    /// # Errors
    ///
    /// - [`Error::InvalidShape`] if `values.len() != shape.iter().product()`.
    /// - Propagates any allocation error from [`Self::new`].
    pub fn from_slice(values: &[T], shape: &[usize]) -> Result<Self>
    where
        T: Copy,
    {
        let expected: usize = shape.iter().product();
        if values.len() != expected {
            return Err(Error::InvalidShape(format!(
                "from_slice: values.len()={} but shape product={expected} (shape={shape:?})",
                values.len()
            )));
        }
        let t = Self::new(shape, Some(TensorMemory::Mem), None)?;
        {
            let mut m = t.map()?;
            m.as_mut_slice().copy_from_slice(values);
        }
        Ok(t)
    }

    /// Wrap externally-owned memory as a tensor without copying. The tensor
    /// borrows `[ptr, ptr + shape.product() * size_of::<T>())` as
    /// [`TensorMemory::Mem`]; `owner`, when `Some`, co-owns the source so it
    /// outlives the tensor (and all derived views/maps). See [`ForeignOwner`].
    ///
    /// The canonical use is CUDA zero-copy: allocate host-coherent memory
    /// (`cudaHostAlloc`), wrap the host pointer here, and bind the matching
    /// device pointer to the inference engine — reads and writes hit the same
    /// physical buffer with no host copy. The identical primitive backs the
    /// Python `Tensor.from_numpy` zero-copy borrow (owner = the NumPy object).
    ///
    /// # Safety
    ///
    /// `ptr` must be non-null, aligned to `align_of::<T>()`, and valid for
    /// `shape.product()` elements of `T` for as long as the returned tensor —
    /// and every view/map sharing its backing — is alive. Pass an `owner` that
    /// co-owns the source to uphold that contract.
    ///
    /// # Errors
    ///
    /// [`Error::InvalidSize`] if `shape` is empty.
    pub unsafe fn from_foreign(
        ptr: *mut T,
        shape: &[usize],
        owner: Option<crate::ForeignOwner>,
        name: Option<&str>,
    ) -> Result<Self> {
        // SAFETY: forwarded to `from_foreign_with_capacity`'s contract; `0`
        // clamps to the tight shape-derived footprint below, i.e. no extra
        // headroom -- identical to this function's own prior behaviour.
        unsafe { Self::from_foreign_with_capacity(ptr, shape, 0, owner, name) }
    }

    /// [`Self::from_foreign`], additionally recording that the allocation
    /// behind `ptr` holds at least `capacity_bytes` bytes -- headroom beyond
    /// the tight `shape.product() * size_of::<T>()` footprint that a later
    /// [`configure_image`](Self::configure_image) / `set_logical_shape` can
    /// grow into without erroring.
    ///
    /// This is the consumer half of the cross-package capsule protocol's
    /// [`crate::protocol::TensorDesc::capacity`]: a producer's pool tensor
    /// (allocated for its largest expected image, holding a smaller one
    /// today) reports its real allocation size so the imported alias
    /// inherits the same headroom instead of being clamped to today's
    /// logical shape. `capacity_bytes` below the tight footprint is clamped
    /// up to it, never down -- the shape-implied floor always holds.
    ///
    /// # Safety
    ///
    /// Same as [`Self::from_foreign`], except `ptr` must be valid for
    /// `capacity_bytes` bytes (or the tight shape footprint, whichever is
    /// larger), not just the shape-implied footprint.
    ///
    /// # Errors
    ///
    /// [`Error::InvalidSize`] if `shape` is empty.
    pub unsafe fn from_foreign_with_capacity(
        ptr: *mut T,
        shape: &[usize],
        capacity_bytes: usize,
        owner: Option<crate::ForeignOwner>,
        name: Option<&str>,
    ) -> Result<Self> {
        if shape.is_empty() {
            return Err(Error::InvalidSize(0));
        }
        if ptr.is_null() {
            return Err(Error::InvalidArgument(
                "from_foreign: ptr must be non-null".to_owned(),
            ));
        }
        shape
            .iter()
            .copied()
            .try_fold(1usize, |acc, dim| acc.checked_mul(dim))
            .ok_or_else(|| {
                Error::InvalidArgument(format!(
                    "from_foreign: shape.product() overflows usize (shape={shape:?})"
                ))
            })?;
        let capacity_elems = capacity_bytes / std::mem::size_of::<T>();
        // SAFETY: this function's own contract (see its doc comment) is
        // exactly `MemTensor::from_foreign_with_capacity`'s contract.
        let mem = unsafe {
            MemTensor::<T>::from_foreign_with_capacity(ptr, shape, capacity_elems, owner, name)
        };
        Ok(Self::wrap(TensorStorage::Mem(mem)))
    }

    /// Pin a stable host address for this tensor's data.
    ///
    /// The returned [`HostPin`] carries **no borrow of the tensor**, so a
    /// caller can pin once at init and still pass `&mut self` to
    /// `ImageProcessor::convert` every frame. That borrow conflict is the
    /// blocker reported in [#134](https://github.com/EdgeFirstAI/hal/issues/134).
    ///
    /// The address stays valid until the pin is dropped, and survives
    /// re-layout: `configure_image` and `set_logical_shape` only rewrite the
    /// logical shape after a capacity check, and every backend's pin owns its
    /// own mapping, so nothing can move underneath it.
    ///
    /// A pin is therefore a **snapshot**, not a tracker: [`HostPin::len`]
    /// reports the extent at pin time and does not follow a later re-layout.
    /// That is the safe direction — the window always stays inside the
    /// allocation — but it means a caller who re-layouts should re-pin if it
    /// wants the new extent.
    ///
    /// The address is **not** a coherency guarantee: on non-coherent backends
    /// bracket CPU access with
    /// [`sync_for_cpu`](Self::sync_for_cpu) and
    /// [`sync_for_device`](Self::sync_for_device), which are no-ops where the
    /// backend does not require them.
    ///
    /// # Cost
    ///
    /// On `Mem` this is an `Arc` refcount bump — the backing allocation is
    /// never resized, so its base pointer is already stable. Other backends
    /// establish a mapping once and reuse it.
    ///
    /// # Errors
    ///
    /// - [`Error::InvalidArgument`] when `access` is [`CpuAccess::None`]: a
    ///   pinned mapping is CPU access by definition, so this is an error
    ///   rather than a warn-and-stage.
    /// - [`Error::NotImplemented`] for the two backends that **cannot** pin,
    ///   rather than merely not having been wired yet: a PBO
    ///   (`glMapBufferRange` establishes the address and the visibility
    ///   together, and there is no `GL_MAP_PERSISTENT_BIT` in GLES) and an
    ///   AHardwareBuffer (`AHardwareBuffer_lock` is what yields the address at
    ///   all, so there is no address outside the lock). Both name
    ///   `map()`/`map_with()` as the alternative. `Mem`, `Shm`, DMA-BUF,
    ///   IOSurface and the Windows D3D11 texture all pin — the texture through
    ///   a persistent host buffer the storage owns, which
    ///   [`sync_for_cpu`](Self::sync_for_cpu) and
    ///   [`sync_for_device`](Self::sync_for_device) move bytes between and the
    ///   texture, rather than through the staging mapping (a pin outlives every
    ///   map guard, so holding the staging texture mapped would freeze it).
    pub fn pin_host<'a>(&self, access: CpuAccess) -> Result<HostPin<'a>>
    where
        T: 'a,
    {
        if access == CpuAccess::None {
            return Err(Error::InvalidArgument(
                "pin_host: CpuAccess::None is not a valid pin; a pinned mapping \
                 is CPU access by definition"
                    .to_owned(),
            ));
        }
        // Backends yield everything addressable from the tensor's offset;
        // narrow to the logical extent so a consumer cannot mistake pitch
        // padding for data. A map guard keeps the wider window.
        let logical = self.len() * std::mem::size_of::<T>();
        let pin = match &self.storage {
            TensorStorage::Mem(m) => Ok(m.host_pin()),
            #[cfg(unix)]
            TensorStorage::Shm(s) => s.host_pin(),
            #[cfg(target_os = "linux")]
            TensorStorage::Dma(d) => d.host_pin(),
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(s) => s.host_pin(),
            // Windows D3D11: the pin is the storage's own persistent host
            // buffer, not the staging mapping -- see `D3d11TextureTensor::host_pin`.
            // The direction goes with it: a writable pin is what tells
            // `sync_for_device` the host buffer, not the staging copy, carries
            // the caller's writes.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(t) => t.host_pin(access),
            // AHardwareBuffer cannot support a pin at all, and that is a
            // platform contract rather than missing work: the NDK exposes no
            // way to obtain a CPU address outside AHardwareBuffer_lock, so a
            // "persistent" address would mean holding the lock for the pin's
            // lifetime -- which blocks the GPU from the buffer and makes any
            // further lock undefined. Both are the opposite of what a pin is
            // for. Say so, rather than implying a TODO.
            #[cfg(target_os = "android")]
            TensorStorage::Dma(_) => Err(Error::NotImplemented(
                "pin_host: AHardwareBuffer has no host address outside \
                 AHardwareBuffer_lock, so it cannot hand out one that outlives \
                 a guard. Use map()/map_with() for CPU access; for zero-copy \
                 handoff pass the buffer itself."
                    .to_owned(),
            )),
            // PBO is the same shape of constraint as AHardwareBuffer. The
            // message is a shared constant because `TensorDyn::pin_host`
            // (`tensor_dyn/dynamic_backend.rs`) must repeat this refusal --
            // the ABI has `ef_tensor_map` and no `ef_tensor_pin_host`, so the
            // library cannot tell a pin from a map. See
            // `crate::pbo::PIN_HOST_PBO_REFUSAL` for the reasoning at length.
            TensorStorage::Pbo(_) => Err(Error::NotImplemented(
                crate::pbo::PIN_HOST_PBO_REFUSAL.to_owned(),
            )),
        }?;
        Ok(pin.narrowed(logical))
    }

    /// Make CPU reads/writes of this tensor coherent — the CPU is about to
    /// access the buffer.
    ///
    /// Corresponds to `DMA_BUF_SYNC_START`, and the name matches the Linux
    /// kernel DMA API for the same reason: `for_cpu` says who is about to
    /// touch the memory, which is what the caller actually knows.
    ///
    /// Pair with [`sync_for_device`](Self::sync_for_device).
    ///
    /// # Which backends owe maintenance
    ///
    /// | backend | behaviour |
    /// |---|---|
    /// | `Mem`, `Shm` | **no-op** — plain CPU memory, coherent by construction |
    /// | `Dma` (Linux DMA-BUF) | one `DMA_BUF_IOCTL_SYNC`, direction-tagged |
    /// | `Dma` (macOS/iOS IOSurface) | `IOSurfaceLock` / `IOSurfaceUnlock`, options matched to `access` |
    /// | `Dma` (Android AHardwareBuffer) | [`Error::NotImplemented`] — no sync independent of the lock |
    /// | `Dma` (Windows D3D11 texture) | refreshes the pinned host buffer from the texture through the staging copy, or uploads it back; a no-op until something pins |
    /// | `Pbo` | [`Error::NotImplemented`] — no coherency window independent of the map |
    ///
    /// Only the first row is a no-op, so "bracket unconditionally and pay
    /// nothing" holds for `Mem`/`Shm` alone. The two that report
    /// `NotImplemented` do so because their platform fuses addressing and
    /// coherency into one call — `AHardwareBuffer_lock` and
    /// `glMapBufferRange` each perform the maintenance *as* they hand out the
    /// address, so a separate bracket would have to nest inside a map guard
    /// that already owns the pair. Both name `map()`/`map_with()` as the
    /// alternative. They previously fell through a wildcard and answered
    /// `Ok(())`, which is worse than an error because the symptom is
    /// stale-but-plausible pixels rather than a failure. The match is
    /// exhaustive so a new backend cannot inherit that silence — it must state
    /// its coherency story to compile.
    ///
    /// # Cost
    ///
    /// `Mem`/`Shm`: nothing. `Dma` on Linux: one ioctl. IOSurface: one
    /// lock/unlock pair. Windows D3D11 texture: one `CopyResource` plus a
    /// staging map per direction, and nothing at all on a tensor no one has
    /// pinned.
    ///
    /// # Errors
    ///
    /// [`Error::InvalidArgument`] when `access` is [`CpuAccess::None`], which
    /// describes no access to make coherent.
    pub fn sync_for_cpu(&self, access: CpuAccess) -> Result<()> {
        Self::check_sync_access(access)?;
        match &self.storage {
            // Plain CPU memory: coherent by construction.
            TensorStorage::Mem(_) => Ok(()),
            #[cfg(unix)]
            TensorStorage::Shm(_) => Ok(()),
            #[cfg(target_os = "linux")]
            TensorStorage::Dma(d) => {
                // The direction tells the kernel which maintenance this access
                // needs: a read-only bracket skips the writeback at END, a
                // write-only one skips the invalidate at START. It MUST match
                // the direction passed to sync_for_device.
                crate::dmabuf::sync_access(&d.fd, true, access).map_err(Error::NixError)
            }
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(s) => s.sync_for_cpu(access),
            // Windows D3D11: refreshes the pinned host buffer from the texture
            // through the staging copy.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(t) => t.sync_for_cpu(access),
            #[cfg(target_os = "android")]
            TensorStorage::Dma(_) => Err(Error::NotImplemented(
                "sync_for_cpu: AHardwareBuffer has no sync independent of its \
                 lock. AHardwareBuffer_lock both establishes the address and \
                 performs the cache invalidate, and the NDK leaves locking an \
                 already-locked buffer undefined, so a bracket on top of a map \
                 guard would nest. Use map()/map_with(), which owns the pair."
                    .to_owned(),
            )),
            TensorStorage::Pbo(_) => Err(Error::NotImplemented(
                "sync_for_cpu: a PBO has no coherency window independent of its \
                 map -- glMapBufferRange establishes the address and the \
                 visibility together, and glUnmapBuffer publishes the writes. \
                 Use map()/map_with(), which owns the pair."
                    .to_owned(),
            )),
        }
    }

    /// Release the buffer back to the device — the CPU is done accessing it.
    ///
    /// Corresponds to `DMA_BUF_SYNC_END`. See
    /// [`sync_for_cpu`](Self::sync_for_cpu) for the pairing and cost.
    pub fn sync_for_device(&self, access: CpuAccess) -> Result<()> {
        Self::check_sync_access(access)?;
        match &self.storage {
            TensorStorage::Mem(_) => Ok(()),
            #[cfg(unix)]
            TensorStorage::Shm(_) => Ok(()),
            #[cfg(target_os = "linux")]
            TensorStorage::Dma(d) => {
                crate::dmabuf::sync_access(&d.fd, false, access).map_err(Error::NixError)
            }
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(s) => s.sync_for_device(access),
            // Windows D3D11: uploads the pinned host buffer to the texture.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(t) => t.sync_for_device(access),
            #[cfg(target_os = "android")]
            TensorStorage::Dma(_) => Err(Error::NotImplemented(
                "sync_for_device: AHardwareBuffer has no sync independent of \
                 its lock — see sync_for_cpu. Use map()/map_with()."
                    .to_owned(),
            )),
            TensorStorage::Pbo(_) => Err(Error::NotImplemented(
                "sync_for_device: a PBO has no coherency window independent of \
                 its map -- see sync_for_cpu. Use map()/map_with()."
                    .to_owned(),
            )),
        }
    }

    fn check_sync_access(access: CpuAccess) -> Result<()> {
        if access == CpuAccess::None {
            return Err(Error::InvalidArgument(
                "sync_for_cpu/sync_for_device: CpuAccess::None describes no \
                 access to synchronise"
                    .to_owned(),
            ));
        }
        Ok(())
    }

    /// Construct a tensor from a 3-D ndarray view. Respects strides — one
    /// copy in all cases; contiguous views take a memcpy fast path.
    ///
    /// Only available when the `ndarray` feature is enabled.
    #[cfg(feature = "ndarray")]
    pub fn from_arrayview3(view: ndarray::ArrayView3<'_, T>) -> Result<Self>
    where
        T: Copy,
    {
        let (h, w, c) = view.dim();
        let t = Self::new(&[h, w, c], Some(TensorMemory::Mem), None)?;
        {
            let mut m = t.map()?;
            let dst = m.as_mut_slice();
            if let Some(src) = view.as_slice() {
                dst.copy_from_slice(src);
            } else {
                for (d, &s) in dst.iter_mut().zip(view.iter()) {
                    *d = s;
                }
            }
        }
        Ok(t)
    }

    /// Create a new tensor with the given shape, memory type, and optional
    /// name. If no name is given, a random name will be generated. If no
    /// memory type is given, the best available memory type will be chosen
    /// based on the platform and environment variables.
    ///
    /// On Linux platforms, the order of preference is: Dma -> Shm -> Mem.
    /// On other Unix platforms (macOS), the order is: Shm -> Mem.
    /// On non-Unix platforms, only Mem is available.
    ///
    /// # Environment Variables
    /// - `EDGEFIRST_TENSOR_FORCE_MEM`: If set to a non-zero and non-false
    ///   value, forces the use of regular system memory allocation
    ///   (`TensorMemory::Mem`) regardless of platform capabilities.
    ///
    /// # Example
    /// ```rust
    /// use edgefirst_tensor::{Error, Tensor, TensorMemory, TensorTrait};
    /// # fn main() -> Result<(), Error> {
    /// let tensor = Tensor::<f32>::new(&[2, 3, 4], Some(TensorMemory::Mem), Some("test_tensor"))?;
    /// assert_eq!(tensor.memory(), TensorMemory::Mem);
    /// assert_eq!(tensor.name(), "test_tensor");
    /// #    Ok(())
    /// # }
    /// ```
    pub fn new(shape: &[usize], memory: Option<TensorMemory>, name: Option<&str>) -> Result<Self> {
        let _span = tracing::trace_span!(
            "tensor.alloc",
            ?shape,
            memory = ?memory,
            dtype = std::any::type_name::<T>(),
        )
        .entered();
        #[cfg_attr(not(target_os = "linux"), allow(unused_mut))]
        let mut t = TensorStorage::new(shape, memory, name).map(Self::wrap)?;
        // Best-effort: attach a CUDA ExternalMemory handle for DMA tensors on
        // CUDA-capable hosts. Never blocks tensor creation on failure.
        // RUNTIME-UNVALIDATED: no CUDA+dma_heap test platform available; ABI
        // layout-asserted vs. CUDA 12.6 driver_types.h; mechanism proven by
        // gpu-probe O5 on Orin.
        #[cfg(target_os = "linux")]
        t.try_init_dma_cuda();
        Ok(t)
    }

    /// Create an image tensor with the given format.
    /// Allocate an image tensor from a declarative request — the
    /// full-featured constructor behind [`Self::image`] and friends.
    ///
    /// Adds the [`Compression`] request to the classic parameters:
    ///
    /// - a request with any CPU access other than [`CpuAccess::None`] is
    ///   [`Error::InvalidArgument`] (CPU mapping pins the layout linear);
    /// - [`Compression::Scheme`] fails with [`Error::NotImplemented`] on
    ///   platforms without vendor tile compression, and with
    ///   [`Error::InvalidArgument`] when the device's native scheme or
    ///   the format eligibility doesn't match;
    /// - [`Compression::Any`] never fails for compression reasons: it
    ///   records the scheme when the allocation is eligible and
    ///   otherwise resolves linear, incrementing
    ///   [`compression_fallback_count`].
    ///
    /// The recorded outcome is readable via [`Tensor::compression`].
    pub fn image_desc(desc: &ImageDesc) -> Result<Self>
    where
        T: 'static,
    {
        let Some(t_dtype) = dtype_of::<T>() else {
            return Err(Error::InvalidArgument(
                "image_desc: element type has no DType mapping".into(),
            ));
        };
        if t_dtype != desc.dtype {
            return Err(Error::InvalidArgument(format!(
                "image_desc: desc.dtype is {:?} but the tensor element type is {t_dtype:?}",
                desc.dtype
            )));
        }

        // Compression-request guards. CPU access pins the layout linear,
        // so a request combined with any declared access is a
        // contradiction the caller should hear about immediately.
        if desc.compression.is_some() && desc.access != CpuAccess::None {
            return Err(Error::InvalidArgument(format!(
                "image_desc: a compression request requires CpuAccess::None                  (declared {:?}) — CPU mapping pins the layout linear",
                desc.access
            )));
        }
        if let Some(Compression::Scheme(requested)) = desc.compression {
            #[cfg(not(target_os = "android"))]
            {
                return Err(Error::NotImplemented(format!(
                    "image_desc: Compression::Scheme({requested:?}) — no vendor tile                      compression on this platform (request Compression::Any for a                      portable fallback)"
                )));
            }
            #[cfg(target_os = "android")]
            {
                if matches!(
                    desc.memory,
                    Some(TensorMemory::Mem) | Some(TensorMemory::Shm) | Some(TensorMemory::Pbo)
                ) {
                    return Err(Error::InvalidArgument(format!(
                        "image_desc: Compression::Scheme({requested:?}) requires                          hardware memory (TensorMemory::DmaBuf or auto-select), got {:?}",
                        desc.memory
                    )));
                }
                if !crate::ahardwarebuffer_layout::compression_eligible(desc.format, desc.dtype) {
                    return Err(Error::InvalidArgument(format!(
                        "image_desc: ({:?}, {:?}) is not compression-eligible                          (RGBA8888 u8/i8 initially)",
                        desc.format, desc.dtype
                    )));
                }
                let device = crate::ahardwarebuffer::device_compression_scheme();
                if device != Some(requested) {
                    return Err(Error::InvalidArgument(format!(
                        "image_desc: Compression::Scheme({requested:?}) but the device's                          native scheme is {device:?}"
                    )));
                }
            }
        }

        // A compression request implies a hardware pipeline, so auto
        // memory promotes to the platform's zero-copy allocation first
        // (`Tensor::image` only takes the AHardwareBuffer/IOSurface path
        // under an explicit Dma request). `Scheme` propagates the Dma
        // failure — the caller demanded a layout only that allocator can
        // produce; `Any` falls back to plain auto-select.
        #[allow(unused_mut)]
        let mut t = match (desc.memory, desc.compression) {
            (None, Some(request)) => {
                match Self::image(
                    desc.width,
                    desc.height,
                    desc.format,
                    Some(TensorMemory::DmaBuf),
                    desc.access,
                ) {
                    Ok(t) => t,
                    Err(e) if matches!(request, Compression::Scheme(_)) => return Err(e),
                    Err(_) => Self::image(desc.width, desc.height, desc.format, None, desc.access)?,
                }
            }
            (memory, _) => Self::image(desc.width, desc.height, desc.format, memory, desc.access)?,
        };

        // Record best knowledge / count fallbacks. Only an Android
        // hardware-only AHardwareBuffer allocation can actually hold a
        // vendor tile layout; everywhere else an Any request resolves
        // linear and is counted.
        if let Some(request) = desc.compression {
            #[cfg(target_os = "android")]
            {
                let eligible =
                    crate::ahardwarebuffer_layout::compression_eligible(desc.format, desc.dtype);
                let scheme = crate::ahardwarebuffer::device_compression_scheme();
                let is_ahb = t.memory() == TensorMemory::DmaBuf;
                match (request, scheme) {
                    (_, Some(s)) if eligible && is_ahb => {
                        t.set_compression_unchecked(Some(s));
                    }
                    (Compression::Scheme(requested), _) => {
                        // Pre-validated eligible + scheme match, so the only
                        // way here is the allocation resolving off-AHB.
                        return Err(Error::InvalidOperation(format!(
                            "image_desc: Compression::Scheme({requested:?}) requested but                              the allocation resolved to {:?} (not an AHardwareBuffer)",
                            t.memory()
                        )));
                    }
                    (Compression::Any, _) => {
                        note_compression_fallback(&format!(
                            "({:?}, {:?}) {}x{}: eligible={eligible}, scheme={scheme:?},                              memory={:?}",
                            desc.format,
                            desc.dtype,
                            desc.width,
                            desc.height,
                            t.memory()
                        ));
                    }
                }
            }
            #[cfg(not(target_os = "android"))]
            {
                debug_assert!(matches!(request, Compression::Any));
                let _ = request;
                note_compression_fallback(&format!(
                    "({:?}, {:?}) {}x{}: no vendor tile compression on this platform",
                    desc.format, desc.dtype, desc.width, desc.height
                ));
            }
        }
        Ok(t)
    }

    /// Allocate an image tensor of `width` × `height` in `format`.
    ///
    /// This is the common-case image constructor. The shape follows from the
    /// format's layout — packed `[H, W, C]`, planar `[C, H, W]`, semi-planar
    /// `[H + chroma_rows, W]` — and the format is recorded on the tensor, so
    /// the image crate and the codec can work from it without out-of-band
    /// parameters.
    ///
    /// `memory` requests a backend, or `None` to auto-select. Auto-select for
    /// images is **DMA → Mem**: unlike [`Tensor::new`] it does not try SHM,
    /// which offers an image nothing that Mem doesn't (it is not
    /// GPU-importable, and Mem always succeeds). Ask for
    /// [`TensorMemory::Shm`] explicitly if you need it.
    ///
    /// `access` declares what the **CPU** intends to do with the buffer and is
    /// required; see [`CpuAccess`]. Hardware access — GPU, NPU, ISP, codec —
    /// is always implied and never declared. Prefer the narrowest declaration
    /// that fits: `None` keeps the allocation eligible for Android vendor tile
    /// compression, and anything else pins the layout linear.
    ///
    /// DMA-backed images always get a **64-byte-aligned row stride**, in every
    /// layout, because Mali and Vivante reject an EGLImage import at an
    /// unaligned pitch. Read the real pitch back with
    /// [`Tensor::effective_row_stride`] rather than assuming `width × bpp`.
    ///
    /// For a compression request or any other less common knob, build an
    /// [`ImageDesc`] and call [`Tensor::image_desc`].
    ///
    /// # Errors
    ///
    /// - [`Error::InvalidArgument`] if `width` × `height` is not a valid size
    ///   for `format` (for example odd dimensions where the format's chroma
    ///   subsampling forbids them), or, on macOS with an explicit
    ///   [`TensorMemory::DmaBuf`], if the format cannot be expressed as an
    ///   image-formatted IOSurface at this width. The message names the
    ///   aligned width to use.
    /// - Whatever the chosen backend returns if the allocation itself fails —
    ///   for an explicit `memory` request there is no fallback.
    ///
    /// # Example
    ///
    /// ```rust
    /// use edgefirst_tensor::{CpuAccess, PixelFormat, Tensor, TensorMemory};
    ///
    /// # fn main() -> Result<(), edgefirst_tensor::Error> {
    /// // A camera frame the GPU converts and the CPU never touches.
    /// let frame = Tensor::<u8>::image(1920, 1080, PixelFormat::Nv12,
    ///                                 Some(TensorMemory::Mem), CpuAccess::None)?;
    /// assert_eq!(frame.format(), Some(PixelFormat::Nv12));
    /// # Ok(())
    /// # }
    /// ```
    pub fn image(
        width: usize,
        height: usize,
        format: PixelFormat,
        memory: Option<TensorMemory>,
        access: CpuAccess,
    ) -> Result<Self>
    where
        T: 'static,
    {
        // Shape comes from the shared `PixelFormat::allocation_shape` helper (packed /
        // planar / semi-planar NV12·NV16). NV12 supports odd dimensions via the
        // `H + ceil(H/2)` combined-plane height.
        // The `T: 'static` bound is required by the macOS IOSurface path below.
        let shape = format.allocation_shape(width, height).ok_or_else(|| {
            Error::InvalidArgument(format!(
                "invalid dimensions {width}x{height} for format {format:?}"
            ))
        })?;

        // macOS Dma path: allocate a format-aware IOSurface (FourCC +
        // 2D dimensions) so the GL backend can bind it via
        // `EGL_ANGLE_iosurface_client_buffer`. Without this, the IOSurface
        // would default to a generic byte buffer (FourCC 'L008') and
        // ANGLE would reject the import with `EGL_BAD_ATTRIBUTE`.
        //
        // Guard: IOSurface rounds `bytes_per_row` up to 64-byte alignment.
        // If the natural row pitch (`width * channels * sizeof(T)`) is not
        // already 64-byte aligned, the padded allocation cannot be mapped
        // as a contiguous packed tensor — CPU reads/writes would use the
        // wrong stride.
        //
        // Explicit-Dma contract: when the caller passes
        // `Some(TensorMemory::DmaBuf)` they have asked for an
        // **image-formatted IOSurface**. Silently downgrading to the
        // generic 'L008' byte-bag when alignment fails buries the
        // mismatch — the caller only finds out hours later when ANGLE
        // (or any GL importer) rejects the bind with
        // `EGL_BAD_ATTRIBUTE`. Same anti-pattern bit us previously on
        // Mali GPUs with DMA-BUF padding. The right behaviour is to
        // fail loudly here with the alignment requirement spelled out
        // so the caller can either pick aligned dimensions, request
        // SHM/Mem explicitly, or pass `memory=None` for auto-select.
        #[cfg(any(target_os = "macos", target_os = "ios"))]
        if matches!(memory, Some(TensorMemory::DmaBuf)) {
            // For planar formats the IOSurface stacks channels
            // vertically (channels * height rows), so the row stride is
            // single-channel width * sizeof(T). Packed formats keep the
            // natural width * channels * sizeof(T) stride.
            let natural_row_bytes = match format.layout() {
                PixelLayout::Planar => width * std::mem::size_of::<T>(),
                _ => width * format.channels() * std::mem::size_of::<T>(),
            };
            // A format with a real IOSurface FourCC (RGBA/BGRA/YUYV packed,
            // GREY/NV12/NV16/NV24 as R8) tolerates a non-64-aligned natural
            // pitch: the surface is allocated with its own 64-aligned
            // `bytes_per_row`, the tensor records that stride below, and a CPU
            // map iterates rows correctly via the strided-map path while the GL
            // import uses the surface's pitch directly — fully zero-copy.
            // Planar (the F16 RGBA16F packing) is consumed flat as
            // `[1, C, H, W]` with no stride, so it still requires an aligned
            // pitch; and formats without a FourCC would fall through to a
            // generic byte-bag GL can't bind. Both fail loudly rather than
            // silently downgrade.
            let has_image_fourcc = dtype_of::<T>()
                .and_then(|dt| crate::iosurface_layout::image_iosurface_layout(format, dt))
                .is_some();
            let padded_ok = has_image_fourcc && format.layout() != PixelLayout::Planar;
            if !natural_row_bytes.is_multiple_of(64) && !padded_ok {
                let elem_size = std::mem::size_of::<T>();
                let per_pixel_bytes = match format.layout() {
                    PixelLayout::Planar => elem_size.max(1),
                    _ => format.channels().max(1) * elem_size.max(1),
                };
                // Compute the next 64-byte-aligned width by rounding the
                // natural row pitch up to the next multiple of 64 and
                // dividing back by per-pixel bytes. This handles every
                // `per_pixel_bytes` value correctly:
                //
                //   * Divisors of 64 (1/2/4/8/16/32/64) → the suggestion
                //     is always 64-byte aligned.
                //   * Non-divisors of 64 (e.g. RGB u8 with 3 B/pixel) →
                //     the next aligned row pitch may not be an integer
                //     multiple of per_pixel_bytes (3 doesn't divide 64
                //     in any way), so a "pad width to N" suggestion is
                //     structurally impossible — omit the suggestion
                //     instead of printing a wrong number.
                //   * per_pixel_bytes > 64 → same situation, also
                //     omitted; the previous formula divided by zero.
                //
                // The error always names the alignment requirement
                // verbatim and lists the two non-DMA alternatives so
                // the caller has at least one always-applicable fix.
                let aligned_row_bytes = natural_row_bytes.next_multiple_of(64);
                let pad_hint =
                    if per_pixel_bytes > 0 && aligned_row_bytes.is_multiple_of(per_pixel_bytes) {
                        let w = aligned_row_bytes / per_pixel_bytes;
                        format!("Pad width to {w} (the next 64-byte-aligned stride), ")
                    } else {
                        String::new()
                    };
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: {format:?} {width}x{height} with element \
                     size {elem_size} produces a {natural_row_bytes}-byte natural \
                     row pitch, which is not 64-byte aligned. \
                     IOSurface rounds bytes_per_row up to 64 bytes, so a \
                     contiguous CPU map of this tensor would read garbage. \
                     {pad_hint}pass memory=None to auto-fall-back to SHM, or \
                     pass memory=Some(TensorMemory::Shm) or \
                     Some(TensorMemory::Mem) explicitly."
                )));
            }
            // Alignment OK. Explicit-Dma contract: the caller asked for an
            // **image-formatted, GL-importable** IOSurface, so every failure
            // from here on is loud. The old behaviour fell through to the
            // generic 'L008' byte-bag `Some(other)` arm below, and the caller
            // only found out when the GL import rejected the bind with
            // `EGL_BAD_ATTRIBUTE` — the same silent-downgrade anti-pattern as
            // the alignment case above. (Semi-planar/Grey u8 map to 'L008'
            // *by design* in `image_iosurface_layout` — the R8-plane
            // representation the YUV shaders sample — so they return through
            // the mapped path and never reach these errors.)
            let dtype = dtype_of::<T>().ok_or_else(|| {
                Error::InvalidArgument(format!(
                    "Tensor::image: element type {} has no DType, so no \
                     image-formatted IOSurface exists. Pass memory=None or \
                     Some(TensorMemory::Mem) for a CPU tensor.",
                    std::any::type_name::<T>()
                ))
            })?;
            if crate::iosurface_layout::image_iosurface_layout(format, dtype).is_none() {
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: no zero-copy IOSurface mapping exists for \
                     {format:?}/{dtype:?} on macOS/iOS (supported: \
                     Rgba/Rgb @ U8/I8, Bgra/Yuyv/Grey/Nv12/Nv16/Nv24 @ U8, \
                     Rgba/PlanarRgb/PlanarRgba @ F16). Pass memory=None to \
                     auto-select, or Some(TensorMemory::Mem) explicitly, for \
                     a CPU tensor."
                )));
            }
            // Packed RGB u8/i8 rides an RGBA8888 surface at (W*3/4, H) —
            // reject a width the texel packing cannot express up front
            // (mirrors the Android pre-guard).
            if format == PixelFormat::Rgb
                && matches!(dtype, DType::U8 | DType::I8)
                && packed_rgb888_layout(width, height).is_none()
            {
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: Rgb {dtype:?} requires width%4==0 for the RGBA8888 \
                     IOSurface packing (got width={width}). Pad the width, or pass \
                     memory=Some(TensorMemory::Mem) for a CPU tensor."
                )));
            }
            let storage = TensorStorage::<T>::new_image_iosurface(
                width, height, format, dtype, &shape, None,
            )?;
            let mut t = Self::wrap(storage);
            t.format = Some(format);
            // IOSurface rounds `bytes_per_row` up to 64 bytes. When that
            // pitch exceeds the natural packed/planar row stride, record
            // it so CPU consumers iterate rows correctly (the GL import
            // already uses the surface's own pitch). For 64-aligned rows
            // — the common model-input case — the two match and no stride
            // is stored, leaving the flat mapping unchanged.
            if let TensorStorage::Dma(ref io) = t.storage {
                let bpr = io.bytes_per_row();
                if let Some(natural) = t.effective_row_stride() {
                    if bpr > natural {
                        t.set_row_stride_unchecked(bpr);
                    }
                }
            }
            t.cpu_access = access;
            return Ok(t);
        }

        // Android Dma path: allocate a format-aware AHardwareBuffer so the
        // GL backend can import it as an EGLImage
        // (`eglGetNativeClientBufferANDROID` → `eglCreateImageKHR`).
        //
        // Geometry: gralloc chooses the row pitch (`desc.stride`) at
        // allocation, and pads freely (validated on the Galaxy S26 Ultra,
        // where SnapAlloc pads the planar-F16 RGBA16F surface). A padded
        // pitch is recorded on the tensor so CPU maps iterate rows via the
        // strided-map path; the GL render uses the buffer's own pitch
        // through the EGLImage either way, so the GPU path stays fully
        // zero-copy. Consumers needing a FLAT layout (the future NPU
        // handoff's `[1, C, H, W]` contract) must check `row_stride()` and
        // repack when set — flatness is a per-device property here, unlike
        // macOS where IOSurface's 64-BYTE alignment keeps model-sized F16
        // surfaces naturally flat.
        #[cfg(target_os = "android")]
        if matches!(memory, Some(TensorMemory::DmaBuf)) {
            // Explicit-Dma contract (mirrors the macOS block above): the
            // caller asked for an image-formatted, GL-importable
            // AHardwareBuffer, so an unmapped combination or a gralloc
            // refusal errors here instead of falling through to a BLOB
            // byte-bag the GL backend can never import — that downgrade
            // only surfaced as a silent per-frame CPU upload.
            let dtype = dtype_of::<T>().ok_or_else(|| {
                Error::InvalidArgument(format!(
                    "Tensor::image: element type {} has no DType, so no \
                     image-formatted AHardwareBuffer exists. Pass memory=None \
                     or Some(TensorMemory::Mem) for a CPU tensor.",
                    std::any::type_name::<T>()
                ))
            })?;
            // Planar F16 requires width % 4 == 0 for the RGBA16F
            // packing — reject up front with the requirement spelled
            // out (mirrors the macOS pre-allocation guard) instead of
            // falling through to a byte-bag GL cannot bind.
            if format.layout() == PixelLayout::Planar
                && dtype == DType::F16
                && packed_rgba16f_layout(format, dtype, width, height).is_none()
            {
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: {format:?} F16 requires width%4==0 for the RGBA16F \
                     AHardwareBuffer packing (got width={width}). Pad the width, or pass \
                     memory=Some(TensorMemory::Mem) for a CPU tensor."
                )));
            }
            // Packed RGB u8/i8 rides an RGBA8888 surface at (W*3/4, H) —
            // the same whole-texel constraint as the F16 packing above.
            if format == PixelFormat::Rgb
                && matches!(dtype, DType::U8 | DType::I8)
                && packed_rgb888_layout(width, height).is_none()
            {
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: Rgb {dtype:?} requires width%4==0 for the RGBA8888 \
                     AHardwareBuffer packing (got width={width}). Pad the width, or pass \
                     memory=Some(TensorMemory::Mem) for a CPU tensor."
                )));
            }
            if crate::ahardwarebuffer::image_ahardwarebuffer_layout(format, dtype).is_none() {
                return Err(Error::InvalidArgument(format!(
                    "Tensor::image: no zero-copy AHardwareBuffer mapping exists \
                     for {format:?}/{dtype:?} on Android (Grey/NV* need \
                     R8-format buffers, API 29+; the HAL floor is API 26 — see \
                     `image_ahardwarebuffer_layout`). Pass memory=None to \
                     auto-select, or Some(TensorMemory::Mem) explicitly, for a \
                     CPU tensor; camera NV12 stays zero-copy by wrapping the \
                     camera's own AHardwareBuffer instead of allocating one."
                )));
            }
            let storage = TensorStorage::<T>::new_image_ahardwarebuffer(
                width, height, format, dtype, &shape, None, access,
            )?;
            let mut t = Self::wrap(storage);
            t.format = Some(format);
            if let TensorStorage::Dma(ref ahb) = t.storage {
                // gralloc chooses the row pitch (Qualcomm's
                // SnapAlloc pads e.g. the 160-px-wide RGBA16F
                // surface of a 640-wide planar F16 target).
                // When it exceeds the natural stride, record
                // it so CPU consumers iterate rows correctly
                // via `effective_row_stride()` — the GPU
                // renders through the EGLImage at the
                // buffer's real pitch regardless, so the
                // render stays fully zero-copy. Consumers
                // that need the FLAT `[1, C, H, W]` layout
                // (the future NPU handoff) must check
                // `row_stride()` is unset and repack — or
                // pick an aligned width — rather than assume
                // flatness (see the module docs).
                let bpr = ahb.bytes_per_row();
                if let Some(natural) = t.effective_row_stride() {
                    if bpr > natural {
                        log::debug!(
                            "Tensor::image: gralloc padded the {format:?} \
                             AHardwareBuffer pitch to {bpr} bytes (natural \
                             {natural}); recording row stride"
                        );
                        t.set_row_stride_unchecked(bpr);
                    }
                }
            }
            t.cpu_access = access;
            return Ok(t);
        }

        // Windows Dma path: allocate an `ID3D11Texture2D` on the process
        // device so the GL backend can bind it through ANGLE's D3D11 texture
        // import and a D3D12/CUDA consumer can open its shared NT handle.
        //
        // Explicit-Dma contract, as on macOS and Android: the caller asked for
        // a texture, so a format with no texture layout is an error here
        // rather than a silent fall-through to the host-memory arms below,
        // which would only surface much later as a failed GPU import.
        #[cfg(target_os = "windows")]
        if matches!(memory, Some(TensorMemory::DmaBuf)) {
            let dtype = dtype_of::<T>().ok_or_else(|| {
                Error::InvalidArgument(format!(
                    "Tensor::image: element type {} has no DType, so no D3D11 texture \
                     layout exists. Pass memory=None or Some(TensorMemory::Mem) for a \
                     CPU tensor.",
                    std::any::type_name::<T>()
                ))
            })?;
            let storage = TensorStorage::<T>::new_image_d3d11(
                width, height, format, dtype, &shape, None, access,
            )?;
            let mut t = Self::wrap(storage);
            t.format = Some(format);
            record_d3d11_row_stride(&mut t, format, "Tensor::image");
            t.cpu_access = access;
            // Best-effort CUDA import, as the Linux DMA arms do: a texture a
            // CUDA consumer can map is worth the one import at allocation.
            t.try_init_d3d11_cuda();
            return Ok(t);
        }

        // Compute the **64-byte-aligned** row stride for every image layout.
        //
        // Embedded GPUs reject `eglCreateImage` DMA-BUF imports whose row pitch
        // is not 64-byte aligned: Mali returns `EGL_BAD_ALLOC`, Vivante
        // `EGL_BAD_ACCESS`. This bit packed RGBA/RGB destinations at odd widths
        // AND at even non-multiple-of-16 widths (e.g. 321→1284, 322→1288 bytes —
        // neither divisible by 64), so an odd-source → RGBA convert failed on
        // imx95/imx8mp while succeeding on V3D/Tegra. Semi-planar already aligned
        // here; we now align packed and planar identically so every image()
        // allocation is GPU-importable regardless of width.
        //
        // The per-layout natural pitch and total row count:
        //   * SemiPlanar `[total_h, width]`     — pitch = even(width)·elem, rows = total_h
        //   * Packed     `[height, width, ch]`  — pitch = width·ch·elem,    rows = height
        //   * Planar     `[ch, height, width]`  — pitch = width·elem,       rows = ch·height
        // Allocation byte size = `aligned_stride · total_rows` (NOT the shape
        // product, which reflects only the logical width and under-allocates the
        // padding on odd / unaligned widths).
        let elem = std::mem::size_of::<T>();
        let channels = format.channels();
        let (natural_stride, total_rows) = match format.layout() {
            PixelLayout::SemiPlanar => (width.next_multiple_of(2) * elem, shape[0]),
            PixelLayout::Packed => (width * channels * elem, height),
            PixelLayout::Planar => (width * elem, channels * height),
        };
        let aligned_stride = natural_stride.next_multiple_of(64);
        let semi = format.layout() == PixelLayout::SemiPlanar;

        // DMA buffers MUST carry a 64-aligned row pitch — Mali/Vivante reject a
        // DMA-BUF EGLImage whose pitch is not 64-aligned. Semi-planar also needs
        // the aligned pitch on every backend (its chroma-plane offset math
        // assumes it). Packed/planar on host-only memory (Mem/Shm) keep the
        // natural tight pitch so the many flat CPU consumers are unaffected.
        let host_stride = if semi { aligned_stride } else { natural_stride };
        let host_byte_size = host_stride * total_rows;
        #[cfg(target_os = "linux")]
        let dma_byte_size = aligned_stride * total_rows;

        // `used_stride` is the actual row pitch of the storage created below.
        let (storage, used_stride) = match memory {
            #[cfg(target_os = "linux")]
            Some(TensorMemory::DmaBuf) => (
                TensorStorage::<T>::new_dma_with_byte_size(&shape, dma_byte_size, None)?,
                aligned_stride,
            ),
            #[cfg(unix)]
            Some(TensorMemory::Shm) => (
                TensorStorage::<T>::new_shm_with_byte_size(&shape, host_byte_size, None)?,
                host_stride,
            ),
            Some(TensorMemory::Mem) => (
                TensorStorage::<T>::new_mem_with_byte_size(&shape, host_byte_size, None)?,
                host_stride,
            ),
            #[allow(unused_variables)]
            Some(other) => {
                // PBO and any future variants: fall through to standard new().
                return {
                    let mut t = Self::new(&shape, Some(other), None)?;
                    t.format = Some(format);
                    t.cpu_access = access;
                    Ok(t)
                };
            }
            None => {
                // Auto-select priority: DMA → Mem (DMA gets the 64-aligned
                // pitch; the Mem fallback keeps the tight host pitch, so the
                // recorded stride matches the storage used). Shm is NOT
                // auto-selected — it offers no advantage over Mem for an
                // in-process image and Mem always succeeds, so it sits below Mem
                // and is reached only via an explicit `TensorMemory::Shm`.
                #[cfg(target_os = "linux")]
                {
                    match TensorStorage::<T>::new_dma_with_byte_size(&shape, dma_byte_size, None) {
                        Ok(s) => (s, aligned_stride),
                        Err(_) => (
                            TensorStorage::<T>::new_mem_with_byte_size(
                                &shape,
                                host_byte_size,
                                None,
                            )?,
                            host_stride,
                        ),
                    }
                }
                #[cfg(not(target_os = "linux"))]
                {
                    (
                        TensorStorage::<T>::new_mem_with_byte_size(&shape, host_byte_size, None)?,
                        host_stride,
                    )
                }
            }
        };

        let mut t = Self::wrap(storage);
        t.format = Some(format);
        // Record the row stride when it exceeds the natural tight pitch (padding
        // is present — DMA packed/planar at an unaligned width, or always for
        // semi-planar), mirroring the IOSurface path above. Aligned-width and
        // host-only packed/planar images keep their flat layout with no explicit
        // stride; `effective_row_stride()` then falls back to the identical
        // computed pitch. When padding IS present, consumers must iterate rows by
        // `effective_row_stride()` to skip it.
        if semi || used_stride > natural_stride {
            t.set_row_stride_unchecked(used_stride);
        }
        debug_assert!(
            t.row_stride.is_some() || !semi,
            "image() must always set row_stride for semi-planar tensors"
        );
        t.cpu_access = access;
        #[cfg(target_os = "linux")]
        t.try_init_dma_cuda();
        Ok(t)
    }

    /// Create a DMA-backed image tensor with an explicit row stride that
    /// may exceed the natural `width * channels * sizeof(T)` pitch.
    ///
    /// Used for image tensors that need GPU pitch alignment padding: the
    /// underlying DMA-BUF is sized to `row_stride * height` bytes, but
    /// the tensor's logical shape stays at `[height, width, channels]`.
    /// `width()` / `height()` / `shape()` continue to report the
    /// user-requested values; the padding is visible only via
    /// `row_stride()` / `effective_row_stride()` and is automatically
    /// propagated to the GL backend's EGLImage import so Mali Valhall
    /// accepts the buffer.
    ///
    /// # Supported formats
    ///
    /// Currently only **packed** pixel layouts (RGBA8, BGRA8, RGB888,
    /// Grey, etc.) are supported — the formats the GL backend uses as
    /// render destinations. Semi-planar formats (NV12, NV16) come from
    /// external allocators (camera capture, video decoders) and are
    /// imported via `TensorDyn::from_fd` + `set_row_stride`, which
    /// already supports padded strides.
    ///
    /// # Supported memory
    ///
    /// Currently only `TensorMemory::DmaBuf` is supported. PBO and Mem
    /// storage don't go through EGLImage import so they don't need
    /// pitch alignment; if you pass any other memory type this returns
    /// `NotImplemented`. `None` (auto-select) is treated as `Dma`.
    ///
    /// # Errors
    ///
    /// - `InvalidArgument` if `row_stride_bytes < width * channels * sizeof(T)`
    ///   (the requested stride would not fit a single row)
    /// - `NotImplemented` for non-packed formats or non-DMA memory
    /// - `IoError` if the DMA-heap allocation fails (propagated from
    ///   `DmaTensor::new_with_byte_size`)
    pub fn image_with_stride(
        width: usize,
        height: usize,
        format: PixelFormat,
        row_stride_bytes: usize,
        memory: Option<TensorMemory>,
        access: CpuAccess,
    ) -> Result<Self> {
        #[cfg(not(target_os = "linux"))]
        let _ = access;
        // DMA backing (the only thing this constructor produces) is
        // Linux-only. On macOS/BSD/Windows the non-Linux block below is
        // the only compiled body and returns `NotImplemented` directly;
        // on Linux the non-Linux block is cfg-removed and the function
        // falls through to the real validation + allocation path. Each
        // target compiles exactly one of the two blocks, and the block
        // serves as the function's tail expression in both cases — so
        // neither needs an explicit `return` (avoids
        // `clippy::needless_return` on the macOS CI gate).
        #[cfg(not(target_os = "linux"))]
        {
            let _ = (width, height, format, row_stride_bytes, memory);
            Err(Error::NotImplemented(
                "image_with_stride requires DMA support (Linux only)".to_owned(),
            ))
        }

        #[cfg(target_os = "linux")]
        {
            if format.layout() != PixelLayout::Packed {
                return Err(Error::NotImplemented(format!(
                    "Tensor::image_with_stride only supports packed pixel layouts, got {format:?}"
                )));
            }
            let elem = std::mem::size_of::<T>();
            let min_stride = width
                .checked_mul(format.channels())
                .and_then(|p| p.checked_mul(elem))
                .ok_or_else(|| {
                    Error::InvalidArgument(format!(
                        "image_with_stride: width {width} × channels {} × sizeof::<T>={elem} \
                         overflows usize",
                        format.channels()
                    ))
                })?;
            if row_stride_bytes < min_stride {
                return Err(Error::InvalidArgument(format!(
                    "image_with_stride: row_stride {row_stride_bytes} < minimum {min_stride} \
                     ({width} px × {} ch × {elem} B)",
                    format.channels()
                )));
            }
            let total_byte_size = row_stride_bytes.checked_mul(height).ok_or_else(|| {
                Error::InvalidArgument(format!(
                    "image_with_stride: row_stride {row_stride_bytes} × height {height} overflows usize"
                ))
            })?;

            let shape = vec![height, width, format.channels()];

            let storage = match memory {
                Some(TensorMemory::DmaBuf) | None => {
                    TensorStorage::<T>::new_dma_with_byte_size(&shape, total_byte_size, None)?
                }
                Some(other) => {
                    return Err(Error::NotImplemented(format!(
                        "image_with_stride: only TensorMemory::DmaBuf is supported, got {other:?}"
                    )));
                }
            };

            let mut t = Self::wrap(storage);
            t.format = Some(format);
            t.row_stride = Some(row_stride_bytes);
            t.cpu_access = access;
            // Match new()/from_fd(): a DMA tensor must attempt CUDA external-
            // memory import so a strided DMA buffer is also zero-copy
            // CUDA-mappable (no-op when libcudart is absent).
            t.try_init_dma_cuda();
            Ok(t)
        }
    }

    /// Attach format metadata to an existing tensor.
    ///
    /// # Arguments
    ///
    /// * `format` - The pixel format to attach
    ///
    /// # Returns
    ///
    /// `Ok(())` on success, with the format stored as metadata on the tensor.
    ///
    /// # Errors
    ///
    /// Returns `Error::InvalidShape` if the tensor shape is incompatible with
    /// the format's layout (packed expects `[H, W, C]`, planar expects
    /// `[C, H, W]`, semi-planar expects `[H*k, W]` with format-specific
    /// height constraints).
    pub fn set_format(&mut self, format: PixelFormat) -> Result<()> {
        let shape = self.shape();
        match format.layout() {
            PixelLayout::Packed => {
                if shape.len() != 3 || shape[2] != format.channels() {
                    return Err(Error::InvalidShape(format!(
                        "packed format {format:?} expects [H, W, {}], got {shape:?}",
                        format.channels()
                    )));
                }
            }
            PixelLayout::Planar => {
                if shape.len() != 3 || shape[0] != format.channels() {
                    return Err(Error::InvalidShape(format!(
                        "planar format {format:?} expects [{}, H, W], got {shape:?}",
                        format.channels()
                    )));
                }
            }
            PixelLayout::SemiPlanar => {
                if shape.len() != 2 {
                    return Err(Error::InvalidShape(format!(
                        "semi-planar format {format:?} expects [H*k, W], got {shape:?}"
                    )));
                }
                match format {
                    // Combined-plane height is `H + ceil(H/2)` (luma + chroma
                    // rows). For even H that is `3H/2` (≡ 0 mod 3); for odd H it
                    // is `(3H+1)/2` (≡ 2 mod 3). Only totals ≡ 1 mod 3 are
                    // unreachable, so reject just those — odd-height NV12 is
                    // valid (e.g. 725 rows for a 483-tall image).
                    PixelFormat::Nv12 if shape[0] % 3 == 1 => {
                        return Err(Error::InvalidShape(format!(
                            "NV12 contiguous shape[0] must be H + ceil(H/2) for some height; \
                             {} is unreachable (≡ 1 mod 3)",
                            shape[0]
                        )));
                    }
                    PixelFormat::Nv16 if !shape[0].is_multiple_of(2) => {
                        return Err(Error::InvalidShape(format!(
                            "NV16 contiguous shape[0] must be even, got {}",
                            shape[0]
                        )));
                    }
                    // NV24 (4:4:4): combined-plane height is 3H (Y + 2H chroma).
                    PixelFormat::Nv24 if !shape[0].is_multiple_of(3) => {
                        return Err(Error::InvalidShape(format!(
                            "NV24 contiguous shape[0] must be a multiple of 3 (= 3H), got {}",
                            shape[0]
                        )));
                    }
                    _ => {}
                }
            }
        }
        // Clear stored stride/offset when format changes — they may be invalid
        // for the new format. Caller must re-set after changing format.
        if self.format != Some(format) {
            self.row_stride = None;
            self.plane_offset = None;
            match self.storage {
                TensorStorage::Mem(ref mut m) => m.set_offset(0),
                #[cfg(target_os = "linux")]
                TensorStorage::Dma(ref mut dma) => dma.mmap_offset = 0,
                // Paired with the arm in `set_plane_offset`: a setter that
                // takes effect on this backing needs a clear that does too,
                // or the wrapper reports `None` while `map()` still starts at
                // the old offset -- a stale window rather than a lost one.
                // `reshape`'s clear site needs no such arm:
                // `IoSurfaceTensor::reshape` zeroes `view_offset` itself
                // before the match there runs.
                #[cfg(any(target_os = "macos", target_os = "ios"))]
                TensorStorage::Dma(ref mut io) => io.view_offset = 0,
                // The same pair for D3D11. Unlike `IoSurfaceTensor`,
                // `D3d11TextureTensor::reshape` leaves `view_offset` alone, so
                // `reshape`'s clear site carries this arm as well.
                #[cfg(target_os = "windows")]
                TensorStorage::Dma(ref mut tex) => tex.set_view_offset(0),
                // Paired with the arm in `set_plane_offset`: a setter that
                // takes effect on this backing needs a clear that does too.
                // `reshape`'s clear site needs no `Pbo` arm --
                // `PboTensor::reshape` zeroes `view_offset` itself before the
                // match there runs, exactly as `IoSurfaceTensor::reshape`
                // does. `set_logical_shape` deliberately does not, matching
                // `Mem`.
                TensorStorage::Pbo(ref mut p) => p.view_offset = 0,
                // Same pair, `Shm` side. `cfg(unix)` mirrors the `Shm`
                // variant's own gate on `TensorStorage`, not a per-OS
                // multiplex -- see the comment on the `set_plane_offset`
                // arm.
                #[cfg(unix)]
                TensorStorage::Shm(ref mut s) => s.set_offset(0),
                // No-op, pairing with `set_plane_offset`'s Android arm:
                // nothing writes `AHardwareBufferTensor::view_offset` there
                // either yet, so there is nothing here for a format change
                // to clear. See that arm's comment for the full accounting
                // of the still-incomplete gap.
                #[cfg(target_os = "android")]
                TensorStorage::Dma(_) => {}
            }
        }
        self.format = Some(format);
        Ok(())
    }

    /// Set this tensor's logical dimensions and pixel format to a decoded
    /// image, reusing the existing allocation. The shape is derived from the
    /// format layout; fails with `Error::InsufficientCapacity` if the
    /// allocation cannot hold `width`×`height` in `format`, or
    /// `Error::InvalidArgument` if the dimensions are invalid for the format.
    ///
    /// For NV12/NV16/NV24 the buffer width is rounded up to even (a chroma-plane
    /// interleaving requirement); the true odd width is reported by the decoder
    /// in `ImageInfo` and trimmed by a `convert()` crop. See
    /// [`PixelFormat::allocation_shape`].
    ///
    /// When the backing has a fixed physical row pitch (an IOSurface's
    /// 64-aligned `bytesPerRow`) that exceeds the new format's natural row
    /// stride — i.e. a reused max-sized pool tensor reconfigured to a smaller
    /// image — the physical pitch is preserved as the tensor's `row_stride`.
    /// This keeps the **physical grid** (allocation stride/surface) fixed while
    /// the **logical ROI** (this image's W×H) changes, so the decode writes rows
    /// at the surface's real stride and the GPU samples them at the same stride.
    /// Exact-sized buffers (pitch == natural) stay tightly packed unchanged.
    pub fn configure_image(
        &mut self,
        width: usize,
        height: usize,
        format: PixelFormat,
    ) -> Result<()> {
        let shape = format.allocation_shape(width, height).ok_or_else(|| {
            Error::InvalidArgument(format!(
                "invalid dimensions {width}x{height} for format {format:?}"
            ))
        })?;
        // Capture the pre-existing row stride before `set_format` clears it.
        // For pool tensors that were allocated at a larger width (e.g. 1920-wide
        // pool decoding a 789-wide image), this preserves the backing pitch so
        // rows are still written at the correct physical stride.
        let prior_stride = self.row_stride;

        self.storage.set_logical_shape(&shape)?;
        self.set_format(format)?; // clears any stale row_stride

        // Restore the correct row pitch for the new geometry. A DMA buffer of
        // ANY layout, and a semi-planar buffer on any backing, MUST carry a
        // 64-byte-aligned pitch: Mali/Vivante reject a DMA-BUF EGLImage whose
        // row pitch is not 64-aligned (`EGL_BAD_ALLOC` / `EGL_BAD_ACCESS`), and
        // semi-planar chroma-offset math assumes it. This mirrors the pitch
        // `Tensor::image()` allocates, so a recycled pool buffer imports
        // identically to a fresh one — without it a `configure_image()`'d packed
        // buffer (e.g. Y800 96-wide → tight pitch 96) failed convert() on
        // imx95/imx8mp via the texture-upload fallback while the fresh oracle
        // (aligned 128) succeeded. Packed/planar on host-only memory (Mem/Shm)
        // keep the tight pitch so flat CPU consumers stay unaffected — matching
        // `image()`'s `host_stride` rule.
        let elem = std::mem::size_of::<T>();
        let channels = format.channels();
        let (min_stride, total_rows) = match format.layout() {
            PixelLayout::SemiPlanar => (width.next_multiple_of(2) * elem, shape[0]),
            PixelLayout::Packed => (width * channels * elem, height),
            PixelLayout::Planar => (width * elem, channels * height),
        };
        let needs_align = self.storage.memory() == TensorMemory::DmaBuf
            || format.layout() == PixelLayout::SemiPlanar;

        let active_stride = if let Some(pitch) = self.storage.backing_row_stride() {
            // macOS IOSurface: use the surface's native pitch.
            let natural = self.effective_row_stride().unwrap_or(0);
            if pitch > natural {
                self.set_row_stride_unchecked(pitch);
                pitch
            } else {
                natural
            }
        } else if needs_align {
            // Priority:
            //   1. Prior stride (pool reuse): if the pre-existing stride is
            //      64-aligned, >= this layout's minimum row, and fits the
            //      allocation, keep it. This is the hot-loop reuse case (large
            //      pool, small image).
            //   2. Compute a fresh 64-aligned stride for the current width.
            let aligned = min_stride.next_multiple_of(64);
            let capacity = self.storage.capacity_bytes();

            let candidate = if let Some(ps) = prior_stride {
                if ps >= min_stride && ps % 64 == 0 && ps * total_rows <= capacity {
                    ps
                } else {
                    aligned
                }
            } else {
                aligned
            };

            if candidate * total_rows <= capacity {
                self.set_row_stride_unchecked(candidate);
                candidate
            } else {
                // Shouldn't happen for legitimate pools, but don't crash.
                self.effective_row_stride().unwrap_or(0)
            }
        } else {
            self.effective_row_stride().unwrap_or(0)
        };

        // Ensure the active stride fits the allocation. A pool reconfigured to a
        // wider image than its backing would silently SIGBUS on any subsequent
        // map/write — catch it here instead.
        if needs_align && active_stride > 0 {
            let needed = active_stride * total_rows;
            let capacity = self.storage.capacity_bytes();
            if needed > capacity {
                return Err(Error::InsufficientCapacity { needed, capacity });
            }
        }
        Ok(())
    }

    /// Allocate an image tensor sized to hold up to `width`×`height` in
    /// `format`, reusable for any smaller image via `configure_image`.
    pub fn image_with_capacity(
        width: usize,
        height: usize,
        format: PixelFormat,
        memory: Option<TensorMemory>,
        access: CpuAccess,
    ) -> Result<Self>
    where
        T: 'static,
    {
        Self::image(width, height, format, memory, access)
    }

    /// Pixel format (None if not an image).
    pub fn format(&self) -> Option<PixelFormat> {
        self.format
    }

    /// Image width (None if not an image).
    pub fn width(&self) -> Option<usize> {
        let fmt = self.format?;
        let shape = self.shape();
        match fmt.layout() {
            PixelLayout::Packed => Some(shape[1]),
            PixelLayout::Planar => Some(shape[2]),
            PixelLayout::SemiPlanar => Some(shape[1]),
        }
    }

    /// Image height (None if not an image).
    ///
    /// For semi-planar formats the combined-plane shape row count is divided
    /// by the format's luma-to-total ratio to recover logical height. This
    /// returns the exact logical height (including odd heights) only because
    /// the logical dimensions are tracked separately from the physical shape —
    /// `configure_image` stores the actual `(width, height)` in the format's
    /// `allocation_shape`, which round-trips losslessly via these accessors.
    pub fn height(&self) -> Option<usize> {
        let fmt = self.format?;
        let shape = self.shape();
        match fmt.layout() {
            PixelLayout::Packed => Some(shape[0]),
            PixelLayout::Planar => Some(shape[1]),
            PixelLayout::SemiPlanar => {
                if self.is_multiplane() {
                    Some(shape[0])
                } else {
                    match fmt {
                        PixelFormat::Nv12 => Some(shape[0] * 2 / 3),
                        PixelFormat::Nv16 => Some(shape[0] / 2),
                        PixelFormat::Nv24 => Some(shape[0] / 3),
                        _ => None,
                    }
                }
            }
        }
    }

    /// Create from separate Y and UV planes (multiplane NV12/NV16).
    pub fn from_planes(luma: Tensor<T>, chroma: Tensor<T>, format: PixelFormat) -> Result<Self> {
        if format.layout() != PixelLayout::SemiPlanar {
            return Err(Error::InvalidArgument(format!(
                "from_planes requires a semi-planar format, got {format:?}"
            )));
        }
        if chroma.format.is_some() || chroma.chroma.is_some() {
            return Err(Error::InvalidArgument(
                "chroma tensor must be a raw tensor (no format or chroma metadata)".into(),
            ));
        }
        let luma_shape = luma.shape();
        let chroma_shape = chroma.shape();
        if luma_shape.len() != 2 || chroma_shape.len() != 2 {
            return Err(Error::InvalidArgument(format!(
                "from_planes expects 2D shapes, got luma={luma_shape:?} chroma={chroma_shape:?}"
            )));
        }
        if luma_shape[1] != chroma_shape[1] {
            return Err(Error::InvalidArgument(format!(
                "luma width {} != chroma width {}",
                luma_shape[1], chroma_shape[1]
            )));
        }
        match format {
            PixelFormat::Nv12 => {
                if luma_shape[0] % 2 != 0 {
                    return Err(Error::InvalidArgument(format!(
                        "NV12 requires even luma height, got {}",
                        luma_shape[0]
                    )));
                }
                if chroma_shape[0] != luma_shape[0] / 2 {
                    return Err(Error::InvalidArgument(format!(
                        "NV12 chroma height {} != luma height / 2 ({})",
                        chroma_shape[0],
                        luma_shape[0] / 2
                    )));
                }
            }
            PixelFormat::Nv16 => {
                if chroma_shape[0] != luma_shape[0] {
                    return Err(Error::InvalidArgument(format!(
                        "NV16 chroma height {} != luma height {}",
                        chroma_shape[0], luma_shape[0]
                    )));
                }
            }
            // NV24's chroma plane is full-resolution (2×-wide interleaved UV),
            // which the equal-width plane check above doesn't model. Multiplane
            // NV24 is unused (the JPEG decoder emits a contiguous NV24 buffer),
            // so it's not supported here yet.
            _ => {
                return Err(Error::InvalidArgument(format!(
                    "from_planes only supports NV12 and NV16 (NV24 multiplane not yet \
                     supported — use a contiguous NV24 tensor), got {format:?}"
                )));
            }
        }

        Ok(Tensor {
            storage: luma.storage,
            format: Some(format),
            chroma: Some(Box::new(chroma)),
            row_stride: luma.row_stride,
            plane_offset: luma.plane_offset,
            quantization: luma.quantization,
            // A multiplane tensor spans two DMA-BUFs (luma + chroma); CUDA
            // external-memory import is per-fd, so there is no single device
            // pointer for the composite. Any CUDA handle the luma plane carried
            // is intentionally dropped — consumers needing CUDA access to
            // multiplane data must import each plane independently.
            cuda: None,
            colorimetry: luma.colorimetry,
            cpu_access: luma.cpu_access,
            compression: luma.compression,
            // A composed multiplane tensor is a whole image, not a sub-view.
            view_origin: None,
        })
    }

    /// Whether this tensor uses separate plane allocations.
    pub fn is_multiplane(&self) -> bool {
        self.chroma.is_some()
    }

    /// Access the chroma plane for multiplane semi-planar images.
    pub fn chroma(&self) -> Option<&Tensor<T>> {
        self.chroma.as_deref()
    }

    /// Mutable access to the chroma plane for multiplane semi-planar images.
    pub fn chroma_mut(&mut self) -> Option<&mut Tensor<T>> {
        self.chroma.as_deref_mut()
    }

    /// Row stride in bytes (`None` = tightly packed).
    pub fn row_stride(&self) -> Option<usize> {
        self.row_stride
    }

    /// Effective row stride in bytes: the stored stride if set, otherwise the
    /// minimum stride computed from the format, width, and element size.
    /// Returns `None` only when no format is set and no explicit stride was
    /// stored via [`set_row_stride`](Self::set_row_stride).
    ///
    /// **GREY note:** `effective_row_stride()` for a GREY tensor returns the
    /// tight `width` bytes (no padding), which is what `normalize_to_numpy` and
    /// the CPU convert path expect. The codec's internal `native_row_stride`
    /// (64-byte-aligned) is used only during decoding and is not propagated to
    /// the tensor's stored stride, so callers reading via
    /// `effective_row_stride()` always see the tight value for GREY.
    pub fn effective_row_stride(&self) -> Option<usize> {
        if let Some(s) = self.row_stride {
            return Some(s);
        }
        let fmt = self.format?;
        let w = self.width()?;
        let elem = std::mem::size_of::<T>();
        Some(match fmt.layout() {
            PixelLayout::Packed => w * fmt.channels() * elem,
            PixelLayout::Planar => w * elem,
            // Semi-planar: minimum stride must cover the even width so the
            // interleaved chroma columns are byte-aligned on odd-width images.
            PixelLayout::SemiPlanar => w.next_multiple_of(2) * elem,
        })
    }

    /// Copy the tensor's logical bytes into `dst`, compacting away any
    /// recorded row-stride padding.
    ///
    /// The flatness helper for NPU handoff: consumers that need a FLAT
    /// layout (e.g. `[1, C, H, W]` for NNAPI/LiteRT when the runtime cannot
    /// take a padded pitch) call this when [`row_stride`](Self::row_stride)
    /// is `Some` — on a tight tensor it degenerates to one memcpy, so it is
    /// safe to call unconditionally. `dst.len()` must equal the tight byte
    /// footprint (`shape` product × element size). Zero-copy consumers
    /// should prefer the buffer handle + [`Tensor::effective_row_stride`]
    /// (Self::effective_row_stride) and skip this copy entirely.
    pub fn copy_to_flat(&self, dst: &mut [u8]) -> Result<()> {
        let tight_bytes = crate::ahardwarebuffer_layout::checked_shape_bytes::<T>(self.shape())?;
        if dst.len() != tight_bytes {
            return Err(Error::InvalidArgument(format!(
                "copy_to_flat: dst is {} bytes but the tensor's tight \
                 footprint is {tight_bytes} bytes (shape {:?})",
                dst.len(),
                self.shape()
            )));
        }
        // Read-only: this helper never writes back into the tensor, so a
        // read map suffices — and is required on backends (D3D11) that
        // reject a writable map on a tensor allocated CpuAccess::Read.
        let map = self.map_read()?;
        // SAFETY: T is a plain numeric type (crate-wide bound); viewing the
        // mapped elements as bytes is sound.
        let src: &[u8] = unsafe {
            std::slice::from_raw_parts(
                map.as_slice().as_ptr() as *const u8,
                std::mem::size_of_val(map.as_slice()),
            )
        };
        let Some(stride) = self.row_stride else {
            // Tight layout: the mapped window is exactly the logical bytes.
            let got = src.len().min(tight_bytes);
            if got < tight_bytes {
                return Err(Error::InvalidOperation(format!(
                    "copy_to_flat: mapped {got} bytes < tight footprint {tight_bytes}"
                )));
            }
            dst.copy_from_slice(&src[..tight_bytes]);
            return Ok(());
        };
        // Strided: row count follows the strided-map convention (planar
        // stacks C planes of H rows; packed/semi-planar use shape[0]), and
        // the logical row is tight_bytes / rows for every layout.
        let rows = match self.format.map(|f| f.layout()) {
            Some(PixelLayout::Planar) => {
                let s = self.shape();
                if s.len() < 2 {
                    return Err(Error::InvalidOperation(
                        "copy_to_flat: strided planar tensor requires [C, H, W] shape".into(),
                    ));
                }
                s[0].checked_mul(s[1]).ok_or_else(|| {
                    Error::InvalidOperation(format!(
                        "copy_to_flat: planar rows {} × {} overflows usize",
                        s[0], s[1]
                    ))
                })?
            }
            _ => *self.shape().first().ok_or_else(|| {
                Error::InvalidOperation("copy_to_flat: tensor has an empty shape".into())
            })?,
        };
        if rows == 0 || !tight_bytes.is_multiple_of(rows) {
            return Err(Error::InvalidOperation(format!(
                "copy_to_flat: tight footprint {tight_bytes} does not divide \
                 into {rows} rows"
            )));
        }
        let row_bytes = tight_bytes / rows;
        let need = (rows - 1)
            .checked_mul(stride)
            .and_then(|b| b.checked_add(row_bytes))
            .ok_or_else(|| {
                Error::InvalidOperation(format!(
                    "copy_to_flat: stride {stride} × rows {rows} overflows usize"
                ))
            })?;
        if src.len() < need {
            return Err(Error::InvalidOperation(format!(
                "copy_to_flat: mapped {} bytes but strided rows need {need}",
                src.len()
            )));
        }
        for r in 0..rows {
            dst[r * row_bytes..(r + 1) * row_bytes]
                .copy_from_slice(&src[r * stride..r * stride + row_bytes]);
        }
        Ok(())
    }

    /// Set the row stride in bytes for externally allocated buffers with
    /// row padding (e.g. V4L2 or GStreamer allocators).
    ///
    /// The stride is propagated to the EGL DMA-BUF import attributes so
    /// the GPU interprets the padded buffer layout correctly. Must be
    /// called after [`set_format`](Self::set_format) and before the tensor
    /// is first passed to `ImageProcessor::convert`. The stored stride
    /// is cleared automatically if the pixel format is later changed.
    ///
    /// No stride-vs-buffer-size validation is performed because the
    /// backing allocation size is not reliably known: external DMA-BUFs
    /// may be over-allocated by the allocator, and internal tensors store
    /// a logical (unpadded) shape. An incorrect stride will be caught by
    /// the EGL driver at import time.
    ///
    /// # Arguments
    ///
    /// * `stride` - Row stride in bytes. Must be >= the minimum stride for
    ///   the format (width * channels * sizeof(T) for packed,
    ///   width * sizeof(T) for planar/semi-planar).
    ///
    /// # Errors
    ///
    /// * `InvalidArgument` if no pixel format is set on this tensor
    /// * `InvalidArgument` if `stride` is less than the minimum for the
    ///   format and width
    pub fn set_row_stride(&mut self, stride: usize) -> Result<()> {
        let fmt = self.format.ok_or_else(|| {
            Error::InvalidArgument("cannot set row_stride without a pixel format".into())
        })?;
        let w = self.width().ok_or_else(|| {
            Error::InvalidArgument("cannot determine width for row_stride validation".into())
        })?;
        let elem = std::mem::size_of::<T>();
        let min_stride = match fmt.layout() {
            PixelLayout::Packed => w * fmt.channels() * elem,
            PixelLayout::Planar => w * elem,
            // Semi-planar: minimum must cover even width for chroma alignment.
            PixelLayout::SemiPlanar => w.next_multiple_of(2) * elem,
        };
        if stride < min_stride {
            return Err(Error::InvalidArgument(format!(
                "row_stride {stride} < minimum {min_stride} for {fmt:?} at width {w}"
            )));
        }
        self.row_stride = Some(stride);
        Ok(())
    }

    /// Set the row stride without format validation.
    ///
    /// Use this for raw sub-tensors (e.g. chroma planes) that don't carry
    /// format metadata. The caller is responsible for ensuring the stride
    /// is valid.
    pub fn set_row_stride_unchecked(&mut self, stride: usize) {
        self.row_stride = Some(stride);
    }

    /// Builder-style variant of [`set_row_stride`](Self::set_row_stride),
    /// consuming and returning `self`.
    ///
    /// # Errors
    ///
    /// Same conditions as [`set_row_stride`](Self::set_row_stride).
    pub fn with_row_stride(mut self, stride: usize) -> Result<Self> {
        self.set_row_stride(stride)?;
        Ok(self)
    }

    /// Byte offset within the DMA-BUF where image data starts (`None` = 0).
    pub fn plane_offset(&self) -> Option<usize> {
        self.plane_offset
    }

    /// The parent-image snapshot if this tensor is a [`view`](Self::view)/
    /// [`batch`](Self::batch) sub-region; `None` for a whole tensor. The GL
    /// backend keys its import on the parent geometry and renders this view as a
    /// `glViewport`/`glScissor` ROI at `(x, y, width, height)`. See [`ViewOrigin`].
    pub fn view_origin(&self) -> Option<ViewOrigin> {
        self.view_origin
    }

    /// Set the byte offset within the DMA-BUF where image data starts.
    ///
    /// Propagated to `EGL_DMA_BUF_PLANE0_OFFSET_EXT` on GPU import.
    /// Unlike [`set_row_stride`](Self::set_row_stride), no format is required
    /// since the offset is format-independent.
    pub fn set_plane_offset(&mut self, offset: usize) {
        self.plane_offset = Some(offset);
        // The offset consulted by `map()` lives inside the storage variant.
        // Keep it in sync with the wrapper field for every backing that
        // honors it; see also the clear sites in `set_format` and `reshape`.
        //
        // Note that `TensorStorage::Dma` is a cfg-multiplexed *name* rather
        // than one type -- `DmaTensor` on Linux, `IoSurfaceTensor` on
        // macOS/iOS, `AHardwareBufferTensor` on Android,
        // `D3d11TextureTensor` on Windows -- so each platform needs its own
        // arm below; a missing one would silently become a fall-through
        // rather than a compile error, which is how macOS went without one
        // for a while. The match is kept exhaustive (no `_ => {}`)
        // specifically so that hazard is a compile error, not a silent gap.
        match self.storage {
            TensorStorage::Mem(ref mut m) => m.set_offset(offset),
            #[cfg(target_os = "linux")]
            TensorStorage::Dma(ref mut dma) => dma.mmap_offset = offset,
            // The offset `IoSurfaceTensor::scoped_pin`/`map_inner` add to the
            // locked base address. Writing it here is what makes a
            // *reconstructed* view address its own sub-region instead of the
            // parent surface's origin; `IoSurfaceTensor::view` already set it
            // on the fresh-view path, which is why only the descriptor round
            // trip was ever wrong. Idempotent against `subview`, which sets
            // the same absolute value by both routes -- pinned by
            // `nested_iosurface_subviews_do_not_compound_their_plane_offset`.
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(ref mut io) => io.view_offset = offset,
            // The offset every `D3d11TextureTensor` pin adds to its host or
            // staging base, in backing (pitched) space like `row_stride()`.
            // `view()` bounds-checks the value it computes; this route does
            // not, so the pins refuse an offset past the backing instead
            // (`check_view_offset` in `d3d11/texture.rs`). Pinned by the
            // `d3d11` plane-offset tests in `crates/tensor/tests`.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(ref mut tex) => tex.set_view_offset(offset),
            // The offset `PboTensor::scoped_pin` adds to the mapped base.
            // Writing it here is what makes a *reconstructed* view address
            // its own sub-region instead of the parent buffer's origin;
            // `PboTensor::view` already set it on the fresh-view path, which
            // is why only the round trip was ever wrong -- the same shape
            // IOSurface had. Idempotent against `subview`, which sets the
            // same absolute value by both routes -- pinned by
            // `nested_pbo_subviews_do_not_compound_their_plane_offset`.
            //
            // Not `cfg`-gated, and deliberately so: unlike
            // `TensorStorage::Dma` -- a cfg-multiplexed *name* whose gated
            // arm silently becomes `_ => {}` on the other targets, the
            // mechanism behind this whole issue class -- `TensorStorage::Pbo`
            // is one type on every platform.
            TensorStorage::Pbo(ref mut p) => p.view_offset = offset,
            // The offset `ShmTensor::map_inner`/`host_pin` add to the mmap
            // base, exactly like `MemTensor::offset`. `cfg(unix)` here
            // mirrors `TensorStorage::Shm`'s own gate on the enum
            // definition -- it is not a per-OS multiplex the way
            // `TensorStorage::Dma` is, so this arm cannot silently become
            // `_ => {}` on a target where the `Shm` variant still exists.
            #[cfg(unix)]
            TensorStorage::Shm(ref mut s) => s.set_offset(offset),
            // STILL INCOMPLETE: `AHardwareBufferTensor` (Android) has a
            // `view_offset` that its own `map()` adds and its own `view()`
            // sets, but nothing writes it here yet, so restoring an offset
            // onto an already-built tensor is silently a no-op on this
            // backing -- a caller gets a map at the parent's origin. Not
            // reachable through `TensorDyn::import_descriptor` today
            // (`import_storage`'s DMABUF arm is `cfg(target_os = "linux")`),
            // so it is latent rather than silent. See
            // `edgefirst-python-common`'s `interop::apply_plane_offset` for
            // the full per-backing accounting. PBO and Shm were on this list
            // until Stage B of the client-side-state work gave them the arms
            // above.
            #[cfg(target_os = "android")]
            TensorStorage::Dma(_) => {}
        }
    }

    /// Colorimetry metadata (`None` = undefined; never auto-filled).
    /// The CPU access declared for this tensor at allocation (see
    /// [`CpuAccess`]). Views share their parent's declaration.
    pub fn cpu_access(&self) -> CpuAccess {
        self.cpu_access
    }

    /// Set the declared CPU access without re-allocating — crate-private:
    /// the declaration must reflect the underlying allocation's real
    /// capabilities (constructors and importers set it; arbitrary widening
    /// would defeat the contract).
    // Only the Android AHardwareBuffer importer derives a declaration from
    // an existing allocation's usage bits today.
    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
    pub(crate) fn set_cpu_access_unchecked(&mut self, access: CpuAccess) {
        self.cpu_access = access;
    }

    /// The vendor tile-compression scheme recorded at allocation, or
    /// `None` for a linear layout. `Some` means the pixels live in a
    /// proprietary tile order: the row-stride accessors describe no
    /// meaningful linear layout and CPU maps are best-effort (see
    /// [`Compression`]). Only Android hardware-only allocations that
    /// requested compression record a scheme.
    pub fn compression(&self) -> Option<CompressionScheme> {
        self.compression
    }

    /// Record the compression scheme — crate-private: recording is an
    /// allocation-time fact ([`Tensor::image_desc`] sets it; arbitrary
    /// mutation would misdescribe the physical layout).
    // Only the Android allocation path records a scheme today.
    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
    pub(crate) fn set_compression_unchecked(&mut self, scheme: Option<CompressionScheme>) {
        self.compression = scheme;
    }

    pub fn colorimetry(&self) -> Option<crate::Colorimetry> {
        self.colorimetry
    }

    /// Attach/clear colorimetry metadata.
    pub fn set_colorimetry(&mut self, c: Option<crate::Colorimetry>) {
        self.colorimetry = c;
    }

    /// Builder-style colorimetry attach.
    pub fn with_colorimetry(mut self, c: crate::Colorimetry) -> Self {
        self.colorimetry = Some(c);
        self
    }

    /// Create a zero-copy sub-region view of this tensor's backing buffer.
    ///
    /// The returned tensor shares this tensor's allocation (no copy) and maps
    /// the window `[offset_bytes, offset_bytes + shape.product()*size_of::<T>())`
    /// measured from this tensor's own logical start. N sub-views into one
    /// parent can be written independently, enabling batched assembly into a
    /// single buffer. Identical semantics across `Mem` (shared `Arc`) and
    /// `Dma` (shared fd) backings.
    ///
    /// # Disjointness
    ///
    /// Independent writes are sound *only* when the windows do not overlap. The
    /// shared backing uses interior mutability (`UnsafeCell` cells), so two
    /// sub-views whose byte ranges intersect alias the same cells: writing one
    /// while reading or writing the other is a data race and therefore
    /// **undefined behaviour**. The caller is responsible for keeping the
    /// windows disjoint; this method does not check for overlap.
    ///
    /// # Errors
    ///
    /// - [`Error::InvalidOperation`] if the backing is not `Mem` or `Dma`, or
    ///   if `offset_bytes` is not a multiple of `align_of::<T>()`.
    /// - [`Error::InsufficientCapacity`] / [`Error::InvalidSize`] if the window
    ///   exceeds the parent allocation.
    pub(crate) fn subview(&self, offset_bytes: usize, shape: &[usize]) -> Result<Tensor<T>> {
        // Offset is absolute into the backing allocation: a sub-view of a
        // sub-view composes by adding this tensor's own offset.
        let abs_offset = self
            .plane_offset
            .unwrap_or(0)
            .checked_add(offset_bytes)
            .ok_or(Error::InvalidSize(offset_bytes))?;
        // Every backend exposes `view(offset, shape)` via `TensorTrait`, sharing
        // the resource AND `BufferIdentity` (unlike `from_fd`/`from_surface`,
        // which mint a fresh identity). The GL backend keys the import on the
        // shared identity so offset-distinct sub-views of one buffer reuse a
        // single import and address their window via `glViewport`. `Mem`/`Shm`
        // share via the allocation `Arc` / a cloned fd; `Pbo` via the GL-buffer
        // `Arc`; Linux DMA-BUF / macOS IOSurface via the shared fd / CFRetain.
        // `TensorStorage::view` performs the one remaining per-variant dispatch.
        let mut t = Tensor::wrap(self.storage.view(offset_bytes, shape)?);
        // Inherit the parent's image metadata so the view is a ready-to-use
        // sub-image (e.g. a `convert()` destination). The offset is applied
        // LAST because `set_format` deliberately clears it — the offset is a
        // structural property of the sub-region, not format-dependent metadata.
        if let Some(fmt) = self.format {
            t.set_format(fmt)?;
        }
        if let Some(rs) = self.row_stride {
            t.set_row_stride_unchecked(rs);
        }
        t.quantization = self.quantization.clone();
        // A sub-region of an image carries the parent's colorimetry — it is the
        // same pixels, same color encoding. Inherit it like the other image
        // metadata above so a sub-view is a faithful convert() source/target.
        t.set_colorimetry(self.colorimetry);
        // The declared CPU access is a property of the underlying
        // allocation, so every view shares the parent's declaration.
        t.cpu_access = self.cpu_access;
        // Likewise the recorded compression scheme: the view shares the
        // parent's physical layout.
        t.compression = self.compression;
        if abs_offset > 0 {
            t.set_plane_offset(abs_offset);
        }
        Ok(t)
    }

    /// Borrow batch element `n` of a batched tensor as a zero-copy view.
    ///
    /// A batched tensor prepends `N` as the leading dimension over the
    /// per-element image layout (`[N, H, W, C]` packed or `[N, C, H, W]`
    /// planar) — `N` is over the whole per-element block regardless of
    /// `HWC`/`CHW`. `batch(n)` returns element `n`: the contiguous per-element
    /// region at byte offset `n * element_size`, sharing the parent's
    /// `BufferIdentity` and inheriting its format / row stride / colorimetry.
    /// `batch(0)` on a tensor with `N == 1` is equivalent to the whole tensor.
    ///
    /// # Errors
    ///
    /// - [`Error::BatchIndexOutOfBounds`] if `n >= N`.
    /// - [`Error::InvalidShape`] if the tensor is not batched (a formatted
    ///   tensor whose rank lacks the leading `N`, or an empty shape).
    pub fn batch(&self, n: usize) -> Result<Tensor<T>> {
        let shape = self.shape();
        // With a format we know the exact per-element rank, so a missing leading
        // `N` is a misuse we reject rather than silently treating a spatial dim
        // as the batch. Raw tensors take shape[0] as `N` by contract.
        if let Some(fmt) = self.format {
            let elem_rank = match fmt.layout() {
                PixelLayout::SemiPlanar => 2,
                _ => 3,
            };
            if shape.len() != elem_rank + 1 {
                return Err(Error::InvalidShape(format!(
                    "batch(): tensor is not batched ({fmt:?} expects a leading N over a \
                     {elem_rank}-D element, got shape {shape:?})"
                )));
            }
        }
        let batch = *shape
            .first()
            .ok_or_else(|| Error::InvalidShape("batch(): empty shape".into()))?;
        if n >= batch {
            return Err(Error::BatchIndexOutOfBounds { index: n, batch });
        }
        let elem_shape: Vec<usize> = shape[1..].to_vec();
        let elem_count: usize = elem_shape.iter().product();
        let elem_bytes = elem_count
            .checked_mul(std::mem::size_of::<T>())
            .ok_or(Error::InvalidSize(elem_count))?;
        let offset = n.checked_mul(elem_bytes).ok_or(Error::InvalidSize(n))?;
        // For a packed `[N, H, W, C]` tensor the N tiles stack vertically in the
        // shared buffer, so the GL import sees one `(W, N*H)` parent and each
        // tile is the row-band at `y = n*H`. Snapshot that parent so the backend
        // imports once and renders the tile via `glViewport`. Non-packed
        // (planar/semi-planar) batching keeps the per-slot path for now (planar
        // NCHW tiling is a separate step); raw tensors have no pixel geometry.
        let view_origin = match self.format.map(|f| f.layout()) {
            Some(PixelLayout::Packed) => {
                let tile_h = elem_shape[0];
                let tile_w = elem_shape[1];
                // Per-row pitch of the tall `(W, N*H)` parent — padded stride if
                // set, else the tight row width. The GL import keys on this.
                let bpp = elem_shape[2] * std::mem::size_of::<T>();
                let parent_stride = self.effective_row_stride().unwrap_or(tile_w * bpp);
                Some(self.compose_view_origin(tile_w, batch * tile_h, parent_stride, 0, n * tile_h))
            }
            _ => None,
        };
        let mut t = self.subview(offset, &elem_shape)?;
        t.view_origin = view_origin;
        Ok(t)
    }

    /// Borrow a rectangular spatial sub-region of an image tensor as a
    /// zero-copy view — the **destination/source crop** primitive.
    ///
    /// `region` is in pixels of the image's leading frame. The returned view
    /// shares the parent's `BufferIdentity` and addresses the sub-rectangle by
    /// offset + the **parent's** row pitch (so each row lands at the correct
    /// columns). `convert(src, &mut dst.view(rect), …)` renders into that
    /// sub-rectangle of `dst`; a letterbox fit then clears the view and renders
    /// the aspect-preserved content into its inner region. `view`/`batch`/the
    /// whole tensor are the one coherent destination model — there is no
    /// separate `dst_rect`.
    ///
    /// # Known limitation: bottom-right multi-row views
    ///
    /// A multi-row view is mapped as `parent_pitch × rows` bytes **from its own
    /// offset**, so the window it asks for overruns the allocation by
    /// `region.x * bpp` whenever the view is both offset horizontally *and*
    /// reaches the parent's last row. Such a view constructs fine but fails at
    /// [`map`](TensorTrait::map) time with [`Error::InsufficientCapacity`] —
    /// loudly, never as an out-of-bounds access. For a tiled destination this is
    /// the bottom row of tiles at every column but the first. The single-row
    /// case is already special-cased below (it keeps its own tight stride); the
    /// general fix is to clamp the last row's exposure to the view's own row
    /// bytes, which is not yet implemented.
    ///
    /// # Errors
    ///
    /// - [`Error::RegionOutOfBounds`] if `region` exceeds the image bounds.
    /// - [`Error::InvalidOperation`] if the tensor is not a packed-format image
    ///   (planar/semi-planar spatial sub-rects are not a single strided window;
    ///   use [`batch`](Self::batch) for batched planar tensors).
    pub fn view(&self, region: Region) -> Result<Tensor<T>> {
        let fmt = self.format.ok_or_else(|| {
            Error::InvalidOperation("view() requires a formatted image tensor".into())
        })?;
        if fmt.layout() != PixelLayout::Packed {
            return Err(Error::InvalidOperation(format!(
                "view() supports packed formats only (got {fmt:?}); use batch(n) for batched \
                 planar tensors"
            )));
        }
        let w = self
            .width()
            .ok_or_else(|| Error::InvalidOperation("view(): tensor has no image width".into()))?;
        let h = self
            .height()
            .ok_or_else(|| Error::InvalidOperation("view(): tensor has no image height".into()))?;
        if !region.fits_within(w, h) {
            return Err(Error::RegionOutOfBounds {
                region,
                bounds: (w, h),
            });
        }
        let elem = std::mem::size_of::<T>();
        let bpp = fmt.channels() * elem;
        let stride = self.effective_row_stride().unwrap_or(w * bpp);
        let offset = region
            .y
            .checked_mul(stride)
            .and_then(|yo| yo.checked_add(region.x.checked_mul(bpp)?))
            .ok_or(Error::InvalidSize(region.y))?;
        let sub_shape = fmt
            .allocation_shape(region.width, region.height)
            .ok_or_else(|| Error::InvalidShape(format!("view(): invalid shape for {fmt:?}")))?;
        let mut t = self.subview(offset, &sub_shape)?;
        // A multi-row sub-rect must advance rows by the PARENT pitch so each row
        // addresses the correct columns. A single-row view uses its own tight
        // stride — the parent pitch would make the strided `map()` (which exposes
        // `stride × rows`) expose a trailing row that runs past the buffer tail
        // for an offset (x>0 / bottom) view. The GL backend does NOT rely on this
        // (single-row-tight) `row_stride`: it reads the parent pitch from
        // `view_origin.parent_row_stride` so its import/cache pitch stays
        // parent-consistent for views of any height — see `ViewOrigin`.
        let view_stride = if region.height > 1 {
            stride
        } else {
            region.width * bpp
        };
        t.set_row_stride_unchecked(view_stride);
        // Snapshot the parent `(w, h, row_stride)` so the GL backend imports the
        // parent once (keyed on the parent pitch, not this view's possibly-tight
        // single-row stride) and renders this sub-rect as a `glViewport`/
        // `glScissor` ROI at `(region.x, region.y)`. Composes when viewing an
        // existing view.
        t.view_origin = Some(self.compose_view_origin(w, h, stride, region.x, region.y));
        Ok(t)
    }

    /// Build the [`ViewOrigin`] for a new sub-region of `self`. When `self` is a
    /// whole tensor the snapshot names `self` as the parent; when `self` is
    /// already a view, the snapshot keeps the **root** parent and accumulates the
    /// local origin so nested views still resolve to one import.
    fn compose_view_origin(
        &self,
        parent_width: usize,
        parent_height: usize,
        parent_row_stride: usize,
        x: usize,
        y: usize,
    ) -> ViewOrigin {
        match self.view_origin {
            Some(root) => ViewOrigin {
                parent_width: root.parent_width,
                parent_height: root.parent_height,
                parent_row_stride: root.parent_row_stride,
                x: root.x.saturating_add(x),
                y: root.y.saturating_add(y),
            },
            None => ViewOrigin {
                parent_width,
                parent_height,
                parent_row_stride,
                x,
                y,
            },
        }
    }

    /// The wrapped `PboTensor`, for this module's own PBO accessors.
    ///
    /// Crate-private: `PboTensor<T>` is a `static`-side value with no
    /// `dynamic` counterpart to lend (there the buffer lives inside
    /// `libedgefirst_tensor.so`), so a public borrow of it could not have
    /// the same signature on both backends. Callers use
    /// [`Self::pbo_id`]/[`Self::pbo_is_mapped`], which are the whole surface
    /// `edgefirst-image` ever used.
    pub(crate) fn as_pbo(&self) -> Option<&PboTensor<T>> {
        match &self.storage {
            TensorStorage::Pbo(p) => Some(p),
            _ => None,
        }
    }

    /// The GL buffer ID backing this tensor (for GL backends / the
    /// cross-package protocol's `handle`). `None` when the tensor is not
    /// PBO-backed.
    pub fn pbo_id(&self) -> Option<u32> {
        self.as_pbo().map(PboTensor::buffer_id)
    }

    /// Whether this PBO currently holds -- or is establishing -- a CPU
    /// mapping. `None` when the tensor is not PBO-backed.
    ///
    /// The question a GL caller is really asking is "is this buffer free
    /// for GL operations?", so a map or unmap still in flight answers
    /// `Some(true)`: the GL side must not touch the buffer until the
    /// transition finishes. See [`PboTensor::is_mapped`].
    pub fn pbo_is_mapped(&self) -> Option<bool> {
        self.as_pbo().map(PboTensor::is_mapped)
    }

    /// The C-ABI `PboOpsVtable` address backing this tensor (for the
    /// cross-package protocol's `ptr` under `kind::PBO`; see
    /// [`crate::protocol::TensorDesc::ptr`]'s doc comment). `None` when the
    /// tensor is not PBO-backed.
    pub fn pbo_vtable_ptr(&self) -> Option<*const std::ffi::c_void> {
        self.as_pbo()
            .map(|p| p.pbo_vtable() as *const _ as *const std::ffi::c_void)
    }

    /// A type-erased keepalive that must stay alive for at least as long as
    /// [`Self::pbo_vtable_ptr`]'s address is used -- see
    /// [`PboTensor::pbo_keepalive`]'s own doc comment. `None` when the
    /// tensor is not PBO-backed.
    pub fn pbo_keepalive(&self) -> Option<Arc<dyn Send + Sync>> {
        self.as_pbo().map(PboTensor::pbo_keepalive)
    }

    /// Downcast to DMA tensor reference (for EGL import, G2D).
    #[cfg(target_os = "linux")]
    pub fn as_dma(&self) -> Option<&DmaTensor<T>> {
        match &self.storage {
            TensorStorage::Dma(d) => Some(d),
            _ => None,
        }
    }

    /// Borrow the DMA-BUF file descriptor backing this tensor.
    ///
    /// # Returns
    ///
    /// A borrowed reference to the DMA-BUF file descriptor, tied to `self`'s
    /// lifetime.
    ///
    /// # Errors
    ///
    /// Returns `Error::NotImplemented` if the tensor is not DMA-backed.
    #[cfg(target_os = "linux")]
    pub fn dmabuf(&self) -> Result<std::os::fd::BorrowedFd<'_>> {
        use std::os::fd::AsFd;
        match &self.storage {
            TensorStorage::Dma(dma) => Ok(dma.fd.as_fd()),
            _ => Err(Error::NotImplemented(format!(
                "dmabuf requires DMA-backed tensor, got {:?}",
                self.storage.memory()
            ))),
        }
    }

    /// Construct a Tensor from a PBO tensor (for GL backends that allocate PBOs).
    ///
    /// Infallible in this backend (`Ok` always) -- kept as `Result` to match
    /// `dynamic`'s own `Tensor::from_pbo` (`dynamic_tensor.rs`), which
    /// genuinely can fail: it must allocate a real `ef_tensor_*` handle
    /// alongside `pbo` to carry shape/dtype/format metadata (this backend
    /// has nowhere else to put it), an allocation this backend never
    /// needed since it just wraps `pbo` into `TensorStorage::Pbo` directly.
    /// One shared, fallible signature lets `edgefirst-image`'s own call
    /// sites (`gl/threaded.rs`) stay backend-agnostic.
    pub fn from_pbo(pbo: PboTensor<T>) -> Result<Self> {
        Ok(Self {
            storage: TensorStorage::Pbo(pbo),
            format: None,
            chroma: None,
            row_stride: None,
            plane_offset: None,
            quantization: None,
            cuda: None,
            colorimetry: None,
            cpu_access: CpuAccess::ReadWrite,
            compression: None,
            view_origin: None,
        })
    }

    /// The CUDA registration for this tensor, if any (set at creation on CUDA devices).
    pub fn cuda(&self) -> Option<&crate::cuda::CudaHandle> {
        self.cuda.as_ref()
    }

    /// Attach a CUDA handle (called by ImageProcessor::create_image after registering a PBO).
    pub fn set_cuda_handle(&mut self, h: crate::cuda::CudaHandle) {
        self.cuda = Some(h);
    }

    /// Fast-fail CUDA map: None (no GL routing) when no handle; else map (PBO routes to the GL worker).
    ///
    /// Returns a scoped [`CudaMap`] guard holding the raw CUDA device pointer
    /// for the duration of the mapping. For GL-buffer-backed tensors the unmap is deferred until the
    /// guard drops, freeing the PBO for the next `convert()` call. When no CUDA handle is attached
    /// (the common case for plain `Mem`/`DMA` tensors without CUDA registration), returns `None`
    /// immediately — no GL routing, no allocation.
    ///
    /// # Example — zero-copy CUDA input with host fallback
    ///
    /// ```no_run
    /// use edgefirst_tensor::{Tensor, TensorMemory, TensorTrait};
    /// # fn feed_tensorrt(_dptr: *mut std::ffi::c_void, _bytes: usize) {}
    /// # fn demo(t: &Tensor<f32>) {
    /// // Try the zero-copy CUDA device pointer first.
    /// if let Some(cuda) = t.cuda_map() {
    ///     feed_tensorrt(cuda.device_ptr(), cuda.len());
    ///     // `cuda` (a CudaMap guard) unmaps when it goes out of scope, freeing
    ///     // the GPU buffer for the next convert().
    /// } else {
    ///     // Fall back to the host mapping when no CUDA handle is attached.
    ///     let _host = t.map().expect("host map fallback must succeed");
    ///     // `_host` is a TensorMap<f32> that derefs to &[f32].
    /// }
    /// # }
    /// ```
    ///
    /// # D3D11 texture tensors: the mapping is tight rows
    ///
    /// On Windows the mapping is a linear copy of the texture laid out at
    /// `width * bytes_per_texel`, and `len()` is that times the row count --
    /// *not* [`row_stride`](Self::row_stride), which reports the D3D11 staging
    /// pitch a CPU map sees and is the larger number on a padded backing. A
    /// consumer that strides the device pointer by `row_stride()` reads past
    /// the end of the mapping.
    ///
    /// Semi-planar formats (NV12, NV16, NV24) are the exception: their texture
    /// is allocated as wide as its own row pitch, so the tight row *is* the
    /// pitch and the mapping equals `row_stride() x combined_height` bytes.
    /// Striding the device pointer by `row_stride()` is exactly right there.
    pub fn cuda_map(&self) -> Option<crate::cuda::CudaMap<'_>> {
        self.cuda.as_ref()?.map()
    }

    /// Writable counterpart of [`cuda_map`](Self::cuda_map). See
    /// [`CudaHandle::map_mut`](crate::cuda::CudaHandle::map_mut) for which
    /// backings distinguish the two.
    ///
    /// The D3D11 arm is the one that does: the guard's release copies the
    /// buffer back into the texture. Its layout is [`cuda_map`](Self::cuda_map)'s
    /// -- tight rows of `width * bytes_per_texel`, not `row_stride()` -- and
    /// writing it at the wrong pitch scrambles the image rather than failing.
    pub fn cuda_map_mut(&self) -> Option<crate::cuda::CudaMap<'_>> {
        self.cuda.as_ref()?.map_mut()
    }

    /// Attempt to attach a CUDA `ExternalMemory` handle for DMA-backed tensors.
    ///
    /// On a CUDA-capable host, imports the DMA-BUF fd via
    /// `cudaImportExternalMemory(OpaqueFd)` and maps it to a device pointer.
    /// Sets `self.cuda` to a persistent `ExternalMem` handle on success. No-op
    /// if CUDA is unavailable, the tensor is not DMA-backed, or a handle is
    /// already set. Import failure is silently ignored — the tensor remains
    /// usable without a CUDA handle.
    ///
    /// # RUNTIME-UNVALIDATED
    ///
    /// No test platform has both `/dev/dma_heap` and a CUDA device. ABI is
    /// layout-asserted vs. CUDA 12.6 `driver_types.h`; the mechanism is proven
    /// by gpu-probe O5 on Orin. Best-effort: tensor creation never fails here.
    #[cfg(target_os = "linux")]
    pub fn try_init_dma_cuda(&mut self) {
        // Fast-path: already imported, CUDA not available, or not a DMA tensor.
        if self.cuda.is_some() || !crate::cuda::is_cuda_available() {
            return;
        }
        let (raw_fd, buf_size) = match &self.storage {
            TensorStorage::Dma(dma) => {
                use std::os::fd::AsRawFd;
                (dma.fd.as_raw_fd(), dma.buf_size)
            }
            _ => return,
        };
        if let Some((ext, dptr)) = crate::cuda::import_dma_fd(raw_fd, buf_size) {
            self.cuda = Some(crate::cuda::CudaHandle::new_external(ext, dptr, buf_size));
        }
    }

    /// Attempt to attach a CUDA external-memory handle for D3D11 texture
    /// tensors — the Windows counterpart of
    /// [`try_init_dma_cuda`](Self::try_init_dma_cuda).
    ///
    /// Imports the texture's shared NT handle via
    /// `cudaImportExternalMemory(D3D11Resource)` and the process device's
    /// fence as an external semaphore, so [`cuda_map`](Self::cuda_map) hands
    /// out a linear device buffer whose refresh is ordered after the D3D11
    /// work a producer recorded with [`set_gpu_write`](Self::set_gpu_write).
    ///
    /// No-op when a handle is already attached or the tensor is not
    /// texture-backed. Import failure is silently ignored: the WARP adapter
    /// has no CUDA device at all, and a texture whose import fails is still a
    /// valid tensor whose `cuda_map()` is `None`.
    #[cfg(target_os = "windows")]
    pub fn try_init_d3d11_cuda(&mut self) {
        if self.cuda.is_some() {
            return;
        }
        let TensorStorage::Dma(tex) = &self.storage else {
            return;
        };
        if let Some(h) = tex.try_init_cuda() {
            self.cuda = Some(h);
        }
    }
}

/// Windows D3D11 texture accessors. No `'static` bound: none of these needs
/// `dtype_of::<T>()`.
#[cfg(all(feature = "static", target_os = "windows"))]
impl<T> Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// The borrowed `ID3D11Texture2D*` backing this tensor, valid while the
    /// tensor lives. `None` when the tensor is not texture-backed.
    pub fn d3d11_texture(&self) -> Option<*mut std::ffi::c_void> {
        match &self.storage {
            TensorStorage::Dma(t) => Some(t.texture_ptr()),
            _ => None,
        }
    }

    /// The texture geometry the HAL chose for this image: DXGI format, texel
    /// dimensions and the matching GL internal format. `None` when the tensor
    /// is not texture-backed.
    pub fn d3d11_layout(&self) -> Option<crate::d3d11_layout::D3d11ImageLayout> {
        match &self.storage {
            TensorStorage::Dma(t) => Some(t.layout()),
            _ => None,
        }
    }

    /// A duplicated NT handle the caller owns: open it on a D3D12 device,
    /// another D3D11 device, or CUDA, or duplicate it into another process.
    /// Closing it does not affect this tensor.
    pub fn d3d11_shared_handle(&self) -> Result<std::os::windows::io::OwnedHandle> {
        match &self.storage {
            TensorStorage::Dma(t) => t.shared_handle(),
            _ => Err(Error::NotImplemented(
                "not a D3D11 texture tensor".to_owned(),
            )),
        }
    }

    /// The fence handle plus value a GPU consumer waits on before reading this
    /// texture, or `None` when no GPU write has been recorded on it.
    pub fn gpu_completion(&self) -> Result<Option<crate::d3d11::GpuCompletion>> {
        match &self.storage {
            TensorStorage::Dma(t) => t.gpu_completion(),
            _ => Err(Error::NotImplemented(
                "not a D3D11 texture tensor".to_owned(),
            )),
        }
    }

    /// Record that GPU work writing this texture completes at `value` of the
    /// process device's fence. Monotonic: an older value never displaces a
    /// newer one, so recording out of order is safe rather than merely
    /// tolerated.
    ///
    /// Takes `&self`, not `&mut self`: the fence slot is an `AtomicU64` and
    /// this is a `fetch_max` on it. A producer records a write on the very
    /// tensor its consumers already hold and are reading, so demanding
    /// exclusive access here would forbid the one call this exists for.
    pub fn set_gpu_write(&self, value: u64) -> Result<()> {
        match &self.storage {
            TensorStorage::Dma(t) => {
                t.set_gpu_write(value);
                Ok(())
            }
            _ => Err(Error::NotImplemented(
                "not a D3D11 texture tensor".to_owned(),
            )),
        }
    }

    /// The tensor's own NT handle value -- not a duplicate -- for descriptors
    /// whose consumer keeps the producing tensor alive.
    ///
    /// Borrowed rather than duplicated because the C exports (task A6) hand
    /// out owned duplicates, which a `Copy` descriptor cannot close; the
    /// cross-package protocol's `kind::D3D11_TEXTURE` reads this instead.
    pub(crate) fn d3d11_shared_handle_value(&self) -> Option<usize> {
        match &self.storage {
            TensorStorage::Dma(t) => Some(t.shared_handle_value()),
            _ => None,
        }
    }
}

/// The recorded GPU write value, on every platform: the descriptor path and
/// the Python bindings forward it without a `cfg` of their own, and only
/// Windows can record one.
#[cfg(feature = "static")]
impl<T> Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// The fence value of the newest GPU write recorded on this tensor, or 0
    /// when there is none: the `value` of `gpu_completion` without the
    /// duplicated fence handle, for a consumer that already holds the process
    /// fence. 0 for a tensor that is not a D3D11 texture, and on every
    /// platform other than Windows.
    pub fn gpu_write_value(&self) -> u64 {
        #[cfg(target_os = "windows")]
        {
            if let TensorStorage::Dma(t) = &self.storage {
                return t.last_gpu_write();
            }
        }
        0
    }
}

/// Records the D3D11 backing's row pitch on `t` when it exceeds the natural
/// stride for its format and width.
///
/// The staging pitch is the row stride CPU consumers see, and for a
/// semi-planar tensor it is also the texture's own width, which the GL
/// backend's Path B shader takes as its `tex_width`. Three constructors need
/// it identically -- `Tensor::image`'s Windows arm and the two wrap
/// constructors below -- and a wrapped texture is the case that makes it
/// load-bearing: without it such a tensor reports the natural `even(width)`
/// stride while its texture is the driver's pitch wide, and the shader samples
/// a padded texture at the image width.
///
/// `t.format` must already be set: the natural stride comes from it.
#[cfg(all(feature = "static", target_os = "windows"))]
fn record_d3d11_row_stride<T>(t: &mut Tensor<T>, format: PixelFormat, what: &str)
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    let pitch = match &t.storage {
        TensorStorage::Dma(tex) => tex.image_backing_row_stride(),
        _ => None,
    };
    let (Some(pitch), Some(natural)) = (pitch, t.effective_row_stride()) else {
        return;
    };
    if pitch > natural {
        log::debug!(
            "{what}: the D3D11 backing pitch for the {format:?} texture is {pitch} bytes \
             (natural {natural}); recording row stride"
        );
        t.set_row_stride_unchecked(pitch);
    }
}

/// The two texture-importing constructors. Separate from the accessors above
/// because `dtype_of::<T>()` needs `T: 'static`.
#[cfg(all(feature = "static", target_os = "windows"))]
impl<T> Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync + 'static,
{
    /// Wrap an existing `ID3D11Texture2D` as a tensor. The texture is checked
    /// against the layout the HAL would have chosen for `format`/`width`/
    /// `height` and must live on the HAL's process device; ownership stays
    /// with the caller, since this takes its own reference.
    ///
    /// The backing's row pitch is recorded as the tensor's
    /// [`row_stride`](Self::row_stride) when it exceeds the natural stride, so
    /// a wrapped semi-planar texture -- whose width *is* the pitch -- reports
    /// the geometry its consumers address it by.
    ///
    /// # Safety
    ///
    /// `texture` must be null or a live `ID3D11Texture2D` created on the HAL
    /// device ([`crate::d3d11::device()`]).
    pub unsafe fn from_d3d11_texture(
        texture: *mut std::ffi::c_void,
        width: usize,
        height: usize,
        format: PixelFormat,
        access: CpuAccess,
        name: Option<&str>,
    ) -> Result<Self> {
        let dtype = dtype_of::<T>().ok_or_else(|| {
            Error::InvalidArgument(format!(
                "from_d3d11_texture: element type {} has no DType",
                std::any::type_name::<T>()
            ))
        })?;
        let shape = format.allocation_shape(width, height).ok_or_else(|| {
            Error::InvalidArgument(format!(
                "invalid dimensions {width}x{height} for format {format:?}"
            ))
        })?;
        // SAFETY: the caller guarantees `texture` is null or a live
        // `ID3D11Texture2D`; the storage takes its own reference.
        let storage = unsafe {
            crate::d3d11::texture::D3d11TextureTensor::<T>::from_d3d11_texture(
                texture, width, height, format, dtype, &shape, access, name,
            )
        }?;
        let mut t = Self::wrap(TensorStorage::Dma(storage));
        t.format = Some(format);
        record_d3d11_row_stride(&mut t, format, "from_d3d11_texture");
        t.cpu_access = access;
        t.try_init_d3d11_cuda();
        Ok(t)
    }

    /// Open a shared texture by its NT handle on the HAL's device. When
    /// `completion` is given, its fence value is waited for on the immediate
    /// context, so a same-device reader needs no further ordering. Both
    /// handles stay owned by the caller: this duplicates what it keeps.
    ///
    /// Records the backing's row pitch as
    /// [`row_stride`](Self::row_stride) on the same rule as
    /// [`from_d3d11_texture`](Self::from_d3d11_texture).
    ///
    /// # Safety
    ///
    /// `handle` must be an NT shared handle of a D3D11 texture, valid in this
    /// process, and `completion`'s handle a shared fence handle.
    pub unsafe fn from_d3d11_shared_handle(
        handle: std::os::windows::io::RawHandle,
        width: usize,
        height: usize,
        format: PixelFormat,
        access: CpuAccess,
        completion: Option<(std::os::windows::io::RawHandle, u64)>,
        name: Option<&str>,
    ) -> Result<Self> {
        let dtype = dtype_of::<T>().ok_or_else(|| {
            Error::InvalidArgument(format!(
                "from_d3d11_shared_handle: element type {} has no DType",
                std::any::type_name::<T>()
            ))
        })?;
        let shape = format.allocation_shape(width, height).ok_or_else(|| {
            Error::InvalidArgument(format!(
                "invalid dimensions {width}x{height} for format {format:?}"
            ))
        })?;
        // SAFETY: the caller guarantees the handles are valid in this process.
        let storage = unsafe {
            crate::d3d11::texture::D3d11TextureTensor::<T>::from_d3d11_shared_handle(
                handle, width, height, format, dtype, &shape, access, completion, name,
            )
        }?;
        let mut t = Self::wrap(TensorStorage::Dma(storage));
        t.format = Some(format);
        record_d3d11_row_stride(&mut t, format, "from_d3d11_shared_handle");
        t.cpu_access = access;
        t.try_init_d3d11_cuda();
        Ok(t)
    }
}

// Quantization accessors — type-gated to integer element types via the
// sealed `IntegerType` trait. Calling `.quantization()` on a `Tensor<f32>`
// produces a compile error, not a runtime one.
#[cfg(feature = "static")]
impl<T> Tensor<T>
where
    T: IntegerType + Num + Clone + fmt::Debug + Send + Sync,
{
    /// Quantization metadata for this tensor, if set.
    pub fn quantization(&self) -> Option<&Quantization> {
        self.quantization.as_ref()
    }

    /// Attach quantization metadata to this tensor. Validates against the
    /// tensor's shape — returns [`Error::QuantizationInvalid`] on any
    /// inconsistency (mismatched scale/zp lengths, out-of-range axis, etc.).
    pub fn set_quantization(&mut self, q: Quantization) -> Result<()> {
        q.validate(self.shape())?;
        self.quantization = Some(q);
        Ok(())
    }

    /// Builder-style variant of [`Self::set_quantization`]. Consumes `self`
    /// and returns `Result<Self>` — on success yields the tensor with the
    /// attached quantization; on validation failure returns
    /// [`Error::QuantizationInvalid`] and drops `self` (the tensor is not
    /// returned in the error arm).
    pub fn with_quantization(mut self, q: Quantization) -> Result<Self> {
        self.set_quantization(q)?;
        Ok(self)
    }

    /// Clear any quantization metadata on this tensor.
    pub fn clear_quantization(&mut self) {
        self.quantization = None;
    }
}

#[cfg(feature = "static")]
fn map_strided_host_view<'a, T>(
    tensor: &Tensor<T>,
    stride: usize,
    access: CpuAccess,
    non_blocking: bool,
) -> Result<crate::view::HostView<'a, T>>
where
    T: Num + Clone + fmt::Debug + Send + Sync + 'a,
{
    // Rows sit at `stride`-byte spacing. The row count is the first
    // shape dim for packed `[H, W, C]` and semi-planar `[H*k, W]`,
    // but planar `[C, H, W]` stacks C planes of H rows — its surface
    // row count is `C × H` (`shape[0]` alone would expose a 3-row
    // window and truncate the map; first hit by Android planar-F16
    // AHardwareBuffers, whose gralloc pads the pitch — macOS/Linux
    // planar pitches happen to be naturally aligned so no stride was
    // ever recorded there).
    let rows = strided_map_rows(tensor)?;
    let total_bytes = stride.checked_mul(rows).ok_or_else(|| {
        Error::InvalidOperation(format!(
            "Tensor::map: row_stride {stride} × rows {rows} overflows usize"
        ))
    })?;
    map_strided_storage(tensor, stride, rows, total_bytes, access, non_blocking)
}

#[cfg(feature = "static")]
fn strided_map_rows<T>(tensor: &Tensor<T>) -> Result<usize>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    match tensor.format.map(|f| f.layout()) {
        Some(PixelLayout::Planar) => {
            let s = tensor.shape();
            if s.len() < 2 {
                return Err(Error::InvalidOperation(
                    "Tensor::map: strided planar mapping requires [C, H, W] shape".into(),
                ));
            }
            s[0].checked_mul(s[1]).ok_or_else(|| {
                Error::InvalidOperation(format!(
                    "Tensor::map: planar rows {} × {} overflows usize",
                    s[0], s[1]
                ))
            })
        }
        _ => tensor.shape().first().copied().ok_or_else(|| {
            Error::InvalidOperation(
                "Tensor::map: strided mapping requires a non-empty shape".into(),
            )
        }),
    }
}

#[cfg(feature = "static")]
fn map_strided_storage<'a, T>(
    tensor: &Tensor<T>,
    _stride: usize,
    _rows: usize,
    total_bytes: usize,
    access: CpuAccess,
    _non_blocking: bool,
) -> Result<crate::view::HostView<'a, T>>
where
    T: Num + Clone + fmt::Debug + Send + Sync + 'a,
{
    match &tensor.storage {
        #[cfg(target_os = "linux")]
        TensorStorage::Dma(dma) => {
            // `set_row_stride()` only validates `stride >= min_stride`,
            // not that `stride × rows` fits the DMA-BUF, so re-check
            // here — mapping past `buf_size` would SIGBUS on access.
            // `buf_size` is real kernel truth either way, not the
            // importer's say-so: for a self-allocated tensor it is
            // the allocation size; for an imported one it is
            // `fstat`-derived when the kernel reports a usable size
            // (`DmaTensor::from_fd`), or the declared logical size in
            // the rare fallback -- either way an out-of-range mmap
            // against the real dma-buf is still rejected by the
            // kernel, so this bound stays sound regardless.
            let available_bytes = dma.buf_size.saturating_sub(dma.mmap_offset);
            if total_bytes > available_bytes {
                return Err(Error::InvalidOperation(format!(
                    "Tensor::map: strided mapping needs {total_bytes} bytes \
                     but DMA buffer only has {available_bytes} available \
                     (buf_size={}, mmap_offset={}, stride={_stride}, rows={_rows}); \
                     the row_stride was likely set larger than the original allocation",
                    dma.buf_size, dma.mmap_offset
                )));
            }
            dma.map_with_byte_size(total_bytes, access)
        }
        TensorStorage::Mem(mem) => {
            let capacity = tensor.storage.capacity_bytes();
            if total_bytes > capacity {
                return Err(Error::InsufficientCapacity {
                    needed: total_bytes,
                    capacity,
                });
            }
            mem.map_with_byte_size(total_bytes, access)
        }
        #[cfg(unix)]
        TensorStorage::Shm(shm) => {
            let capacity = tensor.storage.capacity_bytes();
            if total_bytes > capacity {
                return Err(Error::InsufficientCapacity {
                    needed: total_bytes,
                    capacity,
                });
            }
            shm.map_with_byte_size(total_bytes, access)
        }
        // macOS/iOS: `TensorStorage::Dma` is the IOSurface. The lock yields
        // the full surface base address, and the row pitch
        // (`IOSurfaceGetBytesPerRow`) is known from the API for both
        // self-allocated and imported surfaces — unlike a foreign
        // DMA-BUF — so a strided CPU view is sound and zero-copy.
        #[cfg(any(target_os = "macos", target_os = "ios"))]
        TensorStorage::Dma(io) => {
            // A sub-view's window is `buf_size − view_offset`; the strided
            // span must fit the window, not the whole surface.
            let available = io.buf_size.saturating_sub(io.view_offset);
            if total_bytes > available {
                return Err(Error::InsufficientCapacity {
                    needed: total_bytes,
                    capacity: available,
                });
            }
            io.map_with_byte_size(total_bytes, access)
        }
        // Android: `TensorStorage::Dma` is the AHardwareBuffer. The lock
        // yields the full buffer base address, and the row pitch is
        // known from the allocator-filled descriptor — so a strided CPU
        // view is sound and zero-copy, same as IOSurface.
        #[cfg(target_os = "android")]
        TensorStorage::Dma(ahb) => {
            // A sub-view's window is `buf_size − view_offset`; the strided
            // span must fit the window, not the whole buffer.
            let available = ahb.buf_size.saturating_sub(ahb.view_offset);
            if total_bytes > available {
                return Err(Error::InsufficientCapacity {
                    needed: total_bytes,
                    capacity: available,
                });
            }
            ahb.map_with_byte_size(total_bytes, access)
        }
        // Windows: `TensorStorage::Dma` is the D3D11 texture, whose CPU side
        // is the staging copy at the driver's pitch -- the very pitch
        // `Tensor::image` recorded as this tensor's row stride. Its
        // `map_with_byte_size` bounds-checks the span against this tensor's
        // own window, as the IOSurface arm above does. This is also the only
        // backing with a real non-blocking map, so it is the only arm that
        // reads `_non_blocking`.
        #[cfg(target_os = "windows")]
        TensorStorage::Dma(tex) => {
            if _non_blocking {
                tex.try_map_with_byte_size(total_bytes, access)
            } else {
                tex.map_with_byte_size(total_bytes, access)
            }
        }
        TensorStorage::Pbo(pbo) => {
            // PBO: the GPU-side allocation may have a padded row stride
            // (e.g. 64-byte aligned). Expose the full padded buffer so a
            // CPU producer (JPEG decoder) and a strided convert source
            // can iterate rows via `effective_row_stride()` without
            // running past the slice — the logical `pbo.map()` view would
            // stop after `shape.product()` and lose bytes past row 0.
            // A sub-view's window is `capacity − view_offset`.
            let available = pbo.capacity_bytes().saturating_sub(pbo.view_offset);
            if total_bytes > available {
                return Err(Error::InsufficientCapacity {
                    needed: total_bytes,
                    capacity: available,
                });
            }
            pbo.map_with_byte_size(total_bytes, access)
        }
        // Every `TensorStorage` variant this build can construct is
        // matched explicitly above (Mem/Shm/Dma/Pbo, each cfg-gated
        // to the platforms it exists on) -- this catch-all exists
        // only so the match stays exhaustive across every
        // OS/cfg combination without a matching arm on every one of
        // them, not because any variant is meant to fall through to
        // it. `#[allow(unreachable_patterns)]` because on any given
        // platform it genuinely is unreachable.
        #[allow(unreachable_patterns)]
        _ => Err(Error::InvalidOperation(
            "CPU mapping of strided tensors is supported only for HAL-allocated \
             Mem/Shm (any platform), DMA (Linux, self-allocated or imported), \
             IOSurface (macOS), AHardwareBuffer (Android), D3D11 textures \
             (Windows), and PBO"
                .into(),
        )),
    }
}

#[cfg(feature = "static")]
impl<T> Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    /// The shared body of [`TensorTrait::map_with`] and
    /// [`TensorTrait::try_map_with`]: the direction check, the
    /// declared-vs-requested telemetry, the strided and plane-offset routing,
    /// and finally the backing's own map. `non_blocking` chooses which of the
    /// backing's two maps that last step takes; everything before it is the
    /// same either way.
    fn map_impl<'a>(
        &self,
        access: CpuAccess,
        non_blocking: bool,
    ) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        let _span = tracing::trace_span!(
            "tensor.map",
            memory = ?self.storage.memory(),
            ?access,
            non_blocking,
        )
        .entered();
        if access == CpuAccess::None {
            return Err(Error::InvalidArgument(
                "map_with(CpuAccess::None) is not a mappable direction — use \
                 map_read()/map_write()/map_mut()"
                    .into(),
            ));
        }
        // Declared-vs-requested telemetry (all platforms): mapping beyond
        // the allocation-time declaration is best-effort — tolerated where
        // the backing is CPU-mappable regardless (Mem/Shm/dma-buf/
        // IOSurface), refused by the Android backend for CpuAccess::None
        // buffers — but always loud and counted, never silent.
        if !self.cpu_access.covers(access) {
            note_unplanned_cpu_access(
                self.buffer_identity().id(),
                &format!("{:?}", self.storage.memory()),
                "map access exceeds the declared CpuAccess",
            );
        }
        // CPU mapping of a strided tensor exposes the full padded buffer
        // (`row_stride × rows`) so callers can iterate rows via
        // `effective_row_stride()` without running past the slice. This is sound
        // only when the HAL owns and can size-check the allocation:
        //
        //   * Self-allocated Mem / Shm tensors (any platform) — the backing
        //     `Vec` / shm segment is sized by `capacity_bytes()`, checked here.
        //   * Self-allocated DMA tensors (Linux) — pitch padding from
        //     `image_with_stride()`; checked against the DMA-BUF `buf_size`.
        //
        //   * Self-allocated PBO tensors (any platform with GL) — the GL buffer
        //     is sized by `capacity_bytes()` and may carry 64-byte row padding;
        //     the JPEG decoder mmaps it and convert() reads it, both iterating
        //     by `row_stride`. Checked against the PBO capacity below.
        //
        // A strided **imported** DMA-BUF is accepted here too (Task 10b): the
        // `stride × rows <= buf_size` check just below is exactly what a
        // self-allocated Dma tensor relies on for its own soundness, and
        // `buf_size` for an imported fd is `fstat`-derived when the kernel
        // reports a usable size (`stat.st_size > 0` and at least the
        // declared shape's logical size; `DmaTensor::from_fd`) -- kernel
        // truth, not a caller's claim, in that case. The rare fallback (a
        // kernel that reports `st_size <= 0` for a DMA-BUF fd) uses the
        // declared logical size instead; that is not a hole here either, since
        // an out-of-range mmap against the real dma-buf is still rejected by
        // the kernel regardless of what this crate believed `buf_size` was.
        // So the check is equally load-bearing regardless of who allocated
        // the buffer. What
        // changed is only *which* callers can now reach this path: the
        // cross-package capsule protocol reconstructs an imported alias of a
        // HAL-owned Dma tensor and then calls `configure_image`, which
        // computes its stride with the exact same alignment rule a
        // self-allocated `Tensor::image()` used — so the value being
        // bounds-checked here is HAL-computed and format/width-derived, not
        // read from an external driver. Rejecting it unconditionally used to
        // make every foreign-imported GPU-backed destination fail any CPU
        // write path (the JPEG decoder's MCU writer among them) even when the
        // write was provably in-bounds. `set_row_stride()` was already
        // "trust the caller, bounds-check the map" for every *other* backing
        // (Mem/Shm/self-allocated Dma/PBO) — singling out imported Dma out
        // for a stricter standard was the inconsistency, not the trust model
        // itself. IOSurface keeps its own always-allowed strided path
        // unconditionally (see its arm below): a live `IOSurfaceRef` reports
        // its real `bytesPerRow` from the OS regardless of who allocated it,
        // so there was never anything to distrust there.
        if let Some(stride) = self.row_stride {
            return map_strided_host_view(self, stride, access, non_blocking);
        }
        // Offset tensors are supported for storages that apply the offset
        // inside their own `map()`: DMA (`DmaMap`/IOSurface adjust the mapped
        // base), Mem (`MemMap` adjusts the slice base), Shm (`ShmMap` adjusts
        // the slice base), and PBO (the staged copy starts at the offset). Every
        // self-allocated backing now carries a sub-region concept via `view`, so
        // a non-zero offset is honoured rather than rejected.
        if self.plane_offset.is_some_and(|o| o > 0) {
            let supported = matches!(self.storage, TensorStorage::Mem(_) | TensorStorage::Pbo(_));
            // macOS `Dma` is the IOSurface; Linux `Dma` is the DMA-BUF; Android
            // `Dma` is the AHardwareBuffer, Windows `Dma` is the D3D11 texture
            // (whose pin and map both add the storage's own `view_offset`, the
            // same way IOSurface does) — all apply the offset in their map.
            // (`Dma` is the same variant name on each, hence one `cfg(any(...))`
            // arm rather than four.)
            #[cfg(any(
                target_os = "linux",
                target_os = "macos",
                target_os = "ios",
                target_os = "android",
                target_os = "windows"
            ))]
            let supported = supported || matches!(self.storage, TensorStorage::Dma(_));
            #[cfg(unix)]
            let supported = supported || matches!(self.storage, TensorStorage::Shm(_));
            if !supported {
                return Err(Error::InvalidOperation(
                    "plane offset only supported for DMA, Mem, Shm, and PBO tensors".into(),
                ));
            }
        }
        if non_blocking {
            self.storage.try_map_with(access)
        } else {
            self.storage.map_with(access)
        }
    }
}

#[cfg(feature = "static")]
impl<T> TensorTrait<T> for Tensor<T>
where
    T: Num + Clone + fmt::Debug + Send + Sync,
{
    fn new(shape: &[usize], name: Option<&str>) -> Result<Self>
    where
        Self: Sized,
    {
        Self::new(shape, None, name)
    }

    #[cfg(unix)]
    fn from_fd(fd: std::os::fd::OwnedFd, shape: &[usize], name: Option<&str>) -> Result<Self>
    where
        Self: Sized,
    {
        #[cfg_attr(not(target_os = "linux"), allow(unused_mut))]
        let mut t = Self::wrap(TensorStorage::from_fd(fd, shape, name)?);
        // Best-effort CUDA external memory import for DMA-backed tensors.
        // RUNTIME-UNVALIDATED: see try_init_dma_cuda().
        #[cfg(target_os = "linux")]
        t.try_init_dma_cuda();
        Ok(t)
    }

    #[cfg(unix)]
    fn clone_fd(&self) -> Result<std::os::fd::OwnedFd> {
        self.storage.clone_fd()
    }

    fn memory(&self) -> TensorMemory {
        self.storage.memory()
    }

    fn name(&self) -> String {
        self.storage.name()
    }

    fn shape(&self) -> &[usize] {
        self.storage.shape()
    }

    /// Bytes available in the underlying allocation, from this tensor's
    /// window start -- may exceed [`TensorTrait::size`] when the backing
    /// carries spare room beyond the current logical shape (a pitch-aligned
    /// image, or a pool tensor sized for a larger image than it holds
    /// today). See [`crate::protocol::TensorDesc::capacity`], the
    /// cross-package descriptor field this backs.
    fn capacity_bytes(&self) -> usize {
        self.storage.capacity_bytes()
    }

    fn reshape(&mut self, shape: &[usize]) -> Result<()> {
        if self.chroma.is_some() {
            return Err(Error::InvalidOperation(
                "cannot reshape a multiplane tensor — decompose planes first".into(),
            ));
        }
        self.storage.reshape(shape)?;
        self.format = None;
        self.row_stride = None;
        self.plane_offset = None;
        match self.storage {
            TensorStorage::Mem(ref mut m) => m.set_offset(0),
            #[cfg(target_os = "linux")]
            TensorStorage::Dma(ref mut dma) => dma.mmap_offset = 0,
            // No-op: `IoSurfaceTensor::reshape` (iosurface.rs) zeroes its
            // own `view_offset` before this match runs.
            #[cfg(any(target_os = "macos", target_os = "ios"))]
            TensorStorage::Dma(_) => {}
            // `D3d11TextureTensor::reshape` does not self-zero, so the clear
            // that pairs with `set_plane_offset`'s D3D11 arm lives here.
            #[cfg(target_os = "windows")]
            TensorStorage::Dma(ref mut tex) => tex.set_view_offset(0),
            // No-op: `AHardwareBufferTensor::reshape` (ahardwarebuffer.rs)
            // zeroes its own `view_offset` before this match runs, the same
            // as `IoSurfaceTensor`. Unlike `set_plane_offset`'s Android arm,
            // this one is a genuine self-zeroing no-op, not a still-
            // incomplete gap: `view_offset` never survives a reshape here
            // regardless of whether `set_plane_offset` can restore it.
            #[cfg(target_os = "android")]
            TensorStorage::Dma(_) => {}
            // No-op: `PboTensor::reshape` (pbo.rs) zeroes its own
            // `view_offset` before this match runs, the same as
            // `IoSurfaceTensor`/`AHardwareBufferTensor` above -- which is
            // why, unlike `set_format`'s clear block, this match never
            // needed a `Pbo` arm that writes anything.
            TensorStorage::Pbo(_) => {}
            // Unlike `PboTensor::reshape`, `ShmTensor::reshape` (shm.rs)
            // only revalidates the element count and swaps `self.shape` --
            // it never touches `self.offset` -- so this clear site needs
            // the arm `set_format`'s does. `cfg(unix)` mirrors the `Shm`
            // variant's own gate, not a per-OS multiplex.
            #[cfg(unix)]
            TensorStorage::Shm(ref mut s) => s.set_offset(0),
        }
        Ok(())
    }

    /// Set the logical shape to any shape whose bytes fit the allocation,
    /// without [`reshape`](TensorTrait::reshape)'s equal-count constraint.
    ///
    /// Overridden rather than inherited, which it was not for most of this
    /// crate's life. The trait's default body is `self.reshape(shape)`, so
    /// a caller reaching this through `Tensor<T>` silently got the strict
    /// rule under a name that promises the opposite -- on both backends,
    /// which is why G13 cannot see it.
    ///
    /// The capacity-aware implementations were never dead: every storage
    /// type has one, and [`Tensor::configure_image`] reaches them by
    /// calling `self.storage.set_logical_shape(..)` directly. That is the
    /// pool-reuse path -- a decode into an oversized reusable buffer
    /// reconfiguring it to a smaller image without reallocating -- and it
    /// worked precisely because it bypassed this method. This forwards the
    /// same way, so the two agree.
    ///
    /// A narrower image inside a pitched backing (an IOSurface, an
    /// AHardwareBuffer, a D3D11 texture) still advances rows by the backing's
    /// pitch, so that pitch is recorded as the row stride whenever it exceeds
    /// the new shape's natural stride -- the same adoption `configure_image`
    /// makes. Without it a texture narrowed from 64 to 16 texels wide reports
    /// a 64-byte stride over rows that are 256 bytes apart. A single-row
    /// shape records its own tight stride instead, by [`view`](Self::view)'s
    /// rule: a strided `map()` spans `stride * rows`, and one pitched row
    /// runs past the backing when the window sits in the last row.
    fn set_logical_shape(&mut self, shape: &[usize]) -> Result<()> {
        self.storage.set_logical_shape(shape)?;
        // Only a backing with a pitch of its own, and only while the shape
        // still has the rank the format's row is measured on: a caller may
        // flatten an image to one dimension and leave the format behind.
        let Some(pitch) = self.storage.backing_row_stride() else {
            return Ok(());
        };
        let Some((rank, rows)) = self.format.map(|f| match f.layout() {
            PixelLayout::Packed => (3, shape.first().copied()),
            PixelLayout::Planar => (3, shape.get(1).copied()),
            PixelLayout::SemiPlanar => (2, shape.first().copied()),
        }) else {
            return Ok(());
        };
        if rank != shape.len() {
            return Ok(());
        }
        // The natural stride of the new shape, not of the stride recorded for
        // the old one.
        let prior = self.row_stride.take();
        let Some(natural) = self.effective_row_stride() else {
            self.row_stride = prior;
            return Ok(());
        };
        if rows == Some(1) {
            self.set_row_stride_unchecked(natural);
        } else if pitch > natural {
            self.set_row_stride_unchecked(pitch);
        } else {
            self.row_stride = prior;
        }
        Ok(())
    }

    fn map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_impl(access, false)
    }

    fn try_map_with<'a>(&self, access: CpuAccess) -> Result<crate::view::HostView<'a, T>>
    where
        T: 'a,
    {
        self.map_impl(access, true)
    }

    fn buffer_identity(&self) -> &BufferIdentity {
        self.storage.buffer_identity()
    }
}

// ============================================================================
// Platform availability helpers
// ============================================================================

/// Cached result of the Linux DMA-BUF availability probe.
#[cfg(target_os = "linux")]
static DMA_AVAILABLE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
/// Cached result of the macOS/iOS IOSurface availability probe.
#[cfg(any(target_os = "macos", target_os = "ios"))]
static IOSURFACE_AVAILABLE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

/// Check if Linux DMA-BUF allocation is available on this system.
///
/// Linux-specific availability check (typically requires `/dev/dma_heap`
/// access — running as root or membership in a video/render group). For
/// portable code that wants "any zero-copy GPU buffer", use
/// [`is_gpu_buffer_available`] which also covers IOSurface on macOS.
///
/// This function caches its result after the first call.
#[cfg(target_os = "linux")]
pub fn is_dma_available() -> bool {
    *DMA_AVAILABLE
        .get_or_init(|| Tensor::<u8>::new(&[64], Some(TensorMemory::DmaBuf), None).is_ok())
}

/// Always returns `false` on non-Linux platforms.
#[cfg(not(target_os = "linux"))]
pub fn is_dma_available() -> bool {
    false
}

/// Check if macOS/iOS IOSurface allocation is available on this system.
///
/// IOSurface is part of the macOS/iOS OS and is essentially always present;
/// this probe catches degraded scenarios such as memory pressure or
/// sandboxed contexts where `IOSurfaceCreate` fails. The result is
/// cached after the first call.
///
/// Always returns `false` on non-Apple platforms.
#[cfg(any(target_os = "macos", target_os = "ios"))]
pub fn is_iosurface_available() -> bool {
    *IOSURFACE_AVAILABLE.get_or_init(|| {
        // Probe via the same Dma path — on macOS/iOS this routes through
        // IoSurfaceTensor::new.
        Tensor::<u8>::new(&[64], Some(TensorMemory::DmaBuf), None).is_ok()
    })
}

#[cfg(not(any(target_os = "macos", target_os = "ios")))]
pub fn is_iosurface_available() -> bool {
    false
}

/// Cached result of the Android AHardwareBuffer availability probe.
#[cfg(target_os = "android")]
static AHARDWAREBUFFER_AVAILABLE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

/// Check if Android AHardwareBuffer allocation is available on this system.
///
/// AHardwareBuffer is part of the Android OS (public NDK ABI since API
/// 26) and is essentially always present; this probe catches degraded
/// scenarios such as memory pressure or gralloc failures. The result is
/// cached after the first call.
#[cfg(target_os = "android")]
pub fn is_ahardwarebuffer_available() -> bool {
    *AHARDWAREBUFFER_AVAILABLE.get_or_init(|| {
        // Probe via the same Dma path — on Android this routes through
        // AHardwareBufferTensor::new.
        Tensor::<u8>::new(&[64], Some(TensorMemory::DmaBuf), None).is_ok()
    })
}

/// Always returns `false` on non-Android platforms.
#[cfg(not(target_os = "android"))]
pub fn is_ahardwarebuffer_available() -> bool {
    false
}

/// Portable probe for the platform's native zero-copy GPU buffer allocator
/// (DMA-BUF on Linux, IOSurface on macOS/iOS, AHardwareBuffer on Android,
/// D3D11 textures on Windows). Returns `false` on platforms with no
/// equivalent. Use this when writing cross-platform code that cares whether
/// the `Dma` tensor variant will work, not which underlying mechanism is used.
///
/// On Windows the `Dma` variant is image-formatted: `true` here means
/// [`Tensor::image`] can serve `TensorMemory::DmaBuf`, not [`Tensor::new`].
///
/// # Ordering on Windows
///
/// This probe **creates the process D3D11 device**, because the only honest
/// answer to "can this host allocate one" is to try. A host that must supply
/// its own device calls `d3d11::use_external_device` **before** this probe or
/// any allocation: the device is cached on first creation and installing one
/// afterwards is refused.
pub fn is_gpu_buffer_available() -> bool {
    #[cfg(target_os = "linux")]
    {
        is_dma_available()
    }
    #[cfg(any(target_os = "macos", target_os = "ios"))]
    {
        is_iosurface_available()
    }
    #[cfg(target_os = "android")]
    {
        is_ahardwarebuffer_available()
    }
    // No cached probe: `d3d11::device()` is itself a `OnceLock` over the
    // process device, so asking twice costs one atomic load.
    #[cfg(target_os = "windows")]
    {
        crate::d3d11::device().is_ok()
    }
    #[cfg(not(any(
        target_os = "linux",
        target_os = "macos",
        target_os = "ios",
        target_os = "android",
        target_os = "windows"
    )))]
    {
        false
    }
}

/// Check if POSIX shared memory allocation is available on this system.
///
/// Returns `true` on Unix systems (Linux, macOS, BSD) where POSIX shared memory
/// is supported. Always returns `false` on non-Unix platforms (Windows).
///
/// This function caches its result after the first call for efficiency.
#[cfg(unix)]
static SHM_AVAILABLE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

/// Check if POSIX shared memory allocation is available on this system.
#[cfg(unix)]
pub fn is_shm_available() -> bool {
    *SHM_AVAILABLE.get_or_init(|| Tensor::<u8>::new(&[64], Some(TensorMemory::Shm), None).is_ok())
}

/// Check if POSIX shared memory allocation is available on this system.
///
/// Always returns `false` on non-Unix platforms since POSIX SHM is Unix-specific.
#[cfg(not(unix))]
pub fn is_shm_available() -> bool {
    false
}

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

    #[test]
    fn dtype_size() {
        assert_eq!(DType::U8.size(), 1);
        assert_eq!(DType::I8.size(), 1);
        assert_eq!(DType::U16.size(), 2);
        assert_eq!(DType::I16.size(), 2);
        assert_eq!(DType::U32.size(), 4);
        assert_eq!(DType::I32.size(), 4);
        assert_eq!(DType::U64.size(), 8);
        assert_eq!(DType::I64.size(), 8);
        assert_eq!(DType::F16.size(), 2);
        assert_eq!(DType::F32.size(), 4);
        assert_eq!(DType::F64.size(), 8);
    }

    #[test]
    fn dtype_name() {
        assert_eq!(DType::U8.name(), "u8");
        assert_eq!(DType::F16.name(), "f16");
        assert_eq!(DType::F32.name(), "f32");
    }

    #[test]
    fn dtype_serde_roundtrip() {
        use serde_json;
        let dt = DType::F16;
        let json = serde_json::to_string(&dt).unwrap();
        let back: DType = serde_json::from_str(&json).unwrap();
        assert_eq!(dt, back);
    }
}

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

    #[test]
    fn image_dims_from_shape_inverts_allocation_shape() {
        for (format, w, h) in [
            (PixelFormat::Rgba, 640usize, 480usize),
            (PixelFormat::Rgb, 641, 3),
            (PixelFormat::Grey, 32, 32),
            (PixelFormat::PlanarRgb, 640, 480),
            (PixelFormat::PlanarRgba, 8, 5),
            (PixelFormat::Nv12, 640, 481),
            (PixelFormat::Nv16, 33, 17),
            (PixelFormat::Nv24, 16, 9),
        ] {
            let shape = format.allocation_shape(w, h).unwrap();
            assert_eq!(
                image_dims_from_shape(format, &shape).unwrap(),
                (w, h),
                "{format:?} {w}x{h} via {shape:?}"
            );
        }
    }

    #[test]
    fn image_dims_from_shape_rejects_the_wrong_rank() {
        // Packed and planar want rank 3, semi-planar rank 2.
        for (format, shape) in [
            (PixelFormat::Rgba, vec![480usize, 640usize]),
            (PixelFormat::PlanarRgb, vec![3, 480]),
            (PixelFormat::Nv12, vec![720, 640, 1]),
        ] {
            let err = image_dims_from_shape(format, &shape).unwrap_err();
            assert!(
                matches!(err, Error::InvalidShape(ref m) if m.contains("rank")),
                "{format:?} {shape:?}: {err}"
            );
        }
    }

    #[test]
    fn image_dims_from_shape_rejects_an_unproduced_combined_height() {
        // NV12 maps 480 -> 720 and 481 -> 722; nothing maps to 721, so the
        // shape is rejected rather than rounded to 480.
        let err = image_dims_from_shape(PixelFormat::Nv12, &[721, 640]).unwrap_err();
        assert!(
            matches!(err, Error::InvalidShape(ref m) if m.contains("combined plane height")),
            "{err}"
        );
    }

    #[test]
    fn allocation_shape_per_layout() {
        assert_eq!(
            PixelFormat::Rgb.allocation_shape(640, 480),
            Some(vec![480, 640, 3])
        );
        assert_eq!(
            PixelFormat::Grey.allocation_shape(640, 480),
            Some(vec![480, 640, 1])
        );
        assert_eq!(
            PixelFormat::Nv12.allocation_shape(640, 480),
            Some(vec![720, 640])
        );
        // Odd height: combined-plane height is `481 + ceil(481/2)` = 481 + 241
        // = 722 rows. Logical height is recovered as `722 * 2 / 3` = 481.
        assert_eq!(
            PixelFormat::Nv12.allocation_shape(640, 481),
            Some(vec![722, 640])
        );
        // Odd width: shape carries the LOGICAL width (641).
        // The 64-aligned stride (>= 642) is stored separately on the Tensor.
        assert_eq!(
            PixelFormat::Nv12.allocation_shape(641, 480),
            Some(vec![720, 641])
        );
        // NV16 odd width: same — logical width in shape, stride separate.
        assert_eq!(
            PixelFormat::Nv16.allocation_shape(641, 480),
            Some(vec![960, 641])
        );
        assert_eq!(
            PixelFormat::PlanarRgb.allocation_shape(640, 480),
            Some(vec![3, 480, 640])
        );
        assert_eq!(
            PixelFormat::Nv16.allocation_shape(640, 480),
            Some(vec![960, 640])
        );
    }

    #[test]
    fn raw_tensor_has_no_format() {
        let t = Tensor::<u8>::new(&[480, 640, 3], None, None).unwrap();
        assert!(t.format().is_none());
        assert!(t.width().is_none());
        assert!(t.height().is_none());
        assert!(!t.is_multiplane());
        assert!(t.chroma().is_none());
    }

    #[test]
    fn image_tensor_packed() {
        let t = Tensor::<u8>::image(
            640,
            480,
            PixelFormat::Rgba,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(t.format(), Some(PixelFormat::Rgba));
        assert_eq!(t.width(), Some(640));
        assert_eq!(t.height(), Some(480));
        assert_eq!(t.shape(), &[480, 640, 4]);
        assert!(!t.is_multiplane());
    }

    #[test]
    fn image_tensor_planar() {
        let t = Tensor::<u8>::image(
            640,
            480,
            PixelFormat::PlanarRgb,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(t.format(), Some(PixelFormat::PlanarRgb));
        assert_eq!(t.width(), Some(640));
        assert_eq!(t.height(), Some(480));
        assert_eq!(t.shape(), &[3, 480, 640]);
    }

    #[test]
    #[cfg(target_os = "macos")]
    fn image_tensor_dma_non_aligned_packed_width_pads_zero_copy() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // RGBA u8 at width=4 → 4*4 = 16 bytes/row, not 64-byte aligned. RGBA has
        // a real IOSurface FourCC, so an explicit `Some(TensorMemory::DmaBuf)`
        // request now allocates a padded image IOSurface (64-aligned
        // `bytes_per_row`) and records the stride — a fully zero-copy buffer GL
        // can bind and the CPU can map via the strided path. (Previously this
        // failed loudly to avoid an 'L008' byte-bag downgrade; with a real
        // FourCC surface that concern no longer applies.)
        let t = Tensor::<u8>::image(
            4,
            4,
            PixelFormat::Rgba,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect("padded RGBA IOSurface should allocate");
        assert_eq!(t.format(), Some(PixelFormat::Rgba));
        assert_eq!(t.width(), Some(4));
        assert_eq!(t.height(), Some(4));
        let stride = t.effective_row_stride().expect("stride");
        assert_eq!(stride % 64, 0, "padded to 64-byte row alignment");
        assert!(stride >= 16);
        // A CPU map exposes the full padded surface for strided iteration.
        let m = t.map().expect("strided IOSurface map");
        assert_eq!(m.as_slice().len(), stride * 4);
    }

    /// `per_pixel_bytes` that doesn't divide 64 evenly (e.g. RGB u8 with
    /// 3 B/pixel) makes a "Pad width to N" suggestion structurally
    /// impossible — there is no integer width whose `width * 3` is a
    /// multiple of 64. The error must still fire (no silent SHM
    /// fallback for explicit-DMA requests) and must spell out the
    /// alignment requirement; it just omits the misleading "pad to N"
    /// hint instead of printing a number whose row pitch still won't
    /// align.
    #[test]
    #[cfg(target_os = "macos")]
    fn image_tensor_dma_rejects_indivisible_pixel_pitch_without_pad_hint() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Width=10 RGB f32 → 120 B/row, not 64-byte aligned, and (Rgb,
        // F32) has no IOSurface mapping so the padded-stride tolerance
        // does not apply. The next 64-multiple (128 B) isn't an integer
        // multiple of 12 B/pixel, so the "pad width to N" hint can't
        // produce a valid number and must be omitted. (Rgb u8 used to be
        // this test's subject but now has a real RGBA8888 mapping with
        // padded-stride tolerance — see the test below.)
        let err = Tensor::<f32>::image(
            10,
            10,
            PixelFormat::Rgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect_err("RGB f32 with 12 B/pixel and non-aligned width must be rejected");
        match err {
            Error::InvalidArgument(msg) => {
                assert!(
                    msg.contains("64-byte aligned"),
                    "error must still name the alignment requirement: {msg}"
                );
                assert!(
                    !msg.contains("Pad width"),
                    "indivisible per-pixel pitch makes a width suggestion impossible; \
                     hint must be omitted, got: {msg}"
                );
                assert!(
                    msg.contains("memory=None") && msg.contains("TensorMemory::Mem"),
                    "error must still list the always-applicable alternatives: {msg}"
                );
            }
            other => panic!("expected InvalidArgument, got {other:?}"),
        }
    }

    #[test]
    #[cfg(target_os = "macos")]
    fn image_tensor_dma_packed_rgb_u8_contract() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Packed RGB u8 @Dma is a designed RGBA8888 mapping at
        // (W*3/4, H) — the INT8 NPU input layout, shared with Android.
        // width%4 != 0 cannot form whole texels → loud InvalidArgument…
        let err = Tensor::<u8>::image(
            10,
            10,
            PixelFormat::Rgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect_err("Rgb u8 width%4!=0 must be rejected");
        assert!(
            matches!(&err, Error::InvalidArgument(m) if m.contains("width%4==0")),
            "got {err:?}"
        );
        // …width%4 == 0 with a non-64-aligned pitch allocates PADDED
        // (36 B rows → 64 B surface pitch, recorded on the tensor)…
        let t = Tensor::<u8>::image(
            12,
            4,
            PixelFormat::Rgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect("width 12 Rgb u8 must allocate padded");
        assert_eq!(t.memory(), TensorMemory::DmaBuf);
        assert!(
            t.row_stride()
                .is_some_and(|s| s >= 64 && s.is_multiple_of(64)),
            "padded pitch must be recorded: {:?}",
            t.row_stride()
        );
        // …and the aligned model-input width stays flat (640*3 = 1920 is
        // 64-aligned → no recorded stride, the buffer IS [H, W, 3]).
        let t = Tensor::<u8>::image(
            640,
            8,
            PixelFormat::Rgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect("width 640 Rgb u8 must allocate flat");
        assert_eq!(t.row_stride(), None);
        // I8 shares the layout (INT8 shader bias, not a format change).
        let t = Tensor::<i8>::image(
            640,
            8,
            PixelFormat::Rgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect("Rgb i8 shares the RGBA8888 mapping");
        assert_eq!(t.memory(), TensorMemory::DmaBuf);
    }

    #[test]
    #[cfg(target_os = "macos")]
    fn image_tensor_dma_planar_f16_alignment() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // PlanarRgb F16 uses single-channel row pitch (width * 2 bytes).
        // Width=16 → 32 bytes/row (not aligned); width=32 → 64 bytes/row (aligned).
        let err = Tensor::<half::f16>::image(
            16,
            16,
            PixelFormat::PlanarRgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect_err("width=16 PlanarRgb F16 is 32-byte row, must reject");
        assert!(matches!(err, Error::InvalidArgument(_)), "got {err:?}");
        // 32 wide should work.
        let t = Tensor::<half::f16>::image(
            32,
            8,
            PixelFormat::PlanarRgb,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .expect("width=32 PlanarRgb F16 is 64-byte row, must succeed");
        assert_eq!(t.format(), Some(PixelFormat::PlanarRgb));
    }

    #[test]
    fn image_tensor_semi_planar_contiguous() {
        let t = Tensor::<u8>::image(
            640,
            480,
            PixelFormat::Nv12,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(t.format(), Some(PixelFormat::Nv12));
        assert_eq!(t.width(), Some(640));
        assert_eq!(t.height(), Some(480));
        // NV12: H*3/2 = 720
        assert_eq!(t.shape(), &[720, 640]);
        assert!(!t.is_multiplane());
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn image_tensor_with_stride_preserves_logical_width() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Skip if DMA not available (e.g. sandboxed CI lacking dma_heap access).
        if !is_dma_available() {
            crate::test_support::report_skip("DMA heap not available");
            return;
        }
        // 3004×1688 RGBA8: natural pitch 12016, padded to 12032 (64-aligned).
        let stride = 12032;
        let t = Tensor::<u8>::image_with_stride(
            3004,
            1688,
            PixelFormat::Rgba,
            stride,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        // Logical dimensions unchanged by padding — this is the contract.
        assert_eq!(t.width(), Some(3004));
        assert_eq!(t.height(), Some(1688));
        assert_eq!(t.shape(), &[1688, 3004, 4]);
        // Stride is carried separately and reports the padded pitch.
        assert_eq!(t.effective_row_stride(), Some(stride));
        // Buffer is sized to stride × height so the full padded layout fits,
        // and CPU map() works for self-allocated strided DMA tensors.
        use crate::TensorMapTrait;
        {
            let map = t.map().unwrap();
            assert!(
                map.as_slice().len() >= stride * 1688,
                "mapped buffer {} bytes < expected {}",
                map.as_slice().len(),
                stride * 1688
            );
        }
        // CPU write access works too — iterate rows using the padded stride,
        // touch only the active `width × bpp` region, verify it round-trips.
        {
            let mut map = t.map().unwrap();
            let slice = map.as_mut_slice();
            for y in 0..1688 {
                let row_start = y * stride;
                for x in 0..3004 {
                    let p = row_start + x * 4;
                    slice[p] = (y & 0xFF) as u8;
                    slice[p + 1] = (x & 0xFF) as u8;
                    slice[p + 2] = 0x42;
                    slice[p + 3] = 0xFF;
                }
            }
        }
        {
            let map = t.map().unwrap();
            let slice = map.as_slice();
            // Sample a few pixels to confirm the round-trip.
            assert_eq!(slice[0], 0x00);
            assert_eq!(slice[1], 0x00);
            assert_eq!(slice[2], 0x42);
            assert_eq!(slice[3], 0xFF);
            let mid = 100 * stride + 50 * 4;
            assert_eq!(slice[mid], 100);
            assert_eq!(slice[mid + 1], 50);
            assert_eq!(slice[mid + 2], 0x42);
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn image_tensor_foreign_strided_map_is_bounds_checked_not_refused() {
        // An imported (foreign) DMA-BUF with a row stride used to be refused
        // outright. That changed deliberately: the cross-package capsule
        // protocol reconstructs an imported alias of a HAL-owned Dma tensor,
        // and refusing every strided CPU map broke the flagship
        // create_image() -> decode_file_into() -> convert() pipeline on Linux.
        //
        // What replaced the refusal is a bounds check against `buf_size`,
        // which for an imported fd is `fstat`-derived kernel truth rather
        // than the caller's claim. So the property worth testing is no longer
        // "foreign strided maps fail" but "they succeed exactly when they
        // fit" -- which is what actually keeps the mapping sound.
        //
        // This test previously asserted the old refusal and went red on every
        // board with a dma-heap when the behaviour changed, unnoticed because
        // it needs both Linux and a dma-heap: it skips on macOS and on Orin
        // (nvmap, no CONFIG_DMABUF_HEAPS).
        if !is_dma_available() {
            crate::test_support::report_skip("DMA heap not available");
            return;
        }
        let backing =
            Tensor::<u8>::new(&[240 * 320 * 4], Some(TensorMemory::DmaBuf), None).unwrap();

        // In bounds: the natural stride for the declared image fits the
        // allocation, so the map must succeed.
        {
            let fd = backing.clone_fd().unwrap();
            let shape = [240usize, 320, 4];
            let storage = TensorStorage::<u8>::from_fd(fd, &shape, None).unwrap();
            let mut t = Tensor::<u8>::wrap(storage);
            t.set_format(PixelFormat::Bgra).unwrap();
            t.set_row_stride(320 * 4).unwrap();
            assert!(
                t.map().is_ok(),
                "an in-bounds strided map of an imported DMA-BUF must be \
                 accepted -- refusing it is what broke decode-into-GPU-tensor"
            );
        }

        // Out of bounds: a stride the allocation cannot back must still be
        // refused, and the error must say so. This is the half that carries
        // the soundness.
        {
            let fd = backing.clone_fd().unwrap();
            let shape = [240usize, 320, 4];
            let storage = TensorStorage::<u8>::from_fd(fd, &shape, None).unwrap();
            let mut t = Tensor::<u8>::wrap(storage);
            t.set_format(PixelFormat::Bgra).unwrap();
            // Double the pitch: 240 rows x 2560 bytes is twice the allocation.
            t.set_row_stride(320 * 4 * 2).unwrap();
            let err = t.map();
            assert!(
                matches!(err, Err(Error::InvalidOperation(_))),
                "a strided map larger than the DMA allocation must be refused"
            );
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn image_tensor_with_stride_map_rejects_tampered_stride() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Round-3 PR feedback (C1): `set_row_stride` is public and only
        // validates `stride >= min_stride`, not that the new stride × height
        // fits the underlying buffer. A caller that tampers with the stride
        // after allocation must not be able to coerce `Tensor::map()` into
        // returning a slice larger than the backing mmap (that would be UB
        // in `DmaMap::as_slice`).
        if !is_dma_available() {
            crate::test_support::report_skip("DMA heap not available");
            return;
        }
        // Allocate a 640×480 RGBA8 padded canvas (stride = 3072 = 768 px).
        // Backing buffer is 3072 × 480 = 1,474,560 bytes.
        let mut t = Tensor::<u8>::image_with_stride(
            640,
            480,
            PixelFormat::Rgba,
            3072,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        // Tamper: push the stride up to 4 × the original. This is >=
        // min_stride (2560), so `set_row_stride` accepts it.
        t.set_row_stride(12288).unwrap();
        // Map must now refuse — 12288 × 480 = 5,898,240 > 1,474,560.
        let err = t.map();
        assert!(
            matches!(err, Err(Error::InvalidOperation(_))),
            "map() with oversized stride must return InvalidOperation"
        );
    }

    #[test]
    fn dma_tensor_new_with_byte_size_rejects_shape_overflow() {
        // Round-3 PR feedback (C3): shape.product() * sizeof(T) must use
        // checked arithmetic so a pathological shape can't wrap usize and
        // make the byte_size-vs-logical-size comparison incorrect.
        //
        // This test only exercises the overflow rejection path, which is
        // pure-Rust and doesn't touch dma_heap — safe to run on any target.
        #[cfg(target_os = "linux")]
        {
            let err = crate::dma::DmaTensor::<u64>::new_with_byte_size(
                &[usize::MAX, 2, 2],
                usize::MAX,
                None,
            );
            assert!(
                matches!(err, Err(Error::InvalidArgument(_))),
                "new_with_byte_size must detect shape.product() overflow"
            );
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn image_tensor_with_stride_rejects_too_small_stride() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // 640×480 RGBA8 natural pitch = 2560, request 2400 → should error.
        let err = Tensor::<u8>::image_with_stride(
            640,
            480,
            PixelFormat::Rgba,
            2400,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        );
        assert!(matches!(err, Err(Error::InvalidArgument(_))));
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn image_tensor_with_stride_rejects_non_packed() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // NV12 is SemiPlanar → not supported. (Linux-only because
        // `TensorMemory::DmaBuf` itself is a Linux-only enum variant.)
        let err = Tensor::<u8>::image_with_stride(
            640,
            480,
            PixelFormat::Nv12,
            640,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        );
        assert!(matches!(err, Err(Error::NotImplemented(_))));
    }

    #[test]
    fn set_format_valid() {
        let mut t = Tensor::<u8>::new(&[480, 640, 3], None, None).unwrap();
        assert!(t.format().is_none());
        t.set_format(PixelFormat::Rgb).unwrap();
        assert_eq!(t.format(), Some(PixelFormat::Rgb));
        assert_eq!(t.width(), Some(640));
        assert_eq!(t.height(), Some(480));
    }

    #[test]
    fn set_format_invalid_shape() {
        let mut t = Tensor::<u8>::new(&[480, 640, 4], None, None).unwrap();
        // RGB expects 3 channels, not 4
        let err = t.set_format(PixelFormat::Rgb);
        assert!(err.is_err());
        // Original tensor is unmodified
        assert!(t.format().is_none());
    }

    #[test]
    fn reshape_clears_format() {
        let mut t = Tensor::<u8>::image(
            640,
            480,
            PixelFormat::Rgba,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(t.format(), Some(PixelFormat::Rgba));
        // Reshape to flat — format cleared
        t.reshape(&[480 * 640 * 4]).unwrap();
        assert!(t.format().is_none());
    }

    #[test]
    fn from_planes_nv12() {
        let y = Tensor::<u8>::new(&[480, 640], None, None).unwrap();
        let uv = Tensor::<u8>::new(&[240, 640], None, None).unwrap();
        let img = Tensor::from_planes(y, uv, PixelFormat::Nv12).unwrap();
        assert_eq!(img.format(), Some(PixelFormat::Nv12));
        assert!(img.is_multiplane());
        assert!(img.chroma().is_some());
        assert_eq!(img.width(), Some(640));
        assert_eq!(img.height(), Some(480));
    }

    #[test]
    fn from_planes_rejects_non_semiplanar() {
        let y = Tensor::<u8>::new(&[480, 640], None, None).unwrap();
        let uv = Tensor::<u8>::new(&[240, 640], None, None).unwrap();
        let err = Tensor::from_planes(y, uv, PixelFormat::Rgb);
        assert!(err.is_err());
    }

    #[test]
    fn reshape_multiplane_errors() {
        let y = Tensor::<u8>::new(&[480, 640], None, None).unwrap();
        let uv = Tensor::<u8>::new(&[240, 640], None, None).unwrap();
        let mut img = Tensor::from_planes(y, uv, PixelFormat::Nv12).unwrap();
        let err = img.reshape(&[480 * 640 + 240 * 640]);
        assert!(err.is_err());
    }
}

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

    #[test]
    fn desc_builder_roundtrips() {
        let desc = ImageDesc::new(640, 480, PixelFormat::Rgba, DType::U8)
            .with_memory(Some(TensorMemory::Mem))
            .with_access(CpuAccess::Read)
            .with_compression(Compression::Any);
        assert_eq!(desc.width(), 640);
        assert_eq!(desc.height(), 480);
        assert_eq!(desc.format(), PixelFormat::Rgba);
        assert_eq!(desc.dtype(), DType::U8);
        assert_eq!(desc.memory(), Some(TensorMemory::Mem));
        assert_eq!(desc.access(), CpuAccess::Read);
        assert_eq!(desc.compression(), Some(Compression::Any));

        // Defaults: auto memory, hardware-only, no request.
        let plain = ImageDesc::new(2, 2, PixelFormat::Grey, DType::U8);
        assert_eq!(plain.memory(), None);
        assert_eq!(plain.access(), CpuAccess::None);
        assert_eq!(plain.compression(), None);
    }

    #[test]
    fn desc_dtype_must_match_element_type() {
        let desc = ImageDesc::new(4, 4, PixelFormat::Rgba, DType::F32);
        match Tensor::<u8>::image_desc(&desc) {
            Err(Error::InvalidArgument(msg)) => assert!(msg.contains("dtype")),
            other => panic!("expected InvalidArgument, got {other:?}"),
        }
    }

    #[test]
    fn compression_with_cpu_access_is_invalid() {
        let desc = ImageDesc::new(4, 4, PixelFormat::Rgba, DType::U8)
            .with_access(CpuAccess::ReadWrite)
            .with_compression(Compression::Any);
        match Tensor::<u8>::image_desc(&desc) {
            Err(Error::InvalidArgument(msg)) => assert!(msg.contains("CpuAccess::None")),
            other => panic!("expected InvalidArgument, got {other:?}"),
        }
    }

    #[cfg(not(target_os = "android"))]
    #[test]
    fn scheme_request_off_android_is_not_implemented() {
        let desc = ImageDesc::new(4, 4, PixelFormat::Rgba, DType::U8)
            .with_compression(Compression::Scheme(CompressionScheme::Ubwc));
        match Tensor::<u8>::image_desc(&desc) {
            Err(Error::NotImplemented(msg)) => assert!(msg.contains("Ubwc")),
            other => panic!("expected NotImplemented, got {other:?}"),
        }
    }

    #[cfg(not(target_os = "android"))]
    #[test]
    fn any_request_off_android_resolves_linear_and_counts() {
        let before = compression_fallback_count();
        let desc = ImageDesc::new(64, 64, PixelFormat::Rgba, DType::U8)
            .with_memory(Some(TensorMemory::Mem))
            .with_compression(Compression::Any);
        let t = Tensor::<u8>::image_desc(&desc).unwrap();
        assert_eq!(t.compression(), None);
        assert!(compression_fallback_count() > before);
    }

    #[test]
    fn desc_without_request_matches_classic_constructor() {
        let desc = ImageDesc::new(32, 32, PixelFormat::Rgba, DType::U8)
            .with_memory(Some(TensorMemory::Mem))
            .with_access(CpuAccess::ReadWrite);
        let t = Tensor::<u8>::image_desc(&desc).unwrap();
        assert_eq!(t.compression(), None);
        assert_eq!(t.cpu_access(), CpuAccess::ReadWrite);
        assert_eq!(t.width(), Some(32));
        // Mappable exactly like the classic constructor's result.
        let m = t.map_read().unwrap();
        assert_eq!(m.as_slice().len(), 32 * 32 * 4);
    }

    #[test]
    fn configure_image_preserves_compression_and_views_inherit() {
        // No host platform records a scheme, so emulate the recording to
        // pin the preserve/inherit semantics (the physical layout does
        // not change when the logical image is reconfigured).
        let mut t = Tensor::<u8>::image(
            64,
            64,
            PixelFormat::Rgba,
            Some(TensorMemory::Mem),
            CpuAccess::None,
        )
        .unwrap();
        t.compression = Some(CompressionScheme::Ubwc);
        t.configure_image(32, 32, PixelFormat::Rgba).unwrap();
        assert_eq!(t.compression(), Some(CompressionScheme::Ubwc));
        let view = t.subview(0, &[16, 32, 4]).unwrap();
        assert_eq!(view.compression(), Some(CompressionScheme::Ubwc));
    }

    #[test]
    fn tensor_dyn_dispatches_desc_and_compression() {
        let desc = ImageDesc::new(16, 16, PixelFormat::Rgba, DType::U8)
            .with_memory(Some(TensorMemory::Mem))
            .with_access(CpuAccess::ReadWrite);
        let t = TensorDyn::image_desc(&desc).unwrap();
        assert_eq!(t.compression(), None);
        assert!(matches!(t, TensorDyn::U8(_)));
    }
}

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

    #[test]
    fn covers_matrix() {
        use CpuAccess::*;
        // Every declaration covers a narrower or equal request…
        for a in [None, Read, Write, ReadWrite] {
            assert!(a.covers(None), "{a:?} must cover None");
            assert!(ReadWrite.covers(a), "ReadWrite must cover {a:?}");
        }
        assert!(Read.covers(Read));
        assert!(Write.covers(Write));
        // …and never a wider one.
        assert!(!None.covers(Read));
        assert!(!None.covers(Write));
        assert!(!Read.covers(Write));
        assert!(!Read.covers(ReadWrite));
        assert!(!Write.covers(Read));
        assert!(!Write.covers(ReadWrite));
    }

    #[test]
    fn map_with_none_is_invalid() {
        let t = Tensor::<u8>::new(&[16], Some(TensorMemory::Mem), None).unwrap();
        match t.map_with(CpuAccess::None) {
            Err(Error::InvalidArgument(_)) => {}
            Err(other) => panic!("expected InvalidArgument, got {other:?}"),
            Ok(_) => panic!("map_with(CpuAccess::None) must not succeed"),
        }
    }

    #[test]
    fn read_map_rejects_mutation_uniformly() {
        // Mem backend: map_read yields a working read view whose mutable
        // accessor panics (the uniform cross-backend contract).
        let t = Tensor::<u8>::new(&[8], Some(TensorMemory::Mem), None).unwrap();
        t.map_mut().unwrap().as_mut_slice().copy_from_slice(&[7; 8]);
        let ro = t.map_read().unwrap();
        assert_eq!(ro.as_slice(), &[7; 8]);
        drop(ro);
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            let mut ro = t.map_read().unwrap();
            let _ = ro.as_mut_slice();
        }));
        assert!(result.is_err(), "as_mut_slice through map_read must panic");
    }

    #[test]
    fn write_and_rw_maps_stay_mutable() {
        let t = Tensor::<u8>::new(&[4], Some(TensorMemory::Mem), None).unwrap();
        t.map_write()
            .unwrap()
            .as_mut_slice()
            .copy_from_slice(&[1; 4]);
        t.map().unwrap().as_mut_slice().copy_from_slice(&[2; 4]);
        assert_eq!(t.map_read().unwrap().as_slice(), &[2; 4]);
    }

    /// The read-only IOSurface lock path: a `map_read` must observe data
    /// written through a prior read-write lock, and its unlock (which
    /// skips the cache flush) must not disturb subsequent reads.
    #[test]
    #[cfg(target_os = "macos")]
    fn iosurface_read_only_lock_roundtrip() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        let Ok(t) = Tensor::<u8>::new(&[64], Some(TensorMemory::DmaBuf), None) else {
            crate::test_support::report_skip("IOSurface unavailable");
            return;
        };
        {
            let mut m = t.map_mut().unwrap();
            for (i, b) in m.as_mut_slice().iter_mut().enumerate() {
                *b = (i * 3) as u8;
            }
        }
        for _ in 0..2 {
            let ro = t.map_read().unwrap();
            for (i, b) in ro.as_slice().iter().enumerate() {
                assert_eq!(*b, (i * 3) as u8, "byte {i} through read-only lock");
            }
        }
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            let mut ro = t.map_read().unwrap();
            let _ = ro.as_mut_slice();
        }));
        assert!(result.is_err(), "IOSurface read map must reject mutation");
    }
}

#[cfg(test)]
mod tests {
    #[cfg(target_os = "linux")]
    use nix::unistd::{access, AccessFlags};
    #[cfg(target_os = "linux")]
    use std::io::Write as _;
    use std::sync::{PoisonError, RwLock};

    use super::*;

    #[ctor::ctor(unsafe)]
    fn init() {
        env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
    }

    /// Macro to get the current function name for logging in tests.
    #[cfg(target_os = "linux")]
    macro_rules! function {
        () => {{
            fn f() {}
            fn type_name_of<T>(_: T) -> &'static str {
                std::any::type_name::<T>()
            }
            let name = type_name_of(f);

            // Find and cut the rest of the path
            match &name[..name.len() - 3].rfind(':') {
                Some(pos) => &name[pos + 1..name.len() - 3],
                None => &name[..name.len() - 3],
            }
        }};
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_tensor() {
        let _lock = crate::tests::fd_lock_shared();
        let shape = vec![1];
        let tensor = DmaTensor::<f32>::new(&shape, Some("dma_tensor"));
        let dma_enabled = tensor.is_ok();

        let tensor = Tensor::<f32>::new(&shape, None, None).expect("Failed to create tensor");
        // Auto-select priority is Dma > Mem; Shm is never auto-selected.
        match dma_enabled {
            true => assert_eq!(tensor.memory(), TensorMemory::DmaBuf),
            false => assert_eq!(tensor.memory(), TensorMemory::Mem),
        }
    }

    #[test]
    #[cfg(any(target_os = "macos", target_os = "ios"))]
    fn test_tensor() {
        let shape = vec![1];
        let tensor = Tensor::<f32>::new(&shape, None, None).expect("Failed to create tensor");
        // macOS/iOS auto-fallback chain: IOSurface (Dma) → Mem. Healthy systems
        // return Dma; Mem only appears under memory pressure or sandboxed
        // contexts where IOSurfaceCreate fails. Shm is never auto-selected.
        let m = tensor.memory();
        assert!(
            matches!(m, TensorMemory::DmaBuf | TensorMemory::Mem),
            "Unexpected auto-fallback result on macOS/iOS: {m:?}"
        );
    }

    #[test]
    #[cfg(all(
        unix,
        not(any(target_os = "linux", target_os = "macos", target_os = "ios"))
    ))]
    fn test_tensor() {
        let shape = vec![1];
        let tensor = Tensor::<f32>::new(&shape, None, None).expect("Failed to create tensor");
        // Other Unix (BSD): no DMA, so auto-selection is Mem (Shm is
        // explicit-only, never auto-selected).
        assert_eq!(tensor.memory(), TensorMemory::Mem);
    }

    #[test]
    #[cfg(not(unix))]
    fn test_tensor() {
        let shape = vec![1];
        let tensor = Tensor::<f32>::new(&shape, None, None).expect("Failed to create tensor");
        assert_eq!(tensor.memory(), TensorMemory::Mem);
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_dma_tensor() {
        let _lock = crate::tests::fd_lock_shared();
        match access(
            "/dev/dma_heap/linux,cma",
            AccessFlags::R_OK | AccessFlags::W_OK,
        ) {
            Ok(_) => println!("/dev/dma_heap/linux,cma is available"),
            Err(_) => match access(
                "/dev/dma_heap/system",
                AccessFlags::R_OK | AccessFlags::W_OK,
            ) {
                Ok(_) => println!("/dev/dma_heap/system is available"),
                Err(e) => {
                    writeln!(
                        &mut std::io::stdout(),
                        "[WARNING] DMA Heap is unavailable: {e}"
                    )
                    .unwrap();
                    return;
                }
            },
        }

        let shape = vec![2, 3, 4];
        let tensor =
            DmaTensor::<f32>::new(&shape, Some("test_tensor")).expect("Failed to create tensor");

        const DUMMY_VALUE: f32 = 12.34;

        assert_eq!(tensor.memory(), TensorMemory::DmaBuf);
        assert_eq!(tensor.name(), "test_tensor");
        assert_eq!(tensor.shape(), &shape);
        assert_eq!(tensor.size(), 2 * 3 * 4 * std::mem::size_of::<f32>());
        assert_eq!(tensor.len(), 2 * 3 * 4);

        {
            let mut tensor_map = tensor.map().expect("Failed to map DMA memory");
            tensor_map.fill(42.0);
            assert!(tensor_map.iter().all(|&x| x == 42.0));
        }

        {
            let shared = Tensor::<f32>::from_fd(
                tensor
                    .clone_fd()
                    .expect("Failed to duplicate tensor file descriptor"),
                &shape,
                Some("test_tensor_shared"),
            )
            .expect("Failed to create tensor from fd");

            assert_eq!(shared.memory(), TensorMemory::DmaBuf);
            assert_eq!(shared.name(), "test_tensor_shared");
            assert_eq!(shared.shape(), &shape);

            let mut tensor_map = shared.map().expect("Failed to map DMA memory from fd");
            tensor_map.fill(DUMMY_VALUE);
            assert!(tensor_map.iter().all(|&x| x == DUMMY_VALUE));
        }

        {
            let tensor_map = tensor.map().expect("Failed to map DMA memory");
            assert!(tensor_map.iter().all(|&x| x == DUMMY_VALUE));
        }

        let mut tensor = DmaTensor::<u8>::new(&shape, None).expect("Failed to create tensor");
        assert_eq!(tensor.shape(), &shape);
        let new_shape = vec![3, 4, 4];
        assert!(
            tensor.reshape(&new_shape).is_err(),
            "Reshape should fail due to size mismatch"
        );
        assert_eq!(tensor.shape(), &shape, "Shape should remain unchanged");

        let new_shape = vec![2, 3, 4];
        tensor.reshape(&new_shape).expect("Reshape should succeed");
        assert_eq!(
            tensor.shape(),
            &new_shape,
            "Shape should be updated after successful reshape"
        );

        {
            let mut tensor_map = tensor.map().expect("Failed to map DMA memory");
            tensor_map.fill(1);
            assert!(tensor_map.iter().all(|&x| x == 1));
        }

        {
            let mut tensor_map = tensor.map().expect("Failed to map DMA memory");
            tensor_map[2] = 42;
            assert_eq!(tensor_map[1], 1, "Value at index 1 should be 1");
            assert_eq!(tensor_map[2], 42, "Value at index 2 should be 42");
        }
    }

    #[test]
    #[cfg(unix)]
    fn test_shm_tensor() {
        let _lock = crate::tests::fd_lock_shared();
        if !is_shm_available() {
            log::warn!("SKIPPED: test_shm_tensor - SHM allocation unavailable on this platform");
            return;
        }
        let shape = vec![2, 3, 4];
        let tensor =
            ShmTensor::<f32>::new(&shape, Some("test_tensor")).expect("Failed to create tensor");
        assert_eq!(tensor.shape(), &shape);
        assert_eq!(tensor.size(), 2 * 3 * 4 * std::mem::size_of::<f32>());
        assert_eq!(tensor.name(), "test_tensor");

        const DUMMY_VALUE: f32 = 12.34;
        {
            let mut tensor_map = tensor.map().expect("Failed to map shared memory");
            tensor_map.fill(42.0);
            assert!(tensor_map.iter().all(|&x| x == 42.0));
        }

        {
            let shared = Tensor::<f32>::from_fd(
                tensor
                    .clone_fd()
                    .expect("Failed to duplicate tensor file descriptor"),
                &shape,
                Some("test_tensor_shared"),
            )
            .expect("Failed to create tensor from fd");

            assert_eq!(shared.memory(), TensorMemory::Shm);
            assert_eq!(shared.name(), "test_tensor_shared");
            assert_eq!(shared.shape(), &shape);

            let mut tensor_map = shared.map().expect("Failed to map shared memory from fd");
            tensor_map.fill(DUMMY_VALUE);
            assert!(tensor_map.iter().all(|&x| x == DUMMY_VALUE));
        }

        {
            let tensor_map = tensor.map().expect("Failed to map shared memory");
            assert!(tensor_map.iter().all(|&x| x == DUMMY_VALUE));
        }

        let mut tensor = ShmTensor::<u8>::new(&shape, None).expect("Failed to create tensor");
        assert_eq!(tensor.shape(), &shape);
        let new_shape = vec![3, 4, 4];
        assert!(
            tensor.reshape(&new_shape).is_err(),
            "Reshape should fail due to size mismatch"
        );
        assert_eq!(tensor.shape(), &shape, "Shape should remain unchanged");

        let new_shape = vec![2, 3, 4];
        tensor.reshape(&new_shape).expect("Reshape should succeed");
        assert_eq!(
            tensor.shape(),
            &new_shape,
            "Shape should be updated after successful reshape"
        );

        {
            let mut tensor_map = tensor.map().expect("Failed to map shared memory");
            tensor_map.fill(1);
            assert!(tensor_map.iter().all(|&x| x == 1));
        }

        {
            let mut tensor_map = tensor.map().expect("Failed to map shared memory");
            tensor_map[2] = 42;
            assert_eq!(tensor_map[1], 1, "Value at index 1 should be 1");
            assert_eq!(tensor_map[2], 42, "Value at index 2 should be 42");
        }
    }

    #[test]
    fn mem_subview_partitions_parent_buffer() {
        // One heap [2,4] u8 parent (8 bytes). Two [1,4] sub-views at byte
        // offsets 0 and 4 must share the parent allocation (zero-copy) and be
        // independently writable: view 0 owns bytes [0,4), view 1 owns [4,8).
        // Today this is impossible — heap offset is rejected and there is no
        // shared sub-view constructor.
        let parent = Tensor::<u8>::new(&[2, 4], Some(TensorMemory::Mem), None).unwrap();
        let view0 = parent.subview(0, &[1, 4]).expect("subview at offset 0");
        let view1 = parent.subview(4, &[1, 4]).expect("subview at offset 4");

        view1
            .map()
            .unwrap()
            .as_mut_slice()
            .copy_from_slice(&[10, 20, 30, 40]);
        view0
            .map()
            .unwrap()
            .as_mut_slice()
            .copy_from_slice(&[1, 2, 3, 4]);

        // Each view sees only its own window.
        assert_eq!(view0.map().unwrap().as_slice(), &[1, 2, 3, 4]);
        assert_eq!(view1.map().unwrap().as_slice(), &[10, 20, 30, 40]);
        // The parent buffer is correctly partitioned (shared, zero-copy).
        assert_eq!(
            parent.map().unwrap().as_slice(),
            &[1, 2, 3, 4, 10, 20, 30, 40]
        );
    }

    #[test]
    fn batch_partitions_leading_dim() {
        // Raw [4,2,2,3] u8 batched tensor: 4 elements of 12 bytes each. batch(n)
        // yields element n at offset n*12, sharing the parent buffer (zero-copy).
        let parent = Tensor::<u8>::new(&[4, 2, 2, 3], Some(TensorMemory::Mem), None).unwrap();
        for i in 0..4u8 {
            let e = parent.batch(i as usize).expect("batch element");
            assert_eq!(e.shape(), &[2, 2, 3]);
            // A batch element shares the parent's BufferIdentity.
            assert_eq!(e.buffer_identity().id(), parent.buffer_identity().id());
            for b in e.map().unwrap().as_mut_slice() {
                *b = i + 1;
            }
        }
        // Each element occupies its own 12-byte band of the parent.
        let whole = parent.map().unwrap();
        let s = whole.as_slice();
        for i in 0..4usize {
            assert!(
                s[i * 12..(i + 1) * 12].iter().all(|&b| b == (i as u8 + 1)),
                "band {i} not partitioned: {:?}",
                &s[i * 12..(i + 1) * 12]
            );
        }
    }

    #[test]
    fn view_origin_snapshots_parent_and_composes() {
        // view() on a whole image snapshots the parent dims + the view's origin.
        let parent = Tensor::<u8>::image(
            100,
            80,
            PixelFormat::Rgba,
            Some(TensorMemory::Mem),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(
            parent.view_origin(),
            None,
            "whole tensor has no view_origin"
        );
        let v = parent.view(Region::new(10, 20, 30, 40)).unwrap();
        assert_eq!(
            v.view_origin(),
            Some(ViewOrigin {
                parent_width: 100,
                parent_height: 80,
                parent_row_stride: 100 * 4, // tight RGBA pitch
                x: 10,
                y: 20
            })
        );
        // A view of a view keeps the ROOT parent and accumulates the origin.
        let v2 = v.view(Region::new(5, 5, 10, 10)).unwrap();
        assert_eq!(
            v2.view_origin(),
            Some(ViewOrigin {
                parent_width: 100,
                parent_height: 80,
                parent_row_stride: 100 * 4,
                x: 15,
                y: 25
            }),
            "nested view composes onto the root parent"
        );
    }

    #[test]
    fn view_origin_none_for_raw_batch() {
        // A raw (unformatted) batched tensor has no pixel geometry, so batch()
        // leaves view_origin None (the per-slot path, not the one-import pivot).
        let parent = Tensor::<u8>::new(&[4, 2, 2, 3], Some(TensorMemory::Mem), None).unwrap();
        assert_eq!(parent.batch(2).unwrap().view_origin(), None);
    }

    #[test]
    fn batch_rejects_out_of_bounds_index() {
        let parent = Tensor::<u8>::new(&[4, 2, 2, 3], Some(TensorMemory::Mem), None).unwrap();
        match parent.batch(4) {
            Err(Error::BatchIndexOutOfBounds { index, batch }) => {
                assert_eq!((index, batch), (4, 4));
            }
            other => panic!("expected BatchIndexOutOfBounds, got {other:?}"),
        }
    }

    #[test]
    fn batch_zero_on_unit_n_is_whole() {
        // N == 1: batch(0) is the whole per-element block at offset 0 (no plane_offset).
        let parent = Tensor::<u8>::new(&[1, 2, 2, 3], Some(TensorMemory::Mem), None).unwrap();
        let e = parent.batch(0).unwrap();
        assert_eq!(e.shape(), &[2, 2, 3]);
        assert_eq!(e.plane_offset(), None);
        assert_eq!(e.buffer_identity().id(), parent.buffer_identity().id());
    }

    #[test]
    fn mem_subview_rejects_unaligned_offset() {
        // f32 has align 4; a byte offset of 2 cannot back a valid `*const f32`.
        let parent = Tensor::<f32>::new(&[8], Some(TensorMemory::Mem), None).unwrap();
        assert!(parent.subview(2, &[1]).is_err());
        // A correctly aligned offset is accepted.
        assert!(parent.subview(4, &[1]).is_ok());
    }

    #[test]
    fn mem_subview_rejects_out_of_bounds() {
        let parent = Tensor::<u8>::new(&[8], Some(TensorMemory::Mem), None).unwrap();
        // offset 6 + 4 bytes = 10 exceeds the 8-byte allocation.
        assert!(parent.subview(6, &[4]).is_err());
    }

    /// Regression guard for the `TensorTrait::view` promotion (R2): a `subview`
    /// must share the parent's `BufferIdentity` on **every** backend, not mint a
    /// fresh one. Identity-keyed caches (the GL EGLImage import) rely on this to
    /// treat offset-distinct windows of one buffer as a single import; a fresh
    /// identity would silently break that and regress zero-copy import reuse.
    ///
    /// Runs each backend that can be allocated without a GPU/GL context on the
    /// test host: `Mem` (always); `Shm` (when POSIX shm is available); the
    /// platform-native zero-copy buffer `Dma` (DMA-BUF on Linux / IOSurface on
    /// macOS, when available). `Pbo` shares its identity the same way (see
    /// `pbo.rs` `view`) but needs a live GL context, so it is exercised by the
    /// image-crate GL tests rather than here.
    #[test]
    fn subview_shares_buffer_identity_all_backends() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // u8 has align 1, so every byte offset is valid for the alignment check;
        // this isolates the identity-sharing contract from alignment concerns.
        // `window` is the view shape; a formatted parent validates it against
        // its own format, so an image parent needs an image-shaped window.
        let assert_parent_shares = |parent: Tensor<u8>, window: &[usize], label: &str| {
            let parent_id = parent.buffer_identity().id();
            // Two offset-distinct windows must both carry the parent's identity.
            let v0 = parent
                .subview(0, window)
                .unwrap_or_else(|e| panic!("{label}: subview(0) failed: {e:?}"));
            let v1 = parent
                .subview(16, window)
                .unwrap_or_else(|e| panic!("{label}: subview(16) failed: {e:?}"));
            assert_eq!(
                v0.buffer_identity().id(),
                parent_id,
                "{label}: subview(0) minted a fresh BufferIdentity"
            );
            assert_eq!(
                v1.buffer_identity().id(),
                parent_id,
                "{label}: subview(16) minted a fresh BufferIdentity"
            );
        };
        let assert_shares = |memory: TensorMemory, label: &str| {
            let parent = Tensor::<u8>::new(&[64], Some(memory), None)
                .unwrap_or_else(|e| panic!("{label}: parent alloc failed: {e:?}"));
            assert_parent_shares(parent, &[16], label);
        };

        assert_shares(TensorMemory::Mem, "Mem");

        #[cfg(unix)]
        if crate::is_shm_available() {
            assert_shares(TensorMemory::Shm, "Shm");
        }

        // Dma == DMA-BUF on Linux, IOSurface on macOS, AHardwareBuffer on
        // Android; same public variant.
        #[cfg(not(target_os = "windows"))]
        if crate::is_gpu_buffer_available() {
            assert_shares(TensorMemory::DmaBuf, "Dma");
        }
        // Windows' Dma is an image-formatted D3D11 texture, which
        // `Tensor::new` deliberately refuses -- allocate it the only way it
        // can be allocated and hold it to the same contract.
        #[cfg(target_os = "windows")]
        if crate::is_gpu_buffer_available() {
            let parent = Tensor::<u8>::image(
                64,
                1,
                PixelFormat::Grey,
                Some(TensorMemory::DmaBuf),
                CpuAccess::ReadWrite,
            )
            .expect("D3D11 texture alloc failed");
            assert_parent_shares(parent, &[1, 16, 1], "Dma");
        }
    }

    /// A sub-view records a plane offset, and on Windows the D3D11 storage
    /// already applied that offset itself when the view was made -- so the
    /// map's plane-offset gate must accept it, exactly as it does for the
    /// other zero-copy backings. It used to refuse, with a message that named
    /// every backend but this one.
    #[cfg(target_os = "windows")]
    #[test]
    fn subview_of_a_texture_tensor_maps_at_its_offset() {
        if !crate::is_gpu_buffer_available() {
            return;
        }
        let t = Tensor::<u8>::image(
            32,
            8,
            PixelFormat::Rgba,
            Some(TensorMemory::DmaBuf),
            CpuAccess::ReadWrite,
        )
        .unwrap();
        // For a texture tensor this is the backing pitch either way: the
        // allocation records the staging pitch when it exceeds the tight row,
        // and the two are equal when it does not.
        let stride = t.effective_row_stride().unwrap();
        let v = t.subview(stride * 2, &[2, 32, 4]).unwrap();
        assert!(
            v.plane_offset().is_some_and(|o| o > 0),
            "a sub-view at a row offset must carry one"
        );
        let m = v
            .map_read()
            .expect("a sub-view of a texture tensor must map");
        assert_eq!(m.as_slice().len(), 2 * stride, "two rows of the window");
    }

    #[test]
    fn mem_subview_four_views_no_aliasing() {
        // One [4,3] f32 parent; four [1,3] views at 12-byte strides, each
        // written independently. Exercises a multi-byte element type (offsets
        // must stay element-aligned) and N-way zero-copy sharing.
        let parent = Tensor::<f32>::new(&[4, 3], Some(TensorMemory::Mem), None).unwrap();
        let frame = 3 * std::mem::size_of::<f32>();
        for i in 0..4 {
            let v = parent.subview(i * frame, &[1, 3]).unwrap();
            let val = i as f32 + 1.0;
            v.map()
                .unwrap()
                .as_mut_slice()
                .copy_from_slice(&[val, val, val]);
        }
        assert_eq!(
            parent.map().unwrap().as_slice(),
            &[1.0, 1.0, 1.0, 2.0, 2.0, 2.0, 3.0, 3.0, 3.0, 4.0, 4.0, 4.0]
        );
    }

    #[test]
    fn mem_subview_inherits_format_and_row_stride() {
        // A sub-view is a ready-to-use sub-image: it inherits the parent's
        // pixel format and (crucially) its padded row stride, so a strided
        // parent yields strided windows. Set a stride wider than the tight row
        // to exercise the row_stride inheritance path specifically.
        let mut parent = Tensor::<u8>::image(
            100,
            100,
            PixelFormat::Rgba,
            Some(TensorMemory::Mem),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        parent.set_row_stride_unchecked(512); // padded stride (> 100*4)
        let view = parent.subview(4096, &[10, 10, 4]).unwrap();
        assert_eq!(view.format(), Some(PixelFormat::Rgba), "format inherited");
        assert_eq!(view.row_stride(), Some(512), "row_stride inherited");
    }

    #[test]
    fn mem_strided_subview_maps_offset_and_byte_size() {
        // Integration of the sub-region offset (PR #89) and the strided-map
        // `byte_size_override` (PR #90): a strided sub-view exposes its full
        // padded window (`row_stride × rows`) starting at the view's byte
        // offset, mapped zero-copy into the parent.
        let parent = Tensor::<u8>::new(&[2048], Some(TensorMemory::Mem), None).unwrap();
        let mut view = parent.subview(128, &[8, 16]).unwrap(); // 8 rows × 16 @ off 128
        assert_eq!(view.plane_offset(), Some(128));
        view.set_row_stride_unchecked(32); // padded stride (> 16)

        {
            let mut m = view.map().unwrap();
            let s = m.as_mut_slice();
            // Strided map exposes the padded window: stride(32) × rows(8) = 256.
            assert_eq!(
                s.len(),
                256,
                "strided map exposes the full padded byte window"
            );
            s[0] = 0xAA; // row 0, col 0
            s[32] = 0xBB; // row 1, col 0 (one stride in)
        }

        // Zero-copy: the writes land in the parent at the view's offset.
        let p = parent.map().unwrap();
        let pb = p.as_slice();
        assert_eq!(pb[128], 0xAA, "row 0 writes at parent offset 128");
        assert_eq!(
            pb[128 + 32],
            0xBB,
            "row 1 writes at parent offset 128 + stride"
        );
    }

    #[test]
    #[cfg(unix)]
    fn shm_subview_partitions_parent_buffer() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Mirrors `mem_subview_partitions_parent_buffer` for Shm: one [2,4] u8
        // parent shared segment (8 bytes); two [1,4] sub-views at byte offsets 0
        // and 4 must share the segment (zero-copy, via cloned fd) and be
        // independently writable — view 0 owns [0,4), view 1 owns [4,8).
        if !crate::is_shm_available() {
            crate::test_support::report_skip("shm not available");
            return;
        }
        let parent = Tensor::<u8>::new(&[2, 4], Some(TensorMemory::Shm), None).unwrap();
        let view0 = parent.subview(0, &[1, 4]).expect("shm subview at offset 0");
        let view1 = parent.subview(4, &[1, 4]).expect("shm subview at offset 4");

        view1
            .map()
            .unwrap()
            .as_mut_slice()
            .copy_from_slice(&[10, 20, 30, 40]);
        view0
            .map()
            .unwrap()
            .as_mut_slice()
            .copy_from_slice(&[1, 2, 3, 4]);

        assert_eq!(view0.map().unwrap().as_slice(), &[1, 2, 3, 4]);
        assert_eq!(view1.map().unwrap().as_slice(), &[10, 20, 30, 40]);
        // The parent sees the full partitioned segment (shared, zero-copy).
        assert_eq!(
            parent.map().unwrap().as_slice(),
            &[1, 2, 3, 4, 10, 20, 30, 40]
        );
        // A sub-view of a sub-view composes the offset.
        let nested = view1.subview(2, &[1, 2]).expect("nested shm subview");
        assert_eq!(nested.map().unwrap().as_slice(), &[30, 40]);
    }

    #[test]
    #[cfg(unix)]
    fn shm_subview_rejects_unaligned_and_oob() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        if !crate::is_shm_available() {
            crate::test_support::report_skip("shm not available");
            return;
        }
        // f32 align 4: a 2-byte offset cannot back a valid `*const f32`.
        let parent = Tensor::<f32>::new(&[8], Some(TensorMemory::Shm), None).unwrap();
        assert!(parent.subview(2, &[1]).is_err());
        assert!(parent.subview(4, &[1]).is_ok());
        // Out of bounds: offset 6 + 4 bytes = 10 > 8-byte (u8) segment.
        let p2 = Tensor::<u8>::new(&[8], Some(TensorMemory::Shm), None).unwrap();
        assert!(p2.subview(6, &[4]).is_err());
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn dma_subview_matches_mem_subview() {
        // Serialize against the fd-leak tests: this test opens DMA fds (alloc +
        // clone_fd), which would otherwise perturb their fd counts.
        let _lock = crate::tests::fd_lock_shared();
        // Identical sub-view semantics across Dma (shared fd) and Mem (shared
        // Arc): same offsets → same logical windows → same partition.
        let dma = match Tensor::<u8>::new(&[8], Some(TensorMemory::DmaBuf), None) {
            Ok(t) => t,
            Err(_) => {
                crate::test_support::report_skip("DMA not available");
                return;
            }
        };
        let mem = Tensor::<u8>::new(&[8], Some(TensorMemory::Mem), None).unwrap();
        for parent in [&dma, &mem] {
            let v0 = parent.subview(0, &[4]).unwrap();
            let v1 = parent.subview(4, &[4]).unwrap();
            v0.map()
                .unwrap()
                .as_mut_slice()
                .copy_from_slice(&[1, 2, 3, 4]);
            v1.map()
                .unwrap()
                .as_mut_slice()
                .copy_from_slice(&[5, 6, 7, 8]);
            assert_eq!(parent.map().unwrap().as_slice(), &[1, 2, 3, 4, 5, 6, 7, 8]);
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn dma_strided_subview_maps_padded_window() {
        // The strided-map path differs by backing: DMA maps through
        // `mmap_offset` + the `byte_size_override`, not the Mem `Arc` slice. A
        // padded sub-view of a DMA buffer must still expose its full
        // `row_stride × rows` window zero-copy at the view's offset (the GPU
        // batched-render-to-DMA case). Mirrors
        // `mem_strided_subview_maps_offset_and_byte_size` on a Dma parent.
        let _lock = crate::tests::fd_lock_shared();
        let parent = match Tensor::<u8>::new(&[2048], Some(TensorMemory::DmaBuf), None) {
            Ok(t) => t,
            Err(_) => {
                crate::test_support::report_skip("DMA not available");
                return;
            }
        };
        let mut view = parent.subview(128, &[8, 16]).unwrap();
        assert_eq!(view.plane_offset(), Some(128));
        view.set_row_stride_unchecked(32); // padded stride (> 16)

        {
            let mut m = view.map().unwrap();
            let s = m.as_mut_slice();
            assert_eq!(s.len(), 256, "strided DMA map exposes stride(32) × rows(8)");
            s[0] = 0xAA; // row 0, col 0
            s[32] = 0xBB; // row 1, col 0 (one stride in)
        }

        let p = parent.map().unwrap();
        let pb = p.as_slice();
        assert_eq!(pb[128], 0xAA, "row 0 writes at parent offset 128");
        assert_eq!(
            pb[128 + 32],
            0xBB,
            "row 1 writes at parent offset 128 + stride"
        );
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn view_single_row_snapshots_parent_stride() {
        // A single-row `view()` keeps a TIGHT `row_stride` for map-span safety,
        // but its `view_origin` snapshots the PARENT row stride — the GL backend
        // keys its EGLImage import/pitch on that snapshot (not the view's tight
        // stride), so single-row and multi-row sibling views collapse onto the
        // same parent import.
        let _lock = crate::tests::fd_lock_shared();
        // 8x4 RGBA with a padded 64-byte row stride (tight row = 8*4 = 32).
        let parent = match Tensor::<u8>::image_with_stride(
            8,
            4,
            PixelFormat::Rgba,
            64,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        ) {
            Ok(t) => t,
            Err(_) => {
                crate::test_support::report_skip("DMA not available");
                return;
            }
        };
        assert_eq!(parent.effective_row_stride(), Some(64));
        // Bottom row (y=3) at x>0 — the case the tight single-row stride guards.
        let row = parent.view(Region::new(2, 3, 4, 1)).unwrap();
        // The view's own stride is tight (4*4 = 16) so its strided map stays in
        // bounds; the GL-facing parent pitch (64) lives in `view_origin`.
        assert_eq!(row.effective_row_stride(), Some(16));
        let vo = row.view_origin().expect("a view carries a view_origin");
        assert_eq!(
            vo.parent_row_stride, 64,
            "GL keys/pitches a view on the parent stride, not its tight one"
        );
        // The tight stride keeps map() in-bounds for the bottom / x>0 single row.
        assert_eq!(row.map().unwrap().as_slice().len(), 16);
    }

    #[test]
    fn test_mem_tensor() {
        let shape = vec![2, 3, 4];
        let tensor =
            MemTensor::<f32>::new(&shape, Some("test_tensor")).expect("Failed to create tensor");
        assert_eq!(tensor.shape(), &shape);
        assert_eq!(tensor.size(), 2 * 3 * 4 * std::mem::size_of::<f32>());
        assert_eq!(tensor.name(), "test_tensor");

        {
            let mut tensor_map = tensor.map().expect("Failed to map memory");
            tensor_map.fill(42.0);
            assert!(tensor_map.iter().all(|&x| x == 42.0));
        }

        let mut tensor = MemTensor::<u8>::new(&shape, None).expect("Failed to create tensor");
        assert_eq!(tensor.shape(), &shape);
        let new_shape = vec![3, 4, 4];
        assert!(
            tensor.reshape(&new_shape).is_err(),
            "Reshape should fail due to size mismatch"
        );
        assert_eq!(tensor.shape(), &shape, "Shape should remain unchanged");

        let new_shape = vec![2, 3, 4];
        tensor.reshape(&new_shape).expect("Reshape should succeed");
        assert_eq!(
            tensor.shape(),
            &new_shape,
            "Shape should be updated after successful reshape"
        );

        {
            let mut tensor_map = tensor.map().expect("Failed to map memory");
            tensor_map.fill(1);
            assert!(tensor_map.iter().all(|&x| x == 1));
        }

        {
            let mut tensor_map = tensor.map().expect("Failed to map memory");
            tensor_map[2] = 42;
            assert_eq!(tensor_map[1], 1, "Value at index 1 should be 1");
            assert_eq!(tensor_map[2], 42, "Value at index 2 should be 42");
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_dma_no_fd_leaks() {
        let _lock = fd_lock_exclusive();
        if !is_dma_available() {
            log::warn!(
                "SKIPPED: {} - DMA memory allocation not available (permission denied or no DMA-BUF support)",
                function!()
            );
            return;
        }

        let baseline = open_fd_count(DMA_FD_TARGETS);

        // Self-check — see `test_shm_no_fd_leaks`.
        {
            let probe = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::DmaBuf), None)
                .expect("Failed to create tensor");
            assert!(
                open_fd_count(DMA_FD_TARGETS) > baseline,
                "a live DMA-BUF tensor must be visible to the dmabuf fd counter, \
                 otherwise this test cannot detect a leak"
            );
            drop(probe);
        }

        for _ in 0..100 {
            let tensor = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::DmaBuf), None)
                .expect("Failed to create tensor");
            let mut map = tensor.map().unwrap();
            map.as_mut_slice().fill(233);
        }

        let after = open_fd_count(DMA_FD_TARGETS);
        assert_eq!(
            baseline, after,
            "DMA-BUF file descriptor leak detected: {baseline} -> {after}"
        );
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_dma_from_fd_no_fd_leaks() {
        let _lock = fd_lock_exclusive();
        if !is_dma_available() {
            log::warn!(
                "SKIPPED: {} - DMA memory allocation not available (permission denied or no DMA-BUF support)",
                function!()
            );
            return;
        }

        let baseline = open_fd_count(DMA_FD_TARGETS);
        let orig = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::DmaBuf), None).unwrap();

        // Self-check — see `test_shm_no_fd_leaks`.
        let held = open_fd_count(DMA_FD_TARGETS);
        assert!(
            held > baseline,
            "a live DMA-BUF tensor must be visible to the dmabuf fd counter, \
             otherwise this test cannot detect a leak"
        );

        for _ in 0..100 {
            let tensor =
                Tensor::<u8>::from_fd(orig.clone_fd().unwrap(), orig.shape(), None).unwrap();
            assert_eq!(
                tensor.memory(),
                TensorMemory::DmaBuf,
                "DMA-BUF fd must import as Dma, not be silently downgraded"
            );
            let mut map = tensor.map().unwrap();
            map.as_mut_slice().fill(233);
        }

        let after_loop = open_fd_count(DMA_FD_TARGETS);
        assert_eq!(
            held, after_loop,
            "DMA-BUF file descriptor leak detected: {held} -> {after_loop}"
        );

        // And the source tensor's own fd goes back on drop.
        drop(orig);
        let after_drop = open_fd_count(DMA_FD_TARGETS);
        assert_eq!(
            baseline, after_drop,
            "dropping the source tensor must release its fd: {baseline} -> {after_drop}"
        );
    }

    /// A filesystem magic must report its true 32-bit value regardless of
    /// how wide, and how signed, `fstatfs`'s `f_type` is on the target.
    ///
    /// `fs_type_t` is `__fsword_t` on Linux/gnu — `i64` on 64-bit but `i32`
    /// on 32-bit (armv7, i686, aarch64-ilp32) — `c_int` on uclibc, and
    /// unsigned on musl and s390x. Widening a *signed* 32-bit `f_type`
    /// sign-extends every magic with bit 31 set, so a naive widening cast
    /// reports e.g. `0xffffffff958458f6` for hugetlbfs. The docs tell
    /// callers to look the reported value up in `include/uapi/linux/magic.h`,
    /// so a sign-extended value is actively misleading.
    ///
    /// This cannot be reproduced on a 64-bit host — the defect only exists
    /// where `f_type` is a signed 32-bit type — so the test drives the
    /// conversion directly with the value such a target would produce.
    #[test]
    #[cfg(target_os = "linux")]
    fn test_fs_magic_normalizes_sign_extended_values() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Magics whose bit 31 is set. HUGETLBFS is the one that matters
        // most in practice: a MFD_HUGETLB memfd is the likeliest fd to land
        // in the UnknownBufferType arm.
        const HUGETLBFS_MAGIC: u32 = 0x9584_58f6;
        const F2FS_MAGIC: u32 = 0xf2f5_2010;
        const BTRFS_MAGIC: u32 = 0x9123_683e;

        for magic in [HUGETLBFS_MAGIC, F2FS_MAGIC, BTRFS_MAGIC] {
            // 64-bit gnu: f_type is i64 and already holds the true value.
            assert_eq!(fs_magic(i64::from(magic)), magic);

            // 32-bit gnu / uclibc: f_type is i32, so the value arrives
            // sign-extended once widened. It must still report its true
            // 32 bits.
            let sign_extended = i64::from(magic as i32);
            assert!(sign_extended < 0, "{magic:#x} should have bit 31 set");
            assert_eq!(
                fs_magic(sign_extended),
                magic,
                "{magic:#x} must survive a signed 32-bit f_type"
            );
        }

        // The two magics we actually classify on are below 2^31, so they are
        // unaffected by signedness either way — this is why the DMA-vs-SHM
        // decision is correct on 32-bit even without this normalization.
        for magic in [DMA_BUF_MAGIC, TMPFS_MAGIC] {
            assert!(magic < 0x8000_0000);
            assert_eq!(fs_magic(i64::from(magic as i32)), magic);
        }
    }

    /// A DMA-BUF fd must import as [`TensorMemory::DmaBuf`].
    ///
    /// Regression test for the `st_dev` minor-number classifier, which
    /// hardcoded `9 | 10` as "this is DMA". Those minors come from
    /// `get_anon_bdev()` and are assigned first-come-first-served at boot,
    /// so they vary by kernel build and boot order — a real DMA-BUF is
    /// minor 12 on x86 desktop and minor 8 on the ADIS Verdin. Both fell
    /// into the `_` arm and imported as SHM, which "works" (a DMA-BUF is
    /// mmap-able) but silently forfeits zero-copy.
    #[test]
    #[cfg(target_os = "linux")]
    fn test_from_fd_dma_imports_as_dma() {
        let _lock = crate::tests::fd_lock_shared();
        if !is_dma_available() {
            log::warn!("SKIPPED: {} - DMA memory not available", function!());
            return;
        }

        let orig = Tensor::<u8>::new(&[64, 64], Some(TensorMemory::DmaBuf), None).unwrap();
        assert_eq!(orig.memory(), TensorMemory::DmaBuf);

        let imported = Tensor::<u8>::from_fd(orig.clone_fd().unwrap(), orig.shape(), None).unwrap();

        assert_eq!(
            imported.memory(),
            TensorMemory::DmaBuf,
            "a DMA-BUF fd must import as Dma"
        );
    }

    /// A tmpfs/SHM fd must import as [`TensorMemory::Shm`].
    ///
    /// The companion to `test_from_fd_dma_imports_as_dma`: confirms the
    /// magic-based classifier identifies SHM positively rather than by
    /// falling through.
    #[test]
    #[cfg(target_os = "linux")]
    fn test_from_fd_shm_imports_as_shm() {
        let _lock = crate::tests::fd_lock_shared();
        if !is_shm_available() {
            log::warn!("SKIPPED: {} - SHM memory not available", function!());
            return;
        }

        let orig = Tensor::<u8>::new(&[64, 64], Some(TensorMemory::Shm), None).unwrap();
        assert_eq!(orig.memory(), TensorMemory::Shm);

        let imported = Tensor::<u8>::from_fd(orig.clone_fd().unwrap(), orig.shape(), None).unwrap();

        assert_eq!(
            imported.memory(),
            TensorMemory::Shm,
            "a tmpfs fd must import as Shm"
        );
    }

    /// An fd that is neither a DMA-BUF nor tmpfs must be rejected.
    ///
    /// A pipe is the convenient probe: it lives on `pipefs`, another
    /// `get_anon_bdev()` pseudo-filesystem, so it shares major 0 with the
    /// buffer types we do support and is only distinguishable by magic.
    /// Importing one as SHM is meaningless — `mmap` on a pipe fails — so
    /// the classifier must say "unknown" rather than guess.
    #[test]
    #[cfg(target_os = "linux")]
    fn test_from_fd_rejects_unknown_filesystem() {
        let _lock = crate::tests::fd_lock_shared();

        let (read_end, _write_end) = nix::unistd::pipe().unwrap();

        let result = Tensor::<u8>::from_fd(read_end, &[64], None);

        match result {
            Err(Error::UnknownBufferType(magic)) => {
                // PIPEFS_MAGIC, from include/uapi/linux/magic.h
                assert_eq!(magic, 0x5049_5045, "expected PIPEFS_MAGIC");
            }
            other => panic!("expected UnknownBufferType for a pipe fd, got {other:?}"),
        }
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_shm_no_fd_leaks() {
        let _lock = fd_lock_exclusive();
        if !is_shm_available() {
            log::warn!(
                "SKIPPED: {} - SHM memory allocation not available (permission denied or no SHM support)",
                function!()
            );
            return;
        }

        let baseline = open_fd_count(SHM_FD_TARGETS);

        // Self-check: the counter must actually see a live shm tensor. If
        // it does not — a changed backing object, a different `/proc`
        // rendering — the leak assertion below would hold no matter how
        // much leaked, so fail loudly here instead.
        {
            let probe = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::Shm), None)
                .expect("Failed to create tensor");
            assert!(
                open_fd_count(SHM_FD_TARGETS) > baseline,
                "a live shm tensor must be visible to the shm fd counter, \
                 otherwise this test cannot detect a leak"
            );
            drop(probe);
        }

        for _ in 0..100 {
            let tensor = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::Shm), None)
                .expect("Failed to create tensor");
            let mut map = tensor.map().unwrap();
            map.as_mut_slice().fill(233);
        }

        let after = open_fd_count(SHM_FD_TARGETS);
        assert_eq!(
            baseline, after,
            "shm file descriptor leak detected: {baseline} -> {after}"
        );
    }

    #[test]
    #[cfg(target_os = "linux")]
    fn test_shm_from_fd_no_fd_leaks() {
        let _lock = fd_lock_exclusive();
        if !is_shm_available() {
            log::warn!(
                "SKIPPED: {} - SHM memory allocation not available (permission denied or no SHM support)",
                function!()
            );
            return;
        }

        let baseline = open_fd_count(SHM_FD_TARGETS);
        let orig = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::Shm), None).unwrap();

        // Self-check — see `test_shm_no_fd_leaks`.
        let held = open_fd_count(SHM_FD_TARGETS);
        assert!(
            held > baseline,
            "a live shm tensor must be visible to the shm fd counter, \
             otherwise this test cannot detect a leak"
        );

        for _ in 0..100 {
            let tensor =
                Tensor::<u8>::from_fd(orig.clone_fd().unwrap(), orig.shape(), None).unwrap();
            let mut map = tensor.map().unwrap();
            map.as_mut_slice().fill(233);
        }

        let after_loop = open_fd_count(SHM_FD_TARGETS);
        assert_eq!(
            held, after_loop,
            "shm file descriptor leak detected: {held} -> {after_loop}"
        );

        // And the source tensor's own fd goes back on drop.
        drop(orig);
        let after_drop = open_fd_count(SHM_FD_TARGETS);
        assert_eq!(
            baseline, after_drop,
            "dropping the source tensor must release its fd: {baseline} -> {after_drop}"
        );
    }

    #[cfg(feature = "ndarray")]
    #[test]
    fn test_ndarray() {
        let _lock = crate::tests::fd_lock_shared();
        let shape = vec![2, 3, 4];
        let tensor = Tensor::<f32>::new(&shape, None, None).expect("Failed to create tensor");

        let mut tensor_map = tensor.map().expect("Failed to map tensor memory");
        tensor_map.fill(1.0);

        let view = tensor_map.view().expect("Failed to get ndarray view");
        assert_eq!(view.shape(), &[2, 3, 4]);
        assert!(view.iter().all(|&x| x == 1.0));

        let mut view_mut = tensor_map
            .view_mut()
            .expect("Failed to get mutable ndarray view");
        view_mut[[0, 0, 0]] = 42.0;
        assert_eq!(view_mut[[0, 0, 0]], 42.0);
        assert_eq!(tensor_map[0], 42.0, "Value at index 0 should be 42");
    }

    #[test]
    fn test_buffer_identity_derived_equality() {
        // Two identities derived from the same kind and key must be equal —
        // that is the whole point of `derived`: two independently-linked
        // copies of this crate, each importing the same underlying buffer,
        // have to agree on its id without talking to each other.
        let id1 = BufferIdentity::derived(IdentityKind::DmaBuf, 4242);
        let id2 = BufferIdentity::derived(IdentityKind::DmaBuf, 4242);
        assert_eq!(
            id1.id(),
            id2.id(),
            "Identities derived from the same kind and key should match"
        );

        // A different key still yields a different id.
        let id3 = BufferIdentity::derived(IdentityKind::DmaBuf, 4243);
        assert_ne!(
            id1.id(),
            id3.id(),
            "Identities derived from different keys should differ"
        );
    }

    #[test]
    fn test_buffer_identity_clone_shares_guard() {
        let id1 = BufferIdentity::derived(IdentityKind::DmaBuf, 4242);
        let weak = id1.weak();
        assert!(
            weak.upgrade().is_some(),
            "Weak should be alive while original exists"
        );

        let id2 = id1.clone();
        assert_eq!(id1.id(), id2.id(), "Cloned identity should have same id");

        drop(id1);
        assert!(
            weak.upgrade().is_some(),
            "Weak should still be alive (clone holds Arc)"
        );

        drop(id2);
        assert!(
            weak.upgrade().is_none(),
            "Weak should be dead after all clones dropped"
        );
    }

    #[test]
    fn test_tensor_buffer_identity() {
        let t1 = Tensor::<u8>::new(&[100], Some(TensorMemory::Mem), Some("t1")).unwrap();
        let t2 = Tensor::<u8>::new(&[100], Some(TensorMemory::Mem), Some("t2")).unwrap();
        assert_ne!(
            t1.buffer_identity().id(),
            t2.buffer_identity().id(),
            "Different tensors should have different buffer ids"
        );
    }

    // ------------------------------------------------------------------------
    // Quantization — constructor validation + accessor correctness.
    // ------------------------------------------------------------------------

    #[test]
    fn test_quantization_per_tensor_constructors() {
        let q = Quantization::per_tensor(0.1, -5);
        assert!(q.is_per_tensor());
        assert!(!q.is_per_channel());
        assert!(!q.is_symmetric());
        assert_eq!(q.scale(), &[0.1]);
        assert_eq!(q.zero_point(), Some(&[-5][..]));

        let qs = Quantization::per_tensor_symmetric(0.05);
        assert!(qs.is_per_tensor());
        assert!(qs.is_symmetric());
        assert_eq!(qs.zero_point(), None);
    }

    #[test]
    fn test_quantization_per_channel_constructors() {
        let q = Quantization::per_channel(vec![0.1, 0.2, 0.3], vec![0, -1, 1], 2).unwrap();
        assert!(q.is_per_channel());
        assert!(!q.is_symmetric());
        assert_eq!(q.axis(), Some(2));
        assert_eq!(q.scale().len(), 3);

        let qs = Quantization::per_channel_symmetric(vec![0.054, 0.089, 0.195], 0).unwrap();
        assert!(qs.is_per_channel());
        assert!(qs.is_symmetric());
        assert_eq!(qs.axis(), Some(0));
    }

    #[test]
    fn test_quantization_per_channel_length_mismatch_rejected() {
        // len(scales) != len(zero_points) → rejected at construction.
        let err = Quantization::per_channel(vec![0.1, 0.2], vec![0, 0, 0], 0).unwrap_err();
        assert!(matches!(err, Error::QuantizationInvalid { .. }));
    }

    #[test]
    fn test_quantization_per_channel_empty_rejected() {
        let err = Quantization::per_channel_symmetric(vec![], 0).unwrap_err();
        assert!(matches!(err, Error::QuantizationInvalid { .. }));
    }

    /// Constructors guard scale/zero_point length invariants, but
    /// `Quantization` is `Deserialize`, so malformed JSON (e.g. an
    /// empty `scale` array, or `zero_point` length that disagrees with
    /// `scale`) bypasses the constructor checks. `set_quantization`
    /// must reject these via `validate()` so they don't poison
    /// downstream `mode()` selection or per-channel kernel indexing.
    #[test]
    fn test_quantization_validate_rejects_malformed_deserialize() {
        let mut t = Tensor::<i8>::new(&[1, 1, 4], Some(TensorMemory::Mem), None).unwrap();

        // Empty scale array: must be rejected.
        let q: Quantization = serde_json::from_str(r#"{"scale": []}"#).unwrap();
        assert!(matches!(
            t.set_quantization(q).unwrap_err(),
            Error::QuantizationInvalid { .. }
        ));

        // Per-tensor with multi-element zero_point: must be rejected.
        let q: Quantization =
            serde_json::from_str(r#"{"scale": 0.1, "zero_point": [0, 0, 0]}"#).unwrap();
        assert!(matches!(
            t.set_quantization(q).unwrap_err(),
            Error::QuantizationInvalid { .. }
        ));

        // Per-channel zero_point length != scale length: must be rejected.
        let q: Quantization = serde_json::from_str(
            r#"{"scale": [0.1, 0.2, 0.3, 0.4], "zero_point": [0, 0], "axis": 2}"#,
        )
        .unwrap();
        assert!(matches!(
            t.set_quantization(q).unwrap_err(),
            Error::QuantizationInvalid { .. }
        ));
    }

    #[test]
    fn test_quantization_mode_dispatch() {
        let pt = Quantization::per_tensor(0.1, -5);
        assert!(matches!(
            pt.mode(),
            QuantMode::PerTensor { scale, zero_point } if scale == 0.1 && zero_point == -5
        ));

        let pts = Quantization::per_tensor_symmetric(0.05);
        assert!(matches!(
            pts.mode(),
            QuantMode::PerTensorSymmetric { scale } if scale == 0.05
        ));

        let pc = Quantization::per_channel(vec![0.1, 0.2], vec![0, -1], 2).unwrap();
        assert!(matches!(pc.mode(), QuantMode::PerChannel { axis: 2, .. }));

        let pcs = Quantization::per_channel_symmetric(vec![0.1, 0.2], 0).unwrap();
        assert!(matches!(
            pcs.mode(),
            QuantMode::PerChannelSymmetric { axis: 0, .. }
        ));
    }

    #[test]
    fn test_tensor_quantization_roundtrip_integer() {
        let mut t = Tensor::<i8>::new(&[2, 3, 4], Some(TensorMemory::Mem), None).unwrap();
        assert!(t.quantization().is_none());
        t.set_quantization(Quantization::per_tensor(0.1, -5))
            .unwrap();
        let q = t.quantization().unwrap();
        assert_eq!(q.scale(), &[0.1]);
        t.clear_quantization();
        assert!(t.quantization().is_none());
    }

    #[test]
    fn test_tensor_with_quantization_builder() {
        let t = Tensor::<i8>::new(&[4, 4], Some(TensorMemory::Mem), None)
            .unwrap()
            .with_quantization(Quantization::per_tensor_symmetric(0.05))
            .unwrap();
        assert!(t.quantization().is_some());
    }

    #[test]
    fn test_tensor_dyn_quantization_float_arm_returns_none() {
        let t = Tensor::<f32>::new(&[2, 2], Some(TensorMemory::Mem), None).unwrap();
        let td = TensorDyn::F32(t);
        assert!(td.quantization().is_none());
    }

    #[test]
    fn test_tensor_dyn_set_quantization_float_arm_errors() {
        let t = Tensor::<f32>::new(&[2, 2], Some(TensorMemory::Mem), None).unwrap();
        let mut td = TensorDyn::F32(t);
        let err = td
            .set_quantization(Quantization::per_tensor(0.1, 0))
            .unwrap_err();
        // float path returns a QuantizationInvalid error.
        assert!(matches!(err, Error::QuantizationInvalid { .. }));
    }

    /// Compile-time type gate — calling `Tensor::<f32>::quantization()` must
    /// fail to compile (the `IntegerType` trait bound is not satisfied by
    /// `f32`). This doctest anchors the invariant.
    ///
    /// ```compile_fail
    /// use edgefirst_tensor::{Tensor, TensorMemory};
    /// let t = Tensor::<f32>::new(&[2, 2], Some(TensorMemory::Mem), None).unwrap();
    /// let _ = t.quantization(); // compile error: f32 not IntegerType
    /// ```
    fn _compile_fail_doctest_anchor() {}

    // Any test that cares about the fd count must grab it exclusively.
    // Any tests which modifies the fd count by opening or closing fds must grab it
    // shared.
    pub static FD_LOCK: RwLock<()> = RwLock::new(());

    /// Take [`FD_LOCK`] shared, tolerating poisoning.
    ///
    /// A test that panics while holding the lock poisons it, and every later
    /// `.unwrap()` on it panics too — one real failure turns into a handful
    /// of unrelated ones that bury it. The guarded data is `()`, so a panic
    /// cannot have left an invariant broken and there is nothing to protect
    /// against by refusing the lock.
    pub fn fd_lock_shared() -> std::sync::RwLockReadGuard<'static, ()> {
        FD_LOCK.read().unwrap_or_else(PoisonError::into_inner)
    }

    /// Take [`FD_LOCK`] exclusively. Poison-tolerant, see [`fd_lock_shared`].
    ///
    /// Linux-only, like all four of its callers: the fd-leak tests read fd
    /// state out of `/proc`, which no other platform provides. Ungated, it
    /// is dead code on macOS and the lint denies that.
    /// [`fd_lock_shared`] stays available everywhere — macOS tests declare
    /// fd activity too.
    #[cfg(target_os = "linux")]
    pub fn fd_lock_exclusive() -> std::sync::RwLockWriteGuard<'static, ()> {
        FD_LOCK.write().unwrap_or_else(PoisonError::into_inner)
    }

    /// `/proc` fd-target fragments identifying a POSIX shared memory
    /// segment. `shm_open` then `shm_unlink` leaves the target rendered as
    /// `/dev/shm/<name> (deleted)`.
    #[cfg(target_os = "linux")]
    const SHM_FD_TARGETS: &[&str] = &["/dev/shm/"];

    /// `/proc` fd-target fragments identifying the fds a DMA tensor owns.
    ///
    /// Both the exported buffer and the heap it came from are listed, so a
    /// leak of either is still caught — narrowing this to the buffer alone
    /// would silently stop covering leaked heap handles.
    #[cfg(target_os = "linux")]
    const DMA_FD_TARGETS: &[&str] = &["dmabuf", "dma_heap"];

    /// How many of this process's open fds point at an object whose `/proc`
    /// target contains `needle`.
    ///
    /// The fd-leak tests deliberately do NOT compare total fd counts. Under
    /// `cargo test` every test in this crate runs as a thread in one
    /// process, and roughly twenty of them create shm or DMA tensors —
    /// while anything else may open a file, a socket, or a pipe — so an
    /// unrelated test opening or closing an fd inside the measurement
    /// window moved the total and failed the assertion. Worse, the panic
    /// poisoned [`FD_LOCK`] and took four more tests down with it, so the
    /// visible failure had little to do with the cause.
    ///
    /// Counting only fds that name the object under test makes the
    /// measurement immune to every unrelated fd, while still catching the
    /// leak each test exists to catch. (CI runs nextest, one process per
    /// test, which is why this only ever flaked when run locally.)
    #[cfg(target_os = "linux")]
    fn open_fd_count(needles: &[&str]) -> usize {
        let proc = procfs::process::Process::myself()
            .expect("Failed to get current process using /proc/self");
        proc.fd()
            .expect("Failed to list open file descriptors")
            .filter_map(Result::ok)
            .filter(|entry| {
                let target = format!("{:?}", entry.target);
                needles.iter().any(|needle| target.contains(needle))
            })
            .count()
    }

    /// Test that DMA is NOT available on non-Linux platforms.
    /// This verifies the cross-platform behavior of is_dma_available().
    #[test]
    #[cfg(not(target_os = "linux"))]
    fn test_dma_not_available_on_non_linux() {
        assert!(
            !is_dma_available(),
            "DMA memory allocation should NOT be available on non-Linux platforms"
        );
    }

    #[test]
    fn colorimetry_defaults_none_and_roundtrips_without_auto_fill() {
        use crate::{ColorEncoding, ColorRange, Colorimetry, PixelFormat, TensorMemory};
        let mut t = Tensor::<u8>::image(
            1280,
            720,
            PixelFormat::Nv12,
            Some(TensorMemory::Mem),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        assert_eq!(t.colorimetry(), None); // default undefined
        let c = Colorimetry::default()
            .with_encoding(ColorEncoding::Bt709)
            .with_range(ColorRange::Limited);
        t.set_colorimetry(Some(c));
        assert_eq!(t.colorimetry(), Some(c));
        // configure_image must NOT touch colorimetry
        t.configure_image(640, 480, PixelFormat::Grey).unwrap();
        assert_eq!(t.colorimetry(), Some(c));
    }

    #[test]
    fn configure_image_within_capacity() {
        let mut t = Tensor::<u8>::image_with_capacity(
            640,
            480,
            PixelFormat::Rgb,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        t.configure_image(320, 240, PixelFormat::Nv12).unwrap();
        assert_eq!(t.format(), Some(PixelFormat::Nv12));
        assert_eq!(t.width(), Some(320));
        assert_eq!(t.height(), Some(240));
        assert_eq!(t.shape(), &[360, 320]); // 240*3/2
    }

    #[test]
    fn configure_image_too_large_errors() {
        let mut t = Tensor::<u8>::image_with_capacity(
            64,
            64,
            PixelFormat::Grey,
            None,
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        let err = t
            .configure_image(1920, 1080, PixelFormat::Nv12)
            .unwrap_err();
        assert!(matches!(err, Error::InsufficientCapacity { .. }));
    }

    /// A reused max-sized IOSurface pool keeps its physical `bytesPerRow` when
    /// reconfigured to a smaller logical image (physical-grid / logical-ROI
    /// decoupling), instead of collapsing to the frame's natural row stride.
    #[test]
    #[cfg(target_os = "macos")]
    fn configure_image_preserves_iosurface_physical_stride() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // Pool: GREY/R8 IOSurface 100 wide → bytesPerRow padded to 128.
        let mut pool = Tensor::<u8>::image(
            100,
            64,
            PixelFormat::Grey,
            Some(TensorMemory::DmaBuf),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        let pitch = pool.effective_row_stride().unwrap();
        assert!(
            pitch >= 128 && pitch.is_multiple_of(64),
            "padded bytesPerRow, got {pitch}"
        );

        // Reconfigure to a smaller NV12 frame; the physical pitch must survive
        // (natural would be 32, but the surface stride is the 128-padded pitch).
        pool.configure_image(32, 16, PixelFormat::Nv12).unwrap();
        assert_eq!(pool.format(), Some(PixelFormat::Nv12));
        assert_eq!(pool.width(), Some(32));
        assert_eq!(pool.height(), Some(16));
        assert_eq!(
            pool.effective_row_stride(),
            Some(pitch),
            "configure_image must preserve the IOSurface physical bytesPerRow"
        );

        // Reconfigure again to NV24 — pitch still preserved.
        pool.configure_image(32, 16, PixelFormat::Nv24).unwrap();
        assert_eq!(pool.effective_row_stride(), Some(pitch));
    }

    /// `configure_image` on a Mem backing reconfigures to the format's
    /// **64-byte-aligned** row stride (the odd-dim contract: every image tensor
    /// carries a 64-aligned `row_stride`). For NV12 32×16 the minimum is
    /// `even(32)=32`, rounded up to the 64-byte alignment → 64. The capacity
    /// (64×64×4 RGBA = 16 KiB) easily holds the 24×64 = 1.5 KiB NV12 layout.
    #[test]
    fn configure_image_mem_aligns_stride() {
        let mut t = Tensor::<u8>::image_with_capacity(
            64,
            64,
            PixelFormat::Rgba,
            Some(TensorMemory::Mem),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap();
        t.configure_image(32, 16, PixelFormat::Nv12).unwrap();
        let s = t.effective_row_stride().unwrap();
        assert_eq!(s % 64, 0, "stride must be 64-aligned");
        assert!(s >= 32, "stride must cover the even-width minimum");
        assert_eq!(s, 64);
    }

    #[test]
    fn strided_mem_tensor_cpu_maps_full_padded_buffer() {
        // A packed RGBA image with row padding (GPU-pitch style): logical width
        // 8 px (32 B/row) but a 48-byte row stride. Over-allocate capacity (for
        // 16 px), narrow the logical width, then record the padded stride.
        // Previously `map()` rejected this on non-Linux with
        // "DMA backing is Linux-only"; HAL-owned Mem is now mappable.
        let mut t = Tensor::<u8>::image_with_capacity(
            16,
            3,
            PixelFormat::Rgba,
            Some(TensorMemory::Mem),
            crate::CpuAccess::ReadWrite,
        )
        .unwrap(); // capacity 3 × 16 × 4 = 192 B
        t.configure_image(8, 3, PixelFormat::Rgba).unwrap(); // logical [3, 8, 4] = 96 B
        t.set_row_stride(48).unwrap(); // padded stride (>= 32 B min)

        let map = t.map().expect("strided Mem tensor should CPU-map");
        // Full padded buffer (stride 48 × 3 rows = 144 B), not the 96 B logical
        // view — callers iterate rows via `effective_row_stride()`.
        assert_eq!(map.as_slice().len(), 144);
        // Logical shape is still reported for shape-aware consumers.
        assert_eq!(map.shape(), &[3, 8, 4]);
    }

    #[test]
    fn strided_mem_tensor_over_capacity_errors() {
        // Stride larger than the allocation: 64 B × 3 rows = 192 B > 96 B cap.
        let mut t = Tensor::<u8>::new(&[3, 8, 4], Some(TensorMemory::Mem), None).unwrap();
        t.set_format(PixelFormat::Rgba).unwrap();
        t.set_row_stride(64).unwrap();
        assert!(matches!(t.map(), Err(Error::InsufficientCapacity { .. })));
    }

    /// Test that SHM memory allocation is available and usable on Unix systems.
    /// This is a basic functional test; Linux has additional FD leak tests using procfs.
    #[test]
    #[cfg(unix)]
    fn test_shm_available_and_usable() {
        // Declares this test as an fd-opener; see FD_LOCK.
        let _lock = crate::tests::fd_lock_shared();
        // "Unix" is not one platform here: Android is unix but its bionic libc
        // has no POSIX shared memory, so allocation legitimately reports
        // NotImplemented (see shm.rs module docs). Asserting availability
        // outright fails there for a documented reason.
        if !is_shm_available() {
            log::warn!(
                "SKIPPED: test_shm_available_and_usable - SHM allocation \
                 unavailable on this platform"
            );
            return;
        }

        // Create a tensor with SHM backing
        let tensor = Tensor::<u8>::new(&[100, 100], Some(TensorMemory::Shm), None)
            .expect("Failed to create SHM tensor");

        // Verify we can map and write to it
        let mut map = tensor.map().expect("Failed to map SHM tensor");
        map.as_mut_slice().fill(0xAB);

        // Verify the data was written correctly
        assert!(
            map.as_slice().iter().all(|&b| b == 0xAB),
            "SHM tensor data should be writable and readable"
        );
    }

    // =========================================================================
    // packed_rgba16f_layout — host-runnable geometry unit tests (TDD)
    // =========================================================================

    #[test]
    fn packed_rgba16f_layout_planar_rgb_f16() {
        let layout =
            packed_rgba16f_layout(PixelFormat::PlanarRgb, DType::F16, 640, 640).expect("Some");
        assert_eq!(layout.surface_w, 160);
        assert_eq!(layout.surface_h, 1920);
        assert_eq!(layout.bytes_per_texel, 8);
        assert_eq!(layout.pitch, 1280);
    }

    #[test]
    fn packed_rgba16f_layout_planar_rgba_f16() {
        let layout =
            packed_rgba16f_layout(PixelFormat::PlanarRgba, DType::F16, 640, 640).expect("Some");
        assert_eq!(layout.surface_w, 160);
        assert_eq!(layout.surface_h, 2560); // 4 planes
        assert_eq!(layout.bytes_per_texel, 8);
        assert_eq!(layout.pitch, 1280);
    }

    #[test]
    fn packed_rgba16f_layout_rejects_misaligned() {
        assert!(packed_rgba16f_layout(PixelFormat::PlanarRgb, DType::F16, 642, 640).is_none());
    }

    #[test]
    fn packed_rgba16f_layout_rejects_non_f16() {
        // Non-F16 dtype with planar RGB
        assert!(packed_rgba16f_layout(PixelFormat::PlanarRgb, DType::U8, 640, 640).is_none());
        // Non-planar format with F32
        assert!(packed_rgba16f_layout(PixelFormat::Rgb, DType::F32, 640, 640).is_none());
        // Packed Rgba with F16 is not a planar format → None
        assert!(packed_rgba16f_layout(PixelFormat::Rgba, DType::F16, 640, 640).is_none());
    }

    #[test]
    fn cuda_map_fast_fails_to_none_without_handle() {
        let t = Tensor::<f32>::new(&[4], Some(TensorMemory::Mem), None).unwrap();
        assert!(t.cuda().is_none());
        assert!(t.cuda_map().is_none()); // pure local check, no GL routing
    }

    #[test]
    fn cuda_returns_none_without_handle() {
        // A plain Mem-backed tensor has no CUDA handle attached.
        let t = Tensor::<f32>::new(&[2, 2], Some(TensorMemory::Mem), None).unwrap();
        assert!(t.cuda().is_none(), "no CUDA handle on a Mem tensor");
        assert!(t.cuda_map().is_none(), "fast-fail map → None");
    }

    #[test]
    fn cuda_map_then_host_map_fallback() {
        // The documented client pattern: try cuda_map() first; when it is None
        // (no CUDA handle — the case for a plain Mem tensor), fall back to map().
        let t = Tensor::<f32>::new(&[2, 2], Some(TensorMemory::Mem), None).unwrap();
        // Bind to a named variable so the CudaMap guard (and its borrow of `t`)
        // is dropped at the end of this statement, before the else branch borrows `t` again.
        let cuda = t.cuda_map();
        if let Some(_c) = cuda {
            // On a CUDA-registered tensor we'd use the device ptr here.
            unreachable!("a Mem tensor has no CUDA handle");
        } else {
            let host = t.map().expect("host map fallback must succeed");
            // TensorMapTrait::len() returns the element count (not bytes).
            assert_eq!(host.len(), 4); // 2*2 f32 elements
        }
    }

    // -------------------------------------------------------------------------
    // Tensor::from_foreign — public API tests at the Tensor<T> layer.
    //
    // The low-level MemTensor::from_foreign mechanics (owner-drop, view sharing)
    // are covered in mem.rs.  These tests exercise the Tensor<T> guard paths
    // (null ptr, empty shape, size overflow) and the basic wrap+readback
    // contract, confirming the public unsafe API wires through correctly.
    // -------------------------------------------------------------------------

    #[test]
    fn from_foreign_valid_wrap_and_readback() {
        // The canonical CUDA zero-copy shape: wrap a caller allocation as a
        // Mem tensor and verify the tensor reads the exact same bytes.
        let mut buf: Vec<f32> = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
        let ptr = buf.as_mut_ptr();
        let t = unsafe { Tensor::<f32>::from_foreign(ptr, &[2, 3], None, Some("test_foreign")) }
            .expect("valid from_foreign must succeed");
        assert_eq!(t.shape(), &[2, 3]);
        assert_eq!(t.memory(), TensorMemory::Mem);
        assert_eq!(t.name(), "test_foreign");
        let m = t.map().unwrap();
        // The tensor is a zero-copy borrow — it sees the caller's data.
        assert_eq!(m.as_slice(), &[1.0_f32, 2.0, 3.0, 4.0, 5.0, 6.0]);
    }

    #[test]
    fn from_foreign_write_visible_in_caller_allocation() {
        // Writes through the tensor's map land in the caller's buffer (zero-copy).
        let mut buf: Vec<u8> = vec![0u8; 6];
        let ptr = buf.as_mut_ptr();
        let t = unsafe { Tensor::<u8>::from_foreign(ptr, &[2, 3], None, None) }.unwrap();
        {
            let mut m = t.map().unwrap();
            m.as_mut_slice().copy_from_slice(&[10, 20, 30, 40, 50, 60]);
        }
        drop(t);
        // Mutations are visible in the original Vec — same physical buffer.
        assert_eq!(buf, vec![10, 20, 30, 40, 50, 60]);
    }

    #[test]
    fn from_foreign_rejects_null_ptr() {
        let err = unsafe { Tensor::<u8>::from_foreign(std::ptr::null_mut(), &[4], None, None) }
            .unwrap_err();
        assert!(
            matches!(err, Error::InvalidArgument(ref m) if m.contains("non-null")),
            "expected InvalidArgument(non-null), got {err:?}"
        );
    }

    #[test]
    fn from_foreign_rejects_empty_shape() {
        let mut dummy: u8 = 0;
        let err = unsafe { Tensor::<u8>::from_foreign(&mut dummy, &[], None, None) }.unwrap_err();
        assert!(
            matches!(err, Error::InvalidSize(0)),
            "expected InvalidSize(0) for empty shape, got {err:?}"
        );
    }

    #[test]
    fn from_foreign_rejects_overflow_shape() {
        // Two dimensions whose product overflows usize — the overflow guard must
        // fire before any pointer arithmetic is attempted.
        let mut dummy: u8 = 0;
        let huge = [usize::MAX / 2 + 1, 2];
        let err = unsafe { Tensor::<u8>::from_foreign(&mut dummy, &huge, None, None) }.unwrap_err();
        assert!(
            matches!(err, Error::InvalidArgument(ref m) if m.contains("overflow")),
            "expected InvalidArgument(overflow), got {err:?}"
        );
    }

    #[test]
    fn from_foreign_owner_keeps_allocation_alive() {
        // When `owner` is `Some`, dropping the Tensor must not free the backing
        // before the owner is also gone — the owner's Drop fires on last ref.
        use std::sync::atomic::{AtomicBool, Ordering};
        let flag = std::sync::Arc::new(AtomicBool::new(false));
        let flag2 = flag.clone();
        struct Guard(std::sync::Arc<AtomicBool>);
        impl Drop for Guard {
            fn drop(&mut self) {
                self.0.store(true, Ordering::SeqCst);
            }
        }
        let mut buf: Vec<u32> = vec![42u32; 4];
        let ptr = buf.as_mut_ptr();
        let owner: ForeignOwner = Box::new(Guard(flag2));
        let t = unsafe { Tensor::<u32>::from_foreign(ptr, &[4], Some(owner), None) }.unwrap();
        // Map co-owns the backing Arc; the owner must stay alive while the map lives.
        let m = t.map().unwrap();
        assert_eq!(m.as_slice()[0], 42);
        drop(t); // tensor dropped while map is still live
        assert!(
            !flag.load(Ordering::SeqCst),
            "owner must not drop while a map shares the backing"
        );
        drop(m);
        assert!(
            flag.load(Ordering::SeqCst),
            "owner Drop must fire when the last Arc reference is released"
        );
    }
}