v0.1.0-pre.074
This commit is contained in:
@@ -1,284 +0,0 @@
|
||||
<!-- file: docs/DOCUMENTATION_REFACTOR_AUDIT.md -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Audit de refonte documentaire
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Cet audit établit l’état documentaire de `khadhroony-bot3` à partir de la base `v0.1.0-pre.062`, en comparaison avec l’archive complète fournie de `khadhroony-bot2 v0.4.7-pre.035-tofix07`.
|
||||
|
||||
Il précède toute refonte massive, tout déplacement des règles secondaires et tout réalignement du versionnement vers `0.4.6+`. Il ne constitue pas un nouvel audit technique des surfaces Solana déjà validées.
|
||||
|
||||
## 2. Sources inspectées
|
||||
|
||||
### 2.1 Racine bot3
|
||||
|
||||
Les fichiers suivants existent à la racine :
|
||||
|
||||
- `README.md` ;
|
||||
- `CHANGELOG.md` ;
|
||||
- `ROADMAP.md` ;
|
||||
- `RULES.md` ;
|
||||
- `docs/rules/RULES_GENERAL.md` ;
|
||||
- `docs/rules/RULES_RUST.md` ;
|
||||
- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
|
||||
- `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md`.
|
||||
|
||||
### 2.2 Documentation active bot3
|
||||
|
||||
Le répertoire `docs/` contient sept documents :
|
||||
|
||||
| Document | Statut initial | Classe proposée |
|
||||
|---------------------------------------|---------------------------------------------------------|----------------------------------------------|
|
||||
| `DEVNET_EXECUTION_GUIDE.md` | actif, volumineux, utilisé pour la validation opérateur | `docs/validation/` ou `docs/guides/` |
|
||||
| `PRE_062_DEVNET_VALIDATION_REPORT.md` | rapport de validation daté | `docs/validation/` |
|
||||
| `OPERATION_NAMING_CONVENTION.md` | normatif | `docs/architecture/` ou `docs/rules/` |
|
||||
| `IDL_AUDIT.md` | audit de migration | `docs/audits/` ou archive bot3 après reprise |
|
||||
| `IDL_TO_KB_LIB_NOMENCLATURE.md` | document de correspondance encore utile | `docs/migrations/` |
|
||||
| `MISSING_PROGRAM_IDLS.md` | état ciblé pouvant évoluer | `docs/audits/` ou `docs/protocols/` |
|
||||
| `IDEA_REMINDERS.md` | liste de rappels non normative | `docs/decisions/` ou TODO généraux ciblés |
|
||||
|
||||
Il n’existe pas encore de `docs/README.md` servant d’index.
|
||||
|
||||
### 2.3 Prompts bot3
|
||||
|
||||
Deux prompts sont présents :
|
||||
|
||||
- `prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md` ;
|
||||
- `prompts/khadhroony-bot3_next-session_after-v0.1.0-pre.062.md`.
|
||||
|
||||
Le premier est un prompt de migration très détaillé et historiquement utile, mais il ne doit pas rester le modèle normatif des futures sessions. Le second correspond au prompt de reprise courant et doit être conservé comme source jusqu’à la production du modèle bot3 et à l’archivage contrôlé des prompts antérieurs.
|
||||
|
||||
### 2.4 Documentation et prompts bot2
|
||||
|
||||
L’archive bot2 fournit :
|
||||
|
||||
- 61 fichiers sous `docs/`, comprenant architecture, stockage, pipeline, transports, exécution, matrices SPL/Core, audits de fermeture et validation `0.4.6` ;
|
||||
- 27 fichiers sous `prompts/`, dont un modèle de session, un index et les prompts historiques jusqu’à `0.4.7` Metaplex Token Metadata ;
|
||||
- un `CHANGELOG.md` structuré de `0.0.1` à `0.4.6` ;
|
||||
- un `ROADMAP.md` contenant l’historique détaillé, les prereleases et les validations opérateur.
|
||||
|
||||
Ces documents sont une source historique et technique. Ils ne sont pas normatifs pour bot3 tant qu’ils n’ont pas été adaptés à sa nouvelle architecture.
|
||||
|
||||
## 3. État de `olddocs/`
|
||||
|
||||
L’absence de `olddocs/` dans l’archive bot3 fournie est volontaire : conserver une copie partielle de bot2 dans chaque archive complète bot3 aurait dupliqué la source historique alors que l’archive complète bot2 est fournie au démarrage de la session documentaire. Ce point n’est donc pas un défaut de la base `pre.062`.
|
||||
|
||||
La reconstruction crée deux archives séparées :
|
||||
|
||||
```text
|
||||
olddocs/archivekbot2/
|
||||
olddocs/archivekbot3/
|
||||
```
|
||||
|
||||
`olddocs/archivekbot2/` doit reproduire l’arborescence documentaire utile de bot2, et pas uniquement son ancien répertoire `docs/`. La structure attendue comprend notamment :
|
||||
|
||||
```text
|
||||
olddocs/archivekbot2/README.md
|
||||
olddocs/archivekbot2/CHANGELOG.md
|
||||
olddocs/archivekbot2/ROADMAP.md
|
||||
olddocs/archivekbot2/RULES.md
|
||||
olddocs/archivekbot2/docs/...
|
||||
olddocs/archivekbot2/prompts/...
|
||||
olddocs/archivekbot2/<ancienne-crate>/README.md
|
||||
olddocs/archivekbot2/<ancienne-crate>/CHANGELOG.md
|
||||
olddocs/archivekbot2/<ancienne-crate>/<autres-documents>.md|json
|
||||
```
|
||||
|
||||
Cette archive est reconstruite depuis l’archive complète bot2 fournie, en conservant les chemins relatifs et sans modifier les fichiers historiques. Les documents bot3 devenus temporaires ou remplacés seront déplacés ultérieurement vers `olddocs/archivekbot3/`, après correction de leurs références.
|
||||
|
||||
Le choix opérationnel est une copie documentaire depuis l’archive bot2, et non un déplacement destructif ni une copie complète du code bot2.
|
||||
|
||||
## 4. Contrat documentaire des crates
|
||||
|
||||
Le workspace déclare 11 crates :
|
||||
|
||||
- `kb-core` ;
|
||||
- `kb-config` ;
|
||||
- `kb-lib` ;
|
||||
- `kb-logging` ;
|
||||
- `kb-program-ids` ;
|
||||
- `kb-pipeline` ;
|
||||
- `kb-pipeline-demo-scenarios` ;
|
||||
- `kb-onchain-transport` ;
|
||||
- `kb-store` ;
|
||||
- `kb-wallet` ;
|
||||
- `kb-app-demo-desktop`.
|
||||
|
||||
État actuel :
|
||||
|
||||
| Crate | README | TODO | USAGE | CHANGELOG |
|
||||
|------------------------------|--------:|-------:|-------:|----------:|
|
||||
| `kb-app-demo-desktop` | absent | absent | absent | absent |
|
||||
| `kb-config` | présent | absent | absent | absent |
|
||||
| `kb-core` | présent | absent | absent | absent |
|
||||
| `kb-lib` | présent | absent | absent | absent |
|
||||
| `kb-logging` | présent | absent | absent | absent |
|
||||
| `kb-onchain-transport` | absent | absent | absent | absent |
|
||||
| `kb-pipeline` | absent | absent | absent | absent |
|
||||
| `kb-pipeline-demo-scenarios` | présent | absent | absent | absent |
|
||||
| `kb-program-ids` | présent | absent | absent | absent |
|
||||
| `kb-store` | présent | absent | absent | absent |
|
||||
| `kb-wallet` | présent | absent | absent | absent |
|
||||
|
||||
Aucune crate ne satisfait donc le contrat complet `README.md`, `TODO.md`, `USAGE.md`, `CHANGELOG.md`.
|
||||
|
||||
La contradiction `USAGES.md` contre `USAGE.md` est résolue en faveur de `USAGE.md`. `001.README.md` reste autorisé uniquement comme index lexical de répertoire très fourni, notamment sous `idls/`, et ne remplace jamais le `README.md` obligatoire d’une crate.
|
||||
|
||||
### 4.4 Frontière de l’archive documentaire
|
||||
|
||||
La première sélection fondée sur toutes les extensions Markdown et JSON était trop large. La sélection doit désormais reposer sur la fonction documentaire autonome du fichier.
|
||||
|
||||
Sont notamment exclus les configurations de build et d’exécution Tauri/npm/TypeScript, les capabilities, les fixtures RPC et les fichiers internes sous `kb_store_core/src/` ou `kb_store_pg/src/`.
|
||||
|
||||
Restent conservés les matrices documentaires, les IDL archivées, `config/example.config.json` et `config/schema.config.json`, conformément à [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md).
|
||||
|
||||
## 5. Évaluation des documents racine
|
||||
|
||||
### 5.1 `README.md`
|
||||
|
||||
Le README racine doit être réécrit comme point d’entrée de bot3 : objectif, architecture consolidée, crates, démarrage, validations et liens documentaires. Il ne doit pas reprendre le journal détaillé de migration.
|
||||
|
||||
### 5.2 `CHANGELOG.md`
|
||||
|
||||
Le changelog bot3 actuel est centré sur les prereleases `0.1.0-pre.*`. Il doit être reconstruit sans perdre cette traçabilité, puis enrichi par l’historique pertinent de bot2 de `0.0.1` à `0.4.6` et par une section explicite de transition bot2 vers bot3.
|
||||
|
||||
Le changelog bot2 ne doit pas être supprimé de la source historique avant reprise complète. Sa copie archivée constituera la référence de contrôle.
|
||||
|
||||
### 5.3 `ROADMAP.md`
|
||||
|
||||
Le roadmap bot3 actuel est encore largement une checklist de migration et de prereleases. Le roadmap bot2 contient lui aussi un historique détaillé et des prereleases. Aucun des deux ne satisfait le nouveau contrat général.
|
||||
|
||||
Le futur `ROADMAP.md` doit être reconstruit par versions mineures et grands lots, sans prerelease ni correctif `fix`, avec dépendances, critères de sortie et liens vers les TODO/changelogs des crates.
|
||||
|
||||
### 5.4 `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md`
|
||||
|
||||
Ce document conserve une forte valeur de traçabilité, mais il ne doit pas rester un document actif permanent après clôture de la migration. Il doit alimenter l’audit d’alignement `0.4.6`, les TODO ciblés et la section de transition du changelog, puis être archivé sous `olddocs/archivekbot3/`.
|
||||
|
||||
## 6. Règles et références à corriger
|
||||
|
||||
Le déplacement des règles secondaires vers `docs/rules/` ne doit pas être effectué dans le premier delta.
|
||||
|
||||
Références actives identifiées :
|
||||
|
||||
- `RULES.md` lie directement les trois fichiers secondaires à la racine ;
|
||||
- les scripts, prompts et documents actifs doivent employer les chemins `docs/rules/...` ;
|
||||
- `docs/rules/RULES_SPECIFIC_KHADHROONY.md` lie `docs/rules/RULES_GENERAL.md` et `docs/rules/RULES_RUST.md` par chemins relatifs racine ;
|
||||
- `scripts/audit_khadhroony_workspace_rules.py` vérifie explicitement les quatre chemins racine à deux endroits ;
|
||||
- les deux prompts bot3 citent les chemins racine ;
|
||||
- `KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md` décrit l’organisation actuelle.
|
||||
|
||||
Avant déplacement, il faudra :
|
||||
|
||||
1. modifier `RULES.md` pour pointer vers `docs/rules/` ;
|
||||
2. corriger les liens relatifs internes aux règles ;
|
||||
3. adapter les chemins attendus par `scripts/audit_khadhroony_workspace_rules.py` ;
|
||||
4. vérifier le lanceur `scripts/audit_rust_workspace_rules.py` ;
|
||||
5. corriger README, prompts, documents d’onboarding et checklist de migration ;
|
||||
6. exécuter l’audit workspace et les validations adaptées aux fichiers modifiés avant livraison. Les commandes Git restent sous la responsabilité de l’opérateur et ne font pas partie des validations demandées à la session.
|
||||
|
||||
## 7. Analyse des prompts
|
||||
|
||||
### 7.1 Modèles bot2 à reprendre
|
||||
|
||||
Les meilleurs modèles structurels sont :
|
||||
|
||||
- `prompts/001_version_session_template.md` pour le squelette minimal ;
|
||||
- `prompts/020_v0_4_1_native_solana_programs.md` pour les sources de vérité, le phasage et les critères de sortie ;
|
||||
- `prompts/022_v0_4_3_spl_memo.md` à `026_v0_4_7_metaplex_token_metadata.md` pour la structure numérotée, les frontières, matrices, validations et livraisons.
|
||||
|
||||
### 7.2 Informations bot3 à conserver
|
||||
|
||||
Le futur modèle bot3 doit préserver :
|
||||
|
||||
- l’architecture consolidée autour de `kb-lib`, `kb-store`, `kb-pipeline`, `kb-onchain-transport` et des crates de démonstration ;
|
||||
- les décisions de nommage des crates et binaires ;
|
||||
- les règles Tauri et TS-RS ;
|
||||
- l’état Git et la base d’archive de départ ;
|
||||
- les validations réellement exécutées ;
|
||||
- le statut explicite des surfaces reportées, notamment ElGamal ;
|
||||
- les conventions de delta sans SHA-256 ;
|
||||
- les fichiers normatifs et documents d’architecture à lire.
|
||||
|
||||
### 7.3 Traitement proposé
|
||||
|
||||
Les prompts bot3 existants restent temporairement en place. Après création d’un modèle bot3 et d’un index :
|
||||
|
||||
- le prompt de reprise `pre.062` sera archivé comme preuve de transition ;
|
||||
- le prompt de migration réordonné sera archivé après extraction des décisions encore utiles ;
|
||||
- les futurs prompts actifs seront courts, versionnés par mission et séparés des archives historiques.
|
||||
|
||||
## 8. Classement documentaire proposé
|
||||
|
||||
Arborescence cible à valider progressivement :
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── README.md
|
||||
├── architecture/
|
||||
├── audits/
|
||||
├── decisions/
|
||||
├── generated/
|
||||
├── guides/
|
||||
├── migrations/
|
||||
├── protocols/
|
||||
├── rules/
|
||||
└── validation/
|
||||
```
|
||||
|
||||
Principes de classement :
|
||||
|
||||
- `architecture/` : contrats transversaux et conventions structurelles ;
|
||||
- `audits/` : audits actifs servant une décision non encore clôturée ;
|
||||
- `decisions/` : décisions d’architecture ou de périmètre durables ;
|
||||
- `generated/` : index ou artefacts régénérables explicitement suivis ;
|
||||
- `guides/` : procédures d’utilisation et d’exploitation ;
|
||||
- `migrations/` : correspondances bot2/bot3 et rapports de migration actifs ;
|
||||
- `protocols/` : documents techniques par programme ou famille Solana ;
|
||||
- `rules/` : règles normatives secondaires ;
|
||||
- `validation/` : guides, campagnes et rapports de validation.
|
||||
|
||||
Les déplacements ne doivent commencer qu’après création de `docs/README.md` et correction planifiée de toutes les références.
|
||||
|
||||
## 9. Écarts et contradictions déjà démontrés
|
||||
|
||||
Les écarts suivants sont établis sans nouvel audit fonctionnel des protocoles :
|
||||
|
||||
1. absence volontaire de `olddocs/` dans la base bot3 fournie, à reconstruire depuis l’archive complète bot2 ;
|
||||
2. absence de `docs/README.md` ;
|
||||
3. contrat documentaire incomplet pour les 11 crates ;
|
||||
4. contradiction `USAGES.md` contre `USAGE.md`, résolue en faveur de `USAGE.md` ;
|
||||
5. règles secondaires encore liées à la racine par le code d’audit et les prompts ;
|
||||
6. changelog bot3 ne reprenant pas encore l’historique bot2 ;
|
||||
7. roadmap général encore mélangé à la checklist de migration et aux prereleases ;
|
||||
8. prompts bot3 non encore reconstruits depuis les modèles bot2 ;
|
||||
9. statut documentaire de `kb-wallet` insuffisant au regard de son état d’ébauche ;
|
||||
10. absence de l’audit ciblé `docs/V0_4_6_ALIGNMENT_AUDIT.md`.
|
||||
|
||||
## 10. Ambiguïtés bloquantes
|
||||
|
||||
Aucune ambiguïté ne bloque la première livraison d’audit.
|
||||
|
||||
Les choix suivants restent à trancher avant les deltas de déplacement, mais ne bloquent pas l’archivage documentaire ni la correction des règles :
|
||||
|
||||
- emplacement final de `OPERATION_NAMING_CONVENTION.md` entre `architecture/` et `rules/` ;
|
||||
- maintien temporaire ou archivage immédiat de `IDEA_REMINDERS.md` après ventilation dans les TODO ;
|
||||
- convention de nommage des prompts bot3 actifs et archivés ;
|
||||
- niveau de détail historique conservé dans le changelog général par rapport aux changelogs de crates.
|
||||
|
||||
## 11. Conclusion
|
||||
|
||||
La base technique peut servir à la refonte documentaire, mais elle n’est pas encore démontrée comme officiellement alignée sur `0.4.6`.
|
||||
|
||||
La prochaine étape contrôlée est l’application du plan décrit dans `docs/DOCUMENTATION_REFACTOR_PLAN.md`, par deltas séparés, avant la création de `docs/V0_4_6_ALIGNMENT_AUDIT.md` et avant toute modification des versions Cargo.
|
||||
|
||||
## 12. Précisions acquises après le premier audit
|
||||
|
||||
- L’absence initiale de `olddocs/` dans bot3 était volontaire ; l’archive bot2 fournie séparément évitait une duplication pendant la migration.
|
||||
- Les documents actifs ne seront jamais déplacés ni générés automatiquement depuis `olddocs/archivekbot2/`. Chaque document bot3 sera créé après lecture et adaptation des sources pertinentes.
|
||||
- Les matrices de contrats actives sont déjà centralisées sous `test-fixtures/contract-matrices/` et ne doivent pas être recopiées dans `docs/`.
|
||||
- Le registre ElGamal est implémenté dans `kb-lib`; son intégration pipeline reste à vérifier précisément, son panneau desktop n’est qu’une présentation et son déploiement Devnet/Mainnet ne doit pas être supposé.
|
||||
- La migration bot3 a commencé en cours de `0.4.7` après réalisation du décodeur Metaplex Token Metadata dans bot2 ; ce décodeur existe déjà dans bot3, tandis que le reste de la surface doit être évalué.
|
||||
- La classification des IDL est un besoin actif immédiat à cause du renommage massif déjà effectué. Elle n’est pas reportée à `0.6.x`; seules les infrastructures Anchor supplémentaires relèvent de cette série.
|
||||
- Chaque changelog de crate devra contenir au minimum une section `0.1.0` retraçant sa migration depuis bot2, sa consolidation dans bot3 et l’adoption des nouvelles normes Rust et Khadhroony.
|
||||
- Les TODO pourront intégrer des idées de `docs/IDEA_REMINDERS.md` uniquement après confirmation, attribution, vérification et réordonnancement.
|
||||
@@ -1,400 +0,0 @@
|
||||
<!-- file: docs/DOCUMENTATION_REFACTOR_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Plan de refonte documentaire
|
||||
|
||||
## 1. Objectif
|
||||
|
||||
Ce plan transforme progressivement la documentation de `khadhroony-bot3 v0.1.0-pre.062` sans mélanger audit, déplacements, réécriture historique, documentation par crate et décision de réalignement vers `0.4.6`.
|
||||
|
||||
Aucune version Cargo ne doit être modifiée avant la conclusion de `docs/V0_4_6_ALIGNMENT_AUDIT.md`.
|
||||
|
||||
## 2. Principes d’exécution
|
||||
|
||||
- livrer des deltas courts et thématiques ;
|
||||
- ne pas créer en masse des documents vides ;
|
||||
- documenter une crate à partir de ses APIs publiques, binaires, tests et configurations réels ;
|
||||
- ne jamais déplacer ni migrer automatiquement un document depuis `olddocs/archivekbot2/` ;
|
||||
- créer des documents bot3 nouveaux après lecture, sélection, vérification et adaptation des sources historiques ;
|
||||
- référencer les matrices canoniques de `test-fixtures/contract-matrices/` sans les dupliquer ;
|
||||
- ne pas inventer d’API ou de validation ;
|
||||
- archiver avant de retirer un document ayant une valeur historique ;
|
||||
- corriger toutes les références avant chaque déplacement ;
|
||||
- conserver séparément les archives bot2 et bot3 ;
|
||||
- ne pas rouvrir les audits techniques Solana déjà validés sans écart concret ;
|
||||
- exécuter uniquement les validations réellement nécessaires au delta.
|
||||
|
||||
## 3. Contrat documentaire à inscrire dans les règles
|
||||
|
||||
Chaque crate du workspace doit posséder les quatre fichiers suivants :
|
||||
|
||||
```text
|
||||
README.md
|
||||
TODO.md
|
||||
USAGE.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
### 3.1 `README.md`
|
||||
|
||||
Contenu minimal :
|
||||
|
||||
- objectif et périmètre ;
|
||||
- responsabilités et exclusions ;
|
||||
- fonctionnalités principales ;
|
||||
- principales APIs ou façades ;
|
||||
- relations avec les autres crates ;
|
||||
- liens vers `USAGE.md`, `TODO.md`, `CHANGELOG.md` et l’architecture pertinente.
|
||||
|
||||
Le README ne contient pas le journal détaillé des versions.
|
||||
|
||||
### 3.2 `TODO.md`
|
||||
|
||||
Sections minimales :
|
||||
|
||||
- fonctionnalités manquantes ;
|
||||
- dette technique ;
|
||||
- tests manquants ;
|
||||
- validations Devnet/Mainnet manquantes ;
|
||||
- documentation manquante ;
|
||||
- dépendances externes ;
|
||||
- éléments reportés ;
|
||||
- hors périmètre.
|
||||
|
||||
Les sections sans élément doivent indiquer explicitement qu’aucun élément n’est actuellement recensé, plutôt que rester vides.
|
||||
|
||||
### 3.3 `USAGE.md`
|
||||
|
||||
Contenu minimal :
|
||||
|
||||
- objectif ;
|
||||
- prérequis ;
|
||||
- configuration ;
|
||||
- APIs publiques significatives ;
|
||||
- description des types importants ;
|
||||
- erreurs et invariants ;
|
||||
- exemples réalistes ou compilables ;
|
||||
- au moins un exemple par API publique significative ;
|
||||
- limites connues ;
|
||||
- liens vers tests, fixtures et matrices.
|
||||
|
||||
Une API n’est documentée qu’après vérification dans le code et les exports publics.
|
||||
|
||||
### 3.4 `CHANGELOG.md`
|
||||
|
||||
Le changelog de crate distingue :
|
||||
|
||||
- non publié ;
|
||||
- releases ;
|
||||
- prereleases ;
|
||||
- correctifs `fix` ;
|
||||
- ajouts ;
|
||||
- modifications ;
|
||||
- corrections ;
|
||||
- suppressions ;
|
||||
- migrations ;
|
||||
- compatibilité ;
|
||||
- validations ;
|
||||
- limitations connues.
|
||||
|
||||
Il est mis à jour pour tout changement fonctionnel de la crate. Les changements purement documentaires peuvent être regroupés dans une entrée documentaire explicite.
|
||||
|
||||
## 4. Arborescence cible
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── README.md
|
||||
├── architecture/
|
||||
├── audits/
|
||||
├── decisions/
|
||||
├── generated/
|
||||
├── guides/
|
||||
├── migrations/
|
||||
├── protocols/
|
||||
├── rules/
|
||||
└── validation/
|
||||
|
||||
olddocs/
|
||||
├── archivekbot2/
|
||||
│ ├── README.md
|
||||
│ ├── CHANGELOG.md
|
||||
│ ├── ROADMAP.md
|
||||
│ ├── RULES.md
|
||||
│ ├── docs/
|
||||
│ ├── prompts/
|
||||
│ └── <anciennes-crates>/...
|
||||
└── archivekbot3/
|
||||
```
|
||||
|
||||
Le premier déplacement structurel devra inclure un tableau de correspondance ancien chemin vers nouveau chemin dans `docs/README.md` ou dans un rapport de migration dédié.
|
||||
|
||||
## 5. Séquence de deltas
|
||||
|
||||
### Delta 1 — audit et plan
|
||||
|
||||
Fichiers ajoutés :
|
||||
|
||||
- `docs/DOCUMENTATION_REFACTOR_AUDIT.md` ;
|
||||
- `docs/DOCUMENTATION_REFACTOR_PLAN.md`.
|
||||
|
||||
Aucun déplacement et aucune réécriture massive.
|
||||
|
||||
Validations :
|
||||
|
||||
```bash
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
```
|
||||
|
||||
### Delta 2 — archives et index documentaire
|
||||
|
||||
Travail :
|
||||
|
||||
1. créer `olddocs/archivekbot2/` ;
|
||||
2. y reconstruire le miroir documentaire de bot2 en conservant les chemins relatifs : documents racine, `docs/`, `prompts/` et documents des anciennes crates ;
|
||||
3. inclure les fichiers présentant une fonction documentaire démontrée, conformément à la politique de sélection, sans copier le code, les artefacts de build ou les données privées ;
|
||||
4. appliquer [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) pour distinguer matrices, schémas, exemples et IDL documentaires des fixtures et configurations d’exécution ;
|
||||
4. créer `olddocs/archivekbot3/` ;
|
||||
5. créer `docs/README.md` ;
|
||||
6. créer l’arborescence utile sans fichiers factices ;
|
||||
7. documenter la provenance, la non-normativité et l’intégrité logique de l’archive bot2.
|
||||
|
||||
Aucun document bot3 actif ne doit encore être supprimé.
|
||||
|
||||
### Delta 3 — règles documentaires (`v0.1.0-pre.065`)
|
||||
|
||||
Travail :
|
||||
|
||||
1. corriger `docs/rules/RULES_GENERAL.md` pour imposer les quatre fichiers exacts par crate ;
|
||||
2. interdire `USAGES.md`, retenir définitivement `USAGE.md` et encadrer l’exception `001.README.md` pour les index lexicaux ;
|
||||
3. créer `docs/rules/CRATE_DOCUMENTATION_RULES.md` ;
|
||||
4. définir la frontière entre README, TODO, USAGE, CHANGELOG général et changelogs de crates ;
|
||||
5. imposer que `USAGE.md` documente uniquement les APIs publiques réellement accessibles ;
|
||||
6. imposer dans chaque changelog de crate une base `0.1.0` décrivant la migration bot2, la consolidation bot3 et les nouvelles normes ;
|
||||
7. définir la reprise contrôlée des idées confirmées de `docs/IDEA_REMINDERS.md` dans les TODO ;
|
||||
8. interdire toute duplication des matrices canoniques de `test-fixtures/contract-matrices/` ;
|
||||
9. préciser les statuts Metaplex Token Metadata, ElGamal et IDL ;
|
||||
10. fournir quatre modèles documentaires non génératifs.
|
||||
|
||||
Les règles secondaires restent temporairement à la racine dans ce delta.
|
||||
|
||||
### Delta 4 — déplacement des règles secondaires
|
||||
|
||||
Travail :
|
||||
|
||||
1. créer `docs/rules/` ;
|
||||
2. déplacer `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md` et `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
|
||||
3. mettre à jour `RULES.md` ;
|
||||
4. corriger les liens internes ;
|
||||
5. adapter `scripts/audit_khadhroony_workspace_rules.py` ;
|
||||
6. corriger les références dans prompts, README et documents d’onboarding ;
|
||||
7. vérifier qu’aucune référence active aux anciens chemins ne subsiste.
|
||||
|
||||
Validations obligatoires :
|
||||
|
||||
```bash
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
```
|
||||
|
||||
### 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 :
|
||||
|
||||
1. préserver une copie historique du changelog bot2 ;
|
||||
2. reconstruire le changelog bot3 ;
|
||||
3. reprendre l’historique fonctionnel pertinent de `0.0.1` à `0.4.6` ;
|
||||
4. ajouter la transition bot2 vers bot3 ;
|
||||
5. documenter consolidation, renommages et validations `0.1.0-pre.*` ;
|
||||
6. conserver les limites, notamment ElGamal non validé Devnet ;
|
||||
7. distinguer clairement version fonctionnelle et prereleases de migration.
|
||||
|
||||
Le changelog ne doit pas affirmer que bot3 est déjà officiellement `0.4.6`.
|
||||
|
||||
### Delta 7 — roadmap général
|
||||
|
||||
Reconstruire `ROADMAP.md` selon les séries suivantes :
|
||||
|
||||
- `0.4.6` : fermeture de l’alignement et écarts résiduels ;
|
||||
- `0.4.7` : poursuite de Metaplex Token Metadata déjà partiellement migré, puis clôture `0.4.x` ;
|
||||
- `0.5.x` : configuration, scénarios autonomes, CLI, fixtures et wallet ;
|
||||
- `0.6.x` : infrastructure Anchor, reste SPL et Metaplex ;
|
||||
- `0.7.x` : Meteora ;
|
||||
- `0.8.x` : Raydium ;
|
||||
- `0.9.x` : Pump ;
|
||||
- `0.10.x` : Orca ;
|
||||
- `0.11.x` : Jupiter ;
|
||||
- `0.12.x` : OKX et autres routers ;
|
||||
- `0.13.x` : transports temps réel ;
|
||||
- `0.14.x` : trading, workers et orchestration ;
|
||||
- `0.15.x+` : extensions futures.
|
||||
|
||||
Le roadmap ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé du passé.
|
||||
|
||||
### Delta 8 — documentation des crates fondamentales
|
||||
|
||||
Ordre proposé :
|
||||
|
||||
1. `kb-core` ;
|
||||
2. `kb-config` ;
|
||||
3. `kb-logging` ;
|
||||
4. `kb-program-ids` ;
|
||||
5. `kb-store`.
|
||||
|
||||
Pour chaque crate : auditer les exports publics, tests, erreurs, exemples existants et dépendances avant de rédiger les quatre fichiers.
|
||||
|
||||
### Delta 9 — documentation du noyau fonctionnel
|
||||
|
||||
Ordre proposé :
|
||||
|
||||
1. `kb-lib` ;
|
||||
2. `kb-pipeline` ;
|
||||
3. `kb-onchain-transport`.
|
||||
|
||||
`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 10 — démonstrations et wallet
|
||||
|
||||
Ordre proposé :
|
||||
|
||||
1. `kb-pipeline-demo-scenarios` ;
|
||||
2. `kb-app-demo-desktop` ;
|
||||
3. `kb-wallet`.
|
||||
|
||||
Les TODO doivent expliciter :
|
||||
|
||||
- l’autonomie incomplète éventuelle des scénarios ;
|
||||
- les contraintes de validation Tauri ;
|
||||
- le statut d’ébauche de `kb-wallet` et son périmètre `0.5.x`.
|
||||
|
||||
### Delta 11 — réorganisation des documents actifs
|
||||
|
||||
Travail :
|
||||
|
||||
- déplacer les guides et rapports Devnet ;
|
||||
- classer les documents IDL ;
|
||||
- classer la convention de nommage ;
|
||||
- ventiler `IDEA_REMINDERS.md` dans les TODO ou décisions ;
|
||||
- mettre à jour toutes les références ;
|
||||
- archiver sous `olddocs/archivekbot3/` les audits et plans remplacés qui conservent une valeur historique.
|
||||
|
||||
Aucun déplacement ne doit laisser de lien cassé.
|
||||
|
||||
### Delta 12 — refonte des prompts
|
||||
|
||||
Travail :
|
||||
|
||||
1. copier ou référencer les prompts bot2 historiques dans l’archive appropriée sans les rendre normatifs ;
|
||||
2. créer `prompts/README.md` ;
|
||||
3. créer un modèle bot3 contenant mission, base validée, périmètre, hors périmètre, règles, architecture, fichiers à lire, tests, critères de clôture, livraison, limites, décisions reportées et état Git ;
|
||||
4. migrer les informations bot3 utiles ;
|
||||
5. archiver les deux prompts de migration actuels lorsque leurs informations ont été reprises.
|
||||
|
||||
### Delta 13 — audit d’alignement `0.4.6`
|
||||
|
||||
Créer :
|
||||
|
||||
```text
|
||||
docs/V0_4_6_ALIGNMENT_AUDIT.md
|
||||
```
|
||||
|
||||
L’audit synthétise, sans réauditer intégralement les protocoles :
|
||||
|
||||
- composants migrés ;
|
||||
- renommages ;
|
||||
- consolidations ;
|
||||
- versions Cargo ;
|
||||
- noms de crates et binaires ;
|
||||
- exports ;
|
||||
- tests ;
|
||||
- validations Devnet ;
|
||||
- ElGamal ;
|
||||
- transports ;
|
||||
- documentation par crate ;
|
||||
- prompts et archives ;
|
||||
- `kb-wallet` ;
|
||||
- futur split de `kb-config` ;
|
||||
- autonomie de `kb-pipeline-demo-scenarios` ;
|
||||
- écarts résiduels.
|
||||
|
||||
Conclusion obligatoire :
|
||||
|
||||
```text
|
||||
READY_FOR_0_4_6
|
||||
READY_WITH_DOCUMENTED_EXCEPTIONS
|
||||
NOT_READY_FOR_0_4_6
|
||||
```
|
||||
|
||||
### Delta 13 — décision de versionnement
|
||||
|
||||
Seulement après validation du delta 12 :
|
||||
|
||||
- décider du passage officiel à `0.4.6` ;
|
||||
- modifier les versions Cargo si la conclusion le permet ;
|
||||
- mettre à jour changelogs, documentation et prompt de session ;
|
||||
- exécuter les validations workspace imposées pour les modifications de code ou de structure.
|
||||
|
||||
## 6. Matrice de validation
|
||||
|
||||
### Documentation pure
|
||||
|
||||
```bash
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
```
|
||||
|
||||
Les opérations Git et leurs contrôles sont réalisés séparément par l’opérateur et ne doivent pas être répétés dans les validations demandées à la session.
|
||||
|
||||
### Code, scripts d’audit ou structure utilisée par le code
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --all-targets
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
```
|
||||
|
||||
Ajouter les tests des crates modifiées.
|
||||
|
||||
### Frontend desktop
|
||||
|
||||
La validation frontend ne doit jamais utiliser `npm --prefix kb-app-demo-desktop run build`.
|
||||
|
||||
La validation runtime se fait par :
|
||||
|
||||
```bash
|
||||
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
|
||||
```
|
||||
|
||||
## 7. Risques contrôlés
|
||||
|
||||
| Risque | Mesure |
|
||||
|----------------------------------------------------|-----------------------------------------------------------------------------|
|
||||
| perte d’historique bot2 | miroir documentaire hiérarchique dans `olddocs/archivekbot2/` avant reprise |
|
||||
| règles introuvables après déplacement | correction préalable des scripts et références, delta dédié |
|
||||
| documentation d’API inventée | lecture des exports et tests avant rédaction |
|
||||
| changelog général trop détaillé | déléguer le détail fonctionnel aux changelogs de crates |
|
||||
| roadmap redevenant une checklist | interdire prereleases et correctifs dans le roadmap général |
|
||||
| confusion entre migration et version fonctionnelle | section de transition explicite et audit d’alignement séparé |
|
||||
| fausse validation ElGamal | conserver le statut non validé Devnet |
|
||||
| modification massive difficile à relire | un thème documentaire par delta |
|
||||
|
||||
## 8. Première décision attendue
|
||||
|
||||
Valider le présent audit et le séquençage des deltas avant :
|
||||
|
||||
- la copie de l’archive bot2 dans `olddocs/` ;
|
||||
- le déplacement des règles ;
|
||||
- la reconstruction du changelog et du roadmap ;
|
||||
- la création des documents par crate ;
|
||||
- la modification des versions Cargo.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/README.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Documentation active de Khadhroony Bot3
|
||||
|
||||
@@ -36,14 +36,13 @@ Modèles documentaires non génératifs :
|
||||
- [`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
|
||||
## 4. Audits et décisions actifs
|
||||
|
||||
- [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md) ;
|
||||
- [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md) ;
|
||||
- [`audits/V0_4_6_ALIGNMENT_AUDIT.md`](audits/V0_4_6_ALIGNMENT_AUDIT.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.
|
||||
Les audits et prompts de migration remplacés sont conservés sous `olddocs/archivekbot3/`.
|
||||
|
||||
## 5. Documents techniques actifs à reclasser
|
||||
|
||||
@@ -71,29 +70,19 @@ Elles peuvent être chargées directement par les tests unitaires ou d’intégr
|
||||
|
||||
## 7. Documentation par crate
|
||||
|
||||
Chaque crate devra posséder :
|
||||
Les onze crates possèdent désormais `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` :
|
||||
|
||||
```text
|
||||
README.md
|
||||
TODO.md
|
||||
USAGE.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Documentation des crates
|
||||
|
||||
Le premier lot documenté comprend :
|
||||
|
||||
- [`kb-lib`](../kb-lib/README.md) ;
|
||||
- [`kb-store`](../kb-store/README.md) ;
|
||||
- [`kb-core`](../kb-core/README.md) ;
|
||||
- [`kb-config`](../kb-config/README.md) ;
|
||||
- [`kb-logging`](../kb-logging/README.md).
|
||||
|
||||
## Audits
|
||||
|
||||
- [Audit d’alignement des TODO par crate](audits/CRATE_TODO_VERSION_ALIGNMENT_AUDIT.md)
|
||||
- [`kb-lib`](../kb-lib/README.md) ;
|
||||
- [`kb-logging`](../kb-logging/README.md) ;
|
||||
- [`kb-program-ids`](../kb-program-ids/README.md) ;
|
||||
- [`kb-pipeline`](../kb-pipeline/README.md) ;
|
||||
- [`kb-pipeline-demo-scenarios`](../kb-pipeline-demo-scenarios/README.md) ;
|
||||
- [`kb-onchain-transport`](../kb-onchain-transport/README.md) ;
|
||||
- [`kb-store`](../kb-store/README.md) ;
|
||||
- [`kb-wallet`](../kb-wallet/README.md) ;
|
||||
- [`kb-app-demo-desktop`](../kb-app-demo-desktop/README.md).
|
||||
|
||||
## Guides
|
||||
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
<!-- file: docs/audits/CRATE_TODO_VERSION_ALIGNMENT_AUDIT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Audit d’alignement des TODO par crate
|
||||
|
||||
## Objectif
|
||||
|
||||
Classer les tâches restantes des onze crates selon leur rapport à l’alignement fonctionnel de `khadhroony-bot3` sur `khadhroony-bot2 0.4.6`, à la reprise de l’objectif `0.4.7` et aux versions ultérieures.
|
||||
|
||||
Cet audit ne constitue pas encore `V0_4_6_ALIGNMENT_AUDIT.md`. Il prépare cet audit en supprimant les ambiguïtés de calendrier dans les TODO.
|
||||
|
||||
## Règles de classement
|
||||
|
||||
### Bloquant avant `0.4.6`
|
||||
|
||||
Une tâche appartient à cette catégorie lorsqu’elle doit démontrer ou rétablir une capacité attendue de bot2 `0.4.6`, ou lorsqu’elle est nécessaire à la clôture documentaire de la migration.
|
||||
|
||||
### Entre `0.4.6` et `0.4.7`
|
||||
|
||||
Cette catégorie contient les travaux nécessaires pour reprendre et achever l’objectif Metaplex Token Metadata interrompu dans bot2.
|
||||
|
||||
### Version ultérieure
|
||||
|
||||
Cette catégorie contient les travaux explicitement planifiés après `0.4.7`, notamment `0.5.x`, `0.6.x`, `0.9.x` et `0.13.x`.
|
||||
|
||||
### Report conditionnel
|
||||
|
||||
Une tâche dépendante d’un déploiement, d’une preuve ou d’une source externe non confirmée n’est pas un blocant de version tant que cette dépendance n’est pas établie.
|
||||
|
||||
## Blocants identifiés avant `0.4.6`
|
||||
|
||||
### `kb-app-demo-desktop`
|
||||
|
||||
- synchronisation complète Tauri/TS-RS ;
|
||||
- couverture explicite des cycles de fenêtres ;
|
||||
- maintien de la session WebSocket après fermeture de `demo_ws` ;
|
||||
- restauration de l’état WebSocket lors de la réouverture.
|
||||
|
||||
Ces points sont des preuves de migration attendues, même lorsque leur comportement paraît déjà implicitement couvert.
|
||||
|
||||
### `kb-pipeline`
|
||||
|
||||
- traitement des écarts concrets révélés par l’audit final ;
|
||||
- guide transversal replay, extraction Core et matérialisation.
|
||||
|
||||
### `kb-onchain-transport`
|
||||
|
||||
- guide transversal RPC, backfill et WebSocket.
|
||||
|
||||
### `kb-store`
|
||||
|
||||
- guide transversal PostgreSQL et contrats de stockage.
|
||||
|
||||
## Travaux entre `0.4.6` et `0.4.7`
|
||||
|
||||
- exécuteur Metaplex Token Metadata dans `kb-lib` ;
|
||||
- vérification et complément de la matérialisation migrée ;
|
||||
- intégration replay et orchestration dans `kb-pipeline` ;
|
||||
- scénarios et validations dans `kb-pipeline-demo-scenarios` ;
|
||||
- panneaux applicatifs dans `kb-app-demo-desktop`.
|
||||
|
||||
## Exceptions documentées
|
||||
|
||||
### Registre ElGamal
|
||||
|
||||
Le registre reste implémenté dans certaines couches, mais sa validation réseau dépend :
|
||||
|
||||
- de la confirmation de son déploiement ;
|
||||
- d’une preuve `PubkeyValidity` ;
|
||||
- d’un compte `Proof Context State` valide.
|
||||
|
||||
Ces tâches restent conditionnelles et ne bloquent pas l’alignement `0.4.6`, à condition que la documentation ne déclare jamais une validation réseau inexistante.
|
||||
|
||||
### `kb-wallet`
|
||||
|
||||
Les capacités avancées sont affectées à `0.5.x`. Le wallet temporaire migré suffit au périmètre historique attendu avant l’alignement.
|
||||
|
||||
### Configuration et logging
|
||||
|
||||
Le split de configuration appartient à `0.5.x` et ne bloque pas `0.4.6`.
|
||||
|
||||
### Transports avancés
|
||||
|
||||
Helius étendu, LaserStream, Yellowstone et la résilience streaming appartiennent à `0.13.x`.
|
||||
|
||||
## Résultat
|
||||
|
||||
Les TODO sont désormais classés par version ou dépendance. Le classement ne prouve pas encore que les blocants `0.4.6` sont satisfaits ; il définit les vérifications à exécuter dans les correctifs de `pre.072` et dans `V0_4_6_ALIGNMENT_AUDIT.md`.
|
||||
314
docs/audits/V0_4_6_ALIGNMENT_AUDIT.md
Normal file
314
docs/audits/V0_4_6_ALIGNMENT_AUDIT.md
Normal file
@@ -0,0 +1,314 @@
|
||||
<!-- file: docs/audits/V0_4_6_ALIGNMENT_AUDIT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Audit ciblé d’alignement `0.4.6`
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Cet audit détermine si `khadhroony-bot3` peut être officiellement aligné sur le périmètre fonctionnel de `khadhroony-bot2 0.4.6`.
|
||||
|
||||
Il ne refait pas les audits protocolaires complets déjà réalisés pour Solana Core, SPL Memo, SPL Token, SPL Associated Token Account, Token-2022 et le registre SPL ElGamal. Il synthétise leur migration, les tests disponibles, les validations Devnet connues et les écarts résiduels démontrés.
|
||||
|
||||
## 2. Base examinée
|
||||
|
||||
Base documentaire et source :
|
||||
|
||||
```text
|
||||
khadhroony-bot3 v0.1.0-pre.073
|
||||
```
|
||||
|
||||
Le workspace contient onze crates :
|
||||
|
||||
1. `kb-core` ;
|
||||
2. `kb-config` ;
|
||||
3. `kb-lib` ;
|
||||
4. `kb-logging` ;
|
||||
5. `kb-program-ids` ;
|
||||
6. `kb-pipeline` ;
|
||||
7. `kb-pipeline-demo-scenarios` ;
|
||||
8. `kb-onchain-transport` ;
|
||||
9. `kb-store` ;
|
||||
10. `kb-wallet` ;
|
||||
11. `kb-app-demo-desktop`.
|
||||
|
||||
Toutes utilisent actuellement la version workspace `0.1.0`. Aucun changement vers `0.4.6` ne doit être effectué avant clôture des blocants de la section 9.
|
||||
|
||||
## 3. Architecture migrée
|
||||
|
||||
### 3.1 Consolidations principales
|
||||
|
||||
| Bot2 | Bot3 | Statut |
|
||||
|------------------------------------|------------------------------|-------------------------------------|
|
||||
| modèles et contrats répartis | `kb-core` et `kb-lib` | migré et consolidé |
|
||||
| décodeurs séparés | modules de `kb-lib` | migré |
|
||||
| exécuteurs séparés | modules de `kb-lib` | migré |
|
||||
| matérialisateurs séparés | modules de `kb-lib` | migré |
|
||||
| stockage core et PostgreSQL séparé | `kb-store` | migré et consolidé |
|
||||
| crates RPC et transports | `kb-onchain-transport` | migré et renommé |
|
||||
| pipeline historique | `kb-pipeline` | migré |
|
||||
| scénarios dépendants du desktop | `kb-pipeline-demo-scenarios` | extraits partiellement |
|
||||
| application de démonstration | `kb-app-demo-desktop` | migrée et renommée |
|
||||
| wallet temporaire | `kb-wallet` | migré, capacités avancées reportées |
|
||||
|
||||
La consolidation modifie la structure des crates, mais ne constitue pas en elle-même un écart fonctionnel.
|
||||
|
||||
### 3.2 Binaires et crates mixtes
|
||||
|
||||
- `kb-app-demo-desktop` reste une crate mixte bibliothèque et binaire ;
|
||||
- `kb-pipeline-demo-scenarios` reste une crate mixte ;
|
||||
- sa bibliothèque s’appelle `kb_pipeline_demo_scenarios` ;
|
||||
- son binaire explicite s’appelle `kb-pipeline-demo-scenarios-cli` ;
|
||||
- `autobins = false` empêche la création d’une cible implicite concurrente.
|
||||
|
||||
## 4. Documentation et règles
|
||||
|
||||
### 4.1 Contrat par crate
|
||||
|
||||
Les onze crates disposent désormais de :
|
||||
|
||||
```text
|
||||
README.md
|
||||
TODO.md
|
||||
USAGE.md
|
||||
CHANGELOG.md
|
||||
```
|
||||
|
||||
Les TODO sont classés par échéance :
|
||||
|
||||
- blocants avant `0.4.6` ;
|
||||
- travaux entre `0.4.6` et `0.4.7` ;
|
||||
- versions ultérieures ;
|
||||
- reports conditionnels.
|
||||
|
||||
### 4.2 Documentation transversale
|
||||
|
||||
Les documents actifs couvrent :
|
||||
|
||||
- architecture générale et carte des crates ;
|
||||
- pipeline et stockage ;
|
||||
- configuration et logging ;
|
||||
- RPC, backfill et WebSocket ;
|
||||
- extraction Core, replay et matérialisation ;
|
||||
- PostgreSQL ;
|
||||
- validation Devnet ;
|
||||
- règles documentaires.
|
||||
|
||||
Les anciens plans et prompts de migration ont été archivés sous `olddocs/archivekbot3/`.
|
||||
|
||||
## 5. Capacités fonctionnelles alignées sur bot2 `0.4.6`
|
||||
|
||||
### 5.1 Fondation et stockage
|
||||
|
||||
- contrats d’erreur et identités de modules ;
|
||||
- configuration typée JSON et schéma embarqué ;
|
||||
- logging structuré ;
|
||||
- stockage canonique, observations, tables Core et decode/materialization ;
|
||||
- migrations PostgreSQL et diagnostics ;
|
||||
- pagination et requêtes de replay bornées.
|
||||
|
||||
### 5.2 Transports et acquisition
|
||||
|
||||
- JSON-RPC HTTP standard ;
|
||||
- WebSocket standard ;
|
||||
- pools et rôles d’endpoints ;
|
||||
- acquisition de signatures et transactions ;
|
||||
- adaptation canonique ;
|
||||
- simulation, soumission et confirmation ;
|
||||
- backfill HTTP, reprise et annulation coopérative.
|
||||
|
||||
### 5.3 Pipeline
|
||||
|
||||
- extraction Core ;
|
||||
- decode replay contextualisé ;
|
||||
- matérialisation optionnelle et idempotente ;
|
||||
- inspections stateful ;
|
||||
- corrélations et préflights Token-2022 ;
|
||||
- orchestration de preuves et postconditions.
|
||||
|
||||
### 5.4 Solana Core et SPL
|
||||
|
||||
Sont migrés jusqu’au périmètre historique de bot2 `0.4.6` :
|
||||
|
||||
- Solana Core et programmes natifs ;
|
||||
- SPL Memo v1, v3 et v4 ;
|
||||
- SPL Token classique ;
|
||||
- SPL Associated Token Account ;
|
||||
- Token-2022 et extensions couvertes ;
|
||||
- registre SPL ElGamal dans les couches effectivement implémentées.
|
||||
|
||||
Memo v1 et v3 restent non exécutables. Memo v4 reste la génération exécutable.
|
||||
|
||||
## 6. Validations connues
|
||||
|
||||
### 6.1 Base `pre.062`
|
||||
|
||||
La base de migration a été déclarée validée avec :
|
||||
|
||||
```text
|
||||
kb-pipeline-demo-scenarios :
|
||||
- 39 tests de bibliothèque
|
||||
- 1 test de binaire
|
||||
|
||||
kb-app-demo-desktop :
|
||||
- 117 tests
|
||||
```
|
||||
|
||||
Audits connus :
|
||||
|
||||
```text
|
||||
General Rust rule audit: clean
|
||||
Rust export completeness audit: 0 candidate(s)
|
||||
Khadhroony workspace rule audit: clean
|
||||
```
|
||||
|
||||
### 6.2 Devnet
|
||||
|
||||
Ont été validés sur Solana Devnet :
|
||||
|
||||
- System Transfer ;
|
||||
- Memo v4 ;
|
||||
- ATA classique ;
|
||||
- ATA Token-2022 ;
|
||||
- SPL Token `TransferChecked` ;
|
||||
- Token-2022 :
|
||||
- `MintToChecked` ;
|
||||
- `TransferChecked` ;
|
||||
- `ApproveChecked` ;
|
||||
- `Revoke` ;
|
||||
- `BurnChecked` ;
|
||||
- `FreezeAccount` ;
|
||||
- `ThawAccount` ;
|
||||
- `CloseAccount`.
|
||||
|
||||
Les parcours couverts incluent simulation, confirmation opérateur, envoi, confirmation, insertion canonique, extraction Core, replay, matérialisation et idempotence.
|
||||
|
||||
### 6.3 Validation exécutée pendant cet audit
|
||||
|
||||
Avec le `Cargo.lock` de référence fourni séparément :
|
||||
|
||||
```text
|
||||
General Rust rule audit: clean
|
||||
Rust export completeness audit: 0 candidate(s)
|
||||
Khadhroony workspace rule audit: clean
|
||||
```
|
||||
|
||||
Les commandes Cargo n’ont pas pu être réexécutées dans l’environnement de production du delta, car le binaire `cargo` n’y est pas disponible. Les résultats historiques ne sont donc pas présentés comme nouvellement exécutés.
|
||||
|
||||
## 7. Éléments non bloquants pour `0.4.6`
|
||||
|
||||
### 7.1 Metaplex Token Metadata
|
||||
|
||||
Le décodeur a été commencé dans bot2 `0.4.7`, puis migré dans bot3. La matérialisation historique doit être vérifiée et les éléments suivants restent à terminer après l’alignement `0.4.6` :
|
||||
|
||||
- exécuteur ;
|
||||
- complément éventuel de matérialisation ;
|
||||
- orchestration pipeline ;
|
||||
- scénarios de démonstration ;
|
||||
- panneaux desktop ;
|
||||
- validations finales.
|
||||
|
||||
Ces travaux appartiennent à la future version fonctionnelle `0.4.7`.
|
||||
|
||||
### 7.2 Registre SPL ElGamal
|
||||
|
||||
Le registre est implémenté dans certaines couches, mais n’est pas déclaré validé sur Devnet ou Mainnet.
|
||||
|
||||
La validation dépend notamment :
|
||||
|
||||
- de la confirmation du déploiement réseau ;
|
||||
- d’un générateur de preuve `PubkeyValidity` ;
|
||||
- d’un compte `Proof Context State` valide ;
|
||||
- d’un scénario opérateur fonctionnel.
|
||||
|
||||
Cette absence de validation réseau ne bloque pas l’alignement sur bot2 `0.4.6`, car bot2 ne disposait pas non plus de cette validation réelle. Elle doit rester explicitement documentée.
|
||||
|
||||
### 7.3 Capacités planifiées après `0.4.7`
|
||||
|
||||
Ne bloquent pas `0.4.6` :
|
||||
|
||||
- split de `kb-config` et configuration logging dédiée en `0.5.x` ;
|
||||
- complétion de `kb-wallet` en `0.5.x` ;
|
||||
- décodeur générique Anchor et surfaces complémentaires en `0.6.x` ;
|
||||
- protocoles Meteora, Raydium, Pump, Orca, Jupiter et autres ;
|
||||
- transports streaming avancés en `0.13.x`.
|
||||
|
||||
## 8. Écarts architecturaux acceptés
|
||||
|
||||
Les différences suivantes sont des choix bot3 validés, pas des régressions :
|
||||
|
||||
- fusion des décodeurs, exécuteurs et matérialisateurs dans `kb-lib` ;
|
||||
- fusion des contrats et implémentations de stockage dans `kb-store` ;
|
||||
- renommage de `kb-rpc` en `kb-onchain-transport` ;
|
||||
- séparation des scénarios réutilisables dans `kb-pipeline-demo-scenarios` ;
|
||||
- maintien de `kb-app-demo-desktop` comme package mixte ;
|
||||
- maintien d’un wallet minimal avant sa complétion en `0.5.x`.
|
||||
|
||||
## 9. Blocants démontrés avant passage officiel à `0.4.6`
|
||||
|
||||
### 9.1 Desktop et contrat Tauri
|
||||
|
||||
Il reste à obtenir une validation explicite et complète de :
|
||||
|
||||
1. la synchronisation des adaptateurs Tauri et des payloads TS-RS avec les APIs réutilisables ;
|
||||
2. la couverture des cycles d’ouverture, fermeture et réouverture des fenêtres concernées.
|
||||
|
||||
### 9.2 Cycle de vie WebSocket
|
||||
|
||||
Le code place la session WebSocket dans `AppState`, distinctement de la fenêtre, et expose des commandes explicites de statut, connexion, désabonnement et déconnexion.
|
||||
|
||||
Il reste néanmoins à valider explicitement :
|
||||
|
||||
1. que fermer `demo_ws` ne ferme pas une session active ;
|
||||
2. que rouvrir `demo_ws` récupère l’état courant ;
|
||||
3. que l’arrêt intervient uniquement sur déconnexion explicite, fermeture de l’application ou timeout prévu.
|
||||
|
||||
Ces validations doivent être couvertes par des tests ou une campagne reproductible avant retrait des tâches du TODO.
|
||||
|
||||
### 9.3 Validation complète dans le workspace réel
|
||||
|
||||
Avant le changement de version, exécuter :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --all-targets
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo test -p kb-pipeline-demo-scenarios
|
||||
cargo test -p kb-app-demo-desktop
|
||||
```
|
||||
|
||||
Exécuter également les tests ciblés de toute crate modifiée par les correctifs issus de cet audit.
|
||||
|
||||
La validation frontend doit utiliser :
|
||||
|
||||
```bash
|
||||
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
|
||||
```
|
||||
|
||||
## 10. Liste fermée des écarts à traiter
|
||||
|
||||
Avant `0.4.6`, traiter uniquement :
|
||||
|
||||
- validation Tauri/TS-RS ;
|
||||
- validation des cycles de fenêtres ;
|
||||
- validation du cycle de vie persistant de `demo_ws` ;
|
||||
- éventuelles corrections directement révélées par ces validations ;
|
||||
- exécution finale des commandes de validation du workspace.
|
||||
|
||||
Aucun nouvel audit complet des protocoles déjà validés n’est requis.
|
||||
|
||||
## 11. Conclusion
|
||||
|
||||
```text
|
||||
NOT_READY_FOR_0_4_6
|
||||
```
|
||||
|
||||
Le périmètre fonctionnel historique de bot2 `0.4.6` est largement migré et les différences architecturales sont documentées. Le passage officiel reste bloqué par des validations desktop/WebSocket explicites et par la validation finale du workspace réel.
|
||||
|
||||
Après clôture de ces points, la conclusion pourra devenir :
|
||||
|
||||
```text
|
||||
READY_WITH_DOCUMENTED_EXCEPTIONS
|
||||
```
|
||||
|
||||
Les exceptions documentées attendues sont le registre ElGamal non validé sur réseau et les travaux Metaplex Token Metadata réservés à `0.4.7`.
|
||||
Reference in New Issue
Block a user