v0.1.0-pre.073

docs/guides/RPC_BACKFILL_AND_WEBSOCKET.md

@@ -0,0 +1,101 @@
+<!-- file: docs/guides/RPC_BACKFILL_AND_WEBSOCKET.md -->
+<!-- version: 2 -->
+
+# Guide RPC, backfill et WebSocket
+
+## Séparation des responsabilités
+
+- `kb-onchain-transport` communique avec les endpoints ;
+- `kb-pipeline` orchestre les campagnes ;
+- `kb-store` persiste les acquisitions canoniques et la progression ;
+- `kb-app-demo-desktop` fournit une interface opérateur ;
+- `kb-pipeline-demo-scenarios` construit et exécute les scénarios réutilisables de démonstration et de validation, notamment sur Devnet.
+
+## Passage d’un scénario validé vers le pipeline
+
+`kb-pipeline-demo-scenarios` n’est pas la destination finale d’une logique réutilisable en production. Son rôle est de composer des APIs publiques existantes, préparer les fixtures, imposer les garde-fous opérateur et démontrer un parcours complet sur un réseau de validation.
+
+Lorsqu’un composant d’un scénario est validé et qu’il est générique, déterministe et utilisable indépendamment de la démonstration, il doit résider dans la couche appropriée :
+
+- `kb-lib` pour le décodage, la matérialisation, la construction d’instructions, les préflights et les politiques de sécurité ;
+- `kb-onchain-transport` pour les opérations réseau génériques ;
+- `kb-store` pour les contrats de persistance ;
+- `kb-pipeline` pour l’orchestration réutilisable, y compris sur Mainnet lorsque le profil, la politique et l’appelant l’autorisent.
+
+La crate de scénarios conserve :
+
+- les fixtures et valeurs de démonstration ;
+- la préparation Devnet ;
+- les confirmations opérateur propres aux campagnes de validation ;
+- les enchaînements de bout en bout destinés à prouver le comportement ;
+- les rapports de validation et contrôles postérieurs au scénario.
+
+Une validation Devnet ne provoque pas automatiquement une promotion vers Mainnet. Le composant promu doit également être indépendant du cluster, couvert par des tests, borné, compatible avec les politiques de sécurité et ne pas contenir d’hypothèse propre aux fixtures Devnet.
+
+## Rôles d’endpoints
+
+Un endpoint n’est pas supposé supporter toutes les opérations. La configuration attribue des rôles HTTP ou WebSocket, puis les pools sélectionnent une cible compatible.
+
+Avant une campagne :
+
+1. résoudre le profil ;
+2. vérifier la présence du rôle requis ;
+3. vérifier les limites du fournisseur ;
+4. fixer des bornes de pagination, concurrence et retry ;
+5. préparer l’observateur et l’annulation coopérative.
+
+## Backfill HTTP
+
+Le backfill parcourt les signatures, charge les transactions et les adapte vers le contrat canonique avant stockage.
+
+```rust
+let summary = match kb_pipeline::execute_http_backfill(
+    request,
+    observer,
+).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+println!("completed={}", summary.completed);
+```
+
+La frontière de reprise ne progresse qu’au travers des résultats contigus terminés. Une annulation ne doit pas sauter les candidats inachevés.
+
+## WebSocket
+
+La session WebSocket appartient au processus applicatif et non à la fenêtre qui l’affiche. Pour `demo_ws` :
+
+- fermer la fenêtre ne ferme pas une session active ;
+- rouvrir la fenêtre relit l’état courant ;
+- la déconnexion résulte d’une commande explicite, de la fermeture de l’application ou d’un timeout prévu ;
+- les abonnements et notifications restent bornés.
+
+## Adaptation canonique
+
+Les réponses fournisseur sont converties avant le pipeline. Les différences legacy/v0, ALT, CPI, erreurs de transaction et encodages doivent rester explicites.
+
+## Erreurs
+
+Distinguer :
+
+- transport indisponible ;
+- erreur JSON-RPC distante ;
+- réponse invalide ;
+- adaptation canonique impossible ;
+- erreur de stockage ;
+- annulation opérateur.
+
+## Tests de référence
+
+- pools et rôles d’endpoints ;
+- fixtures `getTransaction` legacy et v0 ;
+- pagination et reprise contiguë du backfill ;
+- cycles de connexion, abonnement et déconnexion WebSocket ;
+- maintien et restauration de l’état desktop.
+
+## Références
+
+- `kb-onchain-transport/USAGE.md` ;
+- `kb-pipeline/USAGE.md` ;
+- `kb-app-demo-desktop/USAGE.md`.