<!-- file: kb_execution_api/README.md -->
<!-- version: 3 -->

# kb_execution_api

Cette crate définit les contrats communs de la couche d’exécution. Elle ne dépend ni du wallet, ni du RPC, ni du stockage, ni des décodeurs et ne construit aucune instruction Solana.

## API publique

### Capacités et traits

| Export                                  | Usage                                                                                                                      |
|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
| `ExApiExecutionCapability`              | Réponse exacte `Supported { operation_code }` ou `Unsupported { reason_code, reason }` pour un couple programme/opération. |
| `ExecutionCapability::supported(...)`   | Construit une capacité supportée avec un code stable.                                                                      |
| `ExecutionCapability::unsupported(...)` | Construit un refus documenté avec code et message.                                                                         |
| `ExecutionCapability::is_supported()`   | Teste la capacité sans perdre le diagnostic du variant complet.                                                            |
| `ExApiTypedInstructionExecutor`         | Contrat actuel : expose `capability(...)` et `build_prepared_plan(...)` sans I/O, signature ou envoi.                      |
| `ExApiInstructionExecutor`              | Pont historique fondé sur `ExApiExecutionRequest`/`ExApiExecutionPlan`; il reste disponible pour les crates réservées.     |
| `ExApiExecutionSupport`                 | Résultat historique `No`, `Maybe` ou `Yes`; les exécuteurs opérationnels doivent éviter `Maybe`.                           |

### Politiques

| Export                               | Usage                                                                                                     |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------|
| `ExApiExecutionPolicy`               | Agrège cluster, simulation, blockhash/nonce, plafonds, signataires autorisés, dry-run et post-validation. |
| `ExApiExecutionCluster`              | Cluster attendu : Localnet, Devnet, Testnet ou Mainnet.                                                   |
| `ExApiExecutionClusterPolicy`        | Autorisation du cluster et double confirmation Mainnet.                                                   |
| `ExApiExecutionSimulationPolicy`     | Indique si la simulation est obligatoire.                                                                 |
| `ExApiExecutionBlockhashKind`        | Sélectionne un recent blockhash ou un durable nonce.                                                      |
| `ExApiExecutionBlockhashPolicy`      | Porte l’âge maximal du blockhash ou le compte et l’autorité nonce.                                        |
| `ExApiExecutionCostLimit`            | Plafonds de dépense, frais totaux et prix par compute unit.                                               |
| `ExApiPostExecutionValidationPolicy` | Étapes exigées après confirmation : canonical insert, core extraction, decode replay et matérialisation.  |

Tous les types de politique implémentent des valeurs par défaut conservatrices : Devnet, simulation obligatoire, recent blockhash borné, dry-run actif et Mainnet désactivé.

### Plan préparé

| Export                       | Usage                                                                               |
|------------------------------|-------------------------------------------------------------------------------------|
| `ExApiPreparedExecutionPlan` | Contrat immutable transmis de l’exécuteur à la sécurité puis à l’assembleur Solana. |
| `ExApiPlannedInstruction`    | Program ID, code d’opération, comptes ordonnés et payload exact.                    |
| `ExApiPlannedAccount`        | Public key et flags signer/writable d’un compte d’instruction.                      |
| `ExApiRequiredSigner`        | Public key et rôle stable d’un signataire requis.                                   |

Un plan contient également l’exécuteur/version, l’identifiant d’intent, le fee payer, la politique, les lamports dépensés ou verrouillés et le prix Compute Budget demandé.

### Résultats d’orchestration

| Export                             | Usage                                                                                                             |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------|
| `ExApiExecutionSimulationResult`   | Preuve provider-neutral d’une simulation, avec contexte cluster/blockhash, frais, unités, logs et erreur runtime. |
| `ExApiExecutionSendResult`         | Signature acceptée par le RPC et slot de soumission éventuel.                                                     |
| `ExApiExecutionConfirmationStatus` | État final ou intermédiaire de confirmation.                                                                      |
| `ExApiExecutionConfirmationResult` | Résultat borné des polls de confirmation.                                                                         |
| `ExApiPostExecutionDiagnostic`     | Résumé des étapes canonical/core/decode/materialization après exécution.                                          |

### Compatibilité et helpers JSON

| Export                               | Usage                                                                  |
|--------------------------------------|------------------------------------------------------------------------|
| `ExApiExecutionRequest`              | Requête historique `program_id + operation_code + payload_json`.       |
| `ExApiExecutionPlan`                 | Plan historique sérialisé, sans garantie d’être directement envoyable. |
| `serialize_payload_json(...)`        | Sérialise un `serde_json::Value` compact avec `kb_core::Error`.        |
| `serialize_payload_json_pretty(...)` | Sérialise le même payload en forme lisible.                            |

## Exemple d’implémentation d’un exécuteur

```rust
impl kb_execution_api::TypedInstructionExecutor for MyExecutor {
    type Intent = MyIntent;

    fn capability(
        &self,
        program_id: &kb_model::ProgramId,
        operation_code: &str,
    ) -> kb_execution_api::ExecutionCapability {
        // Return an exact Supported or Unsupported result.
    }

    fn build_prepared_plan(
        &self,
        intent: &Self::Intent,
    ) -> kb_core::Result<kb_execution_api::PreparedExecutionPlan> {
        // Validate and encode only. Do not access RPC or sign here.
    }
}
```

## Frontières

`kb_execution_api` ne décide pas qu’un plan est sûr, ne compile pas de message Solana et ne contacte aucun endpoint. Le flux attendu est :

```text
executor intent
  -> PreparedExecutionPlan
    -> kb_execution_safety
      -> kb_execution_solana
        -> kb_rpc
          -> post-execution orchestration
```