crtx-reflect 0.1.1

//! Error types for reflection parsing and quarantine handoff.

use thiserror::Error;

/// Reflection parser failures.
///
/// Every variant keeps the original input bytes as UTF-8 text so callers can
/// write a quarantine record without reconstructing or normalizing the model
/// response.
#[derive(Debug, Error, Clone, PartialEq, Eq)]
pub enum ReflectError {
    /// The model output was not valid JSON.
    #[error("reflection JSON parse failed: {message}")]
    InvalidJson {
        /// Original model output.
        raw: String,
        /// Parser-facing error detail.
        message: String,
    },

    /// The JSON was syntactically valid but did not match the reflection type.
    #[error("reflection schema validation failed: {message}")]
    InvalidSchema {
        /// Original model output.
        raw: String,
        /// Structural validation detail.
        message: String,
    },

    /// The JSON parsed structurally but failed the memory admission gate.
    #[error("reflection admission failed: {message}")]
    AdmissionRejected {
        /// Original model output.
        raw: String,
        /// Admission gate detail.
        message: String,
    },

    /// The JSON parsed structurally but failed a source-authority gate.
    #[error("reflection authority failed: {message}")]
    AuthorityRejected {
        /// Original model output.
        raw: String,
        /// Authority gate detail.
        message: String,
    },
}

impl ReflectError {
    /// Original input suitable for a quarantine record.
    #[must_use]
    pub fn quarantine_payload(&self) -> &str {
        match self {
            Self::InvalidJson { raw, .. }
            | Self::InvalidSchema { raw, .. }
            | Self::AdmissionRejected { raw, .. }
            | Self::AuthorityRejected { raw, .. } => raw,
        }
    }

    /// Stable reason code suitable for audit metadata.
    #[must_use]
    pub const fn quarantine_reason(&self) -> &'static str {
        match self {
            Self::InvalidJson { .. } => "invalid_json",
            Self::InvalidSchema { .. } => "invalid_schema",
            Self::AdmissionRejected { .. } => "admission_rejected",
            Self::AuthorityRejected { .. } => "authority_rejected",
        }
    }

    /// Operator-facing detail without the original payload.
    #[must_use]
    pub fn detail(&self) -> &str {
        match self {
            Self::InvalidJson { message, .. }
            | Self::InvalidSchema { message, .. }
            | Self::AdmissionRejected { message, .. }
            | Self::AuthorityRejected { message, .. } => message,
        }
    }
}