v0.1.0-pre.067

2026-07-31 07:38:27 +02:00
parent 06fddf63b3
commit 5382cf8f43
11 changed files with 505 additions and 193 deletions
--- a/docs/DOCUMENTATION_REFACTOR_PLAN.md
+++ b/docs/DOCUMENTATION_REFACTOR_PLAN.md
@@ -1,5 +1,5 @@
 <!-- file: docs/DOCUMENTATION_REFACTOR_PLAN.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->

 # Plan de refonte documentaire

@@ -195,7 +195,20 @@ Validations obligatoires :
 python3 scripts/audit_rust_workspace_rules.py
 ```

-### Delta 5 — changelog général de transition
+### Delta 5 — documentation générale bot3 (`v0.1.0-pre.067`)
+
+Travail :
+
+1. remplacer le README racine obsolète par une présentation stable ;
+2. créer les objectifs et l’architecture générale ;
+3. créer la carte des 11 crates ;
+4. documenter les architectures pipeline et stockage ;
+5. créer une matrice de responsabilités par surface sans dupliquer les matrices contractuelles ;
+6. mettre à jour `docs/README.md`.
+
+Ces documents sont réécrits pour bot3 à partir du workspace actuel et des sources historiques vérifiées.
+
+### Delta 6 — changelog général de transition

 Travail :

@@ -209,7 +222,7 @@ Travail :

 Le changelog ne doit pas affirmer que bot3 est déjà officiellement `0.4.6`.

-### Delta 6 — roadmap général
+### Delta 7 — roadmap général

 Reconstruire `ROADMAP.md` selon les séries suivantes :

@@ -229,7 +242,7 @@ Reconstruire `ROADMAP.md` selon les séries suivantes :

 Le roadmap ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé du passé.

-### Delta 7 — documentation des crates fondamentales
+### Delta 8 — documentation des crates fondamentales

 Ordre proposé :

@@ -241,7 +254,7 @@ Ordre proposé :

 Pour chaque crate : auditer les exports publics, tests, erreurs, exemples existants et dépendances avant de rédiger les quatre fichiers.

-### Delta 8 — documentation du noyau fonctionnel
+### Delta 9 — documentation du noyau fonctionnel

 Ordre proposé :

@@ -251,7 +264,7 @@ Ordre proposé :

 `kb-lib` devra être traité par sections cohérentes et liens vers les matrices, sans transformer son README en catalogue exhaustif de toutes les fonctions.

-### Delta 9 — démonstrations et wallet
+### Delta 10 — démonstrations et wallet

 Ordre proposé :

@@ -265,7 +278,7 @@ Les TODO doivent expliciter :
 - les contraintes de validation Tauri ;
 - le statut d’ébauche de `kb-wallet` et son périmètre `0.5.x`.

-### Delta 10 — réorganisation des documents actifs
+### Delta 11 — réorganisation des documents actifs

 Travail :

@@ -278,7 +291,7 @@ Travail :

 Aucun déplacement ne doit laisser de lien cassé.

-### Delta 11 — refonte des prompts
+### Delta 12 — refonte des prompts

 Travail :

@@ -288,7 +301,7 @@ Travail :
 4. migrer les informations bot3 utiles ;
 5. archiver les deux prompts de migration actuels lorsque leurs informations ont été reprises.

-### Delta 12 — audit d’alignement `0.4.6`
+### Delta 13 — audit d’alignement `0.4.6`

 Créer :

--- a/docs/README.md
+++ b/docs/README.md
@@ -1,84 +1,77 @@
 <!-- file: docs/README.md -->
-<!-- version: 1 -->
+<!-- version: 3 -->

-# Documentation de `khadhroony-bot3`
+# Documentation active de Khadhroony Bot3

-## 1. Rôle
+## 1. Statut

-Ce répertoire contient la documentation active, normative ou encore utilisée de `khadhroony-bot3`.
+Ce répertoire contient la documentation active, normative ou opérationnelle de `khadhroony-bot3`.

-La documentation historique de `khadhroony-bot2` et les documents bot3 remplacés sont conservés séparément sous `olddocs/`. Un document archivé peut servir de source historique, mais il n’est pas normatif pour l’architecture bot3 actuelle.
+La documentation historique de `khadhroony-bot2` est conservée sous `olddocs/archivekbot2/`. Elle ne doit être ni déplacée vers `docs/`, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes.

-## 2. Documents de pilotage actifs
+## 2. Architecture

-| Document                                                                                           | Rôle                                                                              |
-|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
-| [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md)                               | inventaire et écarts documentaires de la base `v0.1.0-pre.062`                    |
-| [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md)                                 | séquence contrôlée de reconstruction documentaire et d’alignement `0.4.6`         |
-| [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md)           | justification durable de la contrainte `wincode 0.5.x` et du contrôle du lockfile |
-| [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) | critères normatifs de conservation et d’exclusion dans les archives documentaires |
+- [`architecture/PROJECT_OBJECTIVES.md`](architecture/PROJECT_OBJECTIVES.md) : objectifs et limites du projet ;
+- [`architecture/ARCHITECTURE.md`](architecture/ARCHITECTURE.md) : couches et flux principaux ;
+- [`architecture/CRATE_MAP.md`](architecture/CRATE_MAP.md) : responsabilités des 11 crates ;
+- [`architecture/PIPELINE_ARCHITECTURE.md`](architecture/PIPELINE_ARCHITECTURE.md) : orchestration, replay et exécution ;
+- [`architecture/STORAGE_ARCHITECTURE.md`](architecture/STORAGE_ARCHITECTURE.md) : contrats de stockage et PostgreSQL ;
+- [`architecture/SURFACE_CRATE_MATRIX.md`](architecture/SURFACE_CRATE_MATRIX.md) : répartition des responsabilités par surface.

-## 3. Documents existants à reclasser
+## 3. Règles

-Les documents suivants restent temporairement à leur chemin actuel jusqu’au delta de réorganisation :
+Le point d’entrée normatif unique est [`../RULES.md`](../RULES.md).
+
+Règles spécialisées :
+
+- [`rules/RULES_GENERAL.md`](rules/RULES_GENERAL.md) ;
+- [`rules/RULES_RUST.md`](rules/RULES_RUST.md) ;
+- [`rules/RULES_SPECIFIC_KHADHROONY.md`](rules/RULES_SPECIFIC_KHADHROONY.md) ;
+- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md).
+
+Modèles documentaires non génératifs :
+
+- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ;
+- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ;
+- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ;
+- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md).
+
+## 4. Audits et décisions en cours
+
+- [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) ;
+- [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) ;
+- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
+- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md).
+
+Ces audits seront archivés sous `olddocs/archivekbot3/` lorsqu’ils auront été remplacés par des documents normatifs ou des rapports de clôture.
+
+## 5. Documents techniques actifs à reclasser
+
+Les documents suivants restent actifs mais seront reclassés progressivement après correction de leurs références :

 - `DEVNET_EXECUTION_GUIDE.md` ;
 - `PRE_062_DEVNET_VALIDATION_REPORT.md` ;
- `OPERATION_NAMING_CONVENTION.md` ;
 - `IDL_AUDIT.md` ;
 - `IDL_TO_KB_LIB_NOMENCLATURE.md` ;
 - `MISSING_PROGRAM_IDLS.md` ;
+- `OPERATION_NAMING_CONVENTION.md` ;
 - `IDEA_REMINDERS.md`.

-Leur présence à la racine de `docs/` est transitoire. Ils ne doivent pas être déplacés avant correction de leurs références.
+Les idées de `IDEA_REMINDERS.md` ne doivent rejoindre un `TODO.md` de crate qu’après confirmation, attribution et reformulation en tâche vérifiable.

-## 4. Arborescence cible
+## 6. Matrices contractuelles
+
+Les matrices canoniques sont conservées sous :

 ```text
-docs/
-├── README.md
-├── architecture/
-├── audits/
-├── decisions/
-├── generated/
-├── guides/
-├── migrations/
-├── protocols/
-├── rules/
-└── validation/
+test-fixtures/contract-matrices/
 ```

-Les répertoires sont créés lorsqu’un document réel doit y être classé. Aucun fichier factice n’est requis.
+Elles peuvent être chargées directement par les tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées sous `docs/`. Les documents actifs peuvent les référencer et expliquer leur rôle.

-## 5. Archives historiques
+## 7. Documentation par crate

-### 5.1 Archive bot2
-
-```text
-olddocs/archivekbot2/
-```
-
-Cette archive reproduit les chemins relatifs des fichiers sélectionnés selon leur fonction documentaire dans l’archive complète bot2 fournie pour la session. La sélection ne dépend pas de l’extension et suit [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md). Elle comprend notamment :
-
- les documents racine historiques ;
- `docs/` ;
- `prompts/` ;
- les README, changelogs et autres documents des anciennes crates ;
- les matrices, schémas, exemples de configuration et IDL ayant une valeur documentaire démontrée.
-
-Les fichiers sont conservés sans adaptation de fond. Les liens relatifs peuvent viser l’ancienne arborescence bot2 et ne garantissent pas une navigation fonctionnelle depuis bot3.
-
-### 5.2 Archive bot3
-
-```text
-olddocs/archivekbot3/
-```
-
-Cette archive recevra progressivement les audits, plans, prompts et documents bot3 remplacés qui conservent une valeur historique, décisionnelle ou de traçabilité.
-
-## 6. Contrat documentaire des crates
-
-Chaque crate doit finalement posséder exactement :
+Chaque crate devra posséder :

 ```text
 README.md
@@ -87,26 +80,4 @@ USAGE.md
 CHANGELOG.md
 ```

-`USAGE.md` est la convention retenue. La variante `USAGES.md` est obsolète.
-
-Le contenu attendu de chaque fichier est défini par [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md). Les modèles de `docs/templates/` servent uniquement d’aide à la rédaction.
-
-## 7. Règles de consultation
-
-Ordre recommandé :
-
-1. `RULES.md` à la racine du workspace ;
-2. les règles secondaires à leur emplacement normatif courant ;
-3. le présent index ;
-4. les documents d’architecture ou de validation liés à la tâche ;
-5. `olddocs/` uniquement pour l’historique ou la reprise contrôlée d’informations.
-
-## Règles et modèles documentaires
-
- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md) : contrat normatif des quatre documents de chaque crate ;
- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ;
- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ;
- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ;
- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md).
-
-Les modèles ne doivent jamais être remplis mécaniquement : la rédaction exige la lecture du code, des exports publics, des tests et des sources historiques pertinentes.
+Leur création commencera après stabilisation des documents transversaux, par lots de crates. `USAGE.md` documentera les APIs publiques réelles et pourra signaler les tests particulièrement instructifs.
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -0,0 +1,107 @@
+<!-- file: docs/architecture/ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture générale
+
+## 1. Vue d’ensemble
+
+Le workspace est organisé en couches orientées responsabilités :
+
+```text
+configuration ─────┐
+logging ───────────┼──────────────┐
+program IDs ───────┘              │
+                                  v
+transport -> store -> pipeline -> kb-lib
+                         │          │
+                         v          v
+                 demo scenarios   wallet/signers
+                         │          │
+                         └────┬─────┘
+                              v
+                    desktop demo application
+```
+
+Cette représentation indique les relations dominantes. Elle ne remplace pas le graphe exact des dépendances Cargo.
+
+## 2. Couches
+
+### 2.1 Fondations
+
+- `kb-core` fournit les erreurs et identités transversales minimales.
+- `kb-config` charge, résout et valide la configuration.
+- `kb-logging` initialise le logging et le tracing.
+- `kb-program-ids` centralise les identifiants de programmes et comptes connus.
+
+### 2.2 Noyau métier
+
+`kb-lib` contient quatre familles principales :
+
+- modèles et contrats partagés ;
+- décodeurs ;
+- exécuteurs ;
+- matérialisateurs.
+
+La façade publique est constituée par les réexports de `kb-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage.
+
+### 2.3 Acquisition et stockage
+
+- `kb-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles d’endpoints, méthodes RPC standard et contrats liés à l’exécution RPC.
+- `kb-store` regroupe les contrats store-neutral et l’implémentation PostgreSQL.
+
+Les transports n’effectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée.
+
+### 2.4 Orchestration
+
+`kb-pipeline` orchestre :
+
+- backfill ;
+- extraction Core ;
+- replay de décodage ;
+- matérialisation ;
+- corrélation stateful ;
+- préflight et orchestration d’exécution pour les surfaces prises en charge.
+
+Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacités de `kb-onchain-transport` sans absorber leurs responsabilités.
+
+### 2.5 Démonstrations et applications
+
+- `kb-pipeline-demo-scenarios` fournit une bibliothèque réutilisable et le binaire `kb-pipeline-demo-scenarios-cli`.
+- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop.
+- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son périmètre reste incomplet.
+
+## 3. Flux principal de données
+
+```text
+Solana RPC / WebSocket
+        │
+        v
+kb-onchain-transport
+        │
+        v
+kb-store (données brutes/canoniques)
+        │
+        v
+kb-pipeline
+        │
+        ├── extraction Core
+        ├── sélection des décodeurs
+        ├── décodage via kb-lib
+        ├── matérialisation via kb-lib
+        └── stockage des résultats
+```
+
+L’exécution suit un flux séparé : intention typée, construction, préflight, simulation, confirmation opérateur, envoi, confirmation et validation postérieure lorsque la surface le permet.
+
+## 4. Frontières obligatoires
+
+- Les IDs canoniques ne doivent pas être dispersés lorsqu’ils appartiennent au registre de `kb-program-ids`.
+- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`.
+- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`.
+- Les scénarios réutilisables doivent migrer vers `kb-pipeline-demo-scenarios` plutôt que rester enfouis dans l’UI.
+- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont consommées par plusieurs tests.
+- Les archives documentaires ne participent ni au build ni aux décisions normatives.
+
+## 5. État de migration
+
+L’architecture bot3 est largement alignée fonctionnellement sur le périmètre bot2 proche de `0.4.6`, avec des travaux `0.4.7` partiellement migrés. L’alignement officiel de version reste conditionné à l’audit ciblé prévu par `docs/V0_4_6_ALIGNMENT_AUDIT.md`.
--- a/docs/architecture/CRATE_MAP.md
+++ b/docs/architecture/CRATE_MAP.md
@@ -0,0 +1,51 @@
+<!-- file: docs/architecture/CRATE_MAP.md -->
+<!-- version: 1 -->
+
+# Carte des crates
+
+## 1. Inventaire
+
+| Crate                        | Type                   | Responsabilité principale                                          | État documentaire                  |
+|------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------|
+| `kb-core`                    | bibliothèque           | erreurs, résultat et identité de module partagés                   | contrat par crate à créer          |
+| `kb-config`                  | bibliothèque           | configuration JSON, environnement, validation et profils           | contrat par crate à créer          |
+| `kb-lib`                     | bibliothèque           | modèles, décodeurs, exécuteurs et matérialisateurs consolidés      | contrat par crate à créer          |
+| `kb-logging`                 | bibliothèque           | initialisation du logging et du tracing                            | contrat par crate à créer          |
+| `kb-program-ids`             | bibliothèque           | registre des programmes et comptes Solana connus                   | contrat par crate à créer          |
+| `kb-pipeline`                | bibliothèque           | backfill, extraction, replay, stateful, préflight et orchestration | contrat par crate à créer          |
+| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI                              | contrat par crate à créer          |
+| `kb-onchain-transport`       | bibliothèque           | transports RPC HTTP/WebSocket et pools d’endpoints                 | contrat par crate à créer          |
+| `kb-store`                   | bibliothèque           | contrats de stockage et adaptateur PostgreSQL                      | contrat par crate à créer          |
+| `kb-wallet`                  | bibliothèque           | wallet temporaire et frontière de signataire                       | ébauche à documenter explicitement |
+| `kb-app-demo-desktop`        | bibliothèque + binaire | application de démonstration Tauri                                 | contrat par crate à créer          |
+
+## 2. Consolidations principales depuis bot2
+
+La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges :
+
+- les modèles et APIs de décodage, matérialisation et exécution ont rejoint `kb-lib` ;
+- les implémentations de stockage core et PostgreSQL ont rejoint `kb-store` ;
+- les responsabilités de pipeline ont été réunies dans `kb-pipeline` ;
+- les transports Solana sont réunis dans `kb-onchain-transport` ;
+- l’application et sa bibliothèque sont réunies dans `kb-app-demo-desktop` ;
+- les scénarios réutilisables ont été extraits dans `kb-pipeline-demo-scenarios`.
+
+Cette carte n’est pas une table de compatibilité exhaustive des anciennes crates. Les correspondances historiques détaillées seront synthétisées dans la documentation de migration et l’audit d’alignement.
+
+## 3. Crates mixtes
+
+### 3.1 `kb-pipeline-demo-scenarios`
+
+- bibliothèque Rust : `kb_pipeline_demo_scenarios` ;
+- binaire : `kb-pipeline-demo-scenarios-cli` ;
+- `autobins = false` évite une cible implicite concurrente.
+
+### 3.2 `kb-app-demo-desktop`
+
+- bibliothèque Rust : `kb_app_demo_desktop_lib` ;
+- binaire : `kb-app-demo-desktop` ;
+- le package reste volontairement unique.
+
+## 4. Relations documentaires
+
+Chaque crate devra disposer de `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md`. Les documents transversaux présents dans `docs/architecture/` évitent de répéter l’architecture complète dans chaque README.
--- a/docs/architecture/PIPELINE_ARCHITECTURE.md
+++ b/docs/architecture/PIPELINE_ARCHITECTURE.md
@@ -0,0 +1,55 @@
+<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture du pipeline
+
+## 1. Responsabilité
+
+`kb-pipeline` coordonne des opérations qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution.
+
+## 2. Familles de traitements
+
+### 2.1 Backfill
+
+Le backfill sélectionne des signatures ou transactions selon une adresse, un programme, un rôle d’endpoint et des bornes explicites. Il gère progression, reprise, annulation et résultats partiels selon les contrats exposés par le pipeline.
+
+### 2.2 Extraction Core
+
+L’extraction Core transforme les transactions stockées en représentations d’instructions contextualisées nécessaires aux décodeurs. Elle constitue une phase distincte du replay de décodage.
+
+### 2.3 Replay de décodage
+
+Le replay sélectionne des candidats, applique les décodeurs compatibles de `kb-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver l’idempotence et les frontières de campagne.
+
+### 2.4 Traitements stateful
+
+Les modules stateful corrèlent instructions, comptes, états précédents et résultats de transaction lorsque le protocole l’exige. Les surfaces SPL Token, ATA, Token-2022 et registre ElGamal disposent de traitements spécialisés à des niveaux différents.
+
+### 2.5 Préflight et exécution
+
+Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `kb-lib` ; le pipeline orchestre leur utilisation.
+
+## 3. Dépendances fonctionnelles
+
+```text
+kb-onchain-transport -> acquisition et appels RPC
+kb-store             -> lecture/écriture canonique et replay
+kb-lib               -> contrats et implémentations métier
+kb-config             -> profils et paramètres opérationnels
+kb-logging            -> observabilité
+kb-wallet             -> signataires lorsque requis
+```
+
+## 4. Scénarios de démonstration
+
+`kb-pipeline-demo-scenarios` doit contenir les scénarios réutilisables hors UI. `kb-app-demo-desktop` adapte leurs requêtes, progrès et résultats en payloads Tauri. Une dépendance à l’application desktop dans le sens inverse serait incorrecte.
+
+## 5. Contrats de preuve
+
+Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contract-matrices/` participent à la preuve contractuelle. Une matrice peut être à la fois une référence lisible et une fixture chargée par le code de test ; elle ne doit pas être dupliquée sous `docs/`.
+
+## 6. Limites connues
+
+- Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
+- Certains scénarios restent à rendre pleinement autonomes hors desktop.
+- La documentation détaillée des APIs publiques du pipeline sera produite dans `kb-pipeline/USAGE.md` après inventaire des exports.
--- a/docs/architecture/PROJECT_OBJECTIVES.md
+++ b/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é.
--- a/docs/architecture/STORAGE_ARCHITECTURE.md
+++ b/docs/architecture/STORAGE_ARCHITECTURE.md
@@ -0,0 +1,64 @@
+<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture du stockage
+
+## 1. Responsabilité de `kb-store`
+
+`kb-store` réunit :
+
+- les contrats store-neutral ;
+- les DTO et entités persistées ;
+- la pagination et les rapports de santé ;
+- les traits de repositories ;
+- l’implémentation PostgreSQL ;
+- les migrations, requêtes et mécanismes de replay associés.
+
+La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL.
+
+## 2. Frontières
+
+### 2.1 Contrats store-neutral
+
+Les contrats ne doivent pas dépendre des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages et erreurs nécessaires aux consommateurs.
+
+### 2.2 Adaptateur PostgreSQL
+
+Le module PostgreSQL possède :
+
+- la connexion et l’initialisation ;
+- l’application idempotente des migrations ;
+- les requêtes typées ;
+- les diagnostics ;
+- les opérations de replay et de sélection de candidats.
+
+### 2.3 Modèles partagés
+
+Les modèles métier communs restent dans `kb-lib` lorsqu’ils dépassent la seule persistance. `kb-store` ne doit pas créer une seconde définition concurrente d’un contrat partagé.
+
+## 3. Catégories de données
+
+Le stockage couvre plusieurs niveaux :
+
+- données brutes acquises ;
+- transactions et instructions canoniques ;
+- événements de décodage et diagnostics ;
+- matérialisations ;
+- états de campagne et candidats de replay ;
+- informations opérationnelles et de santé.
+
+Les noms exacts de tables et APIs publiques seront documentés dans `kb-store/USAGE.md` à partir des exports et migrations actuels.
+
+## 4. Propriétés attendues
+
+- initialisation idempotente ;
+- pagination bornée ;
+- traçabilité des campagnes ;
+- absence de double effet lors des replays ;
+- validation stricte des entrées ;
+- erreurs explicites ;
+- séparation entre données brutes, résultats de décodage et matérialisations.
+
+## 5. Données de test
+
+Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous `test-fixtures/contract-matrices/` lorsqu’elles sont nécessaires aux tests.
--- a/docs/architecture/SURFACE_CRATE_MATRIX.md
+++ b/docs/architecture/SURFACE_CRATE_MATRIX.md
@@ -0,0 +1,35 @@
+<!-- file: docs/architecture/SURFACE_CRATE_MATRIX.md -->
+<!-- version: 1 -->
+
+# Matrice des responsabilités par surface
+
+## 1. Légende
+
+- **Contrat/implémentation** : responsabilité métier principale.
+- **Orchestration** : coordination entre couches.
+- **Persistance** : stockage et replay.
+- **Transport** : acquisition ou appel RPC.
+- **Présentation** : UI ou adaptation de démonstration.
+
+## 2. Matrice
+
+| Surface                 | `kb-lib`                                | `kb-pipeline`                               | `kb-store`             | `kb-onchain-transport` | scénarios                         | desktop                                      |
+|-------------------------|-----------------------------------------|---------------------------------------------|------------------------|------------------------|-----------------------------------|----------------------------------------------|
+| Solana Core             | décodeurs, exécuteurs, matérialisateurs | extraction, replay, exécution               | persistance            | RPC                    | validations Devnet                | panneaux fonctionnels                        |
+| SPL Memo                | décodage v1/v3/v4, exécution v4         | replay et exécution v4                      | persistance            | RPC                    | scénario Memo v4                  | panneau Memo v4                              |
+| SPL Token classique     | contrats et implémentations             | stateful, préflight, orchestration          | persistance            | RPC                    | scénarios Devnet                  | panneaux fonctionnels                        |
+| SPL ATA                 | contrats et implémentations             | état et orchestration                       | persistance            | RPC                    | scénarios classique/Token-2022    | panneaux fonctionnels                        |
+| Token-2022              | contrats et implémentations             | corrélation, preuves, préflight, validation | persistance            | RPC                    | scénarios Devnet                  | panneaux fonctionnels                        |
+| Registre ElGamal        | implémentation partielle confirmée      | traitement stateful à vérifier par API      | persistance selon flux | acquisition de comptes | pas de validation réelle déclarée | présentation non raccordée fonctionnellement |
+| Metaplex Token Metadata | décodeur partiellement migré            | à compléter selon besoins                   | à compléter            | acquisition standard   | à créer/compléter                 | à créer/compléter                            |
+
+## 3. Interprétation
+
+Cette matrice décrit les responsabilités observées au niveau architectural. Elle ne déclare pas une couverture exhaustive de chaque instruction ou compte. La couverture détaillée reste démontrée par le code, les tests et les matrices sous `test-fixtures/contract-matrices/`.
+
+## 4. Statuts sensibles
+
+- Memo v1 et v3 restent non exécutables.
+- Memo v4 est exécutable.
+- Le registre ElGamal ne doit pas être présenté comme validé Devnet/Mainnet.
+- Metaplex Token Metadata appartient au travail `0.4.7` commencé avant la migration et seulement partiellement repris dans bot3.