0.1.0-pre.004

RULES.md

@@ -1,9 +1,9 @@
 <!-- file: RULES.md -->
-<!-- version: 16 -->
+<!-- version: 17 -->
 
-# Règles spécifiques à `khadhroony-bot2`
+# Règles spécifiques à `khadhroony-bot3`
 
-Ce fichier contient uniquement les règles propres au projet et au workspace `khadhroony-bot2`.
+Ce fichier contient uniquement les règles propres au projet et au workspace `khadhroony-bot3`.
 
 Les règles Rust générales et réutilisables dans tous les projets sont définies dans [`RUST_RULES.md`](RUST_RULES.md). Les deux fichiers sont normatifs et cumulatifs. En cas de conflit, la règle la plus stricte s'applique ; une règle spécifique au workspace ne peut jamais assouplir une règle générale sans exception explicitement documentée.
 
@@ -14,10 +14,9 @@ Toute livraison doit exécuter l'audit `python3 scripts/audit_rust_workspace_rul
 - Tous les noms de fichiers et de répertoires doivent être écrits en anglais.
 - Les noms de fichiers et de répertoires ne doivent contenir aucun accent, espace ou caractère spécial inutile.
 - Les noms internes doivent utiliser le format `snake_case` lorsque c'est applicable.
-- Les crates Rust utilisent le préfixe `kb_`.
-- Les crates de décodeur utilisent le format `kb_decoder_<protocol>_<surface>`.
-- Les crates de matérialisation utilisent le format `kb_materializer_<family>`.
-- Le crate de journalisation s'appelle `kb_logging`.
+- Les packages Rust utilisent le préfixe `kb-` ; leur identifiant Rust correspondant utilise automatiquement `kb_`.
+- Les décodeurs, matérialisateurs et exécuteurs sont des modules de `kb-lib`, pas des crates séparées.
+- Le crate de journalisation s'appelle `kb-logging`.
 
 ## Règles Tauri et TypeScript
 
@@ -40,13 +39,13 @@ Toute livraison doit exécuter l'audit `python3 scripts/audit_rust_workspace_rul
 - 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.
-- Les stores exposent leurs comportements via les traits de `kb_store_core`.
-- `kb_store_pg` est le store de production.
-- `kb_store_sqlite` sert aux tests, imports et corpus locaux.
-- `kb_wallet` reste isolé du reste du système.
+- `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.
+- `kb-wallet` reste isolé du reste du système.
 - Les transactions raw sont immuables et restent la source d'audit.
 - Les replays doivent être ciblés par module, version, programme, surface, discriminator, slot ou signatures.
-- La documentation du projet ne doit pas référencer le nom de l'ancien workspace.
+- La documentation active du projet ne doit pas présenter l'ancien workspace comme architecture courante. Les documents de migration et copies de référence peuvent le nommer explicitement.
 
 ## Règles de documentation projet
 
@@ -81,25 +80,25 @@ Les nouvelles surfaces de programmes doivent utiliser un nom canonique basé sur
 <function_code>_<family_code>_<identifier_code>[_vN]
 ```
 
-Les crates de décodage doivent utiliser :
+Les modules de décodage doivent utiliser :
 
 ```text
-kb_decoder_<function_code>_<family_code>_<identifier_code>[_vN]
+kb_lib::decoder::<function_code>::<family_code>_<identifier_code>[_vN]
 ```
 
 Exemples :
 
-- `kb_decoder_amm_raydium_cpmm` ;
-- `kb_decoder_clmm_raydium` ;
-- `kb_decoder_dlmm_meteora` ;
-- `kb_decoder_router_jupiter_aggregator_v6` ;
-- `kb_decoder_orderbook_openbook_v2` ;
-- `kb_decoder_metadata_metaplex_token_metadata` ;
-- `kb_decoder_nft_metaplex_bubblegum`.
+- `kb_lib::decoder::amm::raydium_cpmm` ;
+- `kb_lib::decoder::clmm::raydium` ;
+- `kb_lib::decoder::dlmm::meteora` ;
+- `kb_lib::decoder::router::jupiter_aggregator_v6` ;
+- `kb_lib::decoder::orderbook::openbook_v2` ;
+- `kb_lib::decoder::metadata::metaplex_token_metadata` ;
+- `kb_lib::decoder::nft::metaplex_bubblegum`.
 
-Les noms historiques ou issus d'IDL doivent être conservés dans le registre, mais ne doivent pas créer de nouvelles crates si une crate canonique existe déjà.
+Les noms historiques ou issus d'IDL doivent être conservés dans le registre, mais ne doivent pas créer de nouveau module si un module canonique existe déjà.
 
-Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédiée et sans `cargo build` validé.
+Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédiée et sans validation Cargo.
 
 ## Règles de nommage des surfaces Solana
 
@@ -118,13 +117,13 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 
 ## Index court de programme
 
-- Les noms de crates ne doivent pas commencer par un index hexadécimal.
+- Les noms de modules ne doivent pas commencer par un index hexadécimal.
 - Un champ `registry_code` optionnel peut être ajouté au registre pour l'UI, PostgreSQL ou les matrices.
 - Le nom canonique reste la source principale : fonction + famille + identifiant + version.
 
 ## Comptes non exécutables
 
-- Une adresse de compte, de pool, de PDA ou de vault ne doit pas générer une crate de décodeur.
+- Une adresse de compte, de pool, de PDA ou de vault ne doit pas générer un module de décodeur.
 - Le vrai `program_id` propriétaire doit être prouvé avant création d'une surface canonique.
 
 ## Constantes Rust
@@ -136,13 +135,15 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 
 ## Règles de tracing
 
-- Une crate est opérationnelle lorsqu’elle effectue des I/O, orchestre un pipeline, décode, matérialise, exécute, applique une politique runtime ou prend une décision mutable observable.
+- Une crate ou un composant de `kb-lib` est opérationnel lorsqu’il effectue des I/O, orchestre un pipeline, décode, matérialise, exécute, applique une politique runtime ou prend une décision mutable observable.
 - Toute crate opérationnelle ajoutée ou modifiée doit dépendre de `tracing` depuis le workspace et déclarer exactement un `pub(crate) const TRACING_TARGET` dans `src/constants.rs`.
-- La valeur canonique de `TRACING_TARGET` est le nom exact du package Cargo. Les targets historiques `khbot.*`, les suffixes de module et les targets de fenêtre sont interdits dans les nouvelles modifications.
+- Hors `kb-lib`, la valeur canonique de `TRACING_TARGET` est le nom exact du package Cargo.
+- Dans `kb-lib`, chaque composant opérationnel possède son propre `constants.rs` et un target hiérarchique stable fondé sur son identifiant de décodeur, matérialiseur ou exécuteur ; un target unique `kb-lib` ne doit pas effacer l'identité du composant.
+- Les targets historiques `khbot.*` et les targets de fenêtre sont interdits dans les nouvelles modifications.
 - Les macros `tracing` doivent utiliser `target: crate::TRACING_TARGET` et des champs structurés stables. La granularité interne passe par `action`, `stage`, `window`, `campaign_id`, `signature`, `instruction_path`, `program_id`, `processor_name`, `processor_version`, `status` et `error_code`.
-- Les crates passives de types, contrats, DTO, API sans exécution, registres ou constantes restent sans dépendance `tracing`. `kb_config` reste une exception de bootstrap tant que sa validation précède l’installation du subscriber.
+- Les crates passives de types, contrats, DTO, API sans exécution, registres ou constantes restent sans dépendance `tracing`. `kb-config` reste une exception de bootstrap tant que sa validation précède l’installation du subscriber.
 - Il est interdit d’ajouter `tracing` sans événement réel ou de conserver un faux target uniquement consommé par `let _target`.
-- Une décision interne doit être journalisée par la crate responsable ; `kb_app_demo` ne journalise que les frontières Tauri/UI, les actions utilisateur et les résumés d’orchestration.
+- Une décision interne doit être journalisée par la crate responsable ; `kb-app-demo` ne journalise que les frontières Tauri/UI, les actions utilisateur et les résumés d’orchestration.
 - Tout input sélectionné sans décodeur compatible, tout résultat de décodage `failed` ou `unsupported`, tout résultat de matérialisation `failed`, toute validation de résultat invalide et toute erreur de persistance doivent émettre un événement `error` avant le retour ou la persistance terminale.
 - Une transaction Solana échouée mais correctement décodée n’est pas une erreur du logiciel. Une décision `ignored`, un refus de matérialisation conforme à la politique ou une annulation coopérative ne doivent pas être promus artificiellement au niveau `error`.
 - Les erreurs de décodage et de matérialisation doivent conserver au minimum, lorsque disponibles : `campaign_id`, `signature`, `slot`, `instruction_path`, `program_id`, processor ou materializer avec version, `input_key`, `input_hash` ou hash du payload, statut, code et diagnostic borné.
@@ -169,11 +170,11 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 
 ## Règles des exécuteurs
 
-- Les crates d'exécution utilisent le préfixe `kb_executor_`.
-- Une surface classifiée peut avoir un décodeur `kb_decoder_<surface>` et un exécuteur `kb_executor_<surface>`.
+- Les exécuteurs résident dans `kb_lib::executor`.
+- Une surface classifiée peut avoir un module décodeur et un module exécuteur distincts dans `kb-lib`.
 - Les exécuteurs ne doivent pas dépendre des décodeurs.
-- Les exécuteurs doivent passer par `kb_execution_api` pour leur contrat public.
-- Les garde-fous communs doivent être placés dans `kb_execution_safety`.
+- Les exécuteurs doivent passer par `kb_lib::executor::api` pour leur contrat public.
+- 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)`.
@@ -185,7 +186,7 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 
 ## Règles de configuration
 
-- La configuration applicative commune doit passer par `kb_config`.
+- La configuration applicative commune doit passer par `kb-config`.
 - Les fichiers JSON de configuration ne doivent pas contenir de commentaires.
 - Les secrets ne doivent pas être écrits en clair dans le dépôt.
 - Les valeurs sensibles doivent utiliser des variables d'environnement ou un stockage chiffré dédié.
@@ -193,18 +194,18 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 
 ## Ordre de développement cible
 
-- `kb_logging` doit être stabilisé avant les logs avancés des autres crates.
-- `kb_config` doit être stabilisé avant les stores, RPC, wallet, applications et workers.
+- `kb-logging` doit être stabilisé avant les logs avancés des autres crates.
+- `kb-config` doit être stabilisé avant les stores, RPC, wallet et applications.
 - Les contrats SQL et de matérialisation doivent être définis avant les gros décodeurs DEX.
 - Les implémentations détaillées des matérialisateurs doivent suivre les sorties réelles des décodeurs correspondants.
-- `kb_app_demo` doit fournir des validations live après chaque capacité majeure, sans créer une application Tauri séparée par crate.
+- `kb-app-demo` doit fournir des validations live après chaque capacité majeure, sans créer une application Tauri séparée par crate.
 
 ## Règles de livraison ChatGPT
 
 - Après le squelette initial, ChatGPT doit fournir uniquement des zips delta sauf demande explicite de zip complet.
-- Un delta qui modifie la racine du workspace ou plusieurs modules doit être nommé `khadhroony-bot2_vX.Y.Z-pre.abc-delta.zip`.
+- Un delta qui modifie la racine du workspace ou plusieurs modules doit être nommé `khadhroony-bot3_vX.Y.Z-pre.abc-delta.zip`.
 - Un delta qui ne modifie qu'un seul module Rust doit être nommé `kb_modulename_vX.Y.Z-pre.abc-delta.zip`.
-- Lorsqu'un delta `pre.abc` a déjà été livré et qu'un correctif est nécessaire, le numéro `abc` ne doit pas être incrémenté. Le correctif doit être nommé `khadhroony-bot2_vX.Y.Z-pre.abc-delta-fix-001.zip`, puis `-fix-002.zip`, etc. Pour un seul module, utiliser la même règle avec le préfixe `kb_modulename`.
+- Lorsqu'un delta `pre.abc` a déjà été livré et qu'un correctif est nécessaire, le numéro `abc` ne doit pas être incrémenté. Le correctif doit être nommé `khadhroony-bot3_vX.Y.Z-pre.abc-delta-fix-001.zip`, puis `-fix-002.zip`, etc. Pour un seul module, utiliser la même règle avec le nom de package.
 - Un correctif doit indiquer dans `delta.md` le delta de base et les correctifs antérieurs à appliquer. Il ne doit pas réutiliser silencieusement le nom ou l'empreinte d'une archive déjà livrée.
 - Le numéro `pre.abc` suivant est réservé à une nouvelle tranche fonctionnelle, pas à la réparation d'une archive existante.
 - Chaque zip delta ou correctif doit contenir un fichier `delta.md` non versionné à la racine du zip.
@@ -214,26 +215,31 @@ Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédi
 - Les suppressions de fichiers ou dossiers doivent être indiquées dans `delta.md`, car l'extraction d'un zip ne supprime pas automatiquement les anciens fichiers.
 - Les prompts de session doivent rappeler ce format de livraison et la règle `delta-fix-NNN`.
 
-## Constantes des décodeurs
+## Constantes des composants de `kb-lib`
 
-- Chaque crate `kb_decoder_*` classifié avec un `program_id` doit avoir un fichier `src/constants.rs`.
-- `src/constants.rs` contient les `PROGRAM_ID`, puis les discriminators, sélecteurs, opcodes, constantes Borsh et constantes de décodage quand elles seront connues.
-- `src/lib.rs` doit réexporter les constantes nécessaires avec `pub use crate::constants::...`.
-- `src/decoder.rs` doit utiliser les constantes réexportées par la crate, par exemple `crate::AMM_PUMP_SWAP_PROGRAM_ID`, et non `crate::constants::AMM_PUMP_SWAP_PROGRAM_ID`.
+- Chaque composant classifié avec un `program_id` doit avoir son propre fichier `constants.rs`.
+- `constants.rs` contient les discriminators, sélecteurs, opcodes, constantes Borsh et constantes de décodage quand elles sont connues.
+- Le module parent puis `kb-lib/src/lib.rs` réexportent les constantes publiques nécessaires.
+- Les fichiers d'implémentation utilisent le chemin public le plus court réexporté par `kb-lib`.
 - Les literals de `program_id` ne doivent pas rester dans `program_ids()`, sauf dans un fichier `constants.rs`.
 
 ## Identifiants de programmes
 
-Les `program_id` connus doivent être définis une seule fois dans `kb_program_ids`. Les crates de décodeur, d’exécuteur, de store, d’application ou d’outil doivent référencer directement `kb_program_ids::XXX_PROGRAM_ID`. Les fichiers `constants.rs` locaux ne doivent pas redéfinir ces chaînes ; ils restent réservés aux constantes internes du module, par exemple discriminators, opcodes, seeds, index de comptes ou layouts.
+Les `program_id` connus doivent être définis une seule fois dans `kb-program-ids`. Les composants de décodeur, d’exécuteur, de store, d’application ou d’outil doivent référencer directement `kb_program_ids::XXX_PROGRAM_ID`. Les fichiers `constants.rs` locaux ne doivent pas redéfinir ces chaînes ; ils restent réservés aux constantes internes du module, par exemple discriminators, opcodes, seeds, index de comptes ou layouts.
 
 ## Validation frontend Tauri
 
-- Pour `kb_app_demo`, ne pas lancer `npm --prefix kb_app_demo run build` séparément : la validation frontend de développement est réalisée par `cargo tauri dev -c kb_app_demo/tauri.conf.json`, qui démarre et pilote le serveur Vite.
+- Pour `kb-app-demo`, ne pas lancer `npm --prefix kb-app-demo run build` séparément : la validation frontend de développement est réalisée par `cargo tauri dev -c kb-app-demo/tauri.conf.json`, qui démarre et pilote le serveur Vite.
 
-## Architecture khadhroony-bot3
+## Architecture `khadhroony-bot3`
 
 - Les décodeurs, exécuteurs et matérialisateurs résident exclusivement dans `kb-lib`.
 - Les modules peuvent posséder leur propre fichier de constantes.
 - Toute API publique portée depuis une ancienne crate doit être réexportée au crate root de `kb-lib`.
-- `kb-store` regroupe les contrats store-neutral et PostgreSQL.
+- `kb-store` regroupe les contrats store-neutral et les adaptateurs de persistance, avec PostgreSQL comme adaptateur de production initial.
+- `kb-store/src/lib.rs` reste une façade : les DTO, entités, traits, requêtes et implémentations résident dans des modules privés dédiés et toute API publique est réexportée au crate root.
+- Les modèles source-neutral partagés avec les décodeurs, notamment `CoreInstructionReplayInput`, appartiennent à `kb-lib`; `kb-store` les consomme et les réexporte sans les dupliquer.
+- `kb-lib` ne dépend jamais de `kb-store`. Cette direction de dépendance évite tout cycle entre modèles, décodage et persistance.
+- `kb-store` ne dépend pas de `kb-config`. La frontière applicative transforme une configuration résolue en options de store explicitement validées.
+- Les adaptateurs concrets implémentent les mêmes traits neutres et ne font pas fuiter leurs types de connexion dans les contrats.
 - Seul `kb-app-demo` est conservé comme binaire pendant la migration initiale.