v0.1.0-pre.073

docs/README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/README.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Documentation active de Khadhroony Bot3
 
@@ -7,7 +7,7 @@
 
 Ce répertoire contient la documentation active, normative ou opérationnelle de `khadhroony-bot3`.
 
-La documentation historique de `khadhroony-bot2` est conservée sous `olddocs/archivekbot2/`. Elle ne doit être ni déplacée vers `docs/`, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes.
+La documentation historique de `khadhroony-bot2` est conservée sous `olddocs/archivekbot2/`. La documentation historique de `khadhroony-bobobot` est conservée sous `olddocs/archivekbobobot/`. Elle ne doit être ni déplacée vers `docs/`, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes.
 
 ## 2. Architecture
 
@@ -94,3 +94,12 @@ Le premier lot documenté comprend :
 ## Audits
 
 - [Audit d’alignement des TODO par crate](audits/CRATE_TODO_VERSION_ALIGNMENT_AUDIT.md)
+
+## Guides
+
+- [Configuration](guides/CONFIGURATION.md)
+- [Logging et tracing](guides/LOGGING.md)
+- [RPC, backfill et WebSocket](guides/RPC_BACKFILL_AND_WEBSOCKET.md)
+- [Extraction Core, replay et matérialisation](guides/REPLAY_CORE_EXTRACTION_AND_MATERIALIZATION.md)
+- [PostgreSQL et stockage](guides/POSTGRES_STORAGE.md)
+- [Validation Devnet](guides/DEVNET_VALIDATION.md)

docs/guides/CONFIGURATION.md

@@ -0,0 +1,79 @@
+<!-- file: docs/guides/CONFIGURATION.md -->
+<!-- version: 1 -->
+
+# Guide de configuration
+
+## Objectif
+
+Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste `kb-config/USAGE.md`.
+
+## Fichiers actifs
+
+- `config/example.config.json` : exemple utilisateur complet ;
+- `config/schema.config.json` : contrat JSON formel ;
+- `.env` et variantes locales : valeurs d’environnement non versionnées ;
+- `.env.example` : noms de variables attendues sans secrets.
+
+Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.
+
+## Séquence de chargement
+
+1. charger les fichiers d’environnement autorisés avec `load_workspace_environment` ;
+2. lire le fichier JSON ;
+3. résoudre les placeholders `${NAME}` ou `${NAME:-fallback}` ;
+4. parser avec `load_config_from_str` ou `load_config_from_path` ;
+5. valider le schéma et les invariants typés ;
+6. sélectionner le profil actif avec `active_profile`.
+
+## Exemple opérateur
+
+```rust
+let environment = match kb_config::load_workspace_environment(
+    std::path::Path::new("."),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let config = match kb_config::load_config_from_path(
+    std::path::Path::new("config/example.config.json"),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let profile = match kb_config::active_profile(&config) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+println!("loaded environment files={}", environment.loaded_files.len());
+println!("active profile={}", profile.name);
+```
+
+## Invariants
+
+- aucun secret ne doit être ajouté à l’exemple versionné ;
+- les placeholders non résolus doivent provoquer un diagnostic explicite ;
+- le schéma embarqué et `config/schema.config.json` doivent rester identiques ;
+- une sérialisation publique doit être précédée d’une validation ;
+- les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
+
+## Diagnostic
+
+Pour isoler une erreur :
+
+1. afficher la liste des fichiers d’environnement chargés ;
+2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
+3. valider le schéma ;
+4. valider le modèle typé ;
+5. vérifier le profil actif ;
+6. vérifier les rôles HTTP, WebSocket, stockage et logging.
+
+## Références
+
+- `kb-config/README.md` ;
+- `kb-config/USAGE.md` ;
+- `kb-config/TODO.md` ;
+- `config/README.md` ;
+- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.

docs/guides/DEVNET_VALIDATION.md

