v0.1.0-pre.070

kb-pipeline-demo-scenarios/CHANGELOG.md

@@ -0,0 +1,20 @@
+<!-- file: kb-pipeline-demo-scenarios/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-pipeline-demo-scenarios
+
+## 0.1.0-pre.070
+
+- enrichissement du `USAGE.md` avec plusieurs exemples couvrant les principales familles d’API publiques ;
+- ajout du contrat documentaire de la crate mixte ;
+- inventaire des scénarios publics et du binaire CLI ;
+- documentation des tests Devnet comme références d’exécution réelle ;
+- classement des travaux d’autonomie CLI, fixtures et Metaplex dans le TODO.
+
+## 0.1.0-pre.062
+
+- extraction des scénarios de démonstration hors du desktop ;
+- conservation du nom de bibliothèque `kb_pipeline_demo_scenarios` ;
+- création du binaire explicite `kb-pipeline-demo-scenarios-cli` avec `autobins = false` ;
+- migration des scénarios System Transfer, Memo v4, ATA, SPL Token et Token-2022 ;
+- validation connue de 39 tests de bibliothèque et 1 test de binaire.

kb-pipeline-demo-scenarios/README.md

@@ -1,16 +1,29 @@
+<!-- file: kb-pipeline-demo-scenarios/README.md -->
+<!-- version: 1 -->
 
-## Environnement des scénarios
+# kb-pipeline-demo-scenarios
 
-Les exécutables et tests opt-in peuvent appeler `initialize_demo_scenario_environment(workspace_root)` avant de lire leurs variables. Cette fonction délègue à `kb-config` et applique la même priorité que l'application desktop. La crate ne dépend pas directement de `dotenvy`.
+`kb-pipeline-demo-scenarios` fournit des scénarios opérateur et Devnet réutilisables au-dessus de `kb-pipeline`.
 
-## Préparation de la fixture Token-2022
+La crate est mixte :
 
-```bash
-cargo run -p kb-pipeline-demo-scenarios --bin kb-pipeline-demo-scenarios-cli -- prepare-token-2022-fixture \
-  --rpc-url https://api.devnet.solana.com \
-  --wallet wallets/temporary/local_devnet/local-devnet-operator.json \
-  --wallet-dir wallets/temporary/local_devnet \
-  --decimals 9
-```
+- bibliothèque Rust `kb_pipeline_demo_scenarios` ;
+- binaire `kb-pipeline-demo-scenarios-cli`.
 
-La commande crée ou réutilise un mint avec freeze authority, trois comptes Token-2022 distincts et un delegate, puis écrit `spl_token_2022_validation/fixture.env`. Les keypairs sont générés avec `solana-keygen --silent` et ne sont jamais inclus dans la sortie JSON.
+## Responsabilités
+
+- préparation de l’environnement et du profil Devnet ;
+- scénarios System Program, Memo v4, ATA, SPL Token et Token-2022 ;
+- simulation ou soumission explicitement autorisée ;
+- préparation de fixtures publiques ;
+- validation des matrices et rapports Token-2022 ;
+- progression observable et annulation coopérative.
+
+Elle ne remplace ni le pipeline générique ni l’application desktop.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [Architecture du pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)

kb-pipeline-demo-scenarios/TODO.md

@@ -0,0 +1,13 @@
+<!-- file: kb-pipeline-demo-scenarios/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-pipeline-demo-scenarios
+
+- [ ] CLI - rendre chaque scénario public exécutable hors `kb-app-demo-desktop`.
+- [ ] CLI - compléter les arguments, sorties structurées et diagnostics du binaire.
+- [ ] Fixtures - améliorer la création, réutilisation et validation des fixtures publiques.
+- [ ] Metaplex Token Metadata - ajouter les scénarios de démonstration requis pour la future `0.4.7`.
+- [ ] Registre ElGamal - ne créer un scénario exécutable qu’après confirmation du déploiement et disponibilité des preuves requises.
+- [ ] Tests Devnet - conserver les tests réseau en opt-in et documenter précisément leurs prérequis.
+- [ ] Tests Devnet - compléter les validations de bout en bout manquantes sans dépendre de l’interface desktop.
+- [ ] Documentation - ajouter un guide opérateur des scénarios et de leurs effets réseau.

kb-pipeline-demo-scenarios/USAGE.md

@@ -0,0 +1,181 @@
+<!-- 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.