/// TRACES: NFR-R7 | NFR-R8
/// Failures from the GPU layer.
///
/// `DeviceLost` is deliberately a distinct variant rather than folded into a
/// generic error: it is an expected event on Android (ARCH §6.10), not an
/// exceptional one, and callers recover from it by rebuilding the device and
/// re-driving from the edit graph.
#[derive(Debug, thiserror::Error)]
pub enum GpuError {
    #[error("no suitable GPU adapter found")]
    NoAdapter,

    #[error("failed to request device: {0}")]
    DeviceRequest(String),

    #[error("GPU device lost — recreate and re-render from the edit graph")]
    DeviceLost,

    #[error("shader compilation failed: {0}")]
    ShaderCompilation(String),

    #[error("readback failed: {0}")]
    Readback(String),

    /// The CFA layout is one no demosaic here handles — in practice a file
    /// `dr-decode` could not identify the pattern of. Reported rather than
    /// approximated with the Bayer path, which would produce a maze of colour
    /// artefacts and look like a corrupt file.
    #[error("unsupported CFA pattern: {0}")]
    UnsupportedCfa(String),

    #[error("image too large for this device: {0}")]
    TooLarge(String),

    /// A mask input that cannot describe the image it claims to — a label
    /// field whose length disagrees with its own dimensions, most often.
    ///
    /// Its own variant rather than a panic because the caller assembles this
    /// from a segmentation and a render size that are computed in different
    /// places, and a mismatch between them is a bug worth reporting with its
    /// numbers rather than an abort.
    #[error("invalid mask input: {0}")]
    InvalidMask(String),
}