// file: crates/ksp-program-api/src/program_instruction_decoder.rs
// version: 1

/// Open contract implemented by one Program instruction decoder.
///
/// The decoder owns its concrete [`Self::Decoded`] type. No central Program
/// enum, erased `Any` payload or serialization contract is required. Program
/// identifiers remain opaque [`crate::Pubkey`] values and do not need to be
/// registered by Core.
///
/// Candidate selection is explicit: callers use [`Self::program_ids`] and
/// [`Self::recognize`] before invoking [`Self::decode`]. `decode` therefore
/// reports only a successful typed value, an intentional unsupported state, or
/// a KSP [`crate::Result`] error. The trait defines no default methods and does
/// not promise heterogeneous runtime object composition.
pub trait ProgramInstructionDecoder: Send + Sync {
    /// Concrete decoded instruction type owned by the implementation.
    type Decoded;

    /// Returns the opaque Program identifiers claimed by this decoder.
    fn program_ids(&self) -> &[crate::Pubkey];

    /// Reports how strongly this decoder recognizes one bounded instruction.
    fn recognize(&self, instruction: &crate::ProgramInstruction) -> crate::ProgramInstructionRecognition;

    /// Decodes one instruction already selected for this decoder.
    fn decode(&self, instruction: &crate::ProgramInstruction) -> crate::Result<crate::ProgramInstructionDecodeOutcome<Self::Decoded>>;
}