0.1.0-pre.004

docs/TRACING_CONTRACT.md

@@ -1,7 +1,7 @@
 <!-- file: docs/TRACING_CONTRACT.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
-# Contrat de tracing par crate
+# Contrat de tracing par crate et composant
 
 ## Objectif
 
@@ -21,19 +21,21 @@ Une crate passive contient uniquement des types, contrats, DTO, traits sans impl
 
 ## Cible canonique
 
-Toute crate qui déclare `tracing.workspace = true` doit :
+Toute crate opérationnelle hors `kb-lib` qui déclare `tracing.workspace = true` doit :
 
 - posséder `src/constants.rs` ;
 - définir exactement une constante `pub(crate) const TRACING_TARGET` ;
 - utiliser comme valeur le nom exact du package Cargo ;
-- appeler les macros avec `target: crate::constants::TRACING_TARGET` ;
+- réexporter la constante depuis sa façade puis appeler les macros avec `target: crate::TRACING_TARGET` ;
 - déplacer la granularité interne dans des champs structurés.
 
+`kb-lib` constitue une exception architecturale volontaire : chaque décodeur, matérialiseur ou exécuteur opérationnel possède son propre `constants.rs` et un target hiérarchique `kb-lib.<famille>.<surface>`. La façade de `kb-lib` réexporte chaque target sous un alias interne préfixé afin que plusieurs composants puissent coexister sans collision.
+
 Exemple :
 
 ```rust
 tracing::error!(
-    target: crate::constants::TRACING_TARGET,
+    target: crate::SOLANA_CORE_TRACING_TARGET,
     action = "decoder_outcome_failure",
     campaign_id = %campaign_id,
     signature = %input.signature,
@@ -47,40 +49,19 @@ tracing::error!(
 );
 ```
 
-Les targets `khbot.*`, les targets suffixés par module et les targets de fenêtre ne sont plus utilisés par les crates opérationnelles migrées. Les identifiants frontend historiques restent acceptés comme valeurs du champ `frontend_target`, mais l’événement Rust est émis sous `kb_app_demo`.
+Les targets `khbot.*` et les targets de fenêtre ne sont plus utilisés par les composants opérationnels migrés. Les identifiants frontend historiques restent acceptés comme valeurs du champ `frontend_target`, mais l’événement Rust est émis sous le target canonique de l’application.
 
 ## Crates actuellement routées
 
-La configuration couvre toutes les crates qui déclarent actuellement `tracing.workspace = true` :
+Les targets déjà migrés vers les noms canoniques bot3 sont :
 
 ```text
-kb_app_demo
-kb_decoder_solana_core
-kb_decoder_spl_associated_token_account
-kb_decoder_spl_memo
-kb_decoder_spl_token
-kb_decoder_spl_token_2022
-kb_executor_metadata_spl_name_service
-kb_execution_solana
-kb_executor_solana_core
-kb_executor_spl_account_compression
-kb_executor_spl_associated_token_account
-kb_executor_spl_memo
-kb_executor_spl_noop
-kb_executor_spl_single_pool
-kb_logging
-kb_materializer_admin
-kb_materializer_compliance_audit
-kb_materializer_lifecycle
-kb_materializer_staking
-kb_materializer_transaction_annotations
-kb_pipeline
-kb_rpc
-kb_store_pg
-kb_wallet
+kb-lib.decoder.solana.core
+kb-logging
+kb-store
 ```
 
-Le test `every_tracing_crate_has_one_canonical_target_constant` détecte automatiquement toute crate avec `tracing.workspace = true` et vérifie la présence d’une unique constante canonique. Le test de `kb_config` vérifie parallèlement la matrice de routes de chaque profil.
+L’audit `audit_khadhroony_workspace_rules.py` vérifie les targets de crates et les targets hiérarchiques de `kb-lib`. Il interdit également les faux usages `let _target` et impose que chaque macro de `kb-lib` utilise un alias réexporté par la façade.
 
 Les routes sont filtrées au niveau de leur writer plutôt que par un `Filtered` layer distinct. Un seul filtre d’admission agrégé empêche en amont le formatage des événements refusés par toutes les routes. Cette architecture préserve toutes les sorties globales et par crate au-delà de la limite interne de 64 identifiants de filtres de `tracing-subscriber`. Le test `more_than_64_routes_compose_without_filtered_layer_ids` protège explicitement ce contrat.
 
@@ -137,10 +118,10 @@ Ils sont journalisés en `debug`, `info` ou `warn` selon leur impact.
 
 ## Responsabilité
 
-- `kb_rpc` : sélection d’endpoint, requêtes, réponses bornées, retry, rate limit et transport.
-- `kb_execution_solana` : assemblage du message, contrôle du contrat de signataires, liaison de simulation et signature transactionnelle.
-- `kb_store_pg` : transactions SQL, commit/rollback, compteurs et erreurs de persistance.
-- `kb_pipeline` : sélection, dispatch, concurrence, annulation, backfill et agrégation.
+- `kb-rpc` : sélection d’endpoint, requêtes, réponses bornées, retry, rate limit et transport.
+- composants `kb-lib.executor` : assemblage du message, contrôle du contrat de signataires, liaison de simulation et signature transactionnelle.
+- `kb-store` : transactions SQL, commit/rollback, compteurs et erreurs de persistance.
+- `kb-pipeline` : sélection, dispatch, concurrence, annulation, backfill et agrégation.
 - décodeur : reconnaissance, validation du format, décision et diagnostic borné.
 - matérialiseur : applicabilité exacte, politique de transaction et sorties produites.
 - exécuteur : support, construction, simulation et garde-fous.
@@ -166,3 +147,5 @@ L’ajout ou la suppression de `tracing.workspace = true` impose dans le même d
 3. la mise à jour de `config/example.config.json` ;
 4. la mise à jour des tests de contrat ;
 5. la mise à jour de la liste ci-dessus.
+
+Pour un composant de `kb-lib`, les mêmes obligations s’appliquent au target hiérarchique, à son alias de façade et à ses routes dédiées.