Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.0-pre.055

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-07-26 13:58:14 +02:00
parent 068eb9ece5
commit a3ce8d733f
44 changed files with 7507 additions and 8271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
docs/legacy-khadhroony-bot2/CHANGELOG.md
View File

@@ -1,208 +0,0 @@
<!-- file: CHANGELOG.md -->
<!-- version: 26 -->
# Changelog
Ce fichier est réservé aux versions validées. Les changements non validés restent décrits dans `ROADMAP.md` ou `RULES.md`.
## 0.0.1 — projet vide
Initialisation du dépôt comme point de départ vide. Cette version sert uniquement de repère historique avant la création du squelette modulaire.
## 0.0.2 — squelette stabilisé
Validation du squelette initial de `khadhroony-bot2` : workspace Rust modulaire, règles de développement, nomenclature des surfaces, registres de programmes, configuration multi-profils, couche d'exécution réservée, décodeurs/exécuteurs/matérialisateurs réservés, documentation de cadrage, prompts de session et application Tauri de démonstration en squelette. Cette version devient la base propre avant le développement `0.1.x` consacré à `kb_logging` et `kb_config`.
## 0.1.0 — `kb_logging` réel
Validation du jalon `kb_logging` : API publique minimale, initialisation `tracing_subscriber`, routes console, fichier humain, fichier JSON et fichier erreurs, filtrage par target et niveau, nettoyage ANSI des fichiers pour les messages issus de WebView Tauri, support des globs `crate.*` et `crate::*`, et couverture unitaire renforcée. Validation locale effectuée : `cargo test -p kb_logging` avec 14 tests passés et `cargo clippy -p kb_logging --all-targets` sans erreur. `cargo fmt` n'est pas retenu comme validation obligatoire du jalon, car la configuration `rustfmt.toml` contient des options nightly non applicables sur stable et le formatage courant est géré depuis Eclipse.
## 0.1.1 — `kb_config` typé et validé
Validation du jalon `kb_config` : configuration JSON multi-profils avec un seul profil actif, schéma `config/schema.config.json` validé via `jsonschema`, désérialisation typée, validation métier des profils, endpoints HTTP JSON-RPC et WebSocket Solana standard, listeners standards, sorties de logging configurables, stores PostgreSQL/SQLite, wallet, exécution et sections de démonstration. Les placeholders de clés restent directement dans les URLs et les champs runtime hors périmètre avant `v1.x` sont refusés par le schéma. Les exports TS-rs suivent la convention `../frontend/ts/bindings/kb_config/settings/<Type>.ts`. Validation locale effectuée : `cargo test --tests -p kb_config` avec 35 tests passés, dont les tests générateurs TS-rs `export_bindings_*`, et `cargo clippy` annoncé sans erreur pour le jalon.
## 0.1.2 — liaison `kb_logging`, `kb_config` et démo Tauri
Validation du jalon d’intégration Tauri : `kb_app_demo` charge le profil actif via `kb_config`, initialise `kb_logging` depuis cette configuration, conserve un `AppState` global, garde `demo_config` comme fenêtre de démonstration isolée et réémet les logs frontend vers `tracing` avec des targets statiques. La fenêtre principale rend le README workspace en HTML via `markdown-it`, expose un dropdown de démos, et la fenêtre configuration affiche le profil actif, la configuration complète et le schéma JSON avec un viewer JSON interactif. Le verrou mono-instance est appliqué uniquement dans `kb_app_demo/src/main.rs` afin de préserver l’entrée mobile par `kb_app_demo_lib::run()`. Le provider Rustls par défaut est initialisé dans la librairie pour desktop et mobile. Le splashscreen est aligné sur le modèle de `khadhroony-bobobot/kb_demo_app`, avec fade-in/fade-out, durée minimale extensible et attente initiale avant fade-in pour éviter l’apparition instantanée. `kb_core` expose maintenant l’erreur et le résultat communs sous `kb_core::Error` et `kb_core::Result`. Validation locale effectuée : `cargo test -p kb_core` avec 2 tests passés, `cargo test -p kb_config` avec 35 tests passés, `cargo test -p kb_logging` avec 14 tests passés, `cargo test -p kb_app_demo` avec 12 tests passés, `cargo clippy --all-targets` sans erreur et validation visuelle via `cargo tauri dev -c kb_app_demo/tauri.conf.json`.
## 0.1.3 — clients HTTP/WS Solana standard, rôles et pools
Validation du jalon RPC initial : `kb_rpc` expose les contrats JSON-RPC 2.0 partagés, le routage par rôle et `request_kind`, les clients HTTP JSON-RPC et WebSocket Solana standard, ainsi que les pools HTTP/WS par rôle. `kb_app_demo` ajoute les fenêtres dédiées `demo_http` et `demo_ws`, les listes contrôlées de rôles et méthodes, le refresh explicite des pools, le profil `mainnet` Helius, la connexion WebSocket persistante conservée dans `AppState`, les subscriptions multiples sur une même socket, l’unsubscribe individuel, la déconnexion globale à l’arrêt de l’application et le throttling des notifications WebSocket vers la WebView pour éviter les freezes sur les programmes très bavards. Les transports gRPC, Helius enhanced WebSocket, Helius gRPC et LaserStream restent hors périmètre avant les versions ultérieures. Validation locale effectuée : `cargo test -p kb_rpc` avec 39 tests passés, `cargo test -p kb_app_demo` avec 28 tests passés, `cargo clippy --all-targets` sans erreur, et validation visuelle des démos HTTP/WS via `cargo tauri dev -c kb_app_demo/tauri.conf.json`.
## 0.2.0 — conventions PostgreSQL et contrats DB
Validation du jalon de cadrage stockage : conventions PostgreSQL définies autour du schéma courant/default du profil, généralement `public`, sans espaces applicatifs séparés, et convention de tables Solana `kb_sol_<domain>_<name>` avec les domaines `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` et `wallet` intégrés au nom de table. Les règles SQL de base sont documentées pour `id`, `created_at`, `updated_at`, `slot`, `signature`, `program_id`, `raw_json` et `payload_json`, avec index minimaux et contraintes strictes mais réversibles. Les responsabilités de `kb_store_core` et `kb_store_pg` sont clarifiées, avec séparation `entities/`, `dtos/`, `queries/` et `repositories/`, et interdiction de placer des structures métier ou DB dans les requêtes. Les migrations historiques de brouillon sont neutralisées afin de ne pas créer d'espace PostgreSQL applicatif ni de table qualifiée par espace logique. Validation locale effectuée : `cargo test -p kb_config` avec 35 tests passés, `cargo test -p kb_app_demo` avec 28 tests passés et `cargo clippy --all-targets` sans erreur. `kb_store_core` et `kb_store_pg` ne disposent pas encore de tests à ce stade documentaire.
## 0.2.1 — contrats `kb_store_core` et replay instruction-level
Validation du jalon de contrats storage : `kb_store_core` expose les types communs backend-agnostiques pour pagination, healthcheck, migrations, erreurs de stockage, DTOs applicatifs, entities proches SQL et traits repositories sans implémentation PostgreSQL. Les contrats couvrent le raw RPC et WebSocket, le cycle de vie raw `Full` / `Compacted` / `Archived` / `Purged`, les états de traitement raw, la signature optionnelle des notifications WebSocket, la déduplication par `notification_key`, le lien futur optionnel notification vers transaction canonique, ainsi que le replay par instruction. Le replay est défini comme un scheduling au niveau instruction, mais le décodage reçoit un contexte extrait complet via `MdCoreInstructionReplayInput` : instruction ciblée, account keys, logs, balance changes et contexte transactionnel minimal. Les repositories restent abstraits et ne créent encore ni pool PostgreSQL, ni migration SQL réelle. Validation locale effectuée : `cargo test -p kb_store_core` avec 28 tests passés et `cargo clippy --all-targets` sans avertissement. Les validations précédentes du jalon ont également confirmé `kb_store_pg` sans test actif, `kb_config` avec 35 tests passés et `kb_app_demo` avec 28 tests passés.
## 0.2.2 — infrastructure PostgreSQL minimale
Validation du jalon d'infrastructure PostgreSQL : `kb_store_pg` expose maintenant une première implémentation réelle avec options de connexion, pool `sqlx::PgPool`, construction depuis la configuration active, masquage du DSN pour les diagnostics, healthcheck `SELECT 1`, lecture du schema courant, lecture de la version PostgreSQL et snapshot de migrations non destructif. La stratégie de migrations reste volontairement cadrée sans créer les tables Solana lourdes, qui sont reportées à `0.2.3` pour le raw store minimal. Les validateurs de noms de tables imposent la convention `kb_sol_<domain>_<name>` et refusent les schemas explicites. Validation locale effectuée : `cargo test -p kb_store_pg` avec 11 tests passés, test PostgreSQL réel optionnel `optional_postgres_healthcheck_from_env` validé avec `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana`, `cargo test -p kb_store_core` avec 28 tests passés, `cargo test -p kb_config` avec 35 tests passés, `cargo test -p kb_app_demo` avec 28 tests passés et `cargo clippy --all-targets` sans avertissement après remplacement local de l'exception `allow` par `expect` sur l'incompatibilité connue `async_trait` / `clippy::implicit_return`.
## 0.2.3 — raw store Solana minimal
Validation du jalon raw store minimal : `kb_store_pg` crée et initialise les deux premières tables Solana réelles, `kb_sol_raw_rpc_transactions` et `kb_sol_raw_ws_notifications`, sans créer de schema PostgreSQL applicatif explicite. Le raw RPC est inséré de façon idempotente par signature, les notifications WebSocket sont dédupliquées par `notification_key`, la signature des notifications reste optionnelle et le lien vers la transaction RPC canonique est préparé pour les étapes suivantes. Les tables conservent les champs de cycle de vie `retention_state`, `processing_state`, `processed_at` et `processing_reason`, avec `raw_json` nullable côté SQL afin de permettre les futures politiques `compacted`, `archived` et `purged` sans migration cassante. Les requêtes et l'implémentation PostgreSQL de `RawTransactionStore` couvrent les insertions, lookup de signature, lookup de notification et marquage lifecycle. Validation locale effectuée : `cargo test -p kb_store_pg` avec 21 tests passés, incluant le test PostgreSQL réel optionnel `optional_postgres_raw_store_roundtrip_from_env` avec `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana`, `cargo test -p kb_store_core` avec 28 tests passés, `cargo test -p kb_config` avec 35 tests passés, `cargo test -p kb_app_demo` avec 28 tests passés et `cargo clippy --all-targets` sans avertissement. Une correction locale du test raw PostgreSQL a été intégrée pour appeler directement `test_signature()` depuis le module de test.
## 0.2.4 — core Solana normalisé minimal
Validation du jalon core store minimal : `kb_store_pg` crée et initialise maintenant les tables core `kb_sol_core_transactions`, `kb_sol_core_account_keys`, `kb_sol_core_instructions`, `kb_sol_core_inner_instructions`, `kb_sol_core_logs` et `kb_sol_core_balance_changes`, en complément du raw store `0.2.3`, sans schema PostgreSQL applicatif explicite. Les migrations et l'initializer utilisent des noms SQL préfixés et explicites pour les contraintes et index : `pk_`, `fk_`, `ck_`, `ux_` et `ix_`. L'initialisation raw/core est sérialisée par un verrou PostgreSQL `pg_advisory_xact_lock` afin d'éviter les courses concurrentes pendant les tests ou les démarrages parallèles. `CoreTransactionStore` dispose de l'implémentation PostgreSQL minimale pour insérer les transactions core, account keys, instructions, inner instructions, logs et deltas de balances, puis reconstruire `MdCoreInstructionReplayInput` pour les futurs décodeurs. Le script de maintenance `kb_store_pg/maintenance/drop_raw_core_store.sql` permet de réinitialiser explicitement les tables raw/core locales dans l'ordre inverse des dépendances. Validation locale effectuée : `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana cargo test -p kb_store_pg -- --nocapture` avec 30 tests passés, création vérifiée des 8 tables dans PostgreSQL, réinitialisation validée via le script de maintenance, puis `cargo clippy --all-targets` sans avertissement. Le worker d'extraction raw RPC vers core, les observations et le ledger ops sont conservés pour les jalons suivants.
## 0.2.5 — diagnostics SQL PostgreSQL dans `kb_app_demo`
Validation du jalon diagnostics SQL : `kb_app_demo` ajoute les fenêtres `demo_sql_diag`, `demo_sql_pg_raw` et `demo_sql_pg_core` pour inspecter en lecture seule l’état PostgreSQL courant. Le démarrage Tauri tente l’initialisation raw/core lorsque `database.postgres.auto_initialize_schema` est actif, journalise les tables créées ou déjà présentes via le splashscreen et `tracing`, puis les fenêtres exposent le profil actif, le backend, le DSN masqué, le schema courant, le healthcheck, l’état migrations et les statistiques de tables raw/core. Les payloads JSON des trois fenêtres utilisent le viewer interactif déjà utilisé par `demo_config`, sans ajouter de nouvelle dépendance npm. Le jalon ne lance ni extracteur raw RPC vers core, ni décodage, ni matérialisation ; ces traitements restent reportés à `0.3.x`. Validation locale effectuée : `cargo test -p kb_store_pg` avec 30 tests passés, `cargo test -p kb_config` avec 35 tests passés, `cargo test -p kb_app_demo` avec 32 tests passés, `cargo clippy --all-targets` sans avertissement, et validation visuelle des trois fenêtres via `cargo tauri dev -c kb_app_demo/tauri.conf.json`.
## 0.3.0 — cadrage Agave local et sources temps réel
Validation du jalon de cadrage `0.3.x` : la phase ingestion/backfill/extraction raw vers core est reportée à `0.4.x`, tandis que `0.3.x` devient une phase d’expérimentation Agave local non votant et de stratégie live source. Le jalon documente le profil manuel `agave_local_research`, la commande de départ `agave-validator`, les probes RPC/WS attendus, les mesures ledger/accounts/CPU/RAM/réseau/lag, les règles de fallback vers les providers externes et les critères de décision avant `0.4.x`. Le profil Agave reste désactivé par défaut afin de préserver `mainnet_research` comme base stable, et aucune ingestion de production, aucun backfill historique, aucun décodage DEX, aucune matérialisation et aucune opération de trading ne sont introduits dans ce jalon. Validation locale du delta `0.3.0-pre.001` confirmée par l’utilisateur avant mise à jour du changelog.
## 0.3.1 — transaction canonique et observations d’acquisition
Validation du jalon de stockage canonique : `kb_sol_raw_transactions` conserve désormais une transaction source-indépendante par signature avec `canonical_json`, `canonical_json_hash` et `canonical_format_version`, tandis que `kb_sol_obs_transaction_observations` conserve uniquement les informations de provenance, méthode, session, timestamps, taille, statut et erreur sans dupliquer le payload complet. La lignée core utilise `raw_transaction_id`; les DTOs, entities, repositories, requêtes et diagnostics Tauri ont été alignés. La migration réelle depuis le schéma `0.2.x` a été contrôlée sur PostgreSQL 17.10 : les anciennes tables `kb_sol_raw_rpc_transactions` et `kb_sol_raw_ws_notifications` sont absentes, les tables canoniques sont présentes et les colonnes actives portent les nouveaux noms. Après cette validation, les fichiers SQL ont été consolidés en une baseline propre ne contenant que `0001_canonical_transaction_store.sql` et `0002_core_store.sql`; les fichiers SQL actifs n’embarquent plus les anciennes définitions de tables. Validation locale effectuée : `cargo test -p kb_app_demo` avec 32 tests passés, `cargo test -p kb_store_core` avec 30 tests passés, `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana cargo test -p kb_store_pg -- --nocapture` avec 32 tests passés, `cargo clippy --all-targets` sans avertissement, démarrage Tauri validé et diagnostics des huit tables raw/obs/core confirmés. Les fixtures PostgreSQL de test ont été nettoyées manuellement après validation.
## 0.3.2 — contrat canonique et adaptateur HTTP
Validation du jalon transactionnel canonique : `kb_model` expose désormais un modèle source-indépendant couvrant les transactions legacy et version 0, le message, les comptes statiques et chargés par Address Lookup Tables, les instructions externes et internes, les logs, le statut et les erreurs, les frais, compute units et cost units, les balances SOL et SPL/Token-2022, les rewards, les return data et le block time lorsqu’ils sont disponibles. Les signatures et clés publiques restent en base58, les données d’instruction sont normalisées en base64, les montants SPL bruts sont canonicalisés sans perte et la sérialisation déterministe trie récursivement les objets JSON avant calcul du hash SHA-256. `kb_rpc` fournit l’adaptateur `getTransaction` JSON-RPC et l’interface commune préparant les futurs adaptateurs Helius WebSocket et Yellowstone gRPC dans la crate existante, tandis que `kb_store_core::RawTransactionInsert::from_canonical` relie le modèle au store canonique. Les fixtures offline couvrent legacy/v0, succès/échec, ALT, CPI, SPL Token et Token-2022, et les formes fournisseur équivalentes produisent le même hash. Validation locale effectuée : `cargo test -p kb_model` avec 23 tests passés, `cargo test -p kb_rpc` avec 48 tests passés, `cargo test -p kb_store_core` avec 31 tests passés, `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana cargo test -p kb_store_pg -- --nocapture` avec 32 tests passés, puis `cargo clippy --all-targets` sans avertissement après ajout des retours explicites imposés par `clippy::implicit_return`. Les fixtures PostgreSQL du roundtrip ont été nettoyées manuellement après validation.
## 0.3.3 — backfill HTTP gratuit et `demo_backfill`
Validation du jalon de backfill HTTP : `kb_rpc` expose désormais `getSignaturesForAddress` avec pagination `before` / `until`, tandis que `getTransaction` alimente le modèle canonique sans conserver durablement le payload fournisseur. `kb_pipeline` orchestre les campagnes de signatures explicites et les recherches avant ou après une signature pour un programme, un token ou un pool, avec déduplication, limites de pages, reprise exportable, concurrence, temporisation, retries bornés, arrêt coopératif et journalisation détaillée. Le parcours `after` utilise la borne RPC `until`, des pages pouvant atteindre 1 000 signatures et une sélection bornée en mémoire afin de ne conserver que les `X` signatures directement postérieures à l’ancre dans l’historique de l’adresse. `kb_app_demo` ajoute la fenêtre `demo_backfill`, organisée en accordéons Bootstrap 5, avec paramètres communs, textarea de signatures, formulaires programme/token/pool, journal, résumé et commande d’arrêt. Chaque transaction complète est insérée une seule fois dans `kb_sol_raw_transactions`; chaque tentative d’acquisition produit une observation légère dans `kb_sol_obs_transaction_observations`, tandis que les résultats `missing` et `failed` ne créent aucun faux payload canonique.
La correction finale de l’arrêt coopératif remplace la création globale des futures par une file bornée à la concurrence effective, distingue les candidats sélectionnés, démarrés, terminés, annulés et non démarrés, et calcule `resume_before_signature` depuis le dernier préfixe contigu réellement terminé. Une campagne réelle de 500 candidats a validé l’arrêt avec 7 candidats démarrés, 3 terminés, 4 annulés et 493 non démarrés, sans journalisation artificielle des candidats restants. Validation locale effectuée : `cargo test -p kb_rpc` avec 54 tests passés, `cargo test -p kb_pipeline` avec 10 tests passés, `cargo test -p kb_store_core` avec 31 tests passés, `cargo test -p kb_store_pg` avec 32 tests passés, `cargo test -p kb_app_demo` avec 38 tests passés et `cargo clippy --all-targets` sans avertissement. Les campagnes Tauri réelles ont validé les signatures explicites, programme avant/après, token avant/après et pool avant/après ; le cas `program_after` a parcouru 5 516 signatures indexées avant de sélectionner les 5 signatures les plus proches de l’ancre. Les diagnostics PostgreSQL ont confirmé 62 transactions canoniques et 62 observations, sans alimentation prématurée des tables core, dont l’extraction reste prévue pour `0.3.4`.
## 0.3.4 — extraction canonique vers core et clôture de la fondation `0.3.x`
Validation du jalon d’extraction structurelle : `kb_pipeline` transforme les transactions canoniques en graphes core atomiques comprenant transactions, account keys statiques et ALT, instructions outer et inner à chemins stables, logs reliés prudemment et deltas SOL/SPL Token/Token-2022. `kb_store_core` et `kb_store_pg` exposent et implémentent les contrats de persistance, le ledger versionné `kb_sol_ops_processing_ledger`, le skip par version/hash, le force replay et le rollback complet. `kb_app_demo` ajoute `demo_core_extraction` et le navigateur read-only `demo_sql_replay_candidates` avec filtres, sélection, copie et exports CSV sous `data/exports_csv/`; `kb_program_ids` fournit un registre énumérable de 182 programmes. Les transactions Solana échouées restent extractibles et seront décodables comme observations d’intention ou d’échec, sans être matérialisées automatiquement comme mutations réussies. Validation réelle effectuée sur PostgreSQL 17.10 : 70 transactions extraites sans erreur, sept contrôles d’intégrité sans anomalie, replay normal de 14 signatures entièrement ignoré, force replay des mêmes 14 signatures sans duplication, second replay entièrement ignoré, cardinalité finale de 70 transactions core et ledger final de 70 succès pour 84 tentatives. Validation locale finale : `cargo test -p kb_pipeline` avec 24 tests passés, `KB_POSTGRES_TEST_URL=... cargo test -p kb_store_pg -- --nocapture` avec 39 tests passés dont le rollback/replay corrigé, `cargo test -p kb_app_demo` avec 60 tests passés, `cargo test -p kb_program_ids` avec 2 tests passés et `cargo clippy --all-targets` sans avertissement. L’ancien jalon `0.3.5` est absorbé dans cette version ; la suite active devient `0.4.0` pour l’infrastructure commune de décodage et de matérialisation.
## 0.4.0 — infrastructure commune de décodage et de matérialisation
Validation du socle commun de replay contextualisé : `kb_decoder_api` et `kb_materializer_api` travaillent sur les inputs core complets, `kb_pipeline` sélectionne uniquement les programmes compatibles avec les processors activés, effectue un dispatch déterministe par programme et chemin d’instruction, persiste atomiquement couverture, ledger, événements décodés et sorties matérialisées, et applique le skip par processor/version/hash. Le force replay est autorisé uniquement avec des signatures explicites ou avec l’autorisation opérateur « toutes les signatures » bornée par les filtres et la limite. La matérialisation est refusée lorsqu’aucun matérialiseur n’est enregistré. Le classifieur `solana_native_classifier` déclare les 18 surfaces natives/runtime/loaders/précompiles connues sans produire de faux décodage.
`kb_app_demo` ajoute `demo_decode_replay`, ses diagnostics decode/ledger/couverture et les contrôles de replay normal, force replay ciblé, replay global explicitement autorisé, concurrence bornée et arrêt coopératif. Chaque campagne possède un `campaign_id` propagé par spans jusqu’au pipeline, au store PostgreSQL et au décodeur. Les migrations raw/core/decode sont appliquées une seule fois au démarrage Tauri ; les commandes de démo réutilisent ensuite le schéma initialisé. Les validations frontend du backfill bloquent localement les requêtes incomplètes sans produire de faux événements backend `ERROR`.
Validation locale finale : `cargo test -p kb_config` avec 36 tests passés, `cargo test -p kb_pipeline` avec 41 tests passés, `KB_POSTGRES_TEST_URL=postgres://solana:solana@localhost:5432/solana_test cargo test -p kb_store_pg -- --nocapture` avec 44 tests passés, `cargo test -p kb_app_demo` avec 75 tests passés et `cargo clippy --all-targets` sans avertissement. Les campagnes Tauri réelles ont validé neuf skips version/hash, neuf force replays ciblés, un second skip cohérent, un replay global strictement limité à cinq inputs, l’annulation puis le redémarrage d’une campagne, et la corrélation complète des traces. Le correctif final d’annulation garantit `started + not_started = selected` et `completed = started`; une campagne réelle a terminé avec 382 inputs sélectionnés, 45 démarrés/terminés, 337 non démarrés, 45 dispatchs `unsupported`, aucun unmatched, aucun échec et aucun événement dans `errors.jsonl`. La couverture PostgreSQL confirme 18 déclarations natives, 382 observations Compute Budget reconnues sans erreur et 94 observations System reconnues sans erreur. `0.4.1` devient le jalon actif pour le décodage maximal des programmes Solana natifs, loaders et précompiles.
## 0.4.1 — programmes Solana natifs, loaders, précompiles et matérialisations natives
Validation du jalon `0.4.1` : `kb_decoder_solana_core` couvre désormais les programmes Solana natifs/runtime, historiques, loaders, précompiles et surfaces ZK explicitement incluses dans le périmètre. Le registre exécutable natif contient 18 surfaces après reclassification de `StakeConfig11111111111111111111111111111111` comme compte historique non exécutable et ajout du stateless Slashing Program `S1ashing11111111111111111111111111111111111` observé dans Agave `v4.1.1` derrière feature gate. Les surfaces décodées incluent System, Vote, Stake, Config, Compute Budget, Address Lookup Table, Feature, ZK ElGamal Proof, l’ancien ZK Token Proof historique/no-op, les loaders Native/BPF v1/v2/Upgradeable/v4, Ed25519, secp256k1, secp256r1 et Slashing. SPL Memo, SPL Token, Token-2022, Stake Pool, Single Pool, Account Compression, Noop et SPL Name Service restent réservés aux jalons suivants.
Le jalon a étendu le contrat de replay instructionnel avec les instructions outer ordonnées afin de résoudre les références inter-instructions des précompiles et du profil Compute Budget. Les décodeurs bornent les offsets, tailles, compteurs, références d’instructions, comptes requis et payloads suffixes sans recalcul cryptographique pour les signatures ou preuves ZK. L’ancien `solana-zk-token-sdk` déprécié a été retiré ; le miroir ZK Token historique repose maintenant sur une table wire locale auditée, sans dépendance directe à `bincode`.
Les matérialisations natives sont clôturées au niveau instructionnel stable. `kb_materializer_lifecycle` projette Address Lookup Table, lifecycle des loaders, révocation Feature, durable nonce, comptes System create/allocate, contextes ZK ElGamal et rapports Slashing. `kb_materializer_admin` projette assignations System, écritures Config opaques et changements d’autorité Loader. `kb_materializer_compliance_audit` projette écritures/copies de bytecode Loader et profils Compute Budget transactionnels agrégés. `kb_materializer_staking` projette les intentions commitées Stake/Vote : comptes, autorités, lockup, délégation, désactivation, split, merge, retraits, move stake/lamports, identité Vote, commission, vote state et dépôt de rewards. Les sorties ne prétendent pas reconstruire les snapshots finaux de comptes, les sysvars historiques, les crédits Vote cumulés, l’activation Stake par epoch, les unités compute consommées ou les frais finaux runtime.
`kb_app_demo` enregistre les matérialiseurs natifs `solana_native_lifecycle`, `solana_native_admin`, `solana_native_compliance_audit` et `solana_native_staking`. Les profils de logging montent à 53 routes avec fichiers dédiés pour les crates opérationnelles ajoutées. `demo_backfill` accepte maintenant les modes `program_latest`, `token_latest` et `pool_latest` : une recherche « avant, plus anciennes » sans ancre commence sur les signatures les plus récentes, tandis que la direction « après, plus récentes » conserve une ancre obligatoire.
Les validations utilisateur finales confirment : `kb_program_ids` 5 tests, `kb_decoder_solana_core` 114 tests, `kb_materializer_lifecycle` 16 tests, `kb_materializer_admin` 7 tests, `kb_materializer_compliance_audit` 7 tests, `kb_materializer_staking` 8 tests, `kb_config` 36 tests, `kb_pipeline` 45 tests, `kb_store_pg` 45 tests avec PostgreSQL réel, `kb_app_demo` 78 tests et `cargo clippy --all-targets` sans avertissement. Le correctif de sérialisation test-only des tests PostgreSQL réels élimine l’interblocage intermittent observé lors des tests optionnels concurrents.
Les campagnes mainnet ciblées validées couvrent notamment : System 817 inputs décodés avec 258 sorties et 52 refus attendus sur transactions échouées ; Config 96/96 avec 96 sorties admin ; Stake 448/448 avec 447 sorties et un refus attendu ; Vote 600/600 avec 600 sorties ; Compute Budget 2 746/2 746 avec 1 603 profils transactionnels matérialisés ; ZK ElGamal 151/151 avec 139 sorties de contexte ; ALT 104/104 avec 104 sorties lifecycle ; Slashing sans corpus observable, validé par sources officielles et fixtures synthétiques. Tous ces replays se terminent avec `unmatched = 0`, `failedInputs = 0`, `unsupported = 0` et journaux `error.jsonl` vides dans les archives fournies.
La suite active devient `0.4.2` : infrastructure d’exécution et `kb_executor_solana_core`, avec séparation stricte entre plan, simulation, signature, envoi et validation post-exécution. Les exécuteurs SPL suivront ensuite la politique décodeur maximal → matérialisateurs → exécuteur limité par opération.
## 0.4.2 — infrastructure d’exécution native et RPC Solana standard
Validation du jalon d’exécution native. `kb_execution_api`, `kb_execution_safety`, `kb_execution_solana`, `kb_wallet`, `kb_executor_solana_core`, `kb_rpc` et `kb_pipeline` séparent explicitement intent, plan, politique, lecture stateful, simulation, signature, envoi, confirmation et validation post-exécution. Le wallet temporaire de laboratoire reste confiné à Localnet/Devnet ; dry-run et simulation sont obligatoires par défaut, les plafonds de dépense/frais sont vérifiés et Mainnet reste désactivé sans politique et confirmation explicites.
`kb_executor_solana_core` couvre 18 surfaces natives avec 109 opérations appelables : System, Compute Budget, Address Lookup Table, précompiles Ed25519/secp256k1/secp256r1, Config, Feature, Slashing, ZK ElGamal, Stake, Vote, Loader v3 et Loader v4. BPF Loader v1/v2, Native Loader et l’ancien ZK Token Proof sont classés sans builder client ; Stake `Redelegate` reste historique `decode-only`. Chaque builder est comparé à un encodeur officiel ou à un layout wire audité. La matrice `docs/NATIVE_SOLANA_EXECUTION_MATRIX.json` est vérifiée par un test Rust contre les 109 codes compilés. `kb_decoder_solana_core` conserve l’égalité exacte avec les 18 Program IDs natifs et 121 déclarations de couverture.
Le préflight stateful de `kb_pipeline` inspecte ALT, Config, Feature, Slashing et les contextes ZK ElGamal sur Localnet/Devnet et retourne `NotRequired`, `Ready` ou `Blocked`. Les opérations administratives non validées réellement par un scénario cluster restent derrière ce garde-fou, hors de l’UI et sans activation Mainnet. Le parcours Devnet représentatif System transfer a été validé avec un wallet persistant préfinancé et 1 000 000 lamports : simulation exacte, signature, envoi, confirmation, `getTransaction`, insertion canonique, extraction core et decode replay ciblé ont réussi.
`kb_rpc` expose des contrats propres et configurables pour les 52 méthodes HTTP standard et les neuf paires WebSocket standard. Les options sont composables sans exposer les DTO Agave. `WsSession` gère multiplexage, unsubscribe, timeout, reconnexion bornée et réabonnement. `blockSubscribe`, `slotsUpdatesSubscribe` et `voteSubscribe` sont activables par endpoint ; un rejet serveur indiquant une méthode absente ou non activée désactive automatiquement la capacité pour la session. `kb_app_demo` ne contient plus la boucle de transport WebSocket.
La frontière Tauri/TS-rs a été corrigée pour ne plus transmettre de `bigint` dans les payloads JSON actifs. Les identifiants WebSocket sont contrôlés contre `Number.isSafeInteger` et les limites du navigateur SQL sont validées avant l’invocation backend. Les logs réels confirment les souscriptions/désabonnements WebSocket et le garde-fou de changement d’endpoint avec session active.
Validation finale fournie par l’utilisateur : `kb_program_ids` 5 tests, `kb_decoder_solana_core` 116, `kb_executor_solana_core` 88, `kb_execution_api` 22, `kb_execution_safety` 15, `kb_execution_solana` 12, `kb_rpc` 113, `kb_pipeline` 56, `kb_config` 41, `kb_app_demo` 88 et `kb_store_pg` 45 avec PostgreSQL réel. Le test Devnet opt-in et le replay post-exécution sont réussis, `cargo clippy --all-targets` est propre et `cargo tauri dev` démarre avec Vite et initialise correctement PostgreSQL. Aucun jalon suivant n’est ouvert par cette clôture.
## 0.4.3 — SPL Memo v1, v3 et v4
Validation complète de la surface SPL Memo. `kb_decoder_spl_memo` reconnaît exactement les Program IDs v1, v3 et v4, décode le payload UTF-8 brut, sa longueur et son SHA-256, conserve les comptes ordonnés et leurs flags, distingue les règles historiques de signataires, les chemins outer/inner, les transactions réussies ou échouées et les tentatives invalides sans produire de faux état commité. La matrice machine-readable `docs/SPL_MEMO_MATRIX.json` relie les contrats officiels, les fixtures synthétiques et le corpus Mainnet réel des trois générations.
`kb_materializer_transaction_annotations` projette uniquement les Memo réussis et commités dans la famille `transaction_annotation`, avec texte borné, génération, Program ID, signataires vérifiés, provenance et clé d’idempotence. Les comptes complets et diagnostics d’audit restent dans le decode. La persistance réutilise `kb_sol_mat_events` et le ledger commun sans nouvelle table ; `demo_decode_replay` expose un journal typé et borné filtrable par signature.
`kb_executor_spl_memo` fournit les intents typés v1/v3/v4 et construit les trois générations avec `spl-memo-interface 2.1.0`, payload exact et signataires readonly ordonnés. La bibliothèque reste universelle sur les clusters ; simulation obligatoire, dry-run par défaut, plafond de frais, autorisation opérateur et politiques Mainnet appartiennent à l’infrastructure commune. Le parcours Memo v4 Devnet réutilise wallet, RPC, safety, transaction Solana, confirmation, hydratation canonique, extraction core et decode replay. Trois transactions réelles ont chacune produit une annotation et un second replay idempotent `skipped`.
La clôture utilisateur confirme : `kb_program_ids` 5 tests, `kb_decoder_spl_memo` 9, `kb_materializer_transaction_annotations` 7, `kb_executor_spl_memo` 15, `kb_execution_api` 22, `kb_execution_safety` 15, `kb_execution_solana` 12, `kb_pipeline` 61, `kb_rpc` 113, `kb_app_demo` 96 et `kb_store_pg` 46 avec PostgreSQL réel. Le test opt-in Devnet avec envoi est réussi et `cargo clippy --all-targets` est propre. La suite active devient `0.4.4 — SPL Token` selon `prompts/023_v0_4_4_spl_token.md`; l’acquisition historique différée reste hors ROADMAP actif.
## 0.4.4 — SPL Token classique
Validation complète du programme SPL Token classique `Tokenkeg...`. `kb_decoder_spl_token`
reconnaît exactement les 28 tags publiés par `spl-token-interface 3.0.0`, conserve le wire borné,
les comptes ordonnés, outer/inner paths, autorités simples ou multisig, montants bruts, decimals,
transactions échouées non commitées et diagnostics sans inventer mint ni état final. `Batch`
conserve son parent et ses enfants déterministes sans accepter les batchs imbriqués. La matrice
`docs/SPL_TOKEN_MATRIX.json` relie interface, processor, builders, corpus et preuves cluster.
Les projections stables produisent des événements instructionnels `token_account`, `admin` et
`risk`, sans fee classique fictive, sans OHLC et sans snapshot final reconstruit. Le replay Mainnet
de 370 instructions a produit 371 sorties, huit refus correspondant exactement à huit transactions
échouées, puis un second replay idempotent sans nouvelle sortie. Le journal Tauri expose des filtres
bornés par signature, mint, compte, famille et opération, avec montants JSON sans perte.
`kb_executor_spl_token` expose 24 opérations typées courantes ou récentes et laisse les quatre
initialisations Rent obsolètes en decode-only. Le préflight stateful Localnet/Devnet valide layouts,
relations mint/comptes, soldes, native reserve, délégations, autorités, multisig et rent hors du
décodeur et de l'exécuteur. Le parcours Devnet `TransferChecked` a réussi simulation, envoi,
confirmation, hydratation, extraction, replay, matérialisation et second replay idempotent. Un
lifecycle contrôlé sans ATA a ensuite initialisé mint et comptes, minté, transféré, approuvé,
révoqué, brûlé puis fermé les comptes avec récupération sûre après interruption RPC.
Les tags récents `Batch` et `UnwrapLamports` ont été simulés avec succès sur le programme classique
Devnet, sans signature ni envoi, respectivement en 270 et 140 compute units. La clôture Tauri charge
77 routes de logs, réussit le préflight et la simulation `TransferChecked`, bloque l'envoi sans
confirmation, affiche la matérialisation commitée exacte et simule Memo v4 sans erreur runtime.
La régression finale communiquée confirme notamment : `kb_program_ids` 5 tests,
`kb_decoder_spl_token` 8, `kb_executor_spl_token` 15, `kb_decoder_spl_memo` 9,
`kb_materializer_transaction_annotations` 7, `kb_execution_api` 22, `kb_execution_safety` 15,
`kb_execution_solana` 12, `kb_pipeline` 81, `kb_rpc` 113, `kb_config` 41, `kb_app_demo` 102 et
`kb_store_pg` 46 avec PostgreSQL réel. `cargo clippy --all-targets` est propre. La suite active
devient `0.4.5 — SPL Associated Token Account` selon
`prompts/024_v0_4_5_spl_associated_token_account.md`.
## 0.4.5 — SPL Associated Token Account
Validation complète du programme SPL Associated Token Account
`ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. Le décodeur consomme
`spl-associated-token-account-interface 2.0.0`, reconnaît exactement `Create`,
`CreateIdempotent`, `RecoverNested` et la forme historique vide de `Create`, puis conserve comptes
ordonnés, flags, doublons, chemins outer/inner, transactions échouées et diagnostics bornés. Les
adresses observées sont comparées aux PDA canoniques dérivés depuis wallet, Token Program ID et
mint ; une incohérence reste décodable et n'est jamais corrigée silencieusement.
`kb_materializer_token_accounts` possède exclusivement le lifecycle de l'adresse associée : créée,
créée ou réutilisée idempotemment, ou récupérée depuis une imbrication. `kb_materializer_risk`
possède le constat distinct d'anti-pattern nested récupéré, sans score arbitraire. Les CPI SPL Token
restent propriétaires des initialisations, transferts et fermetures, et les matérialiseurs lifecycle
général, admin et fees ne produisent aucun doublon. Les transactions non commitées ou invalides sont
refusées comme mutations.
`kb_executor_spl_associated_token_account` expose les trois variantes actuelles pour SPL Token
classique et Token-2022 avec les builders officiels, metas dans l'ordre exact, signataires uniques,
simulation obligatoire, dry-run par défaut et coûts rent/frais plafonnés. Le pipeline stateful
contrôle mints, owners, Program IDs, dérivations, comptes existants, rent, signataires et
postconditions avant et après l'exécution. La fenêtre Tauri Solana existante ajoute création ATA,
dérivation readonly et journal lifecycle borné ; `RecoverNested` reste volontairement hors UI.
Les scénarios Devnet contrôlés du 16 juillet 2026 ont validé la création et la réutilisation
idempotente d'ATA classiques et Token-2022, puis un `RecoverNested` classique transférant
1 000 000 000 unités brutes vers l'ATA wallet et fermant le nested ATA. Chaque envoi a suivi
simulation, confirmation, hydratation canonique, extraction, decode, matérialisation et second
replay idempotent. L'ATA Token-2022 observé mesure 170 octets et expose `ImmutableOwner`, sans que le
jalon ne commence le décodage général de ses extensions.
La clôture confirme 5 tests Program IDs, 8 tests décodeur Token classique, 15 tests exécuteur Token,
9 tests Memo, 7 tests annotations, 9 tests matérialiseur token accounts, 6 tests risk, 17 tests
lifecycle, 9 tests admin, 3 tests fees, 10 tests décodeur ATA, 10 tests exécuteur ATA, 22 tests API
d'exécution, 15 tests safety, 12 tests transaction Solana, 90 tests pipeline, 113 tests RPC, 41 tests
configuration, 111 tests démo et 46 tests PostgreSQL réels. `cargo clippy --all-targets` est propre
et `cargo tauri dev -c kb_app_demo/tauri.conf.json` a démarré Vite, Tauri et PostgreSQL. La suite
active devient `0.4.6 — Token-2022, extensions et registre ElGamal` selon
`prompts/025_v0_4_6_spl_token_2022.md`.
## 0.4.6 — Token-2022, extensions et registre ElGamal
Validation du jalon Token-2022 et ElGamal Registry avec frontières techniques séparées. Token-2022 couvre les instructions de base, les familles d’extensions identifiables, les états Mint/Account/Multisig et TLV, les metadata/group incorporés, les parcours confidentiels, les matérialisations propriétaires et les exécuteurs simulation-first avec préflights stateful et preuves inline/context-state. Huit opérations publiques Token-2022 ont été confirmées sur Devnet, hydratées, extraites, décodées, matérialisées et rejouées idempotemment. Le corpus Mainnet contient 55 instructions Token-2022 décodées sans échec.
Le registre ElGamal dispose de son décodeur, de sa matrice, de son parser d’état de 64 octets, de sa matérialisation administrative, de ses builders `CreateRegistry`/`UpdateRegistry`, de son PDA, de ses préflights et de son orchestration de preuves. La validation réseau publique reste indisponible sur Devnet/Mainnet au 20 juillet 2026 ; la validation synthétique/offline est conservée sans inventer de preuve cluster.
La validation Mainnet a corrigé le wire `Write` du loader immuable : longueur `u32` et données à l’offset 12, supprimant 68 diagnostics `loader_vector_length_mismatch`. Les 76 rejets restants sont tous issus de transactions Solana échouées et restent explicitement fail-closed ; quatre tags Loader v4 inconnus sont classés `Unsupported`. Un timeout ponctuel du pool PostgreSQL a été réparé par replay ciblé.
Le replay de `kb_app_demo` ajoute `incomplete_signatures`, qui sélectionne seulement les signatures contenant une instruction `pending`, `failed`, `replay_requested` ou `unsupported`, limite d’abord les signatures puis étend leurs instructions compatibles sans force replay global. Deux campagnes PostgreSQL réelles ont produit le même résultat : 81 entrées, 1 décodée, 4 unsupported, 76 failed, aucun unmatched et aucun doublon decode/mat. Validation finale : `kb_store_core` 41/41, `kb_store_pg` 46/46 avec PostgreSQL réel, `kb_pipeline` 124/124, `kb_app_demo` 118/118 et `cargo clippy --all-targets` propre. La suite active devient `0.4.7 — Metaplex Token Metadata` selon `prompts/026_v0_4_7_metaplex_token_metadata.md`. Anchor n’étant pas requis par les programmes SPL de `0.4.x`, son infrastructure commune est planifiée en `0.4.18`, immédiatement avant Meteora.

293
docs/legacy-khadhroony-bot2/README.md
View File

@@ -1,293 +0,0 @@
<!-- file: README.md -->
<!-- version: 81 -->
# Khadhroony Bot2
Khadhroony Bot2 est un workspace Rust modulaire pour observer, décoder, matérialiser, exécuter et analyser des transactions Solana.
Le projet poursuit deux objectifs complémentaires. À court terme, il doit fournir un trading assisté contrôlable depuis des démos live Tauri. À long terme, il doit devenir une bibliothèque d'indexation et d'analyse Solana capable de classifier un grand nombre de programmes et de surfaces.
Le socle technique doit permettre de :
- ingérer des transactions Solana depuis RPC HTTP, WebSocket ou futures sources spécialisées ;
- normaliser chaque source vers une transaction canonique source-indépendante ;
- conserver la transaction canonique comme source d’audit et de replay ;
- conserver séparément les observations légères de provenance et de timing ;
- extraire les instructions, inner instructions, logs, comptes résolus et deltas de balances ;
- détecter les programmes impliqués dans chaque transaction ;
- décoder les programmes Solana de base, les programmes SPL, les surfaces DEX, les orderbooks, les routers et les protocoles annexes ;
- matérialiser les événements décodés en tables métier exploitables ;
- rejouer uniquement les modules nécessaires grâce à un ledger de traitement par module et version ;
- alimenter des agrégations, diagnostics, signaux de risque et futures règles de stratégie ;
- construire des plans d'exécution séparés des décodeurs ;
- tester les fonctionnalités live via `kb_app_demo` avant automatisation.
## Architecture générale
Le workspace suit une chaîne de traitement en couches :
```text
canonical transaction -> source observations -> Solana extraction -> decoding -> materialization -> aggregation -> strategy
```
Chaque couche doit être indépendante autant que possible. Les décodeurs ne dépendent pas du stockage, du RPC, de Tauri, du wallet ou des matérialisateurs. Les matérialisateurs travaillent sur les événements décodés et produisent des événements métier normalisés.
## Rôle des dossiers principaux
- `kb_core` contient les primitives partagées minimales.
- `kb_model` contient les types communs du modèle interne.
- `kb_config` définit le contrat JSON multi-profils, le schéma runtime, les validations typées et les exports TS-rs destinés aux applications Tauri.
- `kb_rpc` contient les protocoles et clients RPC Solana HTTP, WebSocket et futurs flux Helius/Yellowstone.
- `kb_execution_solana` assemble les plans communs en transactions Solana, lie la simulation au message exact et résout les signataires via l’interface Solana `Signer`; `kb_wallet` fournit actuellement le backend temporaire.
- Le projet différé d’acquisition historique gratuite est décrit dans `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md`. Il reste hors du ROADMAP actif tant que les décodeurs, matérialisateurs et exécuteurs prioritaires ne sont pas suffisamment avancés.
- `kb_store_core` définit les traits de stockage.
- `kb_store_pg` fournit le backend PostgreSQL cible.
- `kb_store_sqlite` reste limité aux tests et imports locaux.
- `kb_decoder_api` définit le contrat des décodeurs.
- `kb_materializer_api` définit le contrat des matérialisateurs.
- `kb_materializer_*` contient les projections métier par famille : trades, liquidité, NFT, oracle, lending, routing, compliance audit, etc.
- `kb_pipeline` orchestre backfill, extraction canonique vers core, décodage, matérialisation, agrégation et validation.
- `kb_app_demo` sert de démonstrateur Tauri, sans logique métier lourde. Il charge le profil actif, initialise `kb_logging`, rend le README en HTML et expose une fenêtre dédiée à la configuration.
- Chaque crate opérationnelle doit émettre ses propres événements `tracing` avec une cible canonique égale à son nom Cargo ; `kb_app_demo` reste limité aux frontières UI/Tauri et aux résumés.
- Chaque profil écrit des fichiers globaux `debug.log`, `info.log`, `error.jsonl` et `app.log`, ainsi que `debug.log`, `info.log` et `error.jsonl` dans un répertoire par crate utilisant `tracing`.
- Les interfaces officielles Solana/SPL étroites sont privilégiées ; `wincode` puis Borsh sont préférés, et un parser local borné reste autorisé lorsque l’interface officielle n’expose que `bincode`.
## État `0.4.1` validé
`0.4.1` clôt le décodage et les matérialisations instructionnelles stables des programmes Solana natifs, historiques, loaders, précompiles et surfaces ZK du périmètre core.
`kb_decoder_solana_core` couvre maintenant 18 surfaces exécutables natives : System, Vote, Stake, Config, Compute Budget, Address Lookup Table, Feature, ZK ElGamal Proof, l’ancien ZK Token Proof historique/no-op, Native Loader, BPF Loader v1/v2/Upgradeable/v4, Ed25519, secp256k1, secp256r1 et Slashing. `StakeConfig11111111111111111111111111111111` est classé comme compte historique non exécutable, sans dispatch ni plan d’exécution.
Les matérialisations natives actives sont réparties par famille :
- `kb_materializer_lifecycle` : Address Lookup Table, lifecycle loaders, Feature revoke, durable nonce, comptes System create/allocate, contextes ZK ElGamal et rapports Slashing ;
- `kb_materializer_admin` : assignations System, écritures Config opaques, changements d’autorité Loader ;
- `kb_materializer_compliance_audit` : écritures/copies de bytecode Loader et profil transactionnel Compute Budget ;
- `kb_materializer_staking` : projections instructionnelles Stake/Vote commitées, sans prétendre reconstruire les snapshots finaux.
Les précompiles de signature, les preuves ZK sans compte de contexte et l’ancien ZK Token Proof restent en decode/audit, sans duplication dans `kb_sol_mat_events` tant qu’aucun consommateur dédié ne l’exige. Les transactions échouées restent décodées comme intentions ou échecs, mais les matérialiseurs mutables appliquent `SuccessfulCommittedOnly`.
Les validations finales de `0.4.1` couvrent les tests unitaires, PostgreSQL réel, Clippy et des replays mainnet ciblés : System, Config, Stake, Vote, Compute Budget, ALT, ZK ElGamal et Slashing synthétique. Les replays terminent sans `unmatched`, `failedInputs` ou `unsupported`; les archives de logs fournies ont des `error.jsonl` vides.
## Couche d'exécution
Le workspace développe une couche d'exécution séparée du décodage. Les crates `kb_executor_*` sont des bibliothèques universelles : elles construisent des plans pour les applications de trading, les CLI, les workers, les outils d'administration et de futurs exécutables indépendants.
Les opérations dangereuses ne sont pas supprimées des bibliothèques. Elles doivent être encodées, testées et protégées par des politiques renforcées, tandis que `kb_app_demo` peut volontairement ne pas les exposer. Les exécuteurs ne dépendent ni du wallet, ni du RPC, ni des décodeurs ; l'orchestration assemble ensuite plan, sécurité, simulation, signature, envoi et validation post-exécution.
## Démos live
`kb_app_demo` reste le shell Tauri unique pour valider les capacités du workspace : configuration, logs, DB, RPC, wallet, listeners, décodage, matérialisation, exécution et validation post-transaction.
## Documentation
- `RUST_RULES.md` contient les règles Rust générales réutilisables ; `RULES.md` contient les règles spécifiques et normatives du workspace.
- `ROADMAP.md` contient les étapes futures et changements prévus.
- `CHANGELOG.md` ne reçoit une entrée qu'après validation d'une version.
- `docs/` contient les notes d'architecture et de conception, notamment `TRACING_CONTRACT.md`, `SOLANA_INTERFACE_DEPENDENCIES.md`, `NATIVE_SOLANA_CLOSURE_AUDIT.md`, `NATIVE_SOLANA_MATERIALIZATION_AUDIT.md` et `DEVNET_EXECUTION.md`.
- `validation_sql/` contient les contrôles SQL de validation.
## Jalon validé `0.4.2`
`0.4.2` valide l’infrastructure d’exécution et `kb_executor_solana_core`. L’exécuteur expose **109 opérations déterministes** : dix-sept System, quatre Compute Budget, cinq Address Lookup Table, six formes de précompile, deux Config, deux Feature, deux Slashing, trois ZK ElGamal, vingt-quatre Stake, vingt-quatre Vote, onze Loader v3 et neuf Loader v4. La surface Vote couvre les vingt variantes wire actuelles de `solana-vote-interface 6.0.3` ainsi que quatre plans composés de création legacy/V2, avec ou sans seed. Loader v3 consomme `solana-loader-v3-interface 8.x` et son schéma `wincode`; Loader v4 reproduit explicitement son wire officiel sans activer les helpers conditionnés par `bincode`. BPF Loader v1/v2 restent historiques `decode-only`, Native Loader ne possède pas de builder client et l’ancien ZK Token Proof reste historique. Les opérations nécessitant un état courant restent protégées par un préflight séparé et ne sont pas activées sur Mainnet par ce jalon.
`kb_pipeline` fournit le préflight stateful Localnet/Devnet pour ALT, Config, Feature, Slashing et les contextes ZK ElGamal. Le rapport `Ready`/`Blocked`/`NotRequired` expose les contrôles et faits mesurés avant simulation. `docs/NATIVE_SOLANA_EXECUTION_MATRIX.json` inventorie les dix-huit surfaces et les 109 opérations appelables, avec égalité imposée par un test Rust. La matrice décodeur couvre les mêmes dix-huit surfaces et 121 déclarations de couverture.
`kb_rpc` possède des contrats propres et configurables pour les 52 méthodes HTTP standard et les neuf paires WebSocket standard. Les options restent composables champ par champ et aucun DTO Agave n’est exposé par l’API publique. La session WebSocket persistante gère multiplexage, unsubscribe, timeout, reconnexion et réabonnement. `blockSubscribe`, `slotsUpdatesSubscribe` et `voteSubscribe` sont activables par endpoint ; lorsqu’un nœud les rejette comme indisponibles, la capacité concernée est désactivée automatiquement pour la session et les appels suivants sont refusés localement.
`kb_wallet` fournit un wallet temporaire en mémoire ou persistant sous `wallets/temporary/`, avec fichiers non écrasés, permissions privées et secrets confinés côté Rust. `kb_execution_solana` assemble les transactions, lie la simulation au hash exact du message et signe seulement après autorisation de `kb_execution_safety`. `kb_pipeline` orchestre le parcours backend Devnet complet : contrôle du destinataire et du minimum rent-exempt, financement plafonné, System transfer, simulation exacte, signature, envoi, confirmation, hydratation canonique, extraction core et decode replay ciblé. Ce parcours a été validé réellement sur Devnet avec un transfert de 1 000 000 lamports et PostgreSQL réel.
La frontière Tauri/TS-rs n’émet plus de `bigint` dans les payloads JSON actifs. Les identifiants WebSocket sont contrôlés contre `Number.isSafeInteger`, et les limites du navigateur SQL sont validées côté frontend avant l’appel backend. `cargo tauri dev` avec Vite constitue la validation frontend retenue ; aucun `npm run build` séparé n’est exigé pour cette clôture.
## Jalon validé `0.4.3`
Le prompt `prompts/022_v0_4_3_spl_memo.md` reste l’historique de travail du jalon. Le décodeur contextualisé distingue v1, v3 et v4 avec payload UTF‑8 ou tentative invalide, comptes ordonnés, signataires, outer/inner, hash et intentions non commitées. La projection dédiée `kb_materializer_transaction_annotations` transforme uniquement les Memo réussis et commités en annotations consultables et idempotentes ; les faits d’audit détaillés restent dans le decode. `demo_decode_replay` expose ces sorties comme un journal borné filtrable par signature, avec slot, instruction path, génération, texte, hash et signataires vérifiés.
`kb_executor_spl_memo` expose maintenant un intent typé `AddMemo` et appelle le builder officiel `spl-memo-interface 2.1.0` avec l’ID explicite v1/v3/v4. Le wire reste le texte UTF‑8 brut et chaque signer est readonly, ordonné et visible avant signature. La bibliothèque construit les trois générations sur tout cluster ; la disponibilité effective du programme est vérifiée par la simulation obligatoire, et Mainnet reste régi par les garde-fous communs plutôt que désactivé dans l’exécuteur. La démo opérateur reste volontairement limitée à Memo v4 Devnet et réutilise la fenêtre Solana existante. Elle montre la simulation, l’envoi explicitement confirmé, l’hydratation, l’extraction, le replay, l’annotation et l’idempotence avec des DTO Tauri JSON sans `bigint` actif.
Le parcours a été validé le 15 juillet 2026 avec une simulation seule puis trois transactions v4 Devnet confirmées. Chaque signature a produit une insertion canonique, une extraction core, un événement Memo, une annotation `transaction_annotation` et un second replay `skipped` sans nouvelle sortie. Le corpus Mainnet réel couvre séparément v1, v3 et v4 ; aucun envoi historique v1/v3 sur Devnet n’est revendiqué ni requis.
La matrice `docs/SPL_MEMO_MATRIX.json` conserve les différences historiques, le corpus Mainnet réel, les preuves Devnet v4 et les limitations explicitement non revendiquées pour v1/v3. Le worker d’acquisition historique reste un projet différé indépendant, sans numéro de version attribué.
La validation finale confirme 5 tests `kb_program_ids`, 9 tests décodeur Memo, 7 tests matérialiseur d’annotations, 15 tests exécuteur Memo, 22 tests API d’exécution, 15 tests safety, 12 tests Solana, 61 tests pipeline, 113 tests RPC, 96 tests démo et 46 tests PostgreSQL réels. Le test opt-in Devnet avec envoi et `cargo clippy --all-targets` sont propres. La version active devient `0.4.4 — SPL Token` selon `prompts/023_v0_4_4_spl_token.md`.
## Jalon validé `0.4.4`
Les premières tranches SPL Token établissent la matrice machine-readable des 28 tags publiés par
`spl-token-interface 3.0.0` et remplacent le scaffold du décodeur classique. Le wire local borné
conserve montants bruts, decimals explicites, autorités, comptes ordonnés, chemins outer/inner,
transactions échouées non commitées, suffixes et diagnostics. `Batch` produit un parent d'audit et
des enfants à identités dérivées stables sans accepter de batch imbriqué.
Les matérialiseurs actifs produisent un journal instructionnel `token_account`, des faits admin et
des constats de risque sans score ; aucune fee classique n'est inventée. Le replay Mainnet validé de
370 instructions a produit 371 sorties, huit refus expliqués par huit transactions échouées et un
second replay idempotent sans nouvelle sélection.
`kb_executor_spl_token` expose 24 opérations typées courantes ou récentes avec montants JSON en
chaînes, autorités simples/multisig et builders officiels. Quatre initialisations Rent obsolètes
restent decode-only. `UnwrapLamports` et `Batch` sont constructibles selon l'interface publiée ; leur
déploiement sur le programme classique Devnet a été observé le 16 juillet 2026 par deux simulations
réussies sans signature ni envoi. Localnet, Testnet et Mainnet restent non testés pour ces deux tags.
`0.4.4-pre.005` ajoute le préflight stateful Localnet/Devnet dans `kb_pipeline`. Les lectures RPC
restent hors du décodeur et de l’exécuteur ; elles valident les layouts Mint/Account/Multisig,
l’état, les relations de mint, les soldes, les réserves wrapped SOL, les délégations, les autorités,
les seuils multisig et le rent avant simulation. Les tests standards sont offline et un test Devnet
read-only reste opt-in. La démo Token réutilise la fenêtre d’exécution Solana existante : son panneau
`TransferChecked` expose préflight, simulation, confirmation et validation post-exécution, tandis
qu’un journal matérialisé borné accepte des filtres typés par signature, mint, compte, famille et
opération sans créer une WebView par opération.
Le correctif fonctionnel de `pre.005` ajoute l’orchestration Devnet générique : simulation autonome
après préflight, puis envoi explicitement confirmé lorsque le wallet du profil résout tous les
signataires. Une transaction envoyée est confirmée, hydratée, extraite, décodée et matérialisée,
avant un second replay idempotent. Cette couche ne restreint pas les builders universels aux seuls
clusters ou signataires disponibles dans la démo.
Le parcours `TransferChecked` a été validé réellement sur Devnet le 15 juillet 2026 avec deux
comptes Token auxiliaires du même mint et un wallet isolé correspondant exactement à l’autorité.
Le test opt-in impose désormais la présence de la soumission et de la confirmation, l’absence
d’échec ou de refus au premier replay, au moins une matérialisation Token et un second replay sans
nouvelle sortie ; il imprime aussi la signature afin qu’elle puisse rejoindre le corpus audité.
`0.4.4-pre.006` ajoute un lifecycle destructif explicitement autorisé pour trois comptes classiques
sans ATA. Son correctif crée d'abord les comptes bruts via trois instructions System officielles,
avec keypairs éphémères, rent et tailles 82/165/165 vérifiés, puis onze transactions initialisent le mint et deux comptes Token, mintent et
transfèrent un montant contrôlé, créent puis révoquent une délégation, brûlent exactement les deux
soldes et ferment les comptes Token. Chaque étape est simulée, confirmée, hydratée, décodée,
matérialisée et rejouée une seconde fois avant que l'étape suivante ne soit admise.
Le correctif de reprise du lifecycle traite explicitement les confirmations RPC interrompues : une
signature prédécesseur confirmée est hydratée, extraite, décodée, rapprochée de l'opération attendue
et rejouée idempotemment avant de reprendre à l'index demandé. Un délai borné sépare ensuite les
étapes afin de réduire la pression sur les endpoints Devnet publics, sans masquer leurs erreurs.
Le lifecycle Devnet réel a été validé le 15 juillet 2026 après une interruption du RPC public : la
reprise a récupéré l'initialisation déjà confirmée, puis achevé mint, transfer, approve/revoke, deux
burn et deux close. Chaque étape récupérée ou envoyée a produit exactement une matérialisation et un
second replay idempotent. La fenêtre opérateur `pre.007` permet désormais de rejouer le parcours
représentatif `TransferChecked` et de consulter ces faits `token_account`, `admin` et `risk` comme
événements chronologiques, sans inventer un état final de compte.
L'audit `pre.008` reporte dans `docs/SPL_TOKEN_MATRIX.json` les preuves par instruction. Le corpus
Mainnet réel couvre `Transfer`, `Approve`, `CloseAccount`, `TransferChecked`, `BurnChecked` et
`SyncNative`; ses trois initialisations restent volontairement référencées sous leur nom matérialisé
normalisé sans inventer une variante wire. Le lifecycle Devnet prouve `InitializeAccount3`,
`MintToChecked`, `TransferChecked`, `ApproveChecked`, `Revoke`, `BurnChecked` et `CloseAccount`.
Localnet n'a pas été exécuté, et la publication p-token des tags `45`/`255` n'est pas assimilée à
leur déploiement sur un cluster public.
La validation Tauri de `pre.007` a démarré Vite et l'application, réussi le préflight et la
simulation `TransferChecked`, puis refusé correctement l'envoi sans confirmation opérateur. Avec
confirmation, un second refus a identifié que le wallet du profil et l'autorité Token étaient deux
clés distinctes. La démo ne tente jamais de signer à la place d'une autorité externe ; pour envoyer,
les comptes Token doivent appartenir au wallet persistant sélectionné, comme dans le scénario
backend Devnet déjà confirmé et matérialisé.
La clôture du 16 juillet 2026 confirme les régressions ciblées, PostgreSQL réel, Clippy et Tauri.
Les validations finales couvrent notamment 5 tests Program IDs, 8 tests décodeur Token, 15 tests
exécuteur Token, 9 tests décodeur Memo, 7 tests annotations, 22 tests API d'exécution, 15 tests
safety, 12 tests transaction Solana, 81 tests pipeline, 113 tests RPC, 41 tests configuration,
102 tests démo et 46 tests PostgreSQL réels. Tauri charge 77 routes de logs, simule
`TransferChecked`, bloque l'envoi non confirmé, restitue sa matérialisation commitée exacte et
simule Memo v4 sans erreur runtime.
## Jalon validé `0.4.5`
`0.4.5` clôt la surface SPL Associated Token Account avec
`spl-associated-token-account-interface 2.0.0`. Le décodeur reconnaît exactement `Create`,
`CreateIdempotent`, `RecoverNested` et la forme historique vide de `Create`; il conserve comptes
ordonnés, flags, doublons, outer/inner paths, transactions échouées non commitées et diagnostics
bornés. Les PDA sont dérivés et validés explicitement avec les seeds
`[wallet, Token Program ID, mint]`, ce qui distingue les ATA classiques des ATA Token-2022 sans
prétendre décoder les extensions de ce dernier.
Le lifecycle ATA est possédé par `kb_materializer_token_accounts` : création normale, création ou
réutilisation idempotente non distinguable depuis le parent seul, et récupération nested.
`kb_materializer_risk` possède séparément le constat factuel d'anti-pattern nested récupéré. Les
matérialiseurs lifecycle général, admin et fees déclarent explicitement leur absence de projection,
et les CPI SPL Token conservent seules leurs initialisations, transferts et fermetures. Les
transactions échouées ou structurellement invalides ne produisent aucune mutation.
`kb_executor_spl_associated_token_account` construit les trois variantes actuelles avec les
builders officiels, pour SPL Token classique ou Token-2022. Simulation et dry-run sont obligatoires
par défaut. Le préflight Localnet/Devnet contrôle cluster, mints, Program IDs, dérivations, comptes
existants, signataires, rent et plafonds ; la post-validation vérifie création/réutilisation ou les
conditions de fermeture/transfert de `RecoverNested`.
Les preuves Devnet du 16 juillet 2026 couvrent deux parcours complets `CreateIdempotent` classiques,
la création puis la réutilisation d'un ATA Token-2022 avec `ImmutableOwner`, et un
`RecoverNested` classique transférant 1 000 000 000 unités brutes avant fermeture du nested ATA.
Chaque soumission a été simulée, confirmée, hydratée, extraite, décodée et matérialisée, puis rejouée
sans doublon. La fenêtre Tauri unique expose création ATA et journal lifecycle borné ;
`RecoverNested` reste couvert hors UI par un test opt-in contrôlé.
La validation finale confirme les régressions Token/Memo, 10 tests décodeur ATA, 10 tests exécuteur
ATA, 90 tests pipeline, 113 tests RPC, 41 tests configuration, 111 tests démo, 46 tests PostgreSQL
réels et `cargo clippy --all-targets` propre. Les versions Rust, npm et Tauri sont synchronisées en
`0.4.5`.
## Jalon validé `0.4.6`
`0.4.6` clôt Token-2022 et le registre ElGamal comme surfaces séparées. Token-2022 couvre les instructions de base, les extensions identifiables, les états Mint/Account/Multisig et TLV, les matérialisations propriétaires et les exécuteurs simulation-first. Le registre ElGamal conserve son propre Program ID, sa matrice, son état de 64 octets, son PDA et ses opérations administratives ; il n’est pas fusionné avec Token-2022 ni avec le programme natif ZK ElGamal Proof.
La validation publique Token-2022 comprend huit opérations Devnet confirmées et 55 instructions Mainnet décodées sans échec. La validation réseau ElGamal Registry reste indisponible sur les clusters publics au 20 juillet 2026, mais ses builders, parsers, préflights, preuves et scénarios stateful sont validés synthétiquement/offline. Le bilan détaillé est publié dans `docs/V0_4_6_VALIDATION.md`.
Le replay contextualisé dispose désormais du mode `incomplete_signatures`. Il sélectionne uniquement les signatures contenant au moins une instruction `pending`, `failed`, `replay_requested` ou `unsupported`, applique la limite aux signatures avant expansion et réévalue leurs instructions compatibles sans activer le force replay global. Deux campagnes PostgreSQL réelles ont sélectionné 81 entrées chacune : 1 décodée, 4 unsupported et 76 rejets fail-closed appartenant tous à des transactions Solana échouées.
La régression finale confirme `kb_store_core` 41/41, `kb_store_pg` 46/46 avec PostgreSQL réel, `kb_pipeline` 124/124, `kb_app_demo` 118/118 et `cargo clippy --all-targets` propre.
## Jalon actif `0.4.7`
La suite active est Metaplex Token Metadata selon `prompts/026_v0_4_7_metaplex_token_metadata.md`. La préversion `0.4.7-pre.001` ouvre l’audit avec les crates `kb_decoder_metadata_metaplex_token_metadata` et `kb_executor_metadata_metaplex_token_metadata`, ainsi que `docs/METAPLEX_TOKEN_METADATA_MATRIX.json`, sans activation runtime tant que le wire complet n’est pas prouvé. L’exécuteur existe comme frontière audit-only parce que le SDK officiel fournit des builders, mais il n’expose encore aucune construction de transaction. Ce programme indépendant complète les metadata externes des mints SPL Token classique et Token-2022 sans être absorbé par leurs décodeurs. La priorité porte sur la frontière exacte du Program ID, les PDA et layouts versionnés, les NFT/collections/programmable assets, la provenance des metadata et le replay PostgreSQL idempotent.
Anchor n’est pas requis par les programmes SPL planifiés dans `0.4.x`. Son infrastructure commune est reportée à `0.4.18`, immédiatement avant Meteora, afin d’être conçue à partir des besoins réels des protocoles Anchor sans retarder Metaplex et les autres surfaces Core/SPL.
## Backend de données
PostgreSQL est le backend principal prévu. SQLite reste présent uniquement pour les tests, les imports ponctuels ou les petits corpus locaux.
Les tables Solana PostgreSQL utilisent le schéma courant du profil, généralement `public`. Le projet ne crée pas de schémas applicatifs explicites comme `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`. La séparation logique se fait dans le nom physique de table au format `kb_sol_<domain>_<name>`, par exemple `kb_sol_raw_transactions`.
## Replay des signatures incomplètes
La fenêtre de replay contextualisé de `kb_app_demo` expose un mode `signatures_incomplete`. Il sélectionne uniquement les signatures contenant au moins une instruction `pending`, `failed`, `replay_requested` ou un résultat `unsupported`, puis réévalue les instructions compatibles de ces signatures sans activer le force replay global. La limite porte sur le nombre de signatures incomplètes avant expansion. La matérialisation reste optionnelle et idempotente.
Ce mode est destiné aux backfills croissants : une correction de décodeur peut reprendre seulement les signatures incomplètes au lieu de rejouer toutes les signatures déjà réussies.
## Livraison par delta
Après le squelette initial, les modifications doivent être livrées sous forme de zip delta contenant uniquement les fichiers ajoutés ou modifiés. Un delta multi-module ou racine utilise `khadhroony-bot2_vX.Y.Z-pre.abc-delta.zip`. Un delta limité à un module Rust utilise `kb_modulename_vX.Y.Z-pre.abc-delta.zip`. Un correctif conserve le même numéro `pre.abc` et ajoute `-delta-fix-001.zip`, puis `-fix-002.zip`, au lieu d’incrémenter la préversion. Chaque archive contient un `delta.md` non versionné listant les fichiers ajoutés, modifiés, à supprimer manuellement, ainsi que les validations exécutées ou non exécutées.
## Surfaces réservées
Le workspace réserve dès le squelette les crates de décodage pour les DEX, launchpads, orderbooks, routers, perps et surfaces candidates recensés dans `idls/` et dans la documentation de conception. Ces crates restent des points d'ancrage tant que les discriminants, corpus et règles de matérialisation ne sont pas validés.
## Registres de programmes
Le workspace distingue deux registres :
- `registry/program_registry_seed.toml` pour les surfaces applicatives et protocolaires ;
- `registry/core_program_id_seed.toml` pour les programmes primitifs, loaders, sysvars et comptes natifs Solana/SPL.
Les comptes non exécutables observés pendant la recherche restent documentés dans `docs/ACCOUNT_ONLY_CANDIDATES.md`. Bags dispose maintenant aussi d'une note dédiée dans `docs/BAGS_FM.md` pour les programmes Fee Share V1/V2 confirmés.
## Classification des surfaces
La classification des IDL locales est suivie dans `docs/IDL_SURFACE_CLASSIFICATION.md`. Le registre machine principal reste `registry/program_registry_seed.toml`.
## Configuration, endpoints et listeners
Le workspace utilise `kb_config` pour charger plusieurs profils de configuration, avec un seul profil actif. Le fichier JSON est d'abord validé par `config/schema.config.json`, puis désérialisé et validé par les règles métier Rust.
Le pipeline normalise toutes les sources vers une transaction canonique commune. HTTP JSON-RPC est utilisé d’abord pour les backfills gratuits. Helius `transactionSubscribe` et Yellowstone gRPC seront ajoutés plus tard dans `kb_rpc`, après les décodeurs prioritaires, sans créer de crate provider séparée. La fenêtre `demo_backfill` permet de lancer des campagnes bornées par liste de signatures, programme, token ou pool. En direction « avant, plus anciennes », une ancre vide commence sur la page la plus récente ; la direction « après, plus récentes » exige toujours une signature d’ancrage.
Les listeners WebSocket doivent permettre la détection temps réel des créations de token, créations de pool, migrations, swaps, changements de liquidité et changements sur les tokens ou pools surveillés. Les exports TS-rs de `kb_config` servent uniquement à partager les types Rust/TypeScript avec les applications Tauri comme `kb_app_demo`, puis les futures applications wallet ou finales. Les payloads Tauri partagés, comme la page de configuration, doivent aussi être exportés par TS-rs depuis leur crate applicative.
### Metaplex Token Metadata `0.4.7-pre.016`
L’inventaire officiel complet des modules d’instruction a été réaudité avant le passage aux comptes on-chain. `FreezeDelegatedAccount` et `ThawDelegatedAccount` historiques sont désormais décodés avec leurs contrats exacts ; les autres surfaces encore absentes restent planifiées avant toute déclaration de couverture exhaustive.

1439
docs/legacy-khadhroony-bot2/ROADMAP.md
View File

File diff suppressed because it is too large Load Diff

231
docs/legacy-khadhroony-bot2/RULES.md
View File

@@ -1,231 +0,0 @@
<!-- 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_DECODER_METADATA_METAPLEX_TOKEN_METADATA` 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_DECODER_METADATA_METAPLEX_TOKEN_METADATA` 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 `MtApiEventMaterializer` 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 `MtApiEventMaterializer` 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.

134
docs/legacy-khadhroony-bot2/RUST_RULES.md
View File

@@ -1,134 +0,0 @@
<!-- file: RUST_RULES.md -->
<!-- version: 3 -->
# Règles Rust générales
Ce fichier contient les règles normatives applicables à tous les projets Rust. Elles sont indépendantes de `khadhroony-bot2` et doivent pouvoir être réutilisées telles quelles dans un autre workspace.
## En-têtes et versions de fichiers
- Tout fichier texte qui supporte des commentaires commence par une ligne indiquant son chemin relatif dans le projet, puis une ligne `version` entière.
- La version d'un fichier est incrémentée à chaque modification après validation de sa version précédente.
- Les fichiers Rust utilisent `// file: ...` et `// version: N`.
- Les fichiers Markdown utilisent `<!-- file: ... -->` et `<!-- version: N -->`.
- Tous les fichiers texte se terminent par exactement une fin de ligne.
## Langue et documentation
- Les commentaires et rustdocs du code sont rédigés en anglais.
- Les documents Markdown du projet sont rédigés dans la langue documentaire choisie par le projet.
- Tout élément `pub` ou `pub(crate)` possède une rustdoc utile au point de déclaration.
- Toute réexportation `pub use` ou `pub(crate) use` dans `lib.rs` ou `main.rs` possède également sa propre rustdoc copiée ou reformulée de manière équivalente. La documentation du point d'entrée doit permettre de comprendre l'API sans ouvrir le module interne.
## Édition et lints obligatoires
- L'édition Rust cible est Rust 2024, sauf contrainte explicitement documentée.
- Chaque `lib.rs` et `main.rs` contient :
- `#![warn(missing_docs)]` ;
- `#![deny(unreachable_pub)]` ;
- `#![forbid(unsafe_code)]`.
- Les lints Clippy obligatoires sont déclarés au niveau workspace et hérités par toutes les crates.
- Les règles minimales sont : interdiction de `unwrap`, `expect`, `?`, retours implicites, code `unsafe`, APIs publiques inaccessibles et imports globaux non justifiés.
- Les tests peuvent disposer d'exceptions limitées pour `unwrap` et `expect` uniquement lorsqu'elles sont explicitement autorisées par la configuration Clippy.
La configuration workspace doit au minimum déclarer :
```toml
[workspace.lints.rust]
missing_docs = "warn"
unreachable_pub = "deny"
unsafe_code = "forbid"
[workspace.lints.clippy]
unwrap_used = "deny"
expect_used = "deny"
implicit_return = "deny"
needless_return = "allow"
useless_vec = "deny"
question_mark = "deny"
question_mark_used = "deny"
needless_match = "allow"
manual_ok_err = "allow"
manual_unwrap_or = "allow"
manual_map = "allow"
match_like_matches_macro = "allow"
single_match = "allow"
manual_unwrap_or_default = "allow"
manual_find = "allow"
explicit_counter_loop = "allow"
get_first = "allow"
implicit_saturating_sub = "allow"
```
## Formatage
- `cargo fmt --all` est exécuté après application de chaque delta ou correctif et avant les tests.
- Les fichiers Rust ne contiennent pas de lignes vides à l'intérieur d'une fonction, d'une structure, d'une énumération ou d'une implémentation courte.
- Les lignes vides séparent uniquement les fonctions, blocs `impl`, types et sections logiques.
- Les exports de `lib.rs` ou `main.rs` ne contiennent aucune ligne vide à l'intérieur d'une série homogène de `pub use` ou `pub(crate) use`.
- Les séries `pub use` et `pub(crate) use` forment deux groupes séparés lorsqu'elles coexistent.
## Imports et chemins
- `use` est interdit pour les constantes, fonctions, structures, énumérations, unions, alias de types, modules et macros.
- `use` est autorisé uniquement pour un trait lorsque la résolution de méthode, une macro de dérivation ou une contrainte de langage l'exige réellement.
- Un import de trait doit rester étroit et ne doit jamais importer simultanément des éléments non-traits par accolades.
- Les imports globaux, glob imports et imports groupés par accolades sont interdits.
- Pour un élément fourni par une crate externe au workspace, utiliser directement le chemin public le plus court exposé par cette crate. Exemple : utiliser `external_crate::Struct`, jamais `external_crate::module::Struct` si `external_crate::Struct` existe, et jamais `use external_crate::Struct`.
- Pour un élément `pub` déclaré dans le workspace :
- il est réexporté depuis le `lib.rs` ou `main.rs` de sa crate propriétaire ;
- depuis une autre crate, il est appelé via `owner_crate::Item` ;
- depuis sa propre crate, il est appelé via `crate::Item`, même depuis son module de déclaration.
- Pour un élément `pub(crate)` :
- il est réexporté depuis le `lib.rs` ou `main.rs` via `pub(crate) use` ;
- il est appelé via `crate::Item`, même depuis son module de déclaration.
- Un élément strictement privé à un module n'est pas réexporté et est appelé par son nom local uniquement. Il est interdit d'utiliser un chemin long comme `crate::module::helper` ou `owner_crate::module::helper` pour un helper privé du module courant.
- Dans un sous-module de tests, un élément privé du module parent est appelé via `super::Item`. Un élément `pub` ou `pub(crate)` continue d’être appelé via le point d’entrée de crate le plus court, par exemple `crate::Item`.
- Les exports ne sont jamais groupés avec des accolades. Un type, une fonction, une constante ou un alias correspond à une ligne de réexport distincte.
## Visibilité et API de crate
- Aucun `pub mod` n'est autorisé. Les modules restent privés et l'API est constituée par des réexports explicites.
- Un élément `pub` inaccessible depuis le point d'entrée de sa crate est une erreur de conception, pas un simple avertissement.
- Un élément `pub(crate)` utilisé hors de son module est réexporté au niveau du point d'entrée de la crate.
- Les chemins internes de modules ne font pas partie de l'API stable.
- Les méthodes inhérentes publiques restent appelées via le type réexporté ; les fonctions libres publiques sont appelées via le point d'entrée de crate.
## Helpers et réutilisation
- Un helper répété dans plusieurs modules d'une même crate est déplacé dans un module commun explicite, généralement `helper.rs` ou un module spécialisé plus précis.
- Le nom `helpers.rs` ou `helper.rs` n'est utilisé que si aucune responsabilité métier plus précise ne convient.
- Un helper général réutilisable par plusieurs crates est déplacé dans une crate commune appropriée et exposé publiquement.
- Les types d'erreur généraux, identifiants de programme, primitives de validation et fonctions de sérialisation communes ne doivent pas être dupliqués entre crates.
- La mutualisation ne doit pas créer de dépendance cyclique ni déplacer un comportement métier spécifique dans une crate générique.
## Gestion des erreurs et contrôle de flux
- `unwrap`, `expect` et `panic` sont interdits dans le code de production.
- L'opérateur `?` est interdit dans les chemins de production ; utiliser des `match` explicites avec erreurs contextualisées.
- `anyhow` et `thiserror` ne sont pas utilisés par défaut.
- Les erreurs publiques sont typées lorsque leur contrat est stable ; les diagnostics dynamiques restent bornés.
- Les retours sont explicites conformément au lint `clippy::implicit_return`.
## Sécurité et dépendances
- Le code `unsafe` est interdit.
- Une dépendance n'est ajoutée que si elle est réellement utilisée dans le chemin de compilation concerné.
- Une dépendance utilisée uniquement dans les tests reste dans `[dev-dependencies]`.
- Les features sont minimales et explicites.
## Contrôle avant livraison
Chaque livraison Rust exécute au minimum, dans cet ordre :
```bash
cargo fmt --all
python3 scripts/audit_rust_general_rules.py
python3 scripts/audit_khadhroony_workspace_rules.py
cargo test --workspace
cargo clippy --workspace --all-targets
```
Un projet peut utiliser une sélection de tests plus étroite pendant le développement, mais la fermeture d'une version exige le contrôle global.
Le wrapper `python3 scripts/audit_rust_workspace_rules.py` exécute les deux audits sans fusionner leurs responsabilités.