v0.2.14-pre.004

crates/ksp-program-api/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-program-api/src/lib.rs
-// version: 2
+// version: 3
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -8,16 +8,19 @@
 //! Open Program contracts shared by KSP and external Program implementations.
 //!
 //! The foundation exposes Core/Interface types plus the minimal instruction
-//! recognition and decode-outcome vocabulary. Decoder behavior, registries,
-//! codecs, runtime logging and execution preparation are added only by later
-//! contracts when their ownership is justified.
+//! recognition/decode vocabulary and the instruction decoder trait. Registries,
+//! codecs, runtime logging and execution preparation remain outside this
+//! foundation until their ownership is justified.
 
 mod program_instruction_decode;
+mod program_instruction_decoder;
 
 /// Result of a successful Program instruction decode attempt.
 pub use self::program_instruction_decode::ProgramInstructionDecodeOutcome;
 /// Recognition strength reported by one Program instruction implementation.
 pub use self::program_instruction_decode::ProgramInstructionRecognition;
+/// Open contract implemented by one Program instruction decoder.
+pub use self::program_instruction_decoder::ProgramInstructionDecoder;
 /// Common KSP error type used by Program-facing contracts.
 pub use ksp_core_lib::Error;
 /// Stable structured code identifying a KSP error category and condition.

crates/ksp-program-api/src/program_instruction_decoder.rs

@@ -0,0 +1,28 @@
+// 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>>;
+}