<!-- file: kb-pipeline-demo-scenarios/USAGE.md -->
<!-- version: 2 -->

# Utilisation de kb-pipeline-demo-scenarios

## Objectif

La bibliothèque expose des scénarios Devnet contrôlés. Le binaire permet leur exécution hors de l’application desktop lorsque la commande correspondante est disponible.

## Initialiser l’environnement

```rust
fn initialize_environment() -> kb_core::Result<()> {
    kb_pipeline_demo_scenarios::initialize_demo_scenario_environment()
}
```

`resolve_demo_devnet_profile` sélectionne un profil Devnet configuré et `prepare_demo_devnet_profile_store` vérifie ou initialise son stockage PostgreSQL.

## Observer une exécution

`NoopSolanaExecutionObserver` convient aux appels sans progression personnalisée.

```rust
fn observer() -> kb_pipeline_demo_scenarios::NoopSolanaExecutionObserver {
    kb_pipeline_demo_scenarios::NoopSolanaExecutionObserver
}
```

Une application peut implémenter `SolanaExecutionObserver` pour recevoir les événements et demander une annulation coopérative.

## Préparer une simulation System Program

```rust
fn system_transfer_request(
    recipient: kb_lib::MdPubkey,
) -> kb_pipeline_demo_scenarios::DevnetSystemTransferRequest {
    kb_pipeline_demo_scenarios::DevnetSystemTransferRequest::new(
        "system-transfer-001",
        recipient,
        1_000,
    )
}
```

Le constructeur crée une requête conservative : `submit` et `operator_confirmed` restent à `false`.

## Préparer et exécuter un Memo v4

```rust
fn memo_request() -> kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest {
    kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest::new(
        "memo-001",
        "khadhroony-bot3 Devnet validation",
    )
}
```

```rust
async fn run_memo<S, O>(
    store: &S,
    observer: &O,
    request: kb_pipeline_demo_scenarios::DevnetMemoExecutionRequest,
) -> kb_core::Result<kb_pipeline_demo_scenarios::DevnetMemoExecutionSummary>
where
    S: kb_store::Store + Sync,
    O: kb_pipeline_demo_scenarios::SolanaExecutionObserver,
{
    let result = kb_pipeline_demo_scenarios::execute_devnet_memo(
        store,
        observer,
        request,
    )
    .await;

    match result {
        Ok(summary) => Ok(summary),
        Err(error) => Err(error),
    }
}
```

## Simuler Token-2022

```rust
async fn simulate_token_2022<O>(
    request: kb_pipeline_demo_scenarios::DevnetSplToken2022ExecutionRequest,
    observer: &O,
) -> kb_core::Result<kb_pipeline_demo_scenarios::DevnetSplToken2022ExecutionSummary>
where
    O: kb_pipeline_demo_scenarios::SolanaExecutionObserver,
{
    let result =
        kb_pipeline_demo_scenarios::simulate_devnet_spl_token_2022(request, observer).await;

    match result {
        Ok(summary) => Ok(summary),
        Err(error) => Err(error),
    }
}
```

## Charger la matrice de validation Token-2022

```rust
fn load_validation_matrix(
) -> kb_core::Result<kb_pipeline_demo_scenarios::Token2022ValidationMatrix> {
    let result = kb_pipeline_demo_scenarios::load_token_2022_validation_matrix();

    match result {
        Ok(matrix) => Ok(matrix),
        Err(error) => Err(error),
    }
}
```

La matrice provient de `test-fixtures/contract-matrices/SPL_TOKEN_2022_VALIDATION_MATRIX.json` et est validée avant d’être retournée.

## Parcourir les scénarios publics

```rust
fn scenario_ids() -> Vec<String> {
    kb_pipeline_demo_scenarios::devnet_spl_validation_scenarios()
        .iter()
        .map(|scenario| scenario.id.clone())
        .collect()
}
```

Cette liste permet au CLI ou au desktop de présenter l’inventaire sans dupliquer les identifiants.

## Préparer une fixture Token-2022

```rust
async fn prepare_fixture(
    wallet_path: std::path::PathBuf,
    wallet_dir: std::path::PathBuf,
) -> kb_core::Result<kb_pipeline_demo_scenarios::Token2022FixturePreparationSummary> {
    let options = kb_pipeline_demo_scenarios::Token2022FixturePreparationOptions {
        rpc_url: "https://api.devnet.solana.com".to_string(),
        wallet_path,
        wallet_dir,
        decimals: 9,
    };
    let result = kb_pipeline_demo_scenarios::prepare_token_2022_fixture(&options).await;

    match result {
        Ok(summary) => Ok(summary),
        Err(error) => Err(error),
    }
}
```

La préparation peut créer des comptes et exécuter des commandes Solana CLI. Elle doit rester explicitement déclenchée par l’opérateur.

## Tests de référence

Les tests de cette crate sont particulièrement utiles pour comprendre l’orchestration réelle :

- validation de la matrice Token-2022 ;
- préparation et réutilisation des fixtures ;
- simulation et exécution des scénarios ;
- hydratation canonique, extraction Core, replay et matérialisation ;
- idempotence et confirmation des états finaux ;
- test du binaire `kb-pipeline-demo-scenarios-cli`.

Les tests Devnet restent opt-in et peuvent produire des transactions réelles lorsque la soumission est explicitement activée.

## Erreurs et invariants

- aucun envoi ne doit résulter d’une simple demande de simulation ;
- le profil doit cibler Devnet pour les scénarios Devnet ;
- les secrets restent gérés par `kb-wallet` ;
- les résumés ne doivent pas déclarer une validation non observée ;
- ElGamal ne doit pas être présenté comme validé sur réseau.

## Limites durables

- cette crate est destinée aux démonstrations, validations et outils opérateur, pas au moteur de production autonome ;
- les scénarios réseau exigent un endpoint, un wallet et des fonds compatibles ;
- la bibliothèque ne fournit pas d’interface graphique.