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

# Usage de ksp-program-api

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

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

## 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 restent 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;
}
```

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.003` ne fournit pas

Il n'existe encore aucun :

```text
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. Le trait decoder et la preuve d'implémentation externe sont réservés à `pre.004`.