v0.2.14-pre.004

crates/ksp-program-api/tests/dependency_boundary.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-program-api/tests/dependency_boundary.rs
-// version: 2
+// version: 3
 
 //! Dependency and declarative-surface canaries for the Program API foundation.
 
@@ -46,10 +46,11 @@ fn pre_002_manifest_has_exact_core_and_interface_runtime_dependencies() {
 }
 
 #[test]
-fn pre_003_crate_root_adds_only_recognition_and_decode_outcome() {
+fn pre_004_crate_root_adds_decoder_without_runtime_surface() {
     let crate_root = include_str!("../src/lib.rs");
     for required in [
         "ProgramInstructionDecodeOutcome",
+        "ProgramInstructionDecoder",
         "ProgramInstructionRecognition",
         "Error",
         "ErrorCode",
@@ -61,9 +62,18 @@ fn pre_003_crate_root_adds_only_recognition_and_decode_outcome() {
     ] {
         assert!(crate_root.contains(required), "required Program API facade export missing: {required}");
     }
-    for forbidden in ["pub mod ", "ProgramInstructionDecoder", "ProgramExecutionPreparer", "TRACING_TARGET", "ksp_logging_lib", "serde", "Any"] {
-        assert!(!crate_root.contains(forbidden), "forbidden pre.003 Program API surface detected: {forbidden}");
+    for forbidden in ["pub mod ", "ProgramExecutionPreparer", "TRACING_TARGET", "ksp_logging_lib", "serde", "Any"] {
+        assert!(!crate_root.contains(forbidden), "forbidden pre.004 Program API surface detected: {forbidden}");
     }
+    let decoder_source = include_str!("../src/program_instruction_decoder.rs");
+    assert!(decoder_source.contains("pub trait ProgramInstructionDecoder: Send + Sync"));
+    assert!(decoder_source.contains("type Decoded;"));
+    assert!(decoder_source.contains("fn program_ids(&self) -> &[crate::Pubkey];"));
+    assert!(decoder_source.contains("fn recognize(&self, instruction: &crate::ProgramInstruction)"));
+    assert!(decoder_source.contains("crate::Result<crate::ProgramInstructionDecodeOutcome<Self::Decoded>>"));
+    assert!(!decoder_source.contains("ProgramExecutionPreparer"));
+    assert!(!decoder_source.contains("serde"));
+    assert!(!decoder_source.contains("std::any::Any"));
     let outcome_source = include_str!("../src/program_instruction_decode.rs");
     for forbidden in ["Ignored", "Failed", "serde", "Any"] {
         assert!(!outcome_source.contains(forbidden), "forbidden recognition/outcome concept detected: {forbidden}");

crates/ksp-program-api/tests/external_implementation.rs

@@ -0,0 +1,115 @@
+// file: crates/ksp-program-api/tests/external_implementation.rs
+// version: 1
+
+//! Downstream-style implementation canary for the open Program decoder contract.
+
+const EXTERNAL_PROGRAM_ID_BYTES: [u8; 32] = [0xE7_u8; 32];
+const FOREIGN_PROGRAM_ID_BYTES: [u8; 32] = [0xE8_u8; 32];
+const SUPPORTED_OPCODE: u8 = 0x2A_u8;
+
+struct ExternalDecodedInstruction {
+    opcode: u8,
+}
+
+struct ExternalProgramDecoder {
+    program_ids: [ksp_program_api::Pubkey; 1],
+}
+
+impl ExternalProgramDecoder {
+    fn new() -> Self {
+        return Self { program_ids: [ksp_program_api::Pubkey::new_from_array(EXTERNAL_PROGRAM_ID_BYTES)] };
+    }
+}
+
+impl ksp_program_api::ProgramInstructionDecoder for ExternalProgramDecoder {
+    type Decoded = ExternalDecodedInstruction;
+
+    fn program_ids(&self) -> &[ksp_program_api::Pubkey] {
+        return &self.program_ids;
+    }
+
+    fn recognize(&self, instruction: &ksp_program_api::ProgramInstruction) -> ksp_program_api::ProgramInstructionRecognition {
+        if instruction.program_id() != &self.program_ids[0] {
+            return ksp_program_api::ProgramInstructionRecognition::NoMatch;
+        }
+        if instruction.data().first() == std::option::Option::Some(&SUPPORTED_OPCODE) {
+            return ksp_program_api::ProgramInstructionRecognition::ExactMatch;
+        }
+        return ksp_program_api::ProgramInstructionRecognition::ProgramMatch;
+    }
+
+    fn decode(
+        &self,
+        instruction: &ksp_program_api::ProgramInstruction,
+    ) -> ksp_program_api::Result<ksp_program_api::ProgramInstructionDecodeOutcome<Self::Decoded>> {
+        if instruction.program_id() != &self.program_ids[0] {
+            return std::result::Result::Ok(ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported);
+        }
+        let opcode = match instruction.data().first() {
+            std::option::Option::Some(value) if *value == SUPPORTED_OPCODE => *value,
+            _ => return std::result::Result::Ok(ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported),
+        };
+        return std::result::Result::Ok(ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(ExternalDecodedInstruction { opcode }));
+    }
+}
+
+fn assert_send_sync<T: Send + Sync>(_value: &T) {
+    return;
+}
+
+#[test]
+fn pre_004_external_decoder_uses_unregistered_pubkey_and_implementation_owned_output() {
+    let decoder = ExternalProgramDecoder::new();
+    assert_send_sync(&decoder);
+    let external_program_id = ksp_program_api::Pubkey::new_from_array(EXTERNAL_PROGRAM_ID_BYTES);
+    assert!(ksp_core_lib::find_program_pubkey(&external_program_id).is_none());
+    assert_eq!(ksp_program_api::ProgramInstructionDecoder::program_ids(&decoder), &[external_program_id]);
+    let exact = ksp_program_api::ProgramInstruction::try_new(external_program_id, std::vec![], std::vec![SUPPORTED_OPCODE]);
+    assert!(exact.is_ok());
+    let exact = match exact {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(ksp_program_api::ProgramInstructionDecoder::recognize(&decoder, &exact), ksp_program_api::ProgramInstructionRecognition::ExactMatch);
+    let outcome = ksp_program_api::ProgramInstructionDecoder::decode(&decoder, &exact);
+    assert!(outcome.is_ok());
+    let outcome = match outcome {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    let decoded = match outcome {
+        ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(value) => value,
+        _ => return,
+    };
+    assert_eq!(decoded.opcode, SUPPORTED_OPCODE);
+    return;
+}
+
+#[test]
+fn pre_004_external_decoder_distinguishes_program_match_unsupported_and_no_match() {
+    let decoder = ExternalProgramDecoder::new();
+    let external_program_id = ksp_program_api::Pubkey::new_from_array(EXTERNAL_PROGRAM_ID_BYTES);
+    let program_only = ksp_program_api::ProgramInstruction::try_new(external_program_id, std::vec![], std::vec![0x11_u8]);
+    assert!(program_only.is_ok());
+    let program_only = match program_only {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(ksp_program_api::ProgramInstructionDecoder::recognize(&decoder, &program_only), ksp_program_api::ProgramInstructionRecognition::ProgramMatch);
+    let unsupported = ksp_program_api::ProgramInstructionDecoder::decode(&decoder, &program_only);
+    assert!(unsupported.is_ok());
+    let unsupported = match unsupported {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert!(matches!(unsupported, ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported));
+    let foreign_program_id = ksp_program_api::Pubkey::new_from_array(FOREIGN_PROGRAM_ID_BYTES);
+    let foreign = ksp_program_api::ProgramInstruction::try_new(foreign_program_id, std::vec![], std::vec![SUPPORTED_OPCODE]);
+    assert!(foreign.is_ok());
+    let foreign = match foreign {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(_) => return,
+    };
+    assert_eq!(ksp_program_api::ProgramInstructionDecoder::recognize(&decoder, &foreign), ksp_program_api::ProgramInstructionRecognition::NoMatch);
+    return;
+}

crates/ksp-program-api/tests/public_api.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-program-api/tests/public_api.rs
-// version: 2
+// version: 3
 
 //! Integration canaries for the public `ksp-program-api` foundation.
 
@@ -47,3 +47,31 @@ fn public_pre_003_recognition_and_decode_outcome_are_available_from_crate_root()
     assert_eq!(std::format!("{unsupported:?}"), "Unsupported");
     return;
 }
+
+#[test]
+fn public_pre_004_instruction_decoder_trait_is_available_from_crate_root() {
+    let decoder = NeverInstantiatedDecoder;
+    assert!(ksp_program_api::ProgramInstructionDecoder::program_ids(&decoder).is_empty());
+    return;
+}
+
+struct NeverInstantiatedDecoder;
+
+impl ksp_program_api::ProgramInstructionDecoder for NeverInstantiatedDecoder {
+    type Decoded = u8;
+
+    fn program_ids(&self) -> &[ksp_program_api::Pubkey] {
+        return &[];
+    }
+
+    fn recognize(&self, _instruction: &ksp_program_api::ProgramInstruction) -> ksp_program_api::ProgramInstructionRecognition {
+        return ksp_program_api::ProgramInstructionRecognition::NoMatch;
+    }
+
+    fn decode(
+        &self,
+        _instruction: &ksp_program_api::ProgramInstruction,
+    ) -> ksp_program_api::Result<ksp_program_api::ProgramInstructionDecodeOutcome<Self::Decoded>> {
+        return std::result::Result::Ok(ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported);
+    }
+}