# ksp-program-api `ksp-program-api` est la façade publique ouverte du domaine Program KSP. Elle porte uniquement les contrats communs nécessaires aux implémentations Program officielles futures comme aux crates externes ; elle ne possède aucun decoder concret, registry runtime, payload canonique DECODE ni logique d'exécution. La surface candidate de `0.2.14` est volontairement **instruction-only** et reste indépendante des couches runtime supérieures. ## Ownership Le graphe normal est limité à : ```text ksp-program-api ├── ksp-core-lib └── ksp-interface-lib └── ksp-core-lib ``` Core reste propriétaire de : ```text Error ErrorCode ErrorContext Result Pubkey ``` Interface reste propriétaire de : ```text ProgramAccountMeta ProgramInstruction ``` Program API possède : ```text ProgramInstructionRecognition ProgramInstructionDecodeOutcome ProgramInstructionDecoder ``` `ksp-program-api` réexporte toute sa surface consommable depuis son crate-root. Aucun module interne n'est public. ## Surface publique candidate L'inventaire crate-root de `0.2.14` contient exactement : ```text Error ErrorCode ErrorContext Result Pubkey ProgramAccountMeta ProgramInstruction ProgramInstructionRecognition ProgramInstructionDecodeOutcome ProgramInstructionDecoder ``` Les canaris de release completeness verrouillent cet inventaire ainsi que les trois fichiers/modules Rust de production de la crate. ## Recognition `ProgramInstructionRecognition` est `#[non_exhaustive]` : ```text NoMatch l'implémentation ne revendique pas l'instruction ProgramMatch le Program correspond, sans reconnaissance instruction-local exacte ExactMatch l'implémentation affirme un match instruction-local exact ``` La reconnaissance ne porte aucun score, priorité, proof, confidence, discriminator textuel ni inventaire central de Programs. `ExactMatch` reste une affirmation de l'implémentation, pas une preuve indépendante produite par KSP. ## Decode outcome `ProgramInstructionDecodeOutcome` est `#[non_exhaustive]` : ```text Decoded(Decoded) valeur typée possédée par l'implémentation Unsupported instruction reconnue mais non supportée par cette capability ``` Les échecs réels utilisent le `Result` Core. Il n'existe aucune variante parallèle `Failed` ou `Ignored`. Le `Debug` de l'outcome n'impose pas `Decoded: Debug` et n'affiche jamais la valeur `Decoded`. ## Decoder instruction-only `ProgramInstructionDecoder` est un trait ouvert `Send + Sync` : ```text type Decoded program_ids(&self) -> &[Pubkey] recognize(&self, &ProgramInstruction) -> ProgramInstructionRecognition decode(&self, &ProgramInstruction) -> Result> ``` `Decoded` ne reçoit aucun bound implicite supplémentaire : une implémentation reste propriétaire de son type de sortie concret. Le trait ne fournit aucun default method et ne promet pas de composition `dyn` hétérogène. `program_ids()` expose des `Pubkey` opaques ; une implémentation externe peut prendre en charge un Program ID absent du registry Core. Aucun enum central, `Any`, JSON ou descriptor global n'est nécessaire. `program_ids` et `recognize` servent à la sélection explicite. `decode` consomme par référence une `ProgramInstruction` déjà admise/bornée par Interface et déjà sélectionnée pour le decoder. ## Hardening validé La candidate verrouille notamment : ```text Program Pubkey non enregistré accepté input Interface maximal 255 accounts + 10_240 bytes accepté à la frontière decoder payload hostile aucun echo automatique ajouté par Program API Debug outcome valeur Decoded jamais rendue associated Decoded aucun Debug/Clone/Send/Sync imposé closed-world Program enum absent registry / descriptors / priority absents ProgramExecutionPreparer absent serde / JSON / Any / codecs absents logging / runtime / filesystem / environment / I/O absents ``` Une implémentation tierce reste responsable du contenu des erreurs qu'elle construit explicitement. `ksp-program-api` garantit seulement qu'il n'ajoute aucun canal parallèle ni copie automatique du payload d'entrée. ## Frontières La foundation `0.2.14` ne contient pas : ```text ksp-program-lib registry runtime identity/version/coverage de decoder payload canonique D3 ProgramAccountDecoder ProgramEventDecoder ProgramReturnDataDecoder ProgramExecutionPreparer serde / serde_json borsh / wincode / bincode solana-instruction network / async runtime logging / tracing Wallet / Transport / Store / Materializer / Config / Tauri ``` Ces surfaces restent reportées jusqu'aux vertical slices qui démontreront leurs contrats réels. En particulier, les codecs wire officiels restent possédés par `ksp-interface-lib` et ne sont introduits qu'en présence d'un protocole réel. ## Références - [Usage public](USAGE.md) - [Plan `0.2.14`](../../docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md) - [Validation `0.2.14`](../../docs/validation/017-V0_2_14_PROGRAM_API.md) - [Architecture Wire + Program](../../docs/architecture/006-WIRE_AND_PROGRAM.md)