@@ -0,0 +1,65 @@
+<!-- file: docs/guides/DEVNET_VALIDATION.md -->
+<!-- version: 1 -->
+
+# Guide de validation Devnet
+
+## Objectif
+
+Une validation Devnet démontre un parcours réel. Elle ne doit pas être confondue avec un test unitaire, une simulation ou une validation synthétique.
+
+## Niveaux de preuve
+
+1. test unitaire ou contractuel ;
+2. validation synthétique sur fixtures ;
+3. simulation RPC exacte ;
+4. confirmation opérateur ;
+5. soumission ;
+6. confirmation finalisée ;
+7. insertion canonique ;
+8. extraction Core ;
+9. replay et matérialisation ;
+10. idempotence et vérification CLI finale.
+
+Le rapport doit indiquer précisément les niveaux réellement exécutés.
+
+## Prérequis
+
+- profil Devnet explicite ;
+- endpoint compatible ;
+- wallet de test et fonds suffisants ;
+- paramètres bornés ;
+- scénario réutilisable hors desktop lorsque possible ;
+- confirmation opérateur avant tout envoi.
+
+## Commandes
+
+Les scénarios peuvent être déclenchés depuis `kb-pipeline-demo-scenarios` ou le desktop. La validation frontend se fait uniquement avec :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+## Rapport
+
+Conserver :
+
+- scénario et version ;
+- cluster ;
+- signatures publiques ;
+- opérations exécutées ;
+- résultats de simulation et confirmation ;
+- vérifications de stockage, replay et matérialisation ;
+- limites et étapes non exécutées.
+
+Ne pas conserver de keypair, secret ou preuve privée dans les deltas.
+
+## ElGamal
+
+Le registre ElGamal ne doit pas être déclaré validé sur Devnet ou Mainnet sans confirmation de déploiement, preuve `PubkeyValidity`, compte `Proof Context State` valide et scénario complet.
+
+## Références
+
+- `docs/PRE_062_DEVNET_VALIDATION_REPORT.md` ;
+- `docs/DEVNET_EXECUTION_GUIDE.md` ;
+- `kb-pipeline-demo-scenarios/USAGE.md` ;
+- `kb-app-demo-desktop/USAGE.md`.

docs/guides/LOGGING.md

@@ -0,0 +1,74 @@
+<!-- file: docs/guides/LOGGING.md -->
+<!-- version: 1 -->
+
+# Guide de logging et tracing
+
+## Objectif
+
+`kb-logging` initialise les routes de tracing définies par la configuration et conserve les guards nécessaires à leur durée de vie.
+
+## Flux de démarrage
+
+1. charger et valider la configuration avec `kb-config` ;
+2. construire `LoggingConfig` ;
+3. appeler `kb_logging::init_logging` une seule fois ;
+4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
+5. émettre les événements avec des targets canoniques.
+
+```rust
+let guard = match kb_logging::init_logging(&config.logging) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+tracing::info!(
+    target: kb_logging::tracing_target(),
+    routes = guard.route_count(),
+    "logging initialized"
+);
+```
+
+## Routes
+
+Une route définit notamment :
+
+- sink console ou fichier ;
+- niveau minimal ;
+- format humain, compact, pretty ou JSON ;
+- rotation ;
+- targets exactes ou préfixes ;
+- activation ANSI.
+
+Les routes fichier ne doivent jamais écrire de secrets ou de keypairs.
+
+## Nomenclature des targets
+
+Les targets suivent les conventions du workspace, par exemple :
+
+```text
+kb-pipeline.backfill
+kb-pipeline.decode-replay
+kb-onchain-transport.http
+kb-lib.executor.spl.token-2022
+```
+
+Une nouvelle target doit être ajoutée selon `docs/OPERATION_NAMING_CONVENTION.md` et les règles Khadhroony.
+
+## Frontend desktop
+
+Les fenêtres Tauri utilisent la permission tracing prévue par leurs capabilities. Les logs frontend sont adaptés vers le backend sans permettre au frontend de choisir arbitrairement une target sensible.
+
+## Diagnostic
+
+- vérifier les routes actives via `route_names()` ;
+- confirmer le niveau global et les filtres spécifiques ;
+- vérifier le chemin et les permissions d’une route fichier ;
+- vérifier que le guard n’est pas détruit prématurément ;
+- ne pas réinitialiser le subscriber global pendant l’exécution.
+
+## Références
+
+- `kb-logging/README.md` ;
+- `kb-logging/USAGE.md` ;
+- `kb-config/USAGE.md` ;
+- `docs/architecture/ARCHITECTURE.md`.

docs/guides/POSTGRES_STORAGE.md

