alma 0.1.1

use crate::plugin::{
    PluginHostImportDiscardReport, PluginHostImportError, PluginIdentity,
    PluginInstanceAccessError, PluginOperationalEvent, PluginOperationalExport,
    PluginOperationalImport, PluginOperationalRuntimeFailure, PluginRuntimeLimitField,
    PluginWorkspaceObserveTaskEnqueueError, PluginWorkspaceObserveTaskQueueError,
    SealedPluginWorkspaceObserveTaskBatch,
};
use std::fmt::{Debug, Display, Formatter};

/// Redacted Wasmtime or OS failure detail.
#[derive(Clone, Copy, Eq, PartialEq)]
pub struct WasmtimePluginRuntimeFailure {
    /// Failure class only.
    kind: WasmtimePluginRuntimeFailureKind,
}

impl WasmtimePluginRuntimeFailure {
    /// Failure class.
    #[must_use]
    pub const fn kind(self) -> WasmtimePluginRuntimeFailureKind {
        self.kind
    }

    /// Creates a redacted failure class.
    pub(super) const fn new(kind: WasmtimePluginRuntimeFailureKind) -> Self {
        Self { kind }
    }

    /// Drops raw Wasmtime error detail.
    pub(super) const fn from_wasmtime<T>(
        kind: WasmtimePluginRuntimeFailureKind,
        _source: &T,
    ) -> Self {
        Self::new(kind)
    }

    /// Drops raw OS error detail.
    pub(super) const fn from_io(
        kind: WasmtimePluginRuntimeFailureKind,
        _source: &std::io::Error,
    ) -> Self {
        Self::new(kind)
    }
}

/// Closed redacted Wasmtime or OS failure class.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum WasmtimePluginRuntimeFailureKind {
    /// Runtime engine setup.
    Engine,
    /// Runtime epoch driver setup.
    RuntimeTimer,
    /// Component validation or compilation.
    Component,
    /// Host import linker construction.
    Linker,
    /// Component instantiation.
    Instantiate,
    /// Lifecycle export lookup.
    Export,
    /// Fuel setup before guest execution.
    Fuel,
    /// Guest trap during export execution.
    GuestTrap,
    /// Canonical ABI post-return cleanup.
    PostReturn,
}

impl WasmtimePluginRuntimeFailureKind {
    /// Stable redacted failure class text.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Engine => "engine",
            Self::RuntimeTimer => "timer",
            Self::Component => "component",
            Self::Linker => "linker",
            Self::Instantiate => "instantiate",
            Self::Export => "export",
            Self::Fuel => "fuel",
            Self::GuestTrap => "guest trap",
            Self::PostReturn => "post-return",
        }
    }
}

impl Display for WasmtimePluginRuntimeFailureKind {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl Debug for WasmtimePluginRuntimeFailure {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("WasmtimePluginRuntimeFailure")
            .field("kind", &self.kind.as_str())
            .finish()
    }
}

impl Display for WasmtimePluginRuntimeFailure {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.kind.as_str())
    }
}

/// Stable phase for a Wasmtime adapter failure.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum WasmtimePluginRuntimePhase {
    /// Runtime engine setup.
    Engine,
    /// Component validation or compilation.
    Component,
    /// Host-width runtime limit projection.
    Limit,
    /// Component instantiation.
    Instantiate,
    /// Lifecycle export lookup.
    Export,
    /// Fuel setup.
    Fuel,
    /// Deadline setup.
    Timer,
    /// Guest wall-clock deadline.
    Timeout,
    /// Guest trap outside an expected host import rejection.
    GuestTrap,
    /// Update rejected before guest execution.
    Scheduling,
    /// Host session setup before guest execution.
    UpdateSetup,
    /// Host import rejection during guest execution.
    HostImport,
    /// Runtime instance and host state came from different plugins.
    InstanceStateMismatch,
}

