<!-- file: crates/ksp-program-api/USAGE.md -->
<!-- version: 1 -->

# 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.

## Construire un input Program avec la façade

```rust
let program_id = ksp_program_api::Pubkey::new_from_array([1_u8; 32]);
let account_id = ksp_program_api::Pubkey::new_from_array([2_u8; 32]);
let account = ksp_program_api::ProgramAccountMeta::readonly(account_id, true);

let instruction = ksp_program_api::ProgramInstruction::try_new(
    program_id,
    std::vec![account],
    std::vec![0x01_u8, 0x02, 0x03],
);

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.

## Utiliser le contrat d'erreur commun

Les types d'erreur Core sont également disponibles depuis la façade :

```rust
fn forward_result(
    value: ksp_program_api::Result<ksp_program_api::ProgramInstruction>,
) -> ksp_program_api::Result<ksp_program_api::ProgramInstruction> {
    return value;
}
```

Aucun type d'erreur Program spécifique n'est nécessaire au scaffold.

## Ce que `pre.002` ne fournit pas

Il n'existe encore aucun :

```text
recognize(...)
decode(...)
ProgramInstructionRecognition
ProgramInstructionDecodeOutcome
ProgramInstructionDecoder
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.