// file: crates/ksp-program-api/src/program_instruction_decode.rs
// version: 2

/// Recognition strength reported by one Program instruction implementation.
///
/// Recognition is intentionally instruction-local. It does not encode registry
/// priority, a persisted proof, a textual discriminator or a global Program
/// kind. [`Self::ExactMatch`] is an assertion made by the implementation for
/// the current instruction, while [`Self::ProgramMatch`] only establishes the
/// Program-level match.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ProgramInstructionRecognition {
    /// The implementation does not claim the instruction.
    NoMatch,
    /// The Program or Program family matches, but the instruction is not proven exact.
    ProgramMatch,
    /// The implementation claims an exact instruction-local match.
    ExactMatch,
}

/// Result of a successful Program instruction decode attempt.
///
/// Decode failures are represented by the surrounding KSP [`crate::Result`],
/// not by a parallel failure variant. `Unsupported` is reserved for a known
/// Program instruction that the implementation deliberately does not decode.
///
/// The custom [`std::fmt::Debug`] implementation never formats the `Decoded`
/// value, so external decoded payloads are not exposed accidentally through
/// generic diagnostics.
#[non_exhaustive]
pub enum ProgramInstructionDecodeOutcome<Decoded> {
    /// The instruction was decoded into the implementation-owned output type.
    Decoded(Decoded),
    /// The instruction is known but unsupported by this decode capability.
    Unsupported,
}

impl<Decoded> std::fmt::Debug for ProgramInstructionDecodeOutcome<Decoded> {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        return match self {
            Self::Decoded(_) => formatter.write_str("Decoded"),
            Self::Unsupported => formatter.write_str("Unsupported"),
        };
    }
}

#[cfg(test)]
#[path = "../unit_tests/program_instruction_decode.rs"]
mod tests;