# 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. À partir de `0.2.14-pre.004`, la foundation expose les types Core/Interface retenus, le vocabulaire minimal de reconnaissance/décodage et le trait instruction-only `ProgramInstructionDecoder`. ## Ownership La crate dépend uniquement de : ```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 l'ensemble depuis son crate-root. Aucun module interne n'est public. ## Recognition `ProgramInstructionRecognition` est `#[non_exhaustive]` : ```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` est `#[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 ``` Les échecs réels passent par le `Result` Core. Il n'existe aucune variante parallèle `Failed`. 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> ``` Le type `Decoded` est possédé par l'implémentation. Un decoder externe peut utiliser un `Pubkey` absent du registry Core : aucun enum central, `Any`, JSON ou descriptor global n'est requis pour déclarer un Program. Le trait ne fournit aucun default method et ne promet pas de registry dyn hétérogène. `program_ids` et `recognize` servent à la sélection explicite ; `decode` traite une instruction déjà sélectionnée pour le decoder. ## Surface actuelle La façade `pre.004` expose : ```text Error ErrorCode ErrorContext Result Pubkey ProgramAccountMeta ProgramInstruction ProgramInstructionRecognition ProgramInstructionDecodeOutcome ProgramInstructionDecoder ``` ## Frontières La foundation 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 ``` L'absence de ces surfaces est volontaire : `ksp-program-api` reste une API déclarative, ouverte et indépendante des implémentations/runtime supérieurs. ## 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)