v0.4.8-pre.010

docs/audits/V0_4_8_PRE_010_METADATA_SOLANA_PROGRAM_DESKTOP_INTEGRATION_AUDIT.md

@@ -0,0 +1,129 @@
+<!-- file: docs/audits/V0_4_8_PRE_010_METADATA_SOLANA_PROGRAM_DESKTOP_INTEGRATION_AUDIT.md -->
+<!-- version: 4 -->
+
+# Audit `0.4.8-pre.010` — structure Metadata et exécution Devnet
+
+## Périmètre
+
+La prerelease raccorde `demo_execution_metadata` à la campagne Devnet Solana Program Metadata réutilisable. Le correctif `pre.010-fix-001` traite trois écarts révélés pendant la validation réelle :
+
+- la structure desktop ne distinguait pas explicitement les contrats communs, Metaplex Token Metadata et Solana Program Metadata ;
+- le pipeline stateful demandait une lecture complète de `10 MiB`, alors que l’adaptateur `getAccountInfo` borne une réponse complète à `65536` octets ;
+- l’endpoint public Devnet a renvoyé `429 Too Many Requests` pendant une seconde campagne rapprochée.
+
+## Structure desktop normalisée
+
+La surface Rust est séparée en trois modules :
+
+```text
+kb-app-demo-desktop/src/demo_execution_metadata.rs
+kb-app-demo-desktop/src/demo_execution_metadata_metaplex_token_metadata.rs
+kb-app-demo-desktop/src/demo_execution_metadata_solana_program.rs
+```
+
+`demo_execution_metadata.rs` contient uniquement les contrats partagés du panneau :
+
+- options de profils Devnet ;
+- payload de progression Metadata ;
+- observer Metadata commun aux workflows Metaplex et Solana Program Metadata.
+
+Le module Metaplex contient les contrats, préparateurs et commandes propres à `metadata.metaplex_token_metadata`. Le module Solana Program Metadata contient l’inventaire et l’adaptation de la campagne `metadata.solana_program_metadata`.
+
+Les types et commandes Tauri Metaplex portent désormais explicitement le segment `metaplex_token_metadata`.
+
+## Progression et verrou d’exécution
+
+Le workflow Metaplex réutilisait auparavant `DemoExecutionSolanaCoreObserver`, ce qui ciblait la fenêtre `demo_execution_solana_core`. Les deux workflows Metadata utilisent désormais `DemoExecutionMetadataObserver`, qui émet exclusivement vers :
+
+```text
+window = demo_execution_metadata
+event  = demo-execution-metadata-progress
+```
+
+Le garde RAII partagé est déplacé dans `demo_devnet_common.rs` sous le nom `DemoExecutionRunGuard`. Son identité ne dépend plus de Solana Core alors qu’il protège également les exécutions SPL et Metadata.
+
+## Borne des lectures stateful
+
+Deux limites distinctes sont conservées :
+
+- `kb_lib::DC_METADATA_SPM_MAX_ACCOUNT_BYTES = 10 MiB` : capacité défensive du décodeur pour des octets déjà disponibles, notamment offline ou via un futur lecteur par tranches ;
+- `kb_onchain_transport::MAX_COMPLETE_ACCOUNT_DATA_BYTES = 65536` : maximum actuel d’une lecture complète via l’adaptateur d’exécution `getAccountInfo`.
+
+`kb_pipeline::MAX_SOLANA_PROGRAM_METADATA_STATEFUL_ACCOUNT_BYTES` est alignée sur la seconde limite. Une lecture complète ne peut donc plus être construite avec une valeur que le transport refusera avant l’appel RPC.
+
+## Résilience aux limites RPC
+
+`kb-onchain-transport` réessaie désormais les réponses suivantes :
+
+- statut HTTP `429` ;
+- erreur JSON-RPC de code `429`.
+
+Le retry est borné à quatre tentatives supplémentaires. Le délai :
+
+1. utilise `Retry-After` lorsqu’il contient un nombre de secondes ;
+2. utilise sinon `pause_after_rate_limit_ms` du rôle compatible ;
+3. applique un backoff exponentiel plafonné à `60000 ms`.
+
+Le même objet JSON-RPC est réutilisé. Pour `sendTransaction`, la transaction signée et sa signature restent donc identiques pendant les retries.
+
+## Validation attendue
+
+Après application du correctif :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test -p kb-onchain-transport
+cargo test -p kb-pipeline
+cargo test -p kb-app-demo-desktop
+```
+
+La campagne Devnet doit ensuite être relancée une seule fois. Les résultats attendus sont :
+
+- aucun rejet local sur `max_data_bytes` ;
+- retry visible et borné en cas de `429` ;
+- deux préfinancements confirmés ;
+- neuf opérations confirmées ;
+- snapshots stateful présents, sauf preuve d’absence après `Close`.
+
+## 8. Correctif de débit HTTP et cible de logging
+
+La campagne Devnet a montré que les limites de rôle existaient dans la configuration, mais n’étaient pas appliquées par le client HTTP générique utilisé par les RPC d’exécution. Le backfill disposait de son propre pacer ; cette protection ne couvrait pas les lectures stateful, simulations, soumissions et confirmations du desktop.
+
+Le client HTTP applique désormais avant chaque tentative :
+
+1. un token bucket partagé fondé sur `requests_per_second` et `burst_capacity` ;
+2. un sémaphore partagé fondé sur `max_concurrent_requests` ;
+3. le rôle exact retenu par `HttpEndpointPool` lorsque plusieurs rôles acceptent le même type de requête ;
+4. un cooldown partagé après une réponse HTTP ou JSON-RPC `429`.
+
+Le retry borné reste nécessaire : un endpoint public peut imposer un quota dynamique ou partagé avec d’autres processus, adresses IP ou utilisateurs. Un warning `retry_http_json_rpc_after_rate_limit` signifie que la seconde ligne de défense a été activée ; il ne signifie pas que la requête a été perdue.
+
+La fixture Solana Program Metadata réutilise en outre la cible racine `kb-pipeline-demo-scenarios`. La crate ne déclare donc plus deux constantes de tracing lorsqu’elle possède une cible racine canonique.
+
+## 9. Diagnostic Devnet du correctif suivant
+
+La campagne réelle postérieure à l’activation des limiteurs confirme que les réponses `429` sont récupérées : chaque warning observé est suivi du même `request_id` avec `retry_index = 1` et d’une réponse `200 OK`. Elles ralentissent la campagne mais ne constituent pas sa cause terminale.
+
+L’échec reproductible intervient sur `SetAuthority` après `Initialize` et `SetData` :
+
+```text
+InstructionError[0] = InvalidAccountData
+```
+
+La fixture initialisait un compte Metadata non canonique puis tentait de réaffirmer son autorité. Le processeur officiel refuse explicitement `SetAuthority` sur un compte Metadata dont le drapeau `canonical` est faux. La même opération est en revanche autorisée sur un Buffer non canonique dès lors qu’une nouvelle autorité non nulle est fournie.
+
+La campagne corrigée couvre donc toujours les neuf opérations, mais selon l’ordre suivant :
+
+```text
+Buffer:
+Allocate -> Extend -> Write -> SetAuthority -> Trim -> Close
+
+Metadata non canonique:
+Initialize -> SetData -> SetImmutable
+```
+
+Le profil public Devnet de l’exemple est également abaissé à `3 r/s` pour les lectures et `1 r/s` pour les transactions. Les anciens fichiers de configuration locaux doivent être ajustés manuellement.
+

docs/guides/CONFIGURATION.md

@@ -1,5 +1,5 @@
 <!-- file: docs/guides/CONFIGURATION.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Guide de configuration
 
@@ -59,6 +59,17 @@ println!("active profile={}", profile.name);
 - 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.
 
+## Quotas HTTP cumulés
+
+Les limites HTTP sont déclarées par rôle, mais les quotas d’un endpoint public s’appliquent généralement à l’endpoint ou à l’adresse IP entière. Pour un endpoint unique, il faut donc considérer au minimum :
+
+- la somme des `requests_per_second` de tous les rôles actifs ;
+- la somme des bursts pouvant partir dans la même fenêtre ;
+- la limite propre à une méthode RPC répétée ;
+- les autres processus utilisant la même IP ou le même fournisseur.
+
+Le profil public Devnet de l’exemple utilise `3 r/s` pour `http_queries` et `1 r/s` pour `http_transactions`. Un profil privé ou payant peut utiliser d’autres valeurs, mais elles doivent suivre le contrat réel du fournisseur.
+
 ## Diagnostic
 
 Pour isoler une erreur :

docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md

@@ -1,11 +1,11 @@
 <!-- file: docs/plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md -->
-<!-- version: 14 -->
+<!-- version: 17 -->
 
 # Plan `0.4.8` — Solana Program Metadata et complétude Token-2022
 
 ## 1. Statut et rôle
 
-Ce document est le livrable principal de `0.4.8-pre.001`, réconcilié après l’audit contractuel de `0.4.8-pre.002`, les modèles de `pre.003`, les décodeurs de comptes de `pre.004`, le décodeur d’instructions de `pre.005`, la matérialisation de `pre.006`, l’exécuteur de `pre.007`, l’orchestration généraliste de `pre.008` et les scénarios réutilisables de `pre.009`. Il constitue le plan vivant de la version et reste modifiable lorsque l’audit du code, des interfaces officielles, de l’IDL ou des validations Devnet impose un ajustement.
+Ce document est le livrable principal de `0.4.8-pre.001`, réconcilié après l’audit contractuel de `0.4.8-pre.002`, les modèles de `pre.003`, les décodeurs de comptes de `pre.004`, le décodeur d’instructions de `pre.005`, la matérialisation de `pre.006`, l’exécuteur de `pre.007`, l’orchestration généraliste de `pre.008`, les scénarios réutilisables de `pre.009` et leur intégration desktop de `pre.010`. Il constitue le plan vivant de la version et reste modifiable lorsque l’audit du code, des interfaces officielles, de l’IDL ou des validations Devnet impose un ajustement.
 
 Il doit être maintenu pendant chaque prerelease, puis archivé pendant la dernière prerelease après transfert des décisions durables vers le ROADMAP, les matrices, les guides, les rapports, les TODO et les changelogs concernés.
 
@@ -296,8 +296,8 @@ Travaux parallèles intégrés : les fonctions de matérialisation Metaplex exis
 
 - séparation stricte : `kb-pipeline` reste généraliste et inchangé, tandis que les fixtures et campagnes réseau appartiennent à `kb-pipeline-demo-scenarios` ;
 - deux parcours ordonnés couvrent exactement les neuf opérations stables ;
-- parcours Buffer : `Allocate → Extend → Write → Trim → Close` ;
-- parcours Metadata : `Initialize → SetData → SetAuthority → SetImmutable` ;
+- parcours Buffer : `Allocate → Extend → Write → SetAuthority → Trim → Close` ;
+- parcours Metadata non canonique : `Initialize → SetData → SetImmutable` ;
 - création de deux PDA non canoniques uniques et préfinancés avec le wallet persistant du profil Devnet ;
 - calcul RPC du rent pour les tailles initiales et finales ;
 - runner unitaire simulation-first avec `ExSafetyChecker`, soumission contrôlée, confirmation, lectures avant/après et postconditions ;
@@ -306,15 +306,21 @@ Travaux parallèles intégrés : les fonctions de matérialisation Metaplex exis
 - matrice Devnet conservative à `not_run` avant exécution réelle ;
 - aucune modification de `demo_execution_metadata` dans cette prerelease.
 
-### `0.4.8-pre.010` — intégration desktop et campagne Devnet Solana Program Metadata
+### `0.4.8-pre.010` — intégration desktop et campagne Devnet Solana Program Metadata — terminé côté delta
 
-- adapter le sous-panneau `ProgM6…` de `demo_execution_metadata` pour consommer exclusivement les runners de `kb-pipeline-demo-scenarios` ;
-- préparer la fixture, présenter les deux parcours et exiger la confirmation explicite avant les transferts ou mutations ;
-- exécuter les neuf opérations sur Devnet, avec signatures, simulations, confirmations et postconditions ;
-- hydrater les signatures confirmées, lancer Core extraction, decode replay et matérialisation canonique ;
-- mettre à jour la matrice de validation sans convertir une simulation ou une construction synthétique en preuve confirmée ;
-- confirmer particulièrement `Trim` et `Extend`, absentes de l’échantillon mainnet ;
-- conserver des résultats JSON dans le JsonViewer commun.
+- sous-panneau `ProgM6…` séparé dans `demo_execution_metadata`, consommant exclusivement les runners de `kb-pipeline-demo-scenarios` ;
+- profil Devnet synchronisé avec la section Metaplex et préparation PostgreSQL réutilisée ;
+- présentation des deux parcours Buffer et Metadata, avec leurs neuf étapes ordonnées ;
+- confirmation explicite unique avant les deux préfinancements et les neuf mutations ;
+- exécution de la campagne complète, avec simulations, signatures, confirmations, lectures avant/après, postconditions et snapshots matérialisés ;
+- progression réseau dirigée vers la fenêtre Metadata ;
+- résultats intégralement JSON affichés avec le JsonViewer commun ;
+- aucun doublon d’orchestration dans le desktop et aucune modification fonctionnelle de `kb-pipeline-demo-scenarios` ;
+- séparation physique entre le module commun Metadata, Metaplex Token Metadata et Solana Program Metadata ;
+- borne des lectures stateful complètes alignée sur les `65536` octets acceptés par le transport, sans réduire la capacité offline du décodeur ;
+- retry borné des réponses HTTP ou JSON-RPC `429` afin que la campagne puisse respecter les limites de l’endpoint public Devnet ;
+- la validation historique `backfill → extraction → replay → matérialisation` reste la preuve de décodage de `pre.008` ; la campagne Devnet fournit séparément les preuves d’exécution et les snapshots stateful confirmés ;
+- la matrice Devnet reste `not_run` jusqu’à l’exécution opérateur réelle, particulièrement pour `Trim` et `Extend`.
 
 ### `0.4.8-pre.011` — complétude Token-2022 Token Metadata