@@ -0,0 +1,66 @@
+<!-- file: docs/guides/POSTGRES_STORAGE.md -->
+<!-- version: 1 -->
+
+# Guide PostgreSQL et contrats de stockage
+
+## Objectif
+
+`kb-store` consolide les contrats de stockage Core, raw, decode et PostgreSQL de bot2 dans une crate unique.
+
+## Connexion
+
+```rust
+let options = match kb_store::PostgresStoreOptions::new(
+    database_url,
+    10,
+    10_000,
+    true,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let store = match kb_store::PostgresStore::connect(options).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+Toujours utiliser `masked_dsn()` dans les diagnostics.
+
+## Domaines
+
+- raw : acquisitions et observations ;
+- Core : transactions, instructions, comptes et contexte normalisés ;
+- decode : ledger, observations décodées et matérialisations ;
+- replay : candidats et résumés bornés.
+
+## Migrations
+
+Les migrations sont idempotentes et ordonnées. Une nouvelle migration ne doit pas modifier rétroactivement une migration déjà publiée.
+
+## Repositories
+
+Les traits publics séparent le contrat de l’implémentation PostgreSQL. Les opérations de lecture utilisent des filtres et paginations bornés.
+
+## Diagnostics
+
+- health snapshot ;
+- migration snapshot ;
+- backend diagnostics ;
+- diagnostics des tables raw, Core et decode ;
+- validation des noms de tables.
+
+## Invariants
+
+- aucune donnée canonique ne doit être dupliquée sans justification ;
+- les écritures rejouables doivent être idempotentes ;
+- la progression de campagne doit rester cohérente avec les lignes effectivement traitées ;
+- les requêtes dynamiques n’acceptent que des identifiants validés ;
+- les erreurs PostgreSQL restent distinctes des erreurs de contrat.
+
+## Références
+
+- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
+- `kb-store/USAGE.md` ;
+- `kb-store/README.md`.

docs/guides/REPLAY_CORE_EXTRACTION_AND_MATERIALIZATION.md

@@ -0,0 +1,77 @@
+<!-- file: docs/guides/REPLAY_CORE_EXTRACTION_AND_MATERIALIZATION.md -->
+<!-- version: 1 -->
+
+# Guide extraction Core, replay et matérialisation
+
+## Chaîne de traitement
+
+```text
+acquisition canonique
+        ↓
+extraction Core
+        ↓
+entrées de replay instruction-level
+        ↓
+reconnaissance et décodage
+        ↓
+observations et diagnostics
+        ↓
+matérialisation optionnelle
+```
+
+## Extraction Core
+
+L’extraction transforme une transaction canonique persistée en entités Core normalisées. Elle doit conserver les index, comptes, Program IDs, succès ou échec de transaction et contexte nécessaire aux instructions internes.
+
+```rust
+let summary = match kb_pipeline::execute_core_extraction(
+    request,
+    observer,
+).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+## Decode replay
+
+Le replay sélectionne des instructions Core, applique une politique de dispatch et invoque les décodeurs compatibles.
+
+- une reconnaissance incompatible ne produit pas d’observation ;
+- une transaction échouée peut produire une intention non committée ;
+- les diagnostics doivent rester distincts des observations ;
+- la même entrée et la même version de pipeline doivent produire un résultat déterministe.
+
+## Matérialisation
+
+La matérialisation est optionnelle et idempotente. Elle transforme les événements décodés en projections métier sans inventer un état confirmé.
+
+Une tâche de matérialisation doit préciser :
+
+- la provenance de l’événement ;
+- le statut committé ou non committé ;
+- les clés d’idempotence ;
+- les invariants de mise à jour ;
+- le traitement des événements obsolètes ou contradictoires.
+
+## Reprise
+
+La progression persistée ne doit avancer qu’après clôture cohérente du candidat. Les erreurs partielles restent rejouables.
+
+## Tests de référence
+
+- extraction Core legacy et v0 ;
+- instructions outer et inner ;
+- transactions échouées ;
+- dispatch vers le décodeur exact ;
+- matérialisation optionnelle ;
+- replay forcé et idempotence ;
+- corrélations stateful Token-2022.
+
+## Références
+
+- `docs/architecture/PIPELINE_ARCHITECTURE.md` ;
+- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
+- `kb-pipeline/USAGE.md` ;
+- `kb-lib/USAGE.md` ;
+- `kb-store/USAGE.md`.

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`.