vyre-conform 0.1.0

//! Execution-model abstraction for vyre backends.
//!
//! The [`ExecutionModel`] enum is the stable, non-exhaustive envelope that lets
//! the conformance suite add new dispatch styles (persistent, streaming,
//! multi-device) without breaking existing backend implementations.

use super::ConformDispatchConfig;

/// Kind tag for a supported vyre execution model.
///
/// This enum is non-exhaustive because vyre's backend surface must grow to
/// cover future execution models without breaking existing backend crates.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ExecutionModelKind {
    /// One-shot WGSL dispatch with explicit input bytes and output size.
    OneShot,
}

impl ExecutionModelKind {
    /// Stable human-readable name for diagnostics.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::OneShot => "OneShot",
        }
    }
}

/// Payload for one one-shot WGSL dispatch.
#[derive(Clone, Debug)]
pub struct OneShotDispatch {
    /// Complete WGSL shader source ready for backend compilation.
    pub wgsl: String,
    /// Input buffer bytes for this dispatch.
    pub input: Vec<u8>,
    /// Exact number of bytes the backend must return.
    pub output_size: usize,
    /// Workgroup, convention, lookup, and buffer initialization settings.
    pub config: ConformDispatchConfig,
}

/// Universal execution model for vyre backend work.
///
/// This enum is non-exhaustive. Existing backends remain source-compatible as
/// new variants are added because `WgslBackend::execute()` owns the default
/// routing for each new variant and reports unsupported models cleanly.
#[derive(Clone, Debug)]
pub enum ExecutionModel {
    /// One-shot WGSL dispatch, backed by `WgslBackend::dispatch()`.
    OneShot(OneShotDispatch),
}

impl ExecutionModel {
    /// Return the kind tag for this model.
    pub const fn kind(&self) -> ExecutionModelKind {
        match self {
            Self::OneShot(_) => ExecutionModelKind::OneShot,
        }
    }

    #[inline]
    pub(crate) fn kind_name(&self) -> &'static str {
        self.kind().as_str()
    }
}

/// Build an actionable unsupported execution-model error.
///
/// This helper is public so future extension traits can produce identical
/// diagnostics before the corresponding `ExecutionModel` variant is added.
#[inline]
pub fn unsupported_execution_model_error(backend_name: &str, model_name: &str) -> String {
    format!(
        "unsupported execution model {model_name} on backend {backend_name}. Fix: this backend does not support {model_name} dispatch; see supported_models()"
    )
}