v0.4.8-pre.008

kb-pipeline/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-pipeline/USAGE.md -->
-<!-- version: 6 -->
+<!-- version: 8 -->
 
 # Utilisation de kb-pipeline
 
@@ -152,6 +152,57 @@ where
 
 Les rapports stateful ne constituent jamais une autorisation implicite d’exécution.
 
+## Nomenclature interne des modules
+
+Les modules privés sont organisés par domaine :
+
+- `metadata_metaplex_token_metadata_*` ;
+- `metadata_solana_program_*` ;
+- `spl_ata_stateful` et `spl_elgamal_registry_stateful` ;
+- `spl_token_stateful` et `spl_token_2022_*` ;
+- `solana_stateful` uniquement pour les primitives Solana Core partagées.
+
+Cette réorganisation ne renomme pas les fonctions et structures publiques existantes.
+
+## Valider historiquement Solana Program Metadata
+
+La validation historique reste un enchaînement de surfaces généralistes, pas un scénario Devnet :
+
+1. `demo_backfill` hydrate un échantillon borné de signatures confirmées ;
+2. l’extraction Core résout les instructions et comptes ;
+3. `demo_decode_replay` sélectionne le Program ID `ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S` et le décodeur `metadata.solana_program_metadata` ;
+4. `materializeAfterDecode` active `materializer.metadata.solana_program_metadata` ;
+5. la requête bornée des événements matérialisés permet de vérifier les faits produits.
+
+Le registre générique du desktop fournit désormais ce décodeur et ce matérialiseur. `kb-pipeline-demo-scenarios` n’intervient pas dans ce parcours historique.
+
+## Lire et prévalider Solana Program Metadata
+
+```rust
+async fn read_program_metadata(
+    pool: &kb_onchain_transport::HttpEndpointPool,
+    account: kb_lib::MdPubkey,
+) -> kb_core::Result<kb_pipeline::SolanaProgramMetadataStatefulReadResult> {
+    let request = kb_pipeline::SolanaProgramMetadataStatefulReadRequest {
+        query_role: "rpc".to_string(),
+        account,
+        expected_state: kb_pipeline::SolanaProgramMetadataExpectedAccountState::Any,
+        min_context_slot: std::option::Option::None,
+        max_data_bytes: kb_pipeline::MAX_SOLANA_PROGRAM_METADATA_STATEFUL_ACCOUNT_BYTES,
+    };
+    let result = kb_pipeline::read_solana_program_metadata_stateful_snapshot(pool, &request).await;
+
+    return match result {
+        std::result::Result::Ok(value) => std::result::Result::Ok(value),
+        std::result::Result::Err(error) => std::result::Result::Err(error),
+    };
+}
+```
+
+Le préflight reçoit l’intent typé, le plan produit par `ExMetadataSolanaProgramMetadataExecutor`, les snapshots confirmés et, pour les opérations qui allouent ou agrandissent un compte, une observation explicite du minimum de rent. Il refuse un plan `Deny`, mais les opérations dangereuses restent exécutables lorsqu’elles sont explicitement approuvées et que l’enveloppe commune de sécurité est satisfaite.
+
+Après simulation du message exact, `validate_solana_program_metadata_execution_readiness` vérifie les signers et l’autorisation de soumission. Après confirmation, `inspect_solana_program_metadata_post_execution` compare les lectures avant/après pour les neuf opérations.
+
 ## Observateurs
 
 Les campagnes longues exposent des traits d’observation distincts pour le backfill, l’extraction Core et le replay. L’observateur peut publier la progression et participer à l’annulation coopérative selon le contrat concerné.