/// Wasmtime observe-task enqueue failure class.
#[derive(Clone, Copy, Eq, PartialEq)]
#[non_exhaustive]
pub enum WasmtimeWorkspaceObserveTaskEnqueueErrorKind {
    /// Lifecycle state denied scheduling before queue admission.
    SchedulingDenied,
    /// Runtime instance was paired with state for another plugin.
    InstanceStateMismatch,
    /// Runtime instance was paired with a task batch from another plugin.
    BatchIdentityMismatch,
    /// Queue admission failed after lifecycle gating.
    Queue,
}

impl WasmtimeWorkspaceObserveTaskEnqueueErrorKind {
    /// Stable diagnostic spelling.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::SchedulingDenied => "scheduling-denied",
            Self::InstanceStateMismatch => "instance-state-mismatch",
            Self::BatchIdentityMismatch => "batch-identity-mismatch",
            Self::Queue => "queue",
        }
    }
}

impl Display for WasmtimeWorkspaceObserveTaskEnqueueErrorKind {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl Debug for WasmtimeWorkspaceObserveTaskEnqueueErrorKind {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

/// Wasmtime observe-task enqueue failure that preserves retryable work.
#[derive(Eq, PartialEq, thiserror::Error)]
#[error("{source}")]
pub struct WasmtimeWorkspaceObserveTaskEnqueueError {
    /// Rejection paired with its still-retryable task batch.
    #[source]
    source: WasmtimeWorkspaceObserveTaskEnqueueErrorSource,
}

/// Runtime/state identities involved in an instance-state mismatch.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct WasmtimeWorkspaceObserveTaskInstanceStateMismatchIdentities<'identity> {
    /// Runtime instance identity.
    pub runtime_identity: &'identity PluginIdentity,
    /// Host state identity.
    pub state_identity: &'identity PluginIdentity,
}

/// Runtime/batch identities involved in a task-batch mismatch.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct WasmtimeWorkspaceObserveTaskBatchIdentityMismatchIdentities<'identity> {
    /// Runtime instance identity.
    pub runtime_identity: &'identity PluginIdentity,
    /// Task batch identity.
    pub batch_identity: &'identity PluginIdentity,
}

/// Private enqueue rejection payload. Constructors keep the batch and source paired.
#[derive(Debug, Eq, PartialEq, thiserror::Error)]
enum WasmtimeWorkspaceObserveTaskEnqueueErrorSource {
    /// Lifecycle state denied scheduling before queue admission.
    #[error("plugin workspace observe task enqueue denied: {source}")]
    SchedulingDenied {
        /// Lifecycle rejection.
        #[source]
        source: PluginInstanceAccessError,
        /// Still-sealed task batch retained for explicit discard.
        batch: SealedPluginWorkspaceObserveTaskBatch,
    },
    /// Runtime instance was paired with state for another plugin.
    #[error("plugin workspace observe task enqueue denied by instance state mismatch")]
    InstanceStateMismatch {
        /// Runtime instance identity.
        runtime_identity: PluginIdentity,
        /// Host state identity.
        state_identity: PluginIdentity,
        /// Still-sealed task batch retained for explicit discard.
        batch: SealedPluginWorkspaceObserveTaskBatch,
    },
    /// Runtime instance was paired with a task batch for another plugin.
    #[error("plugin workspace observe task enqueue denied by batch identity mismatch")]
    BatchIdentityMismatch {
        /// Runtime instance identity.
        runtime_identity: PluginIdentity,
        /// Task batch identity.
        batch_identity: PluginIdentity,
        /// Still-sealed task batch retained for explicit discard.
        batch: SealedPluginWorkspaceObserveTaskBatch,
    },
    /// Queue admission failed after lifecycle gating.
    #[error(transparent)]
    Queue(#[from] PluginWorkspaceObserveTaskEnqueueError),
}

impl WasmtimeWorkspaceObserveTaskEnqueueError {
    /// Builds a lifecycle-denied enqueue error.
    pub(super) const fn scheduling_denied(
        source: PluginInstanceAccessError,
        batch: SealedPluginWorkspaceObserveTaskBatch,
    ) -> Self {
        Self {
            source: WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied {
                source,
                batch,
            },
        }
    }

