v0.2.14-pre.003

crates/ksp-program-api/USAGE.md

@@ -1,9 +1,9 @@
 <!-- file: crates/ksp-program-api/USAGE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Usage de ksp-program-api
 
-Cette page décrit le scaffold public disponible à partir de `0.2.14-pre.002`. Utiliser uniquement les exports du crate-root ; aucun module interne ne fait partie du contrat consommable.
+Cette page décrit la surface publique disponible à partir de `0.2.14-pre.003`. Utiliser uniquement les exports du crate-root ; aucun module interne ne fait partie du contrat consommable.
 
 ## Construire un input Program avec la façade
 
@@ -23,9 +23,61 @@ assert!(instruction.is_ok());
 
 `Pubkey`, `ProgramAccountMeta` et `ProgramInstruction` conservent leur ownership Core/Interface. Program API fournit seulement une façade cohérente aux futures implémentations de capability Program.
 
+## Représenter une reconnaissance
+
+```rust
+let recognition = ksp_program_api::ProgramInstructionRecognition::ProgramMatch;
+
+match recognition {
+    ksp_program_api::ProgramInstructionRecognition::NoMatch => {}
+    ksp_program_api::ProgramInstructionRecognition::ProgramMatch => {}
+    ksp_program_api::ProgramInstructionRecognition::ExactMatch => {}
+    _ => {}
+}
+```
+
+Le wildcard est volontaire : l'enum est `#[non_exhaustive]` afin de ne pas transformer la foundation en vocabulaire fermé pour toujours.
+
+## Représenter un outcome de décodage
+
+Le type décodé reste possédé par l'implémentation :
+
+```rust
+struct ExternalDecodedInstruction {
+    opcode: u8,
+}
+
+let outcome = ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(
+    ExternalDecodedInstruction { opcode: 7_u8 },
+);
+
+match outcome {
+    ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(value) => {
+        assert_eq!(value.opcode, 7_u8);
+    }
+    ksp_program_api::ProgramInstructionDecodeOutcome::Unsupported => {}
+    _ => {}
+}
+```
+
+Aucun `Any`, JSON ou enum centrale n'est nécessaire pour transporter ce type.
+
+## Debug sûr
+
+`ProgramInstructionDecodeOutcome<Decoded>` possède un `Debug` volontairement opaque sur la valeur décodée :
+
+```rust
+struct SecretDecoded;
+
+let outcome = ksp_program_api::ProgramInstructionDecodeOutcome::Decoded(SecretDecoded);
+assert_eq!(std::format!("{outcome:?}"), "Decoded");
+```
+
+`SecretDecoded` n'a même pas besoin d'implémenter `Debug`. Cela empêche un diagnostic générique de rendre accidentellement un payload externe.
+
 ## Utiliser le contrat d'erreur commun
 
-Les types d'erreur Core sont également disponibles depuis la façade :
+Les types d'erreur Core restent disponibles depuis la façade :
 
 ```rust
 fn forward_result(
@@ -35,21 +87,20 @@ fn forward_result(
 }
 ```
 
-Aucun type d'erreur Program spécifique n'est nécessaire au scaffold.
+Le futur `decode(...)` utilisera ce `Result`. Une erreur sera donc `Err(...)`, tandis que `Unsupported` signifie une instruction connue volontairement non prise en charge.
 
-## Ce que `pre.002` ne fournit pas
+## Ce que `pre.003` ne fournit pas
 
 Il n'existe encore aucun :
 
 ```text
-recognize(...)
-decode(...)
-ProgramInstructionRecognition
-ProgramInstructionDecodeOutcome
 ProgramInstructionDecoder
+program_ids(...)
+recognize(...) sur un trait
+decode(...) sur un trait
 registry de decoders
 payload générique JSON/Any
 execution preparer
 ```
 
-Ces éléments ne doivent pas être simulés côté consumer. Les contrats de recognition/outcome puis le trait decoder seront introduits dans leurs tranches dédiées.
+Ces éléments ne doivent pas être simulés côté consumer. Le trait decoder et la preuve d'implémentation externe sont réservés à `pre.004`.