v0.2.14-pre.003

crates/ksp-program-api/README.md

@@ -1,11 +1,11 @@
 <!-- file: crates/ksp-program-api/README.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # ksp-program-api
 
 `ksp-program-api` est la façade publique ouverte du domaine Program KSP. Elle est destinée aux implémentations officielles futures comme aux crates Program externes et ne possède pas les implémentations concrètes.
 
-La tranche initiale `0.2.14-pre.002` matérialise uniquement le scaffold et les types déjà possédés par les couches fondatrices. Aucun trait decoder n'est encore publié.
+À partir de `0.2.14-pre.003`, la foundation expose les types Core/Interface retenus ainsi que le vocabulaire minimal de reconnaissance et d'outcome de décodage. Le trait decoder reste réservé à la tranche suivante.
 
 ## Ownership
 
@@ -35,11 +35,43 @@ ProgramAccountMeta
 ProgramInstruction
 ```
 
-`ksp-program-api` les réexporte depuis son crate-root pour offrir une façade de consommation stable sans dupliquer leurs types ni transférer leur ownership.
+Program API possède désormais :
 
-## Surface de scaffold
+```text
+ProgramInstructionRecognition
+ProgramInstructionDecodeOutcome<Decoded>
+```
 
-La façade `pre.002` expose exactement :
+`ksp-program-api` réexporte l'ensemble depuis son crate-root pour offrir une façade de consommation stable sans dupliquer les types Core/Interface ni transférer leur ownership.
+
+## Recognition
+
+`ProgramInstructionRecognition` est `#[non_exhaustive]` et possède trois états :
+
+```text
+NoMatch       l'implémentation ne revendique pas l'instruction
+ProgramMatch  le Program ou la famille correspond, sans reconnaissance exacte
+ExactMatch    l'implémentation affirme un match instruction-local exact
+```
+
+Cette reconnaissance ne contient aucun score, priorité, proof, confidence, discriminator textuel ou inventaire central de Programs.
+
+## Decode outcome
+
+`ProgramInstructionDecodeOutcome<Decoded>` est également `#[non_exhaustive]` :
+
+```text
+Decoded(Decoded)  valeur typée possédée par l'implémentation
+Unsupported       instruction connue mais non supportée par cette capability
+```
+
+Un futur `decode(...)` utilisera le `Result` Core : une erreur de validation/décodage restera donc `Err`, sans variante parallèle `Failed`.
+
+Le `Debug` de l'outcome n'impose pas `Decoded: Debug` et n'affiche jamais la valeur `Decoded`. Il produit uniquement le nom sûr de l'état (`Decoded` ou `Unsupported`).
+
+## Surface actuelle
+
+La façade `pre.003` expose :
 
 ```text
 Error
@@ -49,16 +81,16 @@ Result
 Pubkey
 ProgramAccountMeta
 ProgramInstruction
+ProgramInstructionRecognition
+ProgramInstructionDecodeOutcome<Decoded>
 ```
 
 Aucun module interne n'est public.
 
-Les contrats suivants restent réservés aux tranches suivantes :
+Le contrat suivant reste réservé à `pre.004` :
 
 ```text
-ProgramInstructionRecognition        pre.003
-ProgramInstructionDecodeOutcome<T>   pre.003
-ProgramInstructionDecoder            pre.004
+ProgramInstructionDecoder
 ```
 
 ## Frontières