v0.2.14-pre.007

crates/ksp-program-api/USAGE.md

@@ -1,9 +1,9 @@
 <!-- file: crates/ksp-program-api/USAGE.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Usage de ksp-program-api
 
-Cette page décrit la surface publique disponible à partir de `0.2.14-pre.004`. Utiliser uniquement les exports du crate-root ; aucun module interne ne fait partie du contrat consommable.
+Cette page décrit la surface publique candidate de `0.2.14`. Utiliser uniquement les exports du crate-root ; aucun module interne ne fait partie du contrat consommable.
 
 ## Construire un input Program avec la façade
 
@@ -21,7 +21,7 @@ let instruction = ksp_program_api::ProgramInstruction::try_new(
 assert!(instruction.is_ok());
 ```
 
-`Pubkey`, `ProgramAccountMeta` et `ProgramInstruction` conservent leur ownership Core/Interface.
+`Pubkey`, `ProgramAccountMeta` et `ProgramInstruction` conservent leur ownership Core/Interface. Les bornes `255` account metas et `10_240` bytes de data sont appliquées par Interface avant l'entrée dans le decoder.
 
 ## Implémenter un decoder externe
 
@@ -50,6 +50,11 @@ impl ksp_program_api::ProgramInstructionDecoder for ExternalDecoder {
         if instruction.program_id() != &self.program_ids[0] {
             return ksp_program_api::ProgramInstructionRecognition::NoMatch;
         }
+
+        if instruction.data().first() == std::option::Option::Some(&0x2A_u8) {
+            return ksp_program_api::ProgramInstructionRecognition::ExactMatch;
+        }
+
         return ksp_program_api::ProgramInstructionRecognition::ProgramMatch;
     }
 
@@ -58,13 +63,14 @@ impl ksp_program_api::ProgramInstructionDecoder for ExternalDecoder {
         instruction: &ksp_program_api::ProgramInstruction,
     ) -> ksp_program_api::Result<ksp_program_api::ProgramInstructionDecodeOutcome<Self::Decoded>> {
         let opcode = match instruction.data().first() {
-            std::option::Option::Some(value) => *value,
-            std::option::Option::None => {
+            std::option::Option::Some(value) if *value == 0x2A_u8 => *value,
+            _ => {
                 return std::result::Result::Ok(
                     ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported,
                 );
             }
         };
+
         return std::result::Result::Ok(
             ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(
                 ExternalDecodedInstruction { opcode },
@@ -94,7 +100,7 @@ match recognition {
 }
 ```
 
-L'enum est `#[non_exhaustive]`. `decode` n'est pas un substitut à `recognize` : il traite une instruction déjà sélectionnée pour le decoder.
+L'enum est `#[non_exhaustive]`. `ExactMatch` exprime l'affirmation du decoder. `decode` n'est pas un substitut à `recognize` : il traite une instruction déjà sélectionnée pour cette implémentation.
 
 ## Outcome et erreur
 
@@ -115,6 +121,18 @@ match outcome {
 
 Une erreur réelle est un `Err(ksp_program_api::Error)`. `Unsupported` n'est pas une deuxième forme d'erreur : il indique qu'une instruction reconnue n'est volontairement pas décodée par cette capability.
 
+Program API ne recopie automatiquement ni le payload de l'instruction ni les account metas dans l'erreur. Une implémentation externe reste responsable des messages/contextes qu'elle construit explicitement.
+
+## Output sans bounds implicites
+
+L'associated type `Decoded` n'impose pas `Debug`, `Clone`, `Send` ou `Sync`. Les supertraits `Send + Sync` s'appliquent au decoder lui-même, pas à la valeur décodée :
+
+```rust
+struct LocalDecoded(std::rc::Rc<std::cell::Cell<u8>>);
+```
+
+Un decoder peut utiliser ce type comme `Decoded` tant que son propre état satisfait `Send + Sync`.
+
 ## Debug sûr
 
 `ProgramInstructionDecodeOutcome<Decoded>` possède un `Debug` volontairement opaque :
@@ -128,14 +146,15 @@ assert_eq!(std::format!("{outcome:?}"), "Decoded");
 
 `SecretDecoded` n'a pas besoin d'implémenter `Debug` et sa valeur n'est jamais rendue par l'outcome.
 
-## Hors surface `pre.004`
+## Ce qui n'est pas simulé côté consumer
 
-Il n'existe toujours aucun :
+Il n'existe dans `0.2.14` aucun :
 
 ```text
 registry de decoders
 composition dyn hétérogène
 identity/version/coverage descriptor
+priority/conflict policy
 payload canonique D3
 ProgramAccountDecoder / Event / ReturnData
 ProgramExecutionPreparer
@@ -144,4 +163,4 @@ serde / JSON / codec
 logging / runtime réseau
 ```
 
-Ces surfaces ne doivent pas être simulées côté consumer. Elles attendent les vertical slices qui justifieront leurs contrats réels.
+Ces surfaces ne doivent pas être recréées localement comme si elles faisaient déjà partie du contrat commun. Elles attendent les vertical slices qui justifieront leurs invariants réels.