    /// Builds an identity-mismatch enqueue error.
    pub(super) const fn instance_state_mismatch(
        runtime_identity: PluginIdentity,
        state_identity: PluginIdentity,
        batch: SealedPluginWorkspaceObserveTaskBatch,
    ) -> Self {
        Self {
            source: WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                runtime_identity,
                state_identity,
                batch,
            },
        }
    }

    /// Builds a runtime/batch identity-mismatch enqueue error.
    pub(super) const fn batch_identity_mismatch(
        runtime_identity: PluginIdentity,
        batch_identity: PluginIdentity,
        batch: SealedPluginWorkspaceObserveTaskBatch,
    ) -> Self {
        Self {
            source: WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                runtime_identity,
                batch_identity,
                batch,
            },
        }
    }

    /// Builds a queue-admission enqueue error.
    pub(super) const fn from_queue(source: PluginWorkspaceObserveTaskEnqueueError) -> Self {
        Self {
            source: WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source),
        }
    }

    /// Returns the closed failure class.
    #[must_use]
    pub const fn kind(&self) -> WasmtimeWorkspaceObserveTaskEnqueueErrorKind {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { .. } => {
                WasmtimeWorkspaceObserveTaskEnqueueErrorKind::SchedulingDenied
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch { .. } => {
                WasmtimeWorkspaceObserveTaskEnqueueErrorKind::InstanceStateMismatch
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch { .. } => {
                WasmtimeWorkspaceObserveTaskEnqueueErrorKind::BatchIdentityMismatch
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(_) => {
                WasmtimeWorkspaceObserveTaskEnqueueErrorKind::Queue
            }
        }
    }

    /// Returns the sealed batch retained for retry or explicit discard.
    #[must_use]
    pub const fn batch(&self) -> &SealedPluginWorkspaceObserveTaskBatch {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { batch, .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                batch, ..
            }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                batch, ..
            } => batch,
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source) => source.batch(),
        }
    }

    /// Returns the lifecycle rejection when enqueue was denied before queue admission.
    #[must_use]
    pub const fn scheduling_error(&self) -> Option<&PluginInstanceAccessError> {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { source, .. } => {
                Some(source)
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(_) => None,
        }
    }

    /// Returns the mismatched runtime and state identities when lifecycle ownership failed.
    #[must_use]
    pub const fn instance_state_mismatch_identities(
        &self,
    ) -> Option<WasmtimeWorkspaceObserveTaskInstanceStateMismatchIdentities<'_>> {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                runtime_identity,
                state_identity,
                ..
            } => Some(
                WasmtimeWorkspaceObserveTaskInstanceStateMismatchIdentities {
                    runtime_identity,
                    state_identity,
                },
            ),
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(_) => None,
        }
    }

    /// Returns the mismatched runtime and task-batch identities.
    #[must_use]
    pub const fn batch_identity_mismatch_identities(
        &self,
    ) -> Option<WasmtimeWorkspaceObserveTaskBatchIdentityMismatchIdentities<'_>> {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                runtime_identity,
                batch_identity,
                ..
            } => Some(
                WasmtimeWorkspaceObserveTaskBatchIdentityMismatchIdentities {
                    runtime_identity,
                    batch_identity,
                },
            ),
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(_) => None,
        }
    }

    /// Returns the queue rejection when lifecycle gating passed.
    #[must_use]
    pub const fn queue_error(&self) -> Option<&PluginWorkspaceObserveTaskQueueError> {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source) => {
                Some(source.queue_error())
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch { .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch { .. } => None,
        }
    }

    /// Redacted operational event for enqueue failures that should be reported.
    #[must_use]
    pub fn operational_event(&self) -> Option<PluginOperationalEvent> {
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { .. } => None,
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                runtime_identity,
                ..
            } => Some(PluginOperationalEvent::runtime_failure(
                runtime_identity,
                PluginOperationalRuntimeFailure::InstanceStateMismatch,
            )),
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                runtime_identity,
                ..
            } => Some(PluginOperationalEvent::runtime_failure(
                runtime_identity,
                PluginOperationalRuntimeFailure::BatchIdentityMismatch,
            )),
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source) => {
                source.queue_error().operational_event()
            }
        }
    }

    /// Consumes the error and returns the retryable sealed batch.
    #[must_use]
    pub fn into_batch(self) -> SealedPluginWorkspaceObserveTaskBatch {
        match self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { batch, .. }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                batch, ..
            }
            | WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                batch, ..
            } => batch,
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source) => source.into_batch(),
        }
    }

    /// Discards the retained sealed batch instead of retrying admission.
    #[must_use]
    pub fn discard_batch(self) -> crate::plugin::PluginWorkspaceObserveTaskDiscardReport {
        self.into_batch().discard()
    }
}

