0.4.7-pre.001

docs/rules/RULES_SPECIFIC_KHADHROONY.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_SPECIFIC_KHADHROONY.md -->
-<!-- version: 5 -->
+<!-- version: 7 -->
 
 # Règles spécifiques à `khadhroony-bot3`
 
@@ -33,16 +33,53 @@ Toute divergence avec une règle générale doit être explicitement documentée
 
 ## Règles d'architecture
 
+### Couverture des décodeurs
+
 - Les décodeurs ne dépendent pas de PostgreSQL, SQLite, RPC, Tauri, wallet, stratégie ou matérialisateurs.
-- Les matérialisateurs ne dépendent pas du RPC, du wallet, de Tauri ou des décodeurs spécifiques.
-- Pour chaque programme Solana, quelle que soit sa famille, un décodeur doit couvrir maximalement tout wire officiellement identifiable de sa surface, qu'il soit historique, courant, récent, expérimental ou publié avant son déploiement généralisé. Ces statuts doivent rester explicites et ne constituent pas un motif pour supprimer le décodage.
+- Pour chaque programme Solana, quelle que soit sa famille, le décodeur doit couvrir maximalement tout wire officiellement identifiable : historique, courant, déprécié, expérimental, en développement ou publié avant son déploiement généralisé.
+- Le statut historique, déprécié, expérimental, en développement ou non encore déployé partout ne constitue jamais à lui seul un motif pour omettre un discriminant, un layout de compte ou une variante de wire officiellement documentée.
+- Lorsqu'un wire officiel est identifiable mais pas encore interprétable complètement, le décodeur doit produire une classification bornée et explicite, conserver les preuves disponibles et refuser toute interprétation inventée.
+- Les discriminants, layouts et variantes inconnus doivent échouer de manière bornée et diagnostiquée ; ils ne doivent pas être assimilés silencieusement à une variante connue.
 - Une observation lisible issue d'une transaction échouée peut conserver une intention non commitée ; elle ne doit jamais être présentée comme une mutation réussie.
-- Pour chaque programme Solana, les matérialisateurs doivent projeter maximalement tous les faits métier stables et prouvés par le décodage, y compris les états historiques, obsolètes, dépréciés ou seulement rencontrables pendant un backfill. Le statut historique interdit l'exécution, mais ne constitue jamais à lui seul un motif de non-matérialisation.
+- La matrice contractuelle et les tests doivent distinguer explicitement les variantes courantes, historiques, dépréciées, expérimentales, en développement et inconnues.
+
+### Couverture des matérialisateurs
+
+- Les matérialisateurs ne dépendent pas du RPC, du wallet, de Tauri ou des décodeurs spécifiques.
+- Pour chaque programme Solana, les matérialisateurs doivent projeter maximalement tous les faits métier stables et prouvés par les sorties normalisées du décodage, y compris les états historiques, obsolètes, dépréciés, expérimentaux ou seulement rencontrables pendant un backfill.
+- Une instruction ou un compte decode-only peut et doit produire une matérialisation lorsque son observation prouve un fait stable relevant d'un propriétaire métier identifié.
+- Le statut historique interdit éventuellement l'exécution, mais ne constitue jamais à lui seul un motif de non-matérialisation.
 - Toute projection historique doit conserver explicitement son lifecycle, sa version de layout, sa provenance, son slot ou ordre d'observation lorsqu'ils sont connus, et ne doit jamais écraser silencieusement un état actif plus récent.
 - Une même réalité métier doit avoir une seule projection canonique. Les snapshots de comptes sont la source autoritative de l'état final lorsqu'ils sont disponibles ; les instructions et événements corrélés restent des observations de mutation et ne doivent pas produire un doublon concurrent du même état.
 - Les matérialisateurs doivent refuser les transactions non commitées pour les mutations d'état, tout en pouvant conserver séparément une intention non commitée lorsque le modèle métier le prévoit explicitement.
 - Toute absence volontaire de projection doit être documentée avec une justification technique précise. Un matérialisateur ne doit inventer ni état final, ni montant, ni autorité, ni frais, ni agrégation que l'observation ne prouve pas.
-- Pour chaque programme Solana, les exécuteurs doivent couvrir maximalement les opérations officiellement appelables et les opérations expérimentales publiées lorsque leurs contrats exacts et garde-fous sont prouvés. Les opérations historiques, dépréciées ou obsolètes doivent rester décodables et matérialisables, mais ne doivent jamais être exposées à l'exécution ; cette exclusion doit être explicite dans la matrice et le README.
+
+### Couverture des exécuteurs
+
+- Pour chaque programme Solana, les exécuteurs doivent couvrir maximalement toutes les opérations officiellement constructibles ou appelables qui ne sont ni obsolètes ni remplacées par une variante canonique imposée.
+- Cette obligation couvre les opérations courantes, récentes, expérimentales, en développement et publiées avant leur déploiement généralisé dès lors que leur wire, leurs comptes, leurs signers et leurs garde-fous exacts sont prouvés.
+- Une opération ne peut pas être exclue parce qu'elle n'a pas été arbitrairement retenue pour une version. Chaque opération officiellement connue doit recevoir un statut déterministe : `Supported`, `Unsupported(reason)`, `DecodeOnlyHistorical`, `DecodeOnlyObsolete`, `DecodeOnlyReplaced` ou frontière de programme explicitement documentée.
+- `Unsupported(reason)` est réservé à une impossibilité technique ou contractuelle précise et vérifiable. Il ne doit jamais masquer un travail non réalisé, un choix de priorité ou une absence d'inventaire.
+- Les opérations historiques, dépréciées, obsolètes ou remplacées restent décodables et matérialisables lorsqu'elles prouvent des faits, mais ne doivent pas être exposées à l'exécution lorsque la variante n'est plus légitime à construire.
+- Le déploiement sur un cluster, la disponibilité d'une fixture, la simulation réseau et l'autorisation d'envoi sont des niveaux de preuve distincts ; leur absence ne supprime pas un builder universel officiellement constructible.
+- Toute exclusion d'exécution doit être explicite dans la matrice contractuelle, les capacités runtime et la documentation publique de la surface.
+
+### Frontière des pipelines
+
+- `kb-pipeline` est le pipeline généraliste, réutilisable et indépendant d'un environnement de démonstration. Ses contrats doivent pouvoir être appelés depuis une application, un service, un worker, un CLI, des tests ou une autre orchestration, sur tout cluster compatible autorisé par la configuration.
+- `kb-pipeline` possède l'orchestration générique du backfill, de l'extraction Core, du replay, des corrélations stateful, du préflight, de la préparation, de la simulation, de la soumission autorisée, de la confirmation, de la postvalidation et de la matérialisation idempotente.
+- `kb-pipeline` ne doit contenir ni wallet, mint, compte, airdrop, autorité, adresse, séquence ou hypothèse codée en dur pour une démonstration Devnet ou Testnet.
+- `kb-pipeline-demo-scenarios` contient les fixtures, aides de campagne et tests automatisés spécifiques aux réseaux de test, actuellement Devnet ou Testnet.
+- Les scénarios UI Devnet/Testnet restent dans `kb-app-demo-desktop`. Ils ne doivent pas être déplacés vers `kb-pipeline-demo-scenarios` au seul motif qu'un scénario automatisé équivalent est souhaité.
+- Lorsqu'un parcours UI doit être couvert automatiquement, `kb-pipeline-demo-scenarios` ajoute en parallèle un test ou une campagne équivalente fondée sur les mêmes APIs généralistes. Cette couverture parallèle complète la démonstration desktop ; elle ne la remplace pas.
+- `kb-pipeline-demo-scenarios` peut préparer des wallets temporaires, demander des airdrops, créer des actifs de test, enchaîner plusieurs appels du pipeline généraliste et produire des preuves de validation réseau.
+- Le binaire `kb-pipeline-demo-scenarios-cli` reste un outil ciblé tant que son contrat public ne prévoit pas explicitement d'autres commandes. Son usage historique de préparation des fixtures SPL Token-2022 ne doit pas être généralisé implicitement à tous les scénarios.
+- `kb-pipeline-demo-scenarios` dépend de `kb-pipeline` ; la dépendance inverse est interdite.
+- Une primitive ou orchestration réellement réutilisable hors d'un scénario UI ou d'une campagne de validation précise doit être placée dans `kb-pipeline` ou la crate métier propriétaire. Les adaptateurs, états et séquences propres aux démonstrations UI restent dans le desktop.
+- Les scénarios Mainnet sans écriture, par exemple les validations de backfill ou de replay, relèvent du pipeline généraliste et de documents de validation dédiés ; ils ne justifient pas l'introduction d'une logique Mainnet spécifique dans la crate de scénarios Devnet/Testnet.
+
+### Autres frontières
+
 - `kb-store` possède les contrats de persistance neutres et les adaptateurs de base de données.
 - PostgreSQL est l'adaptateur de production de `kb-store`.
 - Un futur adaptateur SQLite doit rester interne à `kb-store` et limité aux tests, imports et corpus locaux.
@@ -182,9 +219,7 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
 - Les garde-fous communs doivent être placés dans les modules de sécurité partagés de `kb-lib`.
 - Aucun exécuteur ne doit envoyer de transaction sans simulation et validation explicite.
 - Les surfaces non classifiées ne doivent pas avoir de crate exécuteur.
-- Pour chaque programme Solana et contrairement aux décodeurs, les exécuteurs ne construisent pas les opérations obsolètes ou purement historiques. Ils couvrent uniquement les opérations courantes et expérimentales officiellement constructibles, avec un statut exact `Supported` ou `Unsupported(reason)`.
-- Le statut expérimental, récent ou non encore déployé partout n'interdit pas un builder universel lorsqu'un wire officiel exact existe. Le déploiement, la simulation et l'autorisation d'envoi restent trois décisions séparées ; la bibliothèque ne doit pas imposer artificiellement un cluster.
-
+- La section « Couverture des exécuteurs » ci-dessus est normative pour chaque surface : la migration fonctionnelle doit fermer l’inventaire complet et ne peut pas sélectionner arbitrairement un sous-ensemble d’opérations officiellement constructibles.
 
 - Les champs JSON exposés à TypeScript ne doivent pas utiliser directement `serde_json::Value` avec `TS-rs`; utiliser une chaîne JSON sérialisée (`std::string::String`) ou un type Rust typé exportable.
 - Les APIs qui gardent des payloads dynamiques doivent fournir des helpers explicites basés sur `serde_json::to_string` et `serde_json::to_string_pretty`.