v0.1.0-pre.067

docs/architecture/PROJECT_OBJECTIVES.md

@@ -0,0 +1,75 @@
+<!-- file: docs/architecture/PROJECT_OBJECTIVES.md -->
+<!-- version: 1 -->
+
+# Objectifs du projet Khadhroony Bot3
+
+## 1. Objet
+
+`khadhroony-bot3` est un workspace Rust modulaire destiné à acquérir, normaliser, décoder, matérialiser, valider et, lorsque le contrat le permet, exécuter des opérations Solana.
+
+Il succède à `khadhroony-bot2` en conservant les contrats fonctionnels validés tout en réduisant fortement le nombre de crates et en clarifiant les frontières entre modèles, traitements, stockage, transports, démonstrations et applications.
+
+## 2. Objectifs structurants
+
+Le projet vise à :
+
+- consolider les contrats et implémentations métier dans un noyau maintenable ;
+- conserver des frontières explicites entre acquisition, stockage, pipeline et exécution ;
+- produire des observations et matérialisations déterministes, traçables et rejouables ;
+- appliquer des politiques de validation et de sécurité avant toute exécution ;
+- permettre les campagnes historiques, le traitement temps réel et les validations Devnet ;
+- conserver les preuves de couverture sous forme de tests, fixtures, matrices contractuelles et rapports de validation ;
+- fournir des scénarios réutilisables indépendamment de l’application desktop ;
+- préparer l’ajout progressif de protocoles Solana sans réintroduire une fragmentation excessive du workspace.
+
+## 3. Principes de conception
+
+### 3.1 Consolidation contrôlée
+
+La consolidation ne signifie pas l’effacement des frontières métier. `kb-lib` regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. `kb-store`, `kb-pipeline` et `kb-onchain-transport` restent des crates séparées parce qu’ils représentent des responsabilités opérationnelles différentes.
+
+### 3.2 Contrats explicites
+
+Les APIs publiques, erreurs, invariants, versions de contrats et statuts de validation doivent être explicites. Les comportements implicites, les chemins permissifs et les validations supposées sont évités.
+
+### 3.3 Rejeu et idempotence
+
+Les données acquises doivent pouvoir être rejouées. Les extractions, décodages et matérialisations doivent préserver la traçabilité et éviter les doubles effets lors d’un rejeu.
+
+### 3.4 Sécurité d’exécution
+
+La construction d’une instruction ne suffit pas à autoriser son envoi. Les exécuteurs, préflights, politiques de signataires, limites de frais, simulations et confirmations opérateur forment un contrat distinct.
+
+### 3.5 Documentation fondée sur le code
+
+La documentation active est réécrite pour bot3 à partir du code, des tests, des matrices et des validations actuels. `olddocs/archivekbot2/` sert de source historique non normative ; aucun document n’en est promu automatiquement.
+
+## 4. Périmètre actuel
+
+Le noyau migré couvre notamment :
+
+- Solana Core ;
+- SPL Memo, avec exécution limitée à Memo v4 ;
+- SPL Token classique ;
+- SPL Associated Token Account ;
+- Token-2022 ;
+- registre SPL ElGamal au niveau de certaines couches internes, sans validation Devnet/Mainnet déclarée ;
+- décodeur Metaplex Token Metadata partiellement repris pendant le développement de `0.4.7` ;
+- acquisition HTTP et WebSocket ;
+- stockage PostgreSQL ;
+- replay, extraction Core, décodage, matérialisation et scénarios Devnet.
+
+## 5. Hors périmètre immédiat
+
+Ne sont pas considérés comme achevés :
+
+- l’intégralité de Metaplex Token Metadata ;
+- un wallet utilisateur complet ;
+- l’autonomie complète de tous les scénarios de démonstration ;
+- tous les protocoles Anchor, SPL, Metaplex, AMM, launchpads et routers planifiés ;
+- l’application de trading et les workers de production ;
+- la validation réelle du registre ElGamal sur un cluster où son déploiement et ses prérequis sont confirmés.
+
+## 6. Critères généraux de qualité
+
+Une fonctionnalité n’est considérée comme livrée que si son niveau de preuve est indiqué : compilation, tests, matrice contractuelle, validation synthétique, simulation, Devnet ou Mainnet selon le cas. Une absence de validation externe doit rester visible et ne peut pas être transformée en affirmation de compatibilité.