impl Debug for WasmtimeWorkspaceObserveTaskEnqueueError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        let mut debug = formatter.debug_struct("WasmtimeWorkspaceObserveTaskEnqueueError");
        let _debug = debug
            .field("kind", &self.kind())
            .field("batch_identity", self.batch().identity_proof())
            .field("task_count", &self.batch().task_count());
        match &self.source {
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::SchedulingDenied { source, .. } => {
                let _debug = debug.field("scheduling_error", source);
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::InstanceStateMismatch {
                runtime_identity,
                state_identity,
                ..
            } => {
                let _debug = debug
                    .field("runtime_identity", runtime_identity)
                    .field("state_identity", state_identity);
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::BatchIdentityMismatch {
                runtime_identity,
                batch_identity,
                ..
            } => {
                let _debug = debug
                    .field("runtime_identity", runtime_identity)
                    .field("mismatched_batch_identity", batch_identity);
            }
            WasmtimeWorkspaceObserveTaskEnqueueErrorSource::Queue(source) => {
                let _debug = debug.field("queue_error_kind", &source.queue_error().kind());
            }
        }
        debug.finish()
    }
}

/// Wasmtime adapter failure with redacted data.
#[derive(thiserror::Error)]
#[non_exhaustive]
pub enum WasmtimePluginRuntimeError {
    /// Engine creation failed.
    Engine {
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Component validation or compilation failed.
    Component {
        /// Stable identity.
        identity: PluginIdentity,
        /// Component bytes.
        byte_len: usize,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Store limit conversion failed.
    Limit {
        /// Stable identity.
        identity: PluginIdentity,
        /// Config field.
        field: PluginRuntimeLimitField,
        /// Rejected value.
        value: u64,
    },
    /// Component instantiation failed.
    Instantiate {
        /// Stable identity.
        identity: PluginIdentity,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Lifecycle export was missing or had the wrong type.
    Export {
        /// Stable identity.
        identity: PluginIdentity,
        /// Lifecycle export.
        export: PluginOperationalExport,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Fuel setup failed before guest execution.
    Fuel {
        /// Stable identity.
        identity: PluginIdentity,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Deadline setup failed before guest execution.
    Timer {
        /// Stable identity.
        identity: PluginIdentity,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Runtime epoch driver setup failed.
    RuntimeTimer {
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Guest execution exceeded the wall-clock limit.
    Timeout {
        /// Stable identity.
        identity: PluginIdentity,
        /// Lifecycle export.
        export: PluginOperationalExport,
        /// Timeout cap.
        timeout_ms: u64,
    },
    /// Guest execution trapped.
    GuestTrap {
        /// Stable identity.
        identity: PluginIdentity,
        /// Lifecycle export.
        export: PluginOperationalExport,
        /// Failure class.
        failure: WasmtimePluginRuntimeFailure,
    },
    /// Update was denied before guest execution.
    SchedulingDenied(#[source] crate::plugin::PluginInstanceAccessError),
    /// Host session setup failed before guest execution.
    UpdateSetup {
        /// Stable identity.
        identity: PluginIdentity,
        /// Setup rejection.
        source: PluginHostImportError,
    },
    /// Host import failed during guest execution.
    HostImport {
        /// Stable identity.
        identity: PluginIdentity,
        /// Lifecycle export.
        export: PluginOperationalExport,
        /// Generated host import that failed.
        import: PluginOperationalImport,
        /// Typed import rejection.
        source: PluginHostImportError,
    },
    /// Runtime instance was paired with state for another plugin.
    InstanceStateMismatch {
        /// Runtime instance identity.
        runtime_identity: PluginIdentity,
        /// Host state identity.
        state_identity: PluginIdentity,
    },
    /// Guest update failed after pending work was discarded.
    UpdateFailed {
        /// Original failure.
        source: Box<Self>,
        /// Discard evidence.
        discarded: PluginHostImportDiscardReport,
    },
}

impl WasmtimePluginRuntimeError {
    /// Attaches discard evidence.
    pub(super) fn with_discard(self, discarded: PluginHostImportDiscardReport) -> Self {
        Self::UpdateFailed {
            source: Box::new(self),
            discarded,
        }
    }

    /// Returns the root failure phase.
    #[must_use]
    pub fn phase(&self) -> WasmtimePluginRuntimePhase {
        match self {
            Self::Engine { .. } => WasmtimePluginRuntimePhase::Engine,
            Self::Component { .. } => WasmtimePluginRuntimePhase::Component,
            Self::Limit { .. } => WasmtimePluginRuntimePhase::Limit,
            Self::Instantiate { .. } => WasmtimePluginRuntimePhase::Instantiate,
            Self::Export { .. } => WasmtimePluginRuntimePhase::Export,
            Self::Fuel { .. } => WasmtimePluginRuntimePhase::Fuel,
            Self::Timer { .. } | Self::RuntimeTimer { .. } => WasmtimePluginRuntimePhase::Timer,
            Self::Timeout { .. } => WasmtimePluginRuntimePhase::Timeout,
            Self::GuestTrap { .. } => WasmtimePluginRuntimePhase::GuestTrap,
            Self::SchedulingDenied(_) => WasmtimePluginRuntimePhase::Scheduling,
            Self::UpdateSetup { .. } => WasmtimePluginRuntimePhase::UpdateSetup,
            Self::HostImport { .. } => WasmtimePluginRuntimePhase::HostImport,
            Self::InstanceStateMismatch { .. } => WasmtimePluginRuntimePhase::InstanceStateMismatch,
            Self::UpdateFailed { source, .. } => source.phase(),
        }
    }

    /// Returns discard evidence when a failed update crossed the pending-work boundary.
    #[must_use]
    pub const fn discarded_update(&self) -> Option<&PluginHostImportDiscardReport> {
        match self {
            Self::UpdateFailed { discarded, .. } => Some(discarded),
            _other => None,
        }
    }

    /// Redacted event for observable failures.
    #[must_use]
    pub fn operational_event(&self) -> Option<PluginOperationalEvent> {
        match self {
            Self::Timeout {
                identity,
                timeout_ms,
                ..
            } => Some(PluginOperationalEvent::timeout(identity, *timeout_ms)),
            Self::UpdateSetup { identity, source } => Some(host_import_operational_event(
                identity,
                PluginOperationalImport::HostImport,
                source,
            )),
            Self::HostImport {
                identity,
                import,
                source,
                ..
            } => Some(host_import_operational_event(identity, *import, source)),
            Self::GuestTrap {
                identity,
                export,
                failure,
            } => match operational_failure_from_runtime_failure(failure.kind()) {
                PluginOperationalRuntimeFailure::Export => {
                    Some(PluginOperationalEvent::guest_trap(identity, *export))
                }
                failure => Some(PluginOperationalEvent::runtime_failure(identity, failure)),
            },
            Self::UpdateFailed { source, .. } => source.operational_event(),
            Self::Engine { .. } => Some(PluginOperationalEvent::unscoped_runtime_failure(
                PluginOperationalRuntimeFailure::Engine,
            )),
            Self::RuntimeTimer { .. } => Some(PluginOperationalEvent::unscoped_runtime_failure(
                PluginOperationalRuntimeFailure::RuntimeTimer,
            )),
            Self::Component { identity, .. } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                PluginOperationalRuntimeFailure::Component,
            )),
            Self::Limit { identity, .. } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                PluginOperationalRuntimeFailure::Limit,
            )),
            Self::Instantiate {
                identity, failure, ..
            } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                operational_failure_from_runtime_failure(failure.kind()),
            )),
            Self::Export { identity, .. } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                PluginOperationalRuntimeFailure::Export,
            )),
            Self::Fuel { identity, .. } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                PluginOperationalRuntimeFailure::Fuel,
            )),
            Self::Timer { identity, .. } => Some(PluginOperationalEvent::runtime_failure(
                identity,
                PluginOperationalRuntimeFailure::Timer,
            )),
            Self::InstanceStateMismatch {
                runtime_identity, ..
            } => Some(PluginOperationalEvent::runtime_failure(
                runtime_identity,
                PluginOperationalRuntimeFailure::InstanceStateMismatch,
            )),
            Self::SchedulingDenied(_) => None,
        }
    }
}

impl Debug for WasmtimePluginRuntimeError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        let mut debug = formatter.debug_struct("WasmtimePluginRuntimeError");
        let _debug = debug.field("phase", &self.phase());
        match self {
            Self::Engine { failure } | Self::RuntimeTimer { failure } => {
                let _debug = debug.field("failure", failure);
            }
            Self::Component {
                identity,
                byte_len,
                failure,
            } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("byte_len", byte_len);
                let _debug = debug.field("failure", failure);
            }
            Self::Limit {
                identity,
                field,
                value,
            } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("field", field);
                let _debug = debug.field("value", value);
            }
            Self::Instantiate { identity, failure }
            | Self::Fuel { identity, failure }
            | Self::Timer { identity, failure } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("failure", failure);
            }
            Self::Export {
                identity,
                export,
                failure,
            }
            | Self::GuestTrap {
                identity,
                export,
                failure,
            } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("export", export);
                let _debug = debug.field("failure", failure);
            }
            Self::Timeout {
                identity,
                export,
                timeout_ms,
            } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("export", export);
                let _debug = debug.field("timeout_ms", timeout_ms);
            }
            Self::SchedulingDenied(source) => {
                let _debug = debug.field("source", source);
            }
            Self::UpdateSetup { identity, source } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("source", source);
            }
            Self::HostImport {
                identity,
                export,
                import,
                source,
            } => {
                let _debug = debug.field("identity", identity);
                let _debug = debug.field("export", export);
                let _debug = debug.field("import", import);
                let _debug = debug.field("source", source);
            }
            Self::InstanceStateMismatch {
                runtime_identity,
                state_identity,
            } => {
                let _debug = debug.field("runtime_identity", runtime_identity);
                let _debug = debug.field("state_identity", state_identity);
            }
            Self::UpdateFailed { source, discarded } => {
                let _debug = debug.field("source", source);
                let _debug = debug.field("discarded", discarded);
            }
        }
        debug.finish()
    }
}

impl Display for WasmtimePluginRuntimeError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Engine { .. } => {
                formatter.write_str("plugin Wasmtime engine initialization failed")
            }
            Self::Component {
                identity, byte_len, ..
            } => fmt_component_validation_error(formatter, identity, *byte_len),
            Self::Limit {
                identity,
                field,
                value,
            } => fmt_limit_error(formatter, identity, *field, *value),
            Self::Instantiate { identity, .. } => {
                write!(
                    formatter,
                    "plugin {:?} component instantiation failed",
                    identity.as_str()
                )
            }
            Self::Export {
                identity, export, ..
            } => {
                write!(
                    formatter,
                    "plugin {:?} export {export} is not callable",
                    identity.as_str()
                )
            }
            Self::Fuel { identity, .. } => write!(
                formatter,
                "plugin {:?} fuel setup failed",
                identity.as_str()
            ),
            Self::Timer { identity, .. } => write!(
                formatter,
                "plugin {:?} timeout setup failed",
                identity.as_str()
            ),
            Self::RuntimeTimer { .. } => {
                formatter.write_str("plugin Wasmtime timeout driver setup failed")
            }
            Self::Timeout {
                identity,
                export,
                timeout_ms,
            } => {
                write!(
                    formatter,
                    "plugin {:?} export {export} exceeded {timeout_ms} ms",
                    identity.as_str()
                )
            }
            Self::GuestTrap {
                identity, export, ..
            } => write!(
                formatter,
                "plugin {:?} export {export} trapped",
                identity.as_str()
            ),
            Self::SchedulingDenied(source) => {
                write!(formatter, "plugin scheduling denied: {source}")
            }
            Self::UpdateSetup { identity, source } => {
                write!(
                    formatter,
                    "plugin {:?} update setup failed: {source}",
                    identity.as_str()
                )
            }
            Self::HostImport {
                identity,
                export,
                import,
                source,
            } => {
                write!(
                    formatter,
                    "plugin {:?} export {export} host import {import} failed: {source}",
                    identity.as_str()
                )
            }
            Self::InstanceStateMismatch {
                runtime_identity,
                state_identity,
            } => fmt_instance_state_mismatch(formatter, runtime_identity, state_identity),
            Self::UpdateFailed { source, discarded } => write!(
                formatter,
                "plugin update failed: {source}; discarded {} effects, {} workspace requests, and {} workspace observe tasks",
                discarded.effects().discarded_effects(),
                discarded.workspace_io().discarded_requests(),
                discarded.workspace_observe_tasks().discarded_tasks()
            ),
        }
    }
}

/// Formats component validation failure without exposing component contents.
fn fmt_component_validation_error(
    formatter: &mut Formatter<'_>,
    identity: &PluginIdentity,
    byte_len: usize,
) -> std::fmt::Result {
    write!(
        formatter,
        "plugin {:?} component validation failed for {byte_len} bytes",
        identity.as_str()
    )
}

/// Formats rejected runtime limit projection.
fn fmt_limit_error(
    formatter: &mut Formatter<'_>,
    identity: &PluginIdentity,
    field: PluginRuntimeLimitField,
    value: u64,
) -> std::fmt::Result {
    write!(
        formatter,
        "plugin {:?} runtime limit {field} value {value} does not fit host",
        identity.as_str()
    )
}

/// Formats runtime/state identity mismatch without exposing instance internals.
fn fmt_instance_state_mismatch(
    formatter: &mut Formatter<'_>,
    runtime_identity: &PluginIdentity,
    state_identity: &PluginIdentity,
) -> std::fmt::Result {
    write!(
        formatter,
        "plugin runtime {:?} cannot use state for {:?}",
        runtime_identity.as_str(),
        state_identity.as_str()
    )
}

/// Maps a host import rejection to a redacted operational event.
fn host_import_operational_event(
    identity: &PluginIdentity,
    import: PluginOperationalImport,
    source: &PluginHostImportError,
) -> PluginOperationalEvent {
    source.operational_rejection().map_or_else(
        || PluginOperationalEvent::denied_import(identity, import),
        |reason| PluginOperationalEvent::rejected_import(identity, import, reason),
    )
}

/// Projects Wasmtime failure detail into the operational runtime vocabulary.
const fn operational_failure_from_runtime_failure(
    failure: WasmtimePluginRuntimeFailureKind,
) -> PluginOperationalRuntimeFailure {
    match failure {
        WasmtimePluginRuntimeFailureKind::Engine => PluginOperationalRuntimeFailure::Engine,
        WasmtimePluginRuntimeFailureKind::RuntimeTimer => {
            PluginOperationalRuntimeFailure::RuntimeTimer
        }
        WasmtimePluginRuntimeFailureKind::Component => PluginOperationalRuntimeFailure::Component,
        WasmtimePluginRuntimeFailureKind::Linker => PluginOperationalRuntimeFailure::Linker,
        WasmtimePluginRuntimeFailureKind::Instantiate => {
            PluginOperationalRuntimeFailure::Instantiate
        }
        WasmtimePluginRuntimeFailureKind::Export | WasmtimePluginRuntimeFailureKind::GuestTrap => {
            PluginOperationalRuntimeFailure::Export
        }
        WasmtimePluginRuntimeFailureKind::PostReturn => PluginOperationalRuntimeFailure::PostReturn,
        WasmtimePluginRuntimeFailureKind::Fuel => PluginOperationalRuntimeFailure::Fuel,
    }
}