khadhroony-bot3/migration/khadhroony-bot2-reference/RULES.md

<!-- file: RULES.md -->
<!-- version: 16 -->

# Règles spécifiques à `khadhroony-bot2`

Ce fichier contient uniquement les règles propres au projet et au workspace `khadhroony-bot2`.

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.

Toute livraison doit exécuter l'audit `python3 scripts/audit_rust_workspace_rules.py`. Tant que l'audit global n'est pas propre, les écarts existants doivent être résorbés par lots de correctifs avant toute nouvelle prérelease.

## Règles de nommage

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

## Règles Tauri et TypeScript

- Toute structure ou énumération Rust exposée au frontend TypeScript doit importer le trait `TS` avec `use ts_rs::TS;` puis dériver `TS`.
- Les types Rust exportés vers TypeScript doivent utiliser des noms stables et explicites.
- Les bindings générés doivent être produits dans un dossier dédié, généralement `../frontend/ts/bindings` ou  `#[ts(export, export_to = "../frontend/ts/bindings/MyStruct.ts")]`.
- Les types purement internes au backend ne doivent pas être exportés vers TypeScript par défaut.
- Un payload de commande ou d’événement Tauri traverse une frontière JSON et ne doit jamais exiger un `bigint` JavaScript. Pour un entier Rust borné et représentable par l’UI, utiliser un override TS-rs `number`; si l’exactitude au-delà de `Number.MAX_SAFE_INTEGER` est nécessaire, sérialiser explicitement une chaîne décimale côté Rust et exporter `string`. Ne jamais construire un `BigInt` dans un objet passé à `invoke` ou `emit`.
- Corriger le type Rust/TS-rs source puis régénérer les bindings ; ne pas considérer une modification manuelle isolée d’un fichier généré comme un correctif durable.

## Règles d'architecture

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

## Règles de documentation projet

- `README.md` décrit le projet, son rôle, ses objectifs et son organisation.
- `ROADMAP.md` contient les futures étapes, versions et changements prévus.
- `ROADMAP.md` conserve une structure documentaire normale par phases, cases cochées et journal de préversions ; les étiquettes conversationnelles de priorité ne doivent pas y être ajoutées.
- Les réponses de livraison doivent reprendre la liste exhaustive des tâches avec les rubriques conversationnelles **Validé**, **En cours**, **Next** et **Planifié**, sans réduire le suivi à un résumé ambigu.
- `CHANGELOG.md` n'est modifié qu'après validation d'une version, avec un paragraphe ajouté à la fin décrivant ce qui a été fait ou ajouté.
- Chaque crate Rust doit avoir un `README.md` ou `001.README.md` expliquant son rôle dans l'écosystème.
- Le README d'une crate opérationnelle doit inventorier ses types, traits, constantes et fonctions publics utiles, expliquer leurs paramètres, résultats, effets et frontières, puis fournir au moins un exemple d'utilisation lorsque l'API est destinée à être appelée directement.
- Une API publique ajoutée ou modifiée n'est pas considérée comme documentée tant que le README de sa crate n'a pas été synchronisé ; les bindings générés seuls ne remplacent pas cette documentation.

## Nomenclature métier

- `protocol_code` désigne la famille : `pump`, `raydium`, `meteora`, `orca`, `jupiter`, etc.
- `surface_code` désigne la surface concrète : `pump_swap`, `raydium_amm_v4`, `meteora_dlmm`, etc.
- `event_code` suit le format `<surface_code>.<event_name>`.
- Les familles d'événements principales sont : `trade`, `liquidity`, `lifecycle`, `fee`, `admin`, `reward`, `orderbook`, `token_account`, `pool_state`, `routing`, `risk`, `audit`, `unknown`.

## Base de données

- Les schémas PostgreSQL cibles sont : `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops`, `wallet`.
- Les colonnes JSONB doivent se terminer par `_jsonb`.
- Les montants bruts on-chain doivent se terminer par `_raw`.
- La transaction canonique raw reste la source rejouable et ne doit pas être supprimée après traitement sans politique de rétention explicite.

## Nommage canonique des surfaces

Les nouvelles surfaces de programmes doivent utiliser un nom canonique basé sur la fonction réelle du programme :

```text
<function_code>_<family_code>_<identifier_code>[_vN]
```

Les crates de décodage doivent utiliser :

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

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

Aucun renommage massif de crates n'est autorisé sans étape de contrôle dédiée et sans `cargo build` validé.

## Règles de nommage des surfaces Solana

- Le nom canonique d'une surface doit commencer par une fonction réelle : `amm`, `clmm`, `dlmm`, `router`, `orderbook`, `launchpad`, `lending`, `vault`, `staking`, `bridge`, `perpetuals`, `oracle`, `nft`, `metadata`, `admin`, etc.
- Le préfixe `program_` est interdit pour les nouveaux noms canoniques.
- Les surfaces non classifiées doivent utiliser `unknown_*` et ne doivent pas avoir de crate cible tant que leur fonction n'est pas validée.
- Les programmes Solana/SPL primitifs doivent rester séparés des surfaces DEX/router dans la documentation de contrôle.
- `damm` ne doit pas être utilisé comme préfixe fonctionnel ; utiliser `amm_meteora_damm_v1` ou `amm_meteora_damm_v2`.

## Registre des identifiants core

- Les identifiants Solana/SPL primitifs doivent être tenus à jour dans `registry/core_program_id_seed.toml`.
- Les sysvars et comptes natifs connus ne doivent pas être classés comme surfaces DEX/router.
- `spl_token`, `spl_token_2022` et `associated_token_account` restent dans leurs crates spécialisées.
- `stake_pool` doit être réservé à un futur crate spécialisé plutôt que mélangé avec le programme `stake`.

## Index court de programme

- Les noms de crates 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.
- Le vrai `program_id` propriétaire doit être prouvé avant création d'une surface canonique.

## Constantes Rust

- Les fichiers `program_ids.rs` sont interdits dans les nouveaux crates. Utiliser `constants.rs`.
- Les `program_id` publics doivent être réexportés depuis `lib.rs`.
- Dans une crate, les modules internes doivent appeler les constantes réexportées via `crate::CONSTANT_NAME`.
- Les discriminants, sélecteurs, longueurs Borsh et constantes internes futures doivent être placés dans `constants.rs` et rester `pub(crate)` sauf besoin d'API publique explicite.

## 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.
- 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.
- 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.
- 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.
- 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é.
- Les payloads complets, DSN non masqués, secrets, clés privées et données non bornées sont interdits dans les logs.
- Chaque profil doit router les événements vers les sorties globales `debug.log`, `info.log`, `error.jsonl` et `app.log`, puis vers `debug.log`, `info.log` et `error.jsonl` dans un répertoire propre à chaque crate utilisant `tracing`.
- L’ajout ou la suppression de `tracing.workspace = true` dans une crate impose la mise à jour simultanée de la matrice de routes, de ses tests et de `docs/TRACING_CONTRACT.md`.
- Le contrat détaillé est défini dans `docs/TRACING_CONTRACT.md`.
- L’audit mécanique spécifique au projet est exécuté par `python3 scripts/audit_khadhroony_workspace_rules.py`. Il couvre notamment `TRACING_TARGET` et l’usage obligatoire de `solana_pubkey::Pubkey` à la place de `solana_address::Address`.

## Règles de réutilisation des interfaces Solana et SPL

- Les dépendances déclarées dans `[workspace.dependencies]` forment un catalogue de versions et de features autorisées ; elles ne doivent être ajoutées à une crate consommatrice que lorsqu’un type, un encodeur, un décodeur ou un identifiant officiel est réellement utilisé.

- Dans un `Cargo.toml`, placer dans `[dependencies]` toute crate référencée par le code de bibliothèque compilé en production. Réserver `[dev-dependencies]` aux références contenues exclusivement dans `#[cfg(test)]`, les tests d’intégration, benches ou exemples. Une dépendance de test vers un décodeur ou matérialiseur concret est légitime lorsqu’elle sert uniquement à éprouver une orchestration générique fondée sur les traits API ; elle ne prouve pas qu’une capacité de production manque. Toute promotion de `dev-dependencies` vers `dependencies` doit être motivée par un appel runtime réel, et toute dépendance runtime inutilisée doit être supprimée.
- Les registres de composition runtime des applications doivent énumérer explicitement chaque décodeur et matérialiseur concret activé. Toute nouvelle surface instructionnelle dotée d’un `EventMaterializer` doit être ajoutée au registre applicatif et couverte par un test d’inventaire ordonné ; une crate présente dans le workspace ou dans `kb_pipeline` n’est pas activée automatiquement. Les matérialiseurs exclusivement stateful qui n’implémentent pas `EventMaterializer` restent routés par leurs APIs de snapshots dédiées.
- Les corrélations instruction/état doivent produire une issue explicite (`confirmed`, `contradicted` ou `not_applicable`) et ne doivent jamais transformer automatiquement une configuration observée en violation, score ou conclusion métier.
- Une interface officielle Solana ou SPL étroite doit être préférée à `solana-sdk` lorsque son contrat suffit.
- L’ordre de préférence des formats est : schéma officiel `wincode`, schéma officiel Borsh, puis parseur local borné reproduisant exactement le runtime lorsque l’interface officielle n’expose que `bincode`.
- Aucun nouveau code ne doit dépendre directement de `bincode`. Une interface officielle uniquement disponible derrière une feature `bincode` ne justifie pas l’activation de cette feature ; le layout doit alors être prouvé depuis les sources officielles et implémenté localement avec des bornes et des tests.
- Les exécuteurs doivent utiliser les builders officiels disponibles, préserver l’ordre exact des metas, borner toute liste de comptes variable avant l’appel au builder et refuser les doublons lorsque leur répétition n’a pas de sémantique publiée.
- Les features des interfaces doivent rester minimales et explicites. Une feature `serde`, `wincode`, `borsh`, `std`, `alloc` ou équivalente n’est activée que si la crate consommatrice l’utilise réellement.
- Les crates applicatives ne doivent pas dépendre d’interfaces RPC ou transactionnelles uniquement pour relayer des types ; ces dépendances appartiennent à `kb_rpc`, aux modèles communs justifiés ou à la crate opérationnelle propriétaire.
- Toute exception et toute implémentation locale doivent être documentées dans `docs/SOLANA_INTERFACE_DEPENDENCIES.md` avec la raison, la source officielle et la stratégie de test.

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


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

## Règles de configuration

- 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é.
- Les structures de configuration exposées à Tauri doivent dériver `TS`.

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

## 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 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`.
- 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.
- `delta.md` doit lister les fichiers ajoutés, les fichiers modifiés, les fichiers à supprimer manuellement, les validations exécutées et les validations non exécutées.
- Le zip delta ne doit pas contenir de fichiers inchangés.
- Le zip delta ne doit pas modifier `CHANGELOG.md` sauf validation explicite d'une version.
- 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

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

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