khadhroony-bot3/prompts/029_v0_5_0_foundation_restructuring_plan.md

Prompt de session — 0.5.0 cadrage de la fondation 0.5.x

Mission

Reprendre khadhroony-bot3 après la clôture validée de 0.4.8 et préparer la série 0.5.x consacrée à la fondation du workspace avant l’ouverture des grands programmes Anchor/DEX.

0.5.0 doit commencer par un audit et un plan complet. Il ne faut pas lancer immédiatement une restructuration de kb-config, kb-wallet ou kb-store sans avoir vérifié les frontières actuelles, les contrats publics, les schémas, les tests et les dépendances du workspace.

La trajectoire cible est :

• 0.5.1 : restructuration de kb-config et contrats de configuration ;
• 0.5.2 : restructuration de kb-wallet ;
• 0.5.3 : audit et normalisation de kb-store en préparation des matérialisations trading/routing ;
• 0.5.4 : centralisation des scénarios dans kb-pipeline-demo-scenarios et audit des exécuteurs/validations manquants.

La première prerelease de 0.5.0 doit produire le plan temporaire de la version et le découpage détaillé des prereleases avant tout changement structurel important.

Base validée à préserver

La release 0.4.8 ferme :

• Solana Program Metadata comme surface indépendante, avec neuf opérations confirmées sur Devnet ;
• les cinq opérations Token-2022 Token Metadata confirmées sur Devnet ;
• la matrice courante Metaplex Token Metadata à 15 confirmed, 5 unavailable, 0 not_run ;
• les scénarios Metadata réutilisables dans kb-pipeline-demo-scenarios et leur intégration desktop ;
• la réconciliation des matrices, exports, registres runtime, IDL, stockage générique et documentation Metadata ;
• la validation finale du workspace par formatage, check, Clippy, audit et cargo test --workspace ;
• le build desktop de release par cargo tauri build, produisant les bundles Linux prévus.

Le registre ElGamal reste une exception connue : implémenté et validé synthétiquement, sans preuve réseau réelle disponible. Ne pas convertir cette exception en tâche implicite de 0.5.0 sans nouvelle possibilité de validation.

Lectures obligatoires avant toute proposition

1. README.md, ROADMAP.md, CHANGELOG.md, RULES.md et ce prompt ;
2. toutes les règles actives sous docs/rules/, en particulier :
   • RULES_GENERAL.md ;
   • RULES_RUST.md ;
   • RULES_SPECIFIC_KHADHROONY.md ;
   • CRATE_DOCUMENTATION_RULES.md ;
   • VERSION_DEVELOPMENT_LIFECYCLE.md ;
3. README.md, USAGE.md, TODO.md et CHANGELOG.md de chaque crate directement concernée ;
4. les documents d’architecture et de stockage actifs ;
5. les schémas, exemples de configuration, migrations SQL, matrices contractuelles et tests existants ;
6. les prompts archivés 027 et 028 uniquement comme références de méthode et d’historique, jamais comme source prioritaire sur le code actuel.

Avant de modifier un contrat public, vérifier son usage réel dans les onze crates et les tests d’API externe.

Règles de développement à conserver

• Rust 2024 ;
• aucune utilisation de unsafe, unwrap, expect ou panic dans le code de production ;
• imports réservés aux traits nécessaires, chemins explicites pour les autres symboles ;
• respect des en-têtes file: / version: et incrément des versions locales des fichiers modifiés ;
• documentation Rust en anglais, documentation Markdown en français ;
• aucune ligne vide interne artificielle dans les fonctions Rust et exactement une newline en fin de fichier ;
• aucune logique métier nouvelle dans kb-app-demo-desktop lorsqu’elle peut résider dans une crate réutilisable ;
• les commandes Tauri restent des adaptateurs minces et n’utilisent ni ? ni unwrap ;
• les archives sous olddocs/ ne sont jamais réécrites hors opération d’archivage explicitement demandée.

Règle frontend/Tauri obligatoire

Ne jamais lancer directement :

npm run dev
npm run build
npm --prefix kb-app-demo-desktop run build

Les commandes npm manuelles sont limitées à l’installation explicite de dépendances nécessaires, notamment npm i et npm i -D.

Le développement desktop est piloté par :

cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

Le build de release est piloté par :

cargo tauri build -c kb-app-demo-desktop/tauri.conf.json

Tauri déclenche lui-même les scripts frontend configurés. Le dist Vite et frontendDist Tauri doivent continuer à désigner le même répertoire de sortie du workspace.

Première prerelease obligatoire de 0.5.0

La première prerelease est exclusivement consacrée au plan et au brainstorming. Elle doit :

• inventorier les responsabilités et couplages de kb-config, kb-logging, kb-wallet, kb-store, kb-pipeline-demo-scenarios et kb-app-demo-desktop ;
• identifier les contrats publics et formats persistés qui ne peuvent pas être modifiés sans migration ;
• comparer le code aux README/USAGE/TODO/changelogs et supprimer les hypothèses obsolètes du plan ;
• établir les problèmes réels et les priorités ;
• proposer un découpage de prereleases bornées pour atteindre les objectifs de 0.5.0 ;
• préciser ce qui appartient réellement à 0.5.0 et ce qui doit rester réservé à 0.5.1 à 0.5.4 ;
• définir les tests, audits, migrations et validations nécessaires avant code ;
• créer un plan temporaire sous docs/plans/, à archiver lors de la dernière prerelease de 0.5.0.

La planification doit être validée avant toute restructuration importante.

Axe 0.5.1 — kb-config

Le plan doit préparer une version dédiée qui :

• restructure kb-config par responsabilités cohérentes ;
• sépare au minimum le schéma de configuration générale du schéma de logging si l’audit confirme cette frontière ;
• autorise d’autres schémas spécialisés uniquement lorsqu’ils réduisent réellement le couplage ;
• audite les profils, valeurs par défaut, validations croisées et erreurs ;
• audite la résolution des variables d’environnement et .env ;
• introduit un camouflage systématique des secrets dans logs, diagnostics, UI, sérialisation et erreurs ;
• interdit qu’un secret résolu soit renvoyé en clair par un payload de configuration ;
• garde les exemples, schémas JSON, TS-RS et documentation alignés.

Axe 0.5.2 — kb-wallet

Préparer :

• l’audit des types de wallets et signers existants ;
• la séparation identité / secret / déverrouillage / signature ;
• les besoins multi-wallets et multi-profils ;
• import/export, chiffrement, sauvegarde/restauration et verrouillage lorsque ces capacités sont retenues ;
• des frontières strictes empêchant la fuite de secrets vers config, logs ou Tauri ;
• des scénarios réutilisables lorsque des validations opérateur sont nécessaires.

Axe 0.5.3 — kb-store

Préparer un audit de fond avant migration :

• contrats DTO, entités, repositories, migrations, index et requêtes ;
• timestamps on-chain et timestamps de persistance séparés explicitement ;
• distinction entre slot, block time ou temps de transaction et temps d’insertion/mise à jour en base ;
• provenance et idempotence ;
• normalisation de la structure du store ;
• champs et index nécessaires aux futures matérialisations trading/routing/multi-pools ;
• interrogation efficace de la création de pools, actifs, liquidité, réserves, prix observés, swaps et séries temporelles ;
• possibilité d’analyser plusieurs pools et routes sans couplage prématuré à Meteora, Raydium, Pump, Orca ou Jupiter.

Aucune table trading spécifique ne doit être inventée avant d’avoir défini les faits stables produits par les matérialisateurs futurs.

Axe 0.5.4 — scénarios et complétude des exécuteurs

Préparer un audit transversal qui :

• détecte les scénarios encore assemblés directement dans kb-app-demo-desktop ;
• déplace leur logique réutilisable vers kb-pipeline-demo-scenarios ;
• laisse le desktop comme adaptateur UI/Tauri uniquement ;
• compare les décodeurs aux exécuteurs disponibles ;
• identifie les exécuteurs manquants réellement justifiés ;
• compare les exécuteurs aux scénarios et validations réseau existants ;
• identifie les capacités présentes dans le desktop sans scénario réutilisable ;
• classe chaque manque comme à implémenter, decode-only, deprecated, unavailable, non applicable ou reporté.

Suite du ROADMAP à respecter

Après 0.5.x :

• 0.6.x : infrastructure Anchor générique et seulement les programmes SPL apportant une valeur directe aux DEX suivants ;
• 0.7.x : Meteora avec alternance decode/materialize puis executor/scénarios ;
• 0.8.x : Raydium selon la même discipline ;
• 0.9.x : Pump ;
• 0.10.x : Orca ;
• 0.11.x : Jupiter ;
• 0.12.x : autres routers/protocoles prioritaires ;
• 0.13.x : transports temps réel ;
• 0.14.x : workers et applications consommatrices ;
• 0.15.x : programmes SPL et Metaplex complémentaires reportés ;
• 0.16.x+ : extensions futures et éventuel kb-offchain-transport.

Ne pas réintroduire en 0.6.x une couverture exhaustive des programmes SPL ou Metaplex qui a été explicitement reportée.

Discipline des scénarios et validations

Pour toute nouvelle capacité exécutable :

1. tests contractuels et synthétiques ;
2. logique de scénario réutilisable dans kb-pipeline-demo-scenarios ;
3. simulation RPC exacte ;
4. soumission Devnet/Testnet lorsque sûre et disponible ;
5. postconditions et matérialisation observables ;
6. panneau desktop seulement comme adaptateur opérateur ;
7. statut de qualification explicite et jamais promu depuis une preuve synthétique seule.

Les scénarios déjà qualifiés ne doivent pas être rejoués automatiquement à chaque refactor si aucune frontière qu’ils couvrent n’a changé.

Documentation et deltas

À chaque prerelease ou correctif :

• mettre à jour uniquement les documents rendus faux ou incomplets ;
• conserver les README/USAGE généralistes ;
• utiliser les changelogs pour la chronologie ;
• supprimer les TODO terminés ;
• maintenir le plan temporaire de la version ;
• livrer uniquement un ZIP delta avec delta.md ;
• ne jamais livrer Cargo.lock, les lockfiles frontend, node_modules, dist, target ou les bindings générés sans nécessité explicite ;
• ne jamais fournir de SHA/checksum dans la réponse de livraison ;
• recommencer la numérotation fix-001 à chaque nouvelle prerelease.

Dernière prerelease obligatoire

La dernière prerelease de 0.5.0 devra :

• exécuter les validations finales ;
• corriger les écarts résiduels ;
• finaliser README, ROADMAP, changelogs, TODO et guides concernés ;
• transférer les décisions durables du plan vers les documents normatifs ;
• archiver le plan et le prompt de session terminés sous olddocs/archivekbot3/ ;
• préparer le prompt de la session suivante ;
• préparer la release finale sans introduire une nouvelle fonctionnalité structurelle majeure.

Contrôles de référence

cargo fmt --all
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
cargo test --workspace

Lorsque le desktop doit être validé :

cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

Pour une validation de release desktop :

cargo tauri build -c kb-app-demo-desktop/tauri.conf.json