From 7dddab6d37ae367fbd260407c9dc5f8c55d33050 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Sun, 9 Aug 2026 18:36:58 +0200 Subject: [PATCH] 0.5.0-pre.004 --- CHANGELOG.md | 32 +- Cargo.toml | 4 +- README.md | 4 +- ROADMAP.md | 76 ++- docs/IDEA_REMINDERS.md | 21 +- docs/README.md | 14 +- docs/architecture/ARCHITECTURE.md | 8 +- docs/architecture/CRATE_MAP.md | 12 +- docs/architecture/PIPELINE_ARCHITECTURE.md | 8 +- docs/architecture/PROJECT_OBJECTIVES.md | 8 +- docs/architecture/STORAGE_ARCHITECTURE.md | 6 +- .../KHADHROONY_SOLANA_NAMESPACE_POLICY.md | 117 +++++ olddocs/archivekbot3/001.README.md | 6 +- .../plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md | 58 ++- ...5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md | 0 ...PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md | 80 +-- ...29_v0_5_0_foundation_restructuring_plan.md | 0 prompts/001.README.md | 4 +- ..._khadhroony_solana_namespace_and_config.md | 466 ++++++++++++++++++ 19 files changed, 793 insertions(+), 131 deletions(-) create mode 100644 docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md rename {docs => olddocs/archivekbot3/docs}/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md (82%) rename {docs => olddocs/archivekbot3/docs}/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md (100%) rename {docs => olddocs/archivekbot3/docs}/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md (78%) rename {prompts => olddocs/archivekbot3/prompts}/029_v0_5_0_foundation_restructuring_plan.md (100%) create mode 100644 prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2beac3f..92470d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,40 @@ - + # CHANGELOG — khadhroony-bot3 Ce changelog décrit les évolutions fonctionnelles globales du projet. Il ne recense pas les prereleases, les correctifs `fix` ni le détail de chaque delta. Ces informations appartiennent aux changelogs des crates concernées. +## 0.5.0 — cadrage de la fondation `0.5.x` + +### Architecture et namespaces + +- audit des frontières réelles de configuration, logging, wallet, store, scénarios et desktop avant toute restructuration ; +- adoption de la séparation entre `khadhroony-solana`, domaine des bibliothèques Solana généralistes, et `khadhroony-bot`, domaine applicatif du futur robot de trading ; +- décision de migrer en `0.5.1` les dix crates généralistes vers `ks-*` / `ks_*`, tout en conservant `kb-app-demo-desktop` côté Bot ; +- adoption du namespace d'environnement `KS_*` et des classes `KS_SECRET_*`, `KS_PUBLIC_*` et `KS_*` interne ; +- décision de migrer les identités techniques généralistes vers `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*`. + +### Configuration, wallet et stockage + +- confirmation du split futur entre configuration généraliste et configuration logging, avec documents, schémas et profils indépendants ; +- cadrage d'une séparation entre configuration source, runtime résolue et surfaces publiques/diagnostiques afin qu'aucun secret résolu ne puisse être exposé involontairement ; +- caractérisation du format wallet `0.4.8` comme contrat de migration à préserver ou importer explicitement en `0.5.2` ; +- audit de `kb-store` confirmant les frontières existantes tout en identifiant `block_time`, provenance et index trading/routing comme axes de `0.5.3` ; +- décision de migrer en `0.5.3` les tables Solana `kb_sol_*` vers `k_sol_*`, `kb_*` restant réservé aux éventuelles données réellement spécifiques au Bot. + +### Scénarios et exécution + +- confirmation que les campagnes réutilisables appartiennent à la future crate `ks-pipeline-demo-scenarios`, le desktop restant adaptateur UI/Tauri ; +- inventaire des exécuteurs actifs et réservés sans convertir les surfaces réservées en dette implicite ; +- maintien du registre ElGamal dans son statut synthétique connu en l'absence de nouvelle possibilité de validation réseau. + +### Préparation des versions suivantes + +- transfert des décisions durables vers le ROADMAP, la politique de namespace Khadhroony Solana et les documents d'architecture ; +- archivage du plan et du prompt `0.5.0` ; +- préparation de `0.5.1`, qui ouvrira la migration `ks-*` / `KS_*` et la restructuration sûre de la configuration. + ## 0.4.8 — Solana Program Metadata et complétude Metadata on-chain ### Solana Program Metadata diff --git a/Cargo.toml b/Cargo.toml index 046e5cd..354d72e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 43 +# version: 44 [workspace] resolver = "3" @@ -18,7 +18,7 @@ members = [ ] [workspace.package] -version = "0.5.0-pre.3" +version = "0.5.0-pre.4" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-bot3" diff --git a/README.md b/README.md index ae94c5c..85f78b5 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # Khadhroony Bot3 @@ -21,6 +21,8 @@ Le workspace contient onze crates : - `kb-wallet` : frontière de wallet et signataires ; - `kb-app-demo-desktop` : application Tauri de démonstration et validation opérateur. +La série `0.5.x` prépare la séparation explicite entre le domaine applicatif `khadhroony-bot` et les bibliothèques généralistes `khadhroony-solana`. En `0.5.1`, les dix crates généralistes doivent migrer vers les noms `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` conserve son nom et reste une application du workspace Bot. La politique de migration est définie dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). + Références : - [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) ; diff --git a/ROADMAP.md b/ROADMAP.md index 33492b9..08cb5e3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # ROADMAP — khadhroony-bot3 @@ -56,56 +56,82 @@ Version clôturée et validée. - aucun fetch HTTP, IPFS ou Arweave n’est intégré aux décodeurs canoniques ; - les URI restent des données on-chain observées ; -- `kb-offchain-transport` est reportée à `0.16.x+`, lorsque les workers et consommateurs réels permettront de définir précisément cache, provenance, hash, redirections, MIME, taille, timeout et protection SSRF. +- `ks-offchain-transport` est reportée à `0.16.x+`, lorsque les workers et consommateurs réels permettront de définir précisément cache, provenance, hash, redirections, MIME, taille, timeout et protection SSRF. ## 0.5.x — consolidation des fondations avant l’extension fonctionnelle -La série `0.5.x` existe pour corriger et stabiliser les fondations transversales avant d’empiler les futurs Program IDs et matérialisations métier. L’objectif est d’éviter de devoir modifier tardivement les contrats de configuration, de wallet ou de stockage lorsque Meteora, Raydium, Pump, Orca, Jupiter et les autres protocoles commenceront à dépendre massivement de ces couches. +La série `0.5.x` corrige et stabilise les fondations transversales avant l'ouverture des grands programmes Anchor/DEX. Elle formalise aussi la séparation entre le domaine applicatif `khadhroony-bot` et les bibliothèques généralistes `khadhroony-solana`. + +La politique de namespace et d'ownership adoptée pendant `0.5.0` est documentée dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). ### 0.5.0 — cadrage et plan de restructuration -- auditer l’état réel de `kb-config`, `kb-logging`, `kb-wallet`, `kb-store`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ; -- inventorier les contrats publics, schémas, migrations, dépendances et couplages avant refactor ; -- produire le plan détaillé de la série `0.5.x` et borner les migrations nécessaires ; -- ne pas introduire de nouvelle surface protocolaire importante pendant ce cadrage. +Cadrage clôturé avant toute restructuration majeure : -### 0.5.1 — `kb-config` et configuration sûre +- audit des responsabilités et couplages de `kb-config`, `kb-logging`, `kb-wallet`, `kb-store`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ; +- inventaire des contrats publics, formats persistés, migrations, dépendances, scénarios et preuves de validation ; +- confirmation du split futur entre configuration généraliste et configuration logging ; +- définition de la politique de secrets et du namespace d'environnement `KS_*` ; +- décision de migrer les dix bibliothèques Solana généralistes vers `ks-*` / `ks_*` ; +- décision de migrer les identités techniques généralistes `kb-lib.decoder.*`, `kb-lib.materializer.*` et `kb-lib.executor.*` vers `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ; +- confirmation que `kb-app-demo-desktop` reste côté Bot et peut héberger à terme des démos Solana généralistes et des démos spécifiques au bot ; +- préparation de la normalisation future du store, notamment `block_time`, provenance, idempotence et migration des tables Solana `kb_sol_*` vers `k_sol_*` ; +- maintien de l'exception ElGamal dans son statut synthétique actuel tant qu'aucune nouvelle preuve réseau n'est disponible. -- restructurer `kb-config` par responsabilités cohérentes ; -- créer au minimum des schémas de validation distincts pour la configuration générale et la configuration logging lorsque l’audit confirme cette frontière ; -- ajouter d’autres schémas spécialisés seulement lorsqu’ils réduisent réellement le couplage ; -- revoir les profils, valeurs par défaut, validations croisées, erreurs et résolutions de variables d’environnement ; -- traiter explicitement les secrets issus de `.env` et des variables d’environnement ; -- camoufler/redacter les secrets dans logs, diagnostics, UI, erreurs et payloads sérialisés ; -- empêcher qu’une configuration résolue expose involontairement un secret en clair ; -- garder exemples, schémas JSON, bindings et documentation synchronisés. +`0.5.0` n'introduit pas de nouvelle surface protocolaire ni de restructuration runtime importante. -### 0.5.2 — `kb-wallet` +### 0.5.1 — `ks-*`, `KS_*` et configuration sûre + +Cette version effectue la migration de namespace des bibliothèques Solana et restructure la configuration sur la nouvelle fondation. + +- renommer les dix crates généralistes : `kb-core`, `kb-config`, `kb-lib`, `kb-logging`, `kb-program-ids`, `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-onchain-transport`, `kb-store` et `kb-wallet` vers leurs équivalents `ks-*` ; +- migrer les identifiants Rust correspondants vers `ks_*`, les manifests, chemins, imports, exports, tests externes, scripts et documentation ; +- conserver `kb-app-demo-desktop` comme application du domaine Bot, consommatrice des composants `ks-*` ; +- migrer les identités runtime/persistées généralistes vers la nomenclature `ks-*`, notamment `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*`, après inventaire exhaustif des chaînes concernées ; +- imposer le namespace d'environnement `KS_*` pour les variables appartenant au workspace ; +- classifier `KS_SECRET_*` comme jamais exposable, `KS_PUBLIC_*` comme publiable uniquement via une surface explicitement autorisée et les autres `KS_*` comme internes/diagnostiques ; +- préserver la sensibilité après substitution : toute valeur composée contenant un `KS_SECRET_*` reste secrète ; +- séparer la configuration généraliste et la configuration logging dans des documents et schémas indépendants ; +- permettre des profils logging indépendants des profils réseau/applicatifs ; +- distinguer configuration source, configuration runtime résolue et DTO publics/diagnostiques ; +- interdire qu'un secret résolu soit renvoyé en clair par logs, erreurs, diagnostics, UI, sérialisation ou payload Tauri ; +- garder exemples, schémas JSON, TS-RS et documentation synchronisés. + +Les préfixes SQL ne sont pas renommés dans cette version sauf nécessité technique strictement liée au maintien d'un workspace compilable ; leur normalisation appartient à `0.5.3`. + +### 0.5.2 — `ks-wallet` - auditer et normaliser les frontières identité, secret, déverrouillage et signature ; - consolider les besoins multi-wallets et multi-profils ; - revoir import/export, chiffrement, verrouillage, sauvegarde et restauration lorsque ces capacités sont retenues ; +- définir explicitement la migration du format keypair JSON `0.4.8` si un nouveau format persistant est adopté ; - empêcher toute fuite de secret vers la configuration, les logs, Tauri ou les DTO publics ; - conserver une API de signature réutilisable par les futurs exécuteurs sans couplage à un protocole particulier. -### 0.5.3 — audit et normalisation de `kb-store` +### 0.5.3 — audit et normalisation de `ks-store` - auditer DTO, entités, repositories, migrations, index, requêtes, idempotence et provenance ; - vérifier les champs temporels et séparer explicitement le temps blockchain du temps de persistance ; -- distinguer notamment slot, block time ou timestamp de transaction des timestamps d’insertion et de mise à jour en base ; -- normaliser la structure de `kb-store` avant l’arrivée des matérialisations trading ; +- distinguer notamment `slot`, `block_time` ou timestamp de transaction des timestamps d'acquisition, d'insertion et de mise à jour en base ; +- normaliser la structure de `ks-store` avant l'arrivée des matérialisations trading ; +- migrer les tables Solana du préfixe historique `kb_sol_*` vers `k_sol_*` ; +- réserver `kb_*` aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot ; +- profiter de la fenêtre pré-`0.6.x` pour reconstruire ou migrer proprement les bases Devnet/Mainnet au lieu de conserver des alias historiques sans valeur durable ; - préparer les index et contrats nécessaires aux faits de création de pools, liquidité, réserves, swaps, évolution de prix et séries temporelles ; - préparer le terrain pour routing, multi-pools et analyse croisée sans introduire prématurément des tables spécifiques à un DEX ; - permettre des extractions et analyses efficaces pour les futurs consommateurs de trading et de recherche historique. +Aucune table trading spécifique à Meteora, Raydium, Pump, Orca ou Jupiter n'est inventée avant définition des faits stables produits par les futurs matérialisateurs. + ### 0.5.4 — scénarios, exécuteurs et validations - auditer les scénarios encore déclarés ou assemblés directement dans `kb-app-demo-desktop` ; -- déplacer toute logique de scénario réutilisable vers `kb-pipeline-demo-scenarios` et laisser le desktop comme adaptateur UI/Tauri ; +- déplacer toute logique de scénario réutilisable vers `ks-pipeline-demo-scenarios` et laisser le desktop comme adaptateur UI/Tauri ; - comparer les décodeurs existants aux exécuteurs disponibles et identifier les exécuteurs réellement manquants ; - comparer les exécuteurs aux scénarios synthétiques, campagnes Devnet/Testnet et validations existantes ; - identifier les capacités présentes dans le desktop sans scénario réutilisable ; -- classer chaque absence comme à implémenter, decode-only, deprecated, unavailable, non applicable ou explicitement reportée. +- classer chaque absence comme à implémenter, decode-only, deprecated, unavailable, non applicable ou explicitement reportée ; +- ne pas transformer les surfaces réservées ni l'exception ElGamal en dette implicite sans changement de possibilité de validation. ## 0.6.x — infrastructure Anchor générique et prérequis prioritaires @@ -117,7 +143,7 @@ La série `0.6.x` prépare directement l’accélération sur les protocoles sui - implémenter uniquement les programmes/interfaces SPL ou autres prérequis dont Meteora, Raydium, Pump, Orca, Jupiter ou les couches de trading suivantes ont réellement besoin ; - reporter à `0.15.x` les programmes SPL non prioritaires, les compléments Metaplex non nécessaires à court terme et, plus généralement, les autres Program IDs déjà recensés ou découverts ultérieurement qui ne bloquent pas la séquence trading prioritaire. -Le report vers `0.15.x` est un choix d’ordre de développement, pas une réduction du périmètre de `kb-lib`. L’objectif à long terme reste de décoder et matérialiser le maximum de Program IDs Solana utiles, qu’ils soient liés ou non au trading. +Le report vers `0.15.x` est un choix d’ordre de développement, pas une réduction du périmètre de `ks-lib` après la migration `0.5.1`. L’objectif à long terme reste de décoder et matérialiser le maximum de Program IDs Solana utiles, qu’ils soient liés ou non au trading. ## 0.7.x — Meteora @@ -251,9 +277,9 @@ Reprendre les Program IDs volontairement différés pour accélérer la séquenc - Program IDs trading secondaires qui n’étaient pas bloquants ; - autres surfaces Solana dont le décodage/matérialisation apporte une valeur durable. -Cette phase réaffirme la vocation généraliste de `kb-lib` : la priorité trading des versions précédentes ne transforme pas la bibliothèque en moteur exclusivement DEX. +Cette phase réaffirme la vocation généraliste de `ks-lib` : la priorité trading des versions précédentes ne transforme pas la bibliothèque en moteur exclusivement DEX. ## 0.16.x+ — extensions futures et off-chain - nouveaux protocoles, transports, backfills, observabilité, administration et optimisations validés par des contrats bornés ; -- étudier puis créer `kb-offchain-transport` seulement lorsqu’un consommateur réel le justifie, avec premiers modules metadata HTTP(S), IPFS et Arweave, cache et provenance bornés, hash, contrôle des redirections, limites MIME/taille/timeout et protection SSRF IPv4/IPv6. +- étudier puis créer `ks-offchain-transport` seulement lorsqu’un consommateur réel le justifie, avec premiers modules metadata HTTP(S), IPFS et Arweave, cache et provenance bornés, hash, contrôle des redirections, limites MIME/taille/timeout et protection SSRF IPv4/IPv6. diff --git a/docs/IDEA_REMINDERS.md b/docs/IDEA_REMINDERS.md index 884c608..e2fbb13 100644 --- a/docs/IDEA_REMINDERS.md +++ b/docs/IDEA_REMINDERS.md @@ -1,17 +1,24 @@ - + # Rappels d’idées -Ce document conserve les idées utiles qui ne constituent pas encore des engagements de version. Les orientations déjà intégrées au ROADMAP ne sont pas répétées comme propositions ouvertes. +Ce document conserve les idées utiles qui ne constituent pas encore des engagements de version ainsi que quelques repères de portefeuille explicitement demandés comme rappels. Lorsqu’une orientation est devenue normative, le document actif correspondant est indiqué et reste prioritaire. ## Positionnement futur des projets -- `khadhroony-project` est destiné à devenir une umbrella de projets trading et crypto ; -- `khadhroony-solana` doit regrouper les bibliothèques généralistes dédiées à Solana, avec une convergence prévue vers les namespaces `ks-*`, `ks_*` et `KS_*` ; -- `khadhroony-bot` / bot3 doit devenir, après stabilisation de la fondation et publication de `1.0`, le robot de trading consommant les composants Khadhroony Solana ; -- la cible bot comprend à terme une partie d'analyse et de création de stratégies ainsi qu'un exécutable de trading automatique ; -- `kb-app-demo-desktop` n'est actuellement pas cette application finale : il sert surtout à tester et valider les composants généralistes qui doivent migrer vers Khadhroony Solana. +Repères durables de portefeuille, désormais également formalisés dans la politique de namespace active : + +- `khadhroony-project` est une umbrella de projets de trading et/ou de crypto ; elle n'est pas limitée à Solana ni même à la crypto ; +- des projets futurs pourront par exemple viser XTB (`khadhroony-xtb`) ou MetaTrader (`khadhroony-mt5`) sans dépendre de Solana ; +- `khadhroony-solana` regroupe les bibliothèques généralistes dédiées à Solana et converge vers les namespaces `ks-*`, `ks_*` et `KS_*` ; +- `ks-pipeline-demo-scenarios` appartient à ce domaine Solana généraliste : les scénarios de validation ne sont pas spécifiques au bot ; +- `khadhroony-bot` / bot3 doit devenir le robot de trading consommant les composants Khadhroony Solana, avec à terme analyse/création de stratégies et exécution de trading automatique ; +- `kb-app-demo-desktop` reste côté Bot : il valide aujourd'hui surtout les composants Solana généralistes mais pourra aussi accueillir des démonstrations spécifiques au bot ; +- les identités techniques généralistes doivent migrer vers `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ; +- les tables Solana doivent à terme utiliser `k_sol_*`, tandis que `kb_*` est réservé aux éventuelles tables réellement spécifiques au domaine Bot. + +La décision normative et son calendrier sont dans [`decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). ## Application desktop diff --git a/docs/README.md b/docs/README.md index 52806cb..3e7056c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@ - + # Documentation active de Khadhroony Bot3 @@ -39,9 +39,9 @@ Modèles documentaires non génératifs : ## 4. Audits et décisions actifs -- [`audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md`](audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md) ; - [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ; -- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md). +- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md) ; +- [`decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md) : séparation Khadhroony Solana/Bot, migration `ks-*` / `KS_*`, identités techniques et namespaces SQL. Les audits et rapports de travail `0.4.8-pre.*` sont archivés sous `../olddocs/archivekbot3/`. Leur contenu reste disponible pour la traçabilité mais n’est plus un index actif. @@ -102,12 +102,10 @@ Les preuves détaillées de `0.4.8-pre.*` restent accessibles sous `../olddocs/a ## 10. Plans de version actifs -- [`Plan 0.5.0 — cadrage de la fondation 0.5.x`](plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md) : plan temporaire actif créé pendant `0.5.0-pre.001`, à maintenir jusqu’à la clôture de `0.5.0`. -- [`Audit 0.5.0-pre.002 — configuration, logging, wallet et namespaces`](plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md) : décisions de sécurité, split logging, namespace `KS_*`, migration wallet et audit du possible préfixe de crates `ks-*`. -- [`Audit 0.5.0-pre.003 — store, scénarios, desktop et complétude`](plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md) : contrat temporel du store, préparation trading générique, frontière des scénarios, couverture des exécuteurs actifs et cible `ks-*`. +Le cadrage `0.5.0` est clôturé. Son plan et les audits `pre.002`/`pre.003` sont archivés sous `../olddocs/archivekbot3/docs/plans/`. -Le plan `0.4.8` reste archivé sous `../olddocs/archivekbot3/docs/plans/`. +Le prochain plan temporaire sera créé pendant la première prerelease de `0.5.1`, conformément au cycle de développement. ## 11. Prompt de reprise -- [`Prompt actif 0.5.0`](../prompts/029_v0_5_0_foundation_restructuring_plan.md). +- [`Prompt actif 0.5.1`](../prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md). diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 6766e09..3542a35 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture générale @@ -69,7 +69,7 @@ Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacité - `kb-pipeline-demo-scenarios` fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop. - Le binaire `kb-pipeline-demo-scenarios-cli` reste un outil ciblé ; son existence n’impose pas d’exposer chaque scénario par un CLI. - `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à `kb-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`. -- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Sa restructuration est planifiée en `0.5.2`. +- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Elle devient `ks-wallet` en `0.5.1`, puis sa restructuration fonctionnelle est planifiée en `0.5.2`. ## 3. Flux principal de données @@ -99,7 +99,7 @@ L’exécution suit un flux séparé : intention typée, construction, préfligh - 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éseau réutilisables spécifiques à Devnet/Testnet appartiennent à `kb-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`. +- Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `kb-pipeline-demo-scenarios`, future `ks-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à l’adaptation Tauri, aux payloads UI, à la présentation et à l’appel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`. - Toute primitive ou orchestration réellement généraliste, indépendante de l’UI et d’une campagne de démonstration précise, appartient à `kb-pipeline` ou à la crate métier propriétaire. - 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. @@ -108,4 +108,4 @@ L’exécution suit un flux séparé : intention typée, construction, préfligh La migration bot2 vers bot3 est close pour le périmètre fonctionnel repris jusqu’à `0.4.7`. La version `0.4.8` complète ensuite la fondation Metadata on-chain en distinguant Solana Program Metadata, Token-2022 Token Metadata et Metaplex Token Metadata, avec leurs décodeurs, matérialisateurs, exécuteurs lorsque applicables, orchestration stateful, scénarios réutilisables et intégration desktop. -La série `0.5.x` ne vise pas à étendre immédiatement la couverture protocolaire : elle stabilise d’abord `kb-config`, `kb-wallet`, `kb-store` et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. `0.6.x` introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter. +La série `0.5.x` ne vise pas à étendre immédiatement la couverture protocolaire : elle migre d’abord les bibliothèques vers `ks-*`, puis stabilise `ks-config`, `ks-wallet`, `ks-store` et les frontières de scénarios afin d’éviter de devoir casser ces fondations après l’arrivée des protocoles trading. `0.6.x` introduira ensuite le décodeur Anchor générique avant la séquence Meteora/Raydium/Pump/Orca/Jupiter. diff --git a/docs/architecture/CRATE_MAP.md b/docs/architecture/CRATE_MAP.md index 658a51f..2a93a78 100644 --- a/docs/architecture/CRATE_MAP.md +++ b/docs/architecture/CRATE_MAP.md @@ -1,5 +1,5 @@ - + # Carte des crates @@ -8,17 +8,19 @@ | Crate | Type | Responsabilité principale | État documentaire | |------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------------| | `kb-core` | bibliothèque | erreurs, résultat et identité de module partagés | README/TODO/USAGE/CHANGELOG présents | -| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | documentée ; restructuration en `0.5.1` | +| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | migration/restructuration en `0.5.1` | | `kb-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | README/TODO/USAGE/CHANGELOG présents | | `kb-logging` | bibliothèque | initialisation du logging et du tracing | README/TODO/USAGE/CHANGELOG présents | | `kb-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | README/TODO/USAGE/CHANGELOG présents | | `kb-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | README/TODO/USAGE/CHANGELOG présents | -| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | documentée ; réconciliation en `0.5.4` | +| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | renommage `0.5.1`, audit `0.5.4` | | `kb-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools d’endpoints | README/TODO/USAGE/CHANGELOG présents | -| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | documentée ; audit structurel en `0.5.3` | -| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | documentée ; restructuration en `0.5.2` | +| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | renommage `0.5.1`, normalisation `0.5.3` | +| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | renommage `0.5.1`, refonte `0.5.2` | | `kb-app-demo-desktop` | bibliothèque + binaire | application de démonstration Tauri | documentée ; réconciliation en `0.5.4` | +La table décrit les noms physiques du workspace `0.5.0`. La migration `0.5.1` renomme les dix crates généralistes en `ks-core`, `ks-config`, `ks-lib`, `ks-logging`, `ks-program-ids`, `ks-pipeline`, `ks-pipeline-demo-scenarios`, `ks-onchain-transport`, `ks-store` et `ks-wallet`. `kb-app-demo-desktop` conserve son nom parce qu’il appartient au domaine applicatif Bot. Voir [`../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). + ## 2. Consolidations principales depuis bot2 La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges : diff --git a/docs/architecture/PIPELINE_ARCHITECTURE.md b/docs/architecture/PIPELINE_ARCHITECTURE.md index bcf15f0..c6a48dc 100644 --- a/docs/architecture/PIPELINE_ARCHITECTURE.md +++ b/docs/architecture/PIPELINE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture du pipeline @@ -48,7 +48,7 @@ Cette crate peut préparer des wallets temporaires, demander des airdrops, crée Le binaire `kb-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios. -`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et d’exécution de campagne appartient à `kb-pipeline-demo-scenarios`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite. +`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et d’exécution de campagne appartient à `kb-pipeline-demo-scenarios`, renommée `ks-pipeline-demo-scenarios` en `0.5.1`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`. ## 5. Contrats de preuve @@ -57,5 +57,5 @@ Les tests unitaires, tests d’intégration et matrices de `test-fixtures/contra ## 6. Limites connues - Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet. -- La réconciliation finale des scénarios encore dupliqués entre desktop et `kb-pipeline-demo-scenarios` est planifiée en `0.5.4`. -- Les futurs protocoles doivent conserver cette frontière : orchestration généraliste dans `kb-pipeline`, scénarios réseau réutilisables dans `kb-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop. +- La réconciliation finale des scénarios encore dupliqués entre desktop et la future `ks-pipeline-demo-scenarios` est planifiée en `0.5.4`. +- Après `0.5.1`, les futurs protocoles doivent conserver cette frontière : orchestration généraliste dans `ks-pipeline`, scénarios réseau réutilisables dans `ks-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop. diff --git a/docs/architecture/PROJECT_OBJECTIVES.md b/docs/architecture/PROJECT_OBJECTIVES.md index 9fe19e0..87728fa 100644 --- a/docs/architecture/PROJECT_OBJECTIVES.md +++ b/docs/architecture/PROJECT_OBJECTIVES.md @@ -1,5 +1,5 @@ - + # Objectifs du projet Khadhroony Bot3 @@ -9,6 +9,8 @@ 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. +La fondation `0.5.x` distingue désormais deux domaines : `khadhroony-solana` pour les bibliothèques généralistes Solana et `khadhroony-bot` pour les applications spécifiques au futur robot de trading. Le portefeuille plus large `khadhroony-project` pourra contenir d'autres projets de trading ou de crypto, y compris des projets non Solana et non crypto. + ## 2. Objectifs structurants Le projet vise à : @@ -66,8 +68,8 @@ Le noyau livré jusqu’à `0.4.8` couvre notamment : Ne sont pas considérés comme achevés : -- la restructuration des fondations `kb-config`, `kb-wallet` et `kb-store`, planifiée en `0.5.x` ; -- la réconciliation complète des scénarios réutilisables entre `kb-pipeline-demo-scenarios` et le desktop ; +- la migration des bibliothèques généralistes vers `ks-*` et les restructurations de `ks-config`, `ks-wallet` et `ks-store`, planifiées en `0.5.x` ; +- la réconciliation complète des scénarios réutilisables entre la future `ks-pipeline-demo-scenarios` et le desktop ; - le décodeur Anchor générique planifié en `0.6.x` ; - les protocoles trading prioritaires Meteora, Raydium, Pump, Orca et Jupiter ; - la couverture généraliste différée des autres Program IDs Solana, qui reste un objectif du projet après la séquence trading prioritaire ; diff --git a/docs/architecture/STORAGE_ARCHITECTURE.md b/docs/architecture/STORAGE_ARCHITECTURE.md index d0289af..2a086fe 100644 --- a/docs/architecture/STORAGE_ARCHITECTURE.md +++ b/docs/architecture/STORAGE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture du stockage @@ -59,7 +59,9 @@ Les noms de tables, contrats de replay et APIs publiques sont documentés dans ` - erreurs explicites ; - séparation entre données brutes, résultats de décodage et matérialisations. -La série `0.5.3` réauditera cette fondation avant l’arrivée des protocoles trading. Cet audit doit notamment distinguer les timestamps observés sur la blockchain des timestamps d’insertion et de mise à jour locaux, normaliser la structure interne de `kb-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans casser les contrats de replay existants. +La série `0.5.3` normalisera cette fondation avant l’arrivée des protocoles trading. Elle doit notamment distinguer `slot`, `block_time` et les timestamps d’acquisition/persistance, normaliser la structure interne de la future `ks-store`, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans perdre les contrats de provenance et d’idempotence. + +La même migration remplace le préfixe historique des tables Solana `kb_sol_*` par `k_sol_*`. La base peut encore être reconstruite ou migrée proprement avant `0.6.x`, il n’est donc pas nécessaire de conserver indéfiniment l’ancien préfixe. Le préfixe `kb_*` est réservé aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot, pas aux faits Solana simplement consommés par le bot. ## 5. Données de test diff --git a/docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md b/docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md new file mode 100644 index 0000000..63102c4 --- /dev/null +++ b/docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md @@ -0,0 +1,117 @@ + + + +# Politique de namespace Khadhroony Solana + +## 1. Statut + +Cette décision est adoptée pendant la clôture de `0.5.0` et devient la cible normative des migrations de fondation `0.5.1` à `0.5.3`. + +Le workspace `0.5.0` conserve encore physiquement les noms `kb-*`, `kb_*`, `KB_*`, `kb-lib.*` et `kb_sol_*` là où ils existent. Leur présence avant migration ne remet pas en cause la cible ci-dessous. + +## 2. Positionnement des projets + +`khadhroony-project` est une umbrella de projets liés au trading et/ou aux technologies crypto. Elle n'est pas limitée à Solana ni même à la crypto. Des projets futurs pourront par exemple viser XTB ou MetaTrader indépendamment des composants Solana. + +`khadhroony-solana` est le domaine des bibliothèques généralistes dédiées à Solana. Ces bibliothèques doivent pouvoir être réutilisées par plusieurs applications sans dépendre du futur robot de trading Khadhroony Bot. + +`khadhroony-bot` / `khadhroony-bot3` est le domaine applicatif du futur robot de trading. Après stabilisation de la fondation et avant/après `1.0` selon le ROADMAP, il doit pouvoir consommer les composants `khadhroony-solana`, fournir des capacités d'analyse et de création de stratégies puis un exécutable de trading automatique. + +`kb-app-demo-desktop` reste une application du workspace Bot. Elle sert actuellement surtout à tester et valider les composants Solana généralistes, mais elle pourra aussi recevoir des démonstrations spécifiques au bot. Son nom n'est donc pas inclus dans la migration `ks-*`. + +## 3. Crates Solana généralistes + +La migration `0.5.1` doit renommer les dix crates généralistes suivantes : + +| Nom `0.5.0` | Nom cible | +|------------------------------|------------------------------| +| `kb-core` | `ks-core` | +| `kb-config` | `ks-config` | +| `kb-lib` | `ks-lib` | +| `kb-logging` | `ks-logging` | +| `kb-program-ids` | `ks-program-ids` | +| `kb-pipeline` | `ks-pipeline` | +| `kb-pipeline-demo-scenarios` | `ks-pipeline-demo-scenarios` | +| `kb-onchain-transport` | `ks-onchain-transport` | +| `kb-store` | `ks-store` | +| `kb-wallet` | `ks-wallet` | + +Les identifiants Rust correspondants migrent vers `ks_*` : par exemple `kb_config` devient `ks_config` et `kb_pipeline_demo_scenarios` devient `ks_pipeline_demo_scenarios`. + +La migration doit couvrir les manifests, chemins de workspace, imports, exports, tests d'API externe, scripts, documentation, targets de build et bindings générés à la source. Les artefacts générés restent régénérés localement selon les règles du workspace et ne sont pas livrés sans nécessité explicite. + +## 4. Variables d'environnement + +Toutes les variables d'environnement appartenant aux contrats Khadhroony Solana/Bot doivent utiliser le namespace `KS_` après la migration `0.5.1`. + +Trois classes sont retenues : + +- `KS_SECRET_*` : secret absolu ; la valeur peut être utilisée côté backend mais ne doit jamais être loggée, sérialisée vers une surface publique, renvoyée par Tauri ni affichée en diagnostic, même en mode debug ; +- `KS_PUBLIC_*` : valeur explicitement classée comme publiable ; le préfixe ne suffit pas à lui seul à autoriser une exposition, qui doit rester définie par un DTO ou une surface publique explicite ; +- `KS_*` hors sous-préfixes précédents : valeur interne ; elle n'est pas exposée en fonctionnement normal mais peut être incluse dans un diagnostic explicitement demandé si sa sémantique n'est pas sensible. + +Une variable appartenant au workspace qui ne commence pas par `KS_` est non conforme après migration. Les variables standard du système ou de dépendances externes ne sont pas reclassées artificiellement comme variables de configuration Khadhroony. + +La classification d'une valeur sensible doit survivre à la substitution. Une chaîne composée contenant une valeur issue de `KS_SECRET_*` reste sensible dans son ensemble et ne doit pas redevenir une simple valeur publiable après résolution. + +## 5. Configuration source, runtime et publique + +La restructuration `0.5.1` doit séparer au minimum : + +- la configuration généraliste dans son propre document et son propre schéma ; +- la configuration logging dans un document et un schéma indépendants, avec des profils logging sélectionnables indépendamment des profils réseau/applicatifs. + +D'autres documents spécialisés ne sont créés que si l'audit démontre une responsabilité, un cycle de vie ou une validation réellement indépendants. + +La conception doit distinguer : + +1. la représentation source, qui peut contenir des références `${KS_*}` ; +2. la représentation runtime résolue, qui peut porter des secrets ; +3. la représentation publique/diagnostique, construite explicitement et incapable d'exposer une valeur secrète résolue. + +Une configuration runtime complète ne doit jamais être sérialisée puis « nettoyée » après coup pour produire un payload public. + +## 6. Identités runtime et persistées + +La migration de namespace ne se limite pas au nom des crates. Les identités techniques actuellement préfixées par `kb-lib` doivent être migrées vers le domaine Khadhroony Solana lorsqu'elles identifient des composants généralistes. + +La convention cible retenue comprend notamment : + +- `kb-lib.decoder.*` → `ks-lib-decoder.*` ; +- `kb-lib.materializer.*` → `ks-lib-materializer.*` ; +- `kb-lib.executor.*` → `ks-lib-executor.*`. + +`0.5.1-pre.001` doit produire l'inventaire exhaustif des targets de tracing, `processor_name`, identités de replay/idempotence, codes persistés et autres chaînes techniques concernées avant modification. Les anciennes identités ne doivent pas être conservées par inertie puisque la fondation et la base peuvent encore être migrées avant `0.6.x`. + +Les segments métier internes (`solana`, `spl`, protocoles, surfaces et opérations) conservent leurs règles propres ; la migration de préfixe ne doit pas altérer arbitrairement leur sémantique. + +## 7. Namespace SQL + +La normalisation SQL appartient à `0.5.3` avec `ks-store`. + +Les tables génériques représentant des faits Solana doivent migrer du préfixe actuel `kb_sol_*` vers : + +```text +k_sol_* +``` + +La base Mainnet/Devnet peut être reconstruite ou migrée proprement avant l'ouverture de `0.6.x`. Il n'est donc pas nécessaire de préserver indéfiniment un préfixe historique incohérent uniquement pour compatibilité. + +Si des tables réellement spécifiques au robot de trading sont introduites ultérieurement, elles utilisent le préfixe : + +```text +kb_* +``` + +Une table ne reçoit pas `kb_*` simplement parce qu'elle est consommée par le bot. Elle doit contenir des données dont la responsabilité appartient réellement au domaine applicatif Bot et non à la blockchain ou aux bibliothèques Solana généralistes. + +La migration `kb_sol_*` → `k_sol_*` doit être traitée avec les contrats temporels, de provenance, d'idempotence, d'index et de replay de `0.5.3`, et non comme un remplacement textuel isolé. + +## 8. Ordre des migrations + +- `0.5.1` : crates `ks-*`, identifiants Rust `ks_*`, variables `KS_*`, identités runtime/persistées Khadhroony Solana et restructuration sûre de la configuration/logging ; +- `0.5.2` : restructuration de `ks-wallet` sur la nouvelle fondation de configuration ; +- `0.5.3` : normalisation de `ks-store`, y compris migration du préfixe SQL vers `k_sol_*` et contrats temporels/provenance ; +- `0.5.4` : centralisation finale des scénarios dans `ks-pipeline-demo-scenarios` et audit de complétude des exécuteurs/validations. + +Aucune de ces migrations ne doit réintroduire une dépendance du domaine Solana généraliste vers une application spécifique au bot. diff --git a/olddocs/archivekbot3/001.README.md b/olddocs/archivekbot3/001.README.md index 78eb567..7c91903 100644 --- a/olddocs/archivekbot3/001.README.md +++ b/olddocs/archivekbot3/001.README.md @@ -1,5 +1,5 @@ - + # Archive documentaire de khadhroony-bot3 @@ -32,3 +32,7 @@ Le plan, le prompt de session et les rapports de prerelease de Metaplex Token Me ## Clôture 0.4.8 Le plan `0.4.8`, le prompt de session `028`, les audits `V0_4_8_PRE_*` et les rapports de validation de prerelease sont archivés sous `docs/plans/`, `docs/audits/`, `docs/validation/` et `prompts/`. Le rapport fonctionnel final `0.4.8` reste actif sous `docs/validation/`. + +## Clôture 0.5.0 + +Le plan de fondation `0.5.0`, les audits `pre.002` et `pre.003` ainsi que le prompt de session `029` sont archivés sous `docs/plans/` et `prompts/`. Les décisions durables ont été transférées au ROADMAP, aux documents d’architecture et à `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`. diff --git a/docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md b/olddocs/archivekbot3/docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md similarity index 82% rename from docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md rename to olddocs/archivekbot3/docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md index dfdd046..e845090 100644 --- a/docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md +++ b/olddocs/archivekbot3/docs/plans/V0_5_0_FOUNDATION_0_5_X_PLAN.md @@ -1,5 +1,5 @@ - + # Plan `0.5.0` — cadrage de la fondation `0.5.x` @@ -17,6 +17,8 @@ Le plan reste temporaire pendant le développement de `0.5.0`. Il doit être mai **État de `pre.003` : audit store/scénarios/desktop effectué ; le contrat temporel, la méthode de complétude et la cible de renommage `ks-*` sont consignés dans [`V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md`](V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md). Aucun changement runtime, SQL ou exécuteur n'est appliqué.** +**État de `pre.004` : cadrage clôturé. La migration des dix crates généralistes vers `ks-*` / `ks_*`, des variables vers `KS_*` et des identités techniques vers `ks-lib-*` est fixée pour `0.5.1`. La migration SQL `kb_sol_*` → `k_sol_*` est fixée pour `0.5.3`. Les décisions durables sont transférées au ROADMAP et à `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`, puis ce plan est archivé.** + ## 2. Base `0.4.8` à préserver La release `0.4.8` constitue la base fonctionnelle fermée de la série `0.5.x` : @@ -47,14 +49,14 @@ Les documents archivés ne sont jamais utilisés pour contredire un contrat actu Le workspace contient onze crates. Les six surfaces directement auditées pour `0.5.0` se placent aujourd'hui comme suit. -| Surface | Responsabilité actuelle | Dépendances workspace directes | Consommateurs directs principaux | Risque de migration | -|---|---|---|---|---| -| `kb-config` | schéma JSON, parsing, validation, profils, résolution d'environnement, sérialisation | `kb-core` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-onchain-transport`, `kb-app-demo-desktop` | très élevé : types publics et TS-RS largement consommés | -| `kb-logging` | runtime `tracing`, routes, formats, rotations, filtres | `kb-core` | `kb-app-demo-desktop` | moyen : contrat runtime dupliqué dans `kb-config` | -| `kb-wallet` | alias, keypair local temporaire, persistance JSON, signature | `kb-core` | `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | élevé : secret persistant et API signer traversant les scénarios | -| `kb-store` | DTO, entités, repositories, migrations PostgreSQL, diagnostics, replay/persistance | `kb-core`, `kb-lib` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | très élevé : schéma SQL publié et grande façade publique | -| `kb-pipeline-demo-scenarios` | fixtures et campagnes synthétiques/réseau réutilisables | `kb-core`, `kb-config`, `kb-lib`, `kb-onchain-transport`, `kb-pipeline`, `kb-program-ids`, `kb-store`, `kb-wallet` | `kb-app-demo-desktop` | élevé : convergence de presque toutes les fondations | -| `kb-app-demo-desktop` | composition applicative, état Tauri, IPC, TS-RS et UI opérateur | les dix autres crates | frontend Tauri | élevé côté IPC ; ne doit pas devenir propriétaire de logique réutilisable | +| Surface | Responsabilité actuelle | Dépendances workspace directes | Consommateurs directs principaux | Risque de migration | +|------------------------------|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| +| `kb-config` | schéma JSON, parsing, validation, profils, résolution d'environnement, sérialisation | `kb-core` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-onchain-transport`, `kb-app-demo-desktop` | très élevé : types publics et TS-RS largement consommés | +| `kb-logging` | runtime `tracing`, routes, formats, rotations, filtres | `kb-core` | `kb-app-demo-desktop` | moyen : contrat runtime dupliqué dans `kb-config` | +| `kb-wallet` | alias, keypair local temporaire, persistance JSON, signature | `kb-core` | `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | élevé : secret persistant et API signer traversant les scénarios | +| `kb-store` | DTO, entités, repositories, migrations PostgreSQL, diagnostics, replay/persistance | `kb-core`, `kb-lib` | `kb-pipeline`, `kb-pipeline-demo-scenarios`, `kb-app-demo-desktop` | très élevé : schéma SQL publié et grande façade publique | +| `kb-pipeline-demo-scenarios` | fixtures et campagnes synthétiques/réseau réutilisables | `kb-core`, `kb-config`, `kb-lib`, `kb-onchain-transport`, `kb-pipeline`, `kb-program-ids`, `kb-store`, `kb-wallet` | `kb-app-demo-desktop` | élevé : convergence de presque toutes les fondations | +| `kb-app-demo-desktop` | composition applicative, état Tauri, IPC, TS-RS et UI opérateur | les dix autres crates | frontend Tauri | élevé côté IPC ; ne doit pas devenir propriétaire de logique réutilisable | Cette topologie confirme l'ordre du ROADMAP : stabiliser d'abord la configuration, puis le wallet, puis le store, avant l'audit final des scénarios et exécuteurs. Une inversion de cet ordre multiplierait les adaptations transitoires. @@ -248,7 +250,7 @@ L'audit a recensé 84 noms d'environnement actifs ou de fixture dans le code/con - tests d'API externe de la façade `kb-config` avant changement structurel ; - documentation et exemples alignés. -## 9. Préparation de `0.5.2` — `kb-wallet` +## 9. Préparation de `0.5.2` — `ks-wallet` ### Frontières à concevoir @@ -277,7 +279,7 @@ L'audit a recensé 84 noms d'environnement actifs ou de fixture dans le code/con - absence de secret dans `Debug`, erreurs, résumés, config et Tauri ; - backup/restore si cette capacité est retenue. -## 10. Préparation de `0.5.3` — `kb-store` +## 10. Préparation de `0.5.3` — `ks-store` ### Vocabulaire temporel à normaliser @@ -307,12 +309,14 @@ Le résultat attendu est un contrat de faits et d'indexation, pas un schéma Met ### Migration à préparer -- ne jamais modifier `0001` à `0004` ; -- définir une nouvelle migration uniquement après validation du modèle ; +- conserver `0001` à `0004` comme historique du schéma `0.5.0` ; +- définir la stratégie de reconstruction/migration vers le nouveau namespace SQL sans réécrire silencieusement l’historique ; +- migrer les tables Solana `kb_sol_*` vers `k_sol_*` et réserver `kb_*` aux données réellement spécifiques au Bot ; +- définir une nouvelle migration uniquement après validation du modèle lorsque la stratégie retenue conserve une chaîne de migrations ; - préciser la nullabilité et le backfill de `block_time` ; - tester migration sur schéma `0.4.8`, réexécution idempotente et données existantes ; - mesurer/inspecter les index destinés aux requêtes temporelles et multi-entités ; -- conserver les identités persistées de processeurs et clés d'idempotence ou fournir une migration explicite. +- consommer les identités `ks-lib-*` migrées en `0.5.1` et préserver leurs clés de provenance/idempotence selon le nouveau contrat. ## 11. Préparation de `0.5.4` — scénarios et complétude d'exécution @@ -340,7 +344,7 @@ Chaque absence doit être classée dans une des catégories imposées : Un exécuteur n'est pas requis uniquement parce qu'un décodeur existe. La justification doit intégrer sécurité, programme courant, possibilité de fixture et valeur pour les versions suivantes. -Le déplacement d'un scénario vers `kb-pipeline-demo-scenarios` doit conserver le desktop comme adaptateur et préserver les noms/payloads Tauri lorsque leur changement n'apporte aucune valeur. +Le déplacement d'un scénario vers `ks-pipeline-demo-scenarios` doit conserver le desktop comme adaptateur et préserver les noms/payloads Tauri lorsque leur changement n'apporte aucune valeur. ## 12. Découpage borné de `0.5.0` @@ -389,22 +393,24 @@ Livrables réalisés : - inventaire statique des exécuteurs : 8 actifs et 103 réservés ; - confirmation qu'ElGamal est le seul exécuteur actif sans scénario réseau réutilisable et reste conditionnel faute de preuve disponible ; - correction de la frontière normative : campagnes réutilisables dans `kb-pipeline-demo-scenarios`, adaptation UI/Tauri dans le desktop ; -- décision de faire du renommage des bibliothèques généralistes vers `ks-*` une partie de `0.5.1`, sans renommer mécaniquement les tables ou identités persistées. +- décision de faire du renommage des dix bibliothèques généralistes vers `ks-*` / `ks_*` une partie de `0.5.1` ; décision finale de migrer aussi les identités `kb-lib.*` vers `ks-lib-*` en `0.5.1`, tandis que les tables `kb_sol_*` migreront vers `k_sol_*` pendant `0.5.3`. Critère de sortie : contrats de `0.5.3` et méthode de complétude `0.5.4` suffisamment fermés pour éviter une refonte spéculative. L'audit détaillé est consigné dans [`V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md`](V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md). ### `0.5.0-pre.004` — clôture obligatoire de `0.5.0` -Livrables prévus : +Livrables réalisés : -- réconciliation transversale des audits et corrections résiduelles ; -- validations finales du workspace ; -- mise à jour des README/USAGE/TODO/guides rendus faux ou incomplets ; -- transfert des décisions durables dans ROADMAP/règles/architecture lorsque nécessaire ; -- archivage du présent plan et du prompt `029` sous `olddocs/archivekbot3/` ; -- préparation du prompt `0.5.1` ; +- réconciliation transversale des audits et décisions de namespace ; +- fixation du périmètre Khadhroony Solana : dix crates généralistes, `ks-pipeline-demo-scenarios` inclus, `kb-app-demo-desktop` exclu ; +- fixation des conventions `KS_*`, `ks-lib-*`, `k_sol_*` et `kb_*` selon leur domaine ; +- transfert des décisions durables dans le ROADMAP, l’architecture et la politique de namespace ; +- archivage du présent plan, des audits `pre.002`/`pre.003` et du prompt `029` sous `olddocs/archivekbot3/` ; +- préparation du prompt `030` pour `0.5.1` ; - préparation de la release finale `0.5.0` sans nouvelle fonctionnalité structurelle majeure. +Les validations Cargo finales restent à exécuter sur le workspace réel après application du delta `pre.004`, l’environnement de préparation ne fournissant pas Cargo. + Le CHANGELOG racine conserve sa règle : les entrées fonctionnelles publiées sont ajoutées au moment de la release finale, pas sous une section « non publiée » artificielle. ## 13. Tests et audits à préparer avant code structurel @@ -492,10 +498,10 @@ Ne jamais lancer directement les scripts npm de développement ou build. Les com - le chemin de fuite de configuration résolue est explicitement attribué à `0.5.1` avec critères de non-divulgation ; - le namespace d'environnement `KS_*` et les classes `Secret/Public/Internal` sont documentés avec propagation de sensibilité ; - le split logging en document et schéma indépendants est retenu comme cible de `0.5.1` ; -- le format wallet `0.4.8` et ses exigences de migration sont documentés ; -- le vocabulaire temporel/provenance/idempotence du store est défini avant tout schéma trading ; +- la liste des dix crates `ks-*`, la migration des identités `ks-lib-*`, le format wallet `0.4.8` et ses exigences de migration sont documentés ; +- le vocabulaire temporel/provenance/idempotence du store et la cible SQL `k_sol_*` sont définis avant tout schéma trading ; - la méthode d'audit decoder/executor/scenario/validation de `0.5.4` est fermée ; - aucun chantier `0.5.1` à `0.5.4` n'a été implémenté prématurément ; - les documents actifs ne présentent plus les hypothèses obsolètes identifiées ; - les contrôles de référence sont propres sur le workspace réel ; -- le plan et le prompt terminés sont archivés et le prompt `0.5.1` est prêt. +- le plan et le prompt terminés sont archivés et le prompt `030` de `0.5.1` est prêt. diff --git a/docs/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md b/olddocs/archivekbot3/docs/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md similarity index 100% rename from docs/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md rename to olddocs/archivekbot3/docs/plans/V0_5_0_PRE_002_CONFIG_LOGGING_WALLET_AUDIT.md diff --git a/docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md b/olddocs/archivekbot3/docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md similarity index 78% rename from docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md rename to olddocs/archivekbot3/docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md index c95d493..125561f 100644 --- a/docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md +++ b/olddocs/archivekbot3/docs/plans/V0_5_0_PRE_003_STORE_SCENARIOS_EXECUTION_AUDIT.md @@ -32,17 +32,17 @@ Cette orientation générale est aussi conservée dans `docs/IDEA_REMINDERS.md`. Les crates suivantes sont des bibliothèques ou composants de support Solana généralistes et sont donc candidates au renommage direct en `0.5.1` : -| Actuel | Cible de travail | -|------------------------------|------------------------------------------------------------------------------------------| -| `kb-core` | `ks-core` | -| `kb-config` | `ks-config` | -| `kb-lib` | `ks-lib` | -| `kb-logging` | `ks-logging` | -| `kb-program-ids` | `ks-program-ids` | -| `kb-pipeline` | `ks-pipeline` | -| `kb-onchain-transport` | `ks-onchain-transport` | -| `kb-store` | `ks-store` | -| `kb-wallet` | `ks-wallet` | +| Actuel | Cible de travail | +|---|---| +| `kb-core` | `ks-core` | +| `kb-config` | `ks-config` | +| `kb-lib` | `ks-lib` | +| `kb-logging` | `ks-logging` | +| `kb-program-ids` | `ks-program-ids` | +| `kb-pipeline` | `ks-pipeline` | +| `kb-onchain-transport` | `ks-onchain-transport` | +| `kb-store` | `ks-store` | +| `kb-wallet` | `ks-wallet` | | `kb-pipeline-demo-scenarios` | `ks-pipeline-demo-scenarios` à confirmer comme composant de validation Khadhroony Solana | `kb-app-demo-desktop` reste hors de cette substitution automatique : c'est une application Khadhroony Bot, même si son rôle courant est surtout de tester les composants `ks-*`. @@ -121,13 +121,13 @@ En revanche : Le contrat `0.5.3` doit donc imposer la distinction suivante : -| Dimension | Sens | -|-------------------------------------------------|----------------------------------------------------------| -| `slot` | ordre/position Solana ; jamais assimilé à un temps civil | -| `block_time` | temps on-chain Unix optionnel observé depuis le cluster | -| `detected_at` / `received_at` / `normalized_at` | temps locaux d'acquisition | -| `persisted_at` | instant d'écriture de l'observation | -| `created_at` / `updated_at` | cycle de vie de la ligne SQL | +| Dimension | Sens | +|---|---| +| `slot` | ordre/position Solana ; jamais assimilé à un temps civil | +| `block_time` | temps on-chain Unix optionnel observé depuis le cluster | +| `detected_at` / `received_at` / `normalized_at` | temps locaux d'acquisition | +| `persisted_at` | instant d'écriture de l'observation | +| `created_at` / `updated_at` | cycle de vie de la ligne SQL | Une requête de prix ou série temporelle ne doit jamais prendre `created_at` comme substitut implicite de `block_time`. @@ -211,16 +211,16 @@ L'inventaire statique de `kb-lib` trouve : Les huit exécuteurs actifs sont : -| Exécuteur actif | Scénario réutilisable actuel | Qualification | -|------------------------------|------------------------------|-----------------------------------------------------------------| -| Solana Core | oui | plusieurs parcours Devnet ; matrice native existante | -| SPL Memo v4 | oui | Devnet ; v1/v3 restent decode-only | -| SPL Associated Token Account | oui | scénario Devnet | -| SPL Token classique | oui | scénarios et lifecycle Devnet | -| SPL Token-2022 | oui | scénarios Devnet et campagne Token Metadata | -| SPL ElGamal registry | non | implémenté + synthétique seulement ; preuve réseau indisponible | -| Metaplex Token Metadata | oui | matrice `15 confirmed / 5 unavailable` | -| Solana Program Metadata | oui | 9 opérations confirmées Devnet | +| Exécuteur actif | Scénario réutilisable actuel | Qualification | +|---|---|---| +| Solana Core | oui | plusieurs parcours Devnet ; matrice native existante | +| SPL Memo v4 | oui | Devnet ; v1/v3 restent decode-only | +| SPL Associated Token Account | oui | scénario Devnet | +| SPL Token classique | oui | scénarios et lifecycle Devnet | +| SPL Token-2022 | oui | scénarios Devnet et campagne Token Metadata | +| SPL ElGamal registry | non | implémenté + synthétique seulement ; preuve réseau indisponible | +| Metaplex Token Metadata | oui | matrice `15 confirmed / 5 unavailable` | +| Solana Program Metadata | oui | 9 opérations confirmées Devnet | Le seul exécuteur actif sans scénario réseau réutilisable est donc ElGamal, et son absence est **`unavailable`/report conditionnel**, pas `implement`, tant qu'une nouvelle possibilité de preuve n'existe pas. @@ -284,18 +284,18 @@ La future matrice transversale doit comparer uniquement les **surfaces actives o Pour chaque capacité, enregistrer : -| Dimension | Valeur attendue | -|-------------------|---------------------------------------------------------------------------------------| -| decoder | actif / réservé / absent | -| materializer | actif / state-only / réservé / non applicable | -| executor | actif / decode-only / deprecated / réservé / absent | -| synthetic | présent / absent / non applicable | -| reusable scenario | présent / absent / unavailable / non applicable | -| simulation | prouvée / non exécutée / unavailable | -| submission | confirmed / non exécutée / unsafe / unavailable | -| postcondition | stateful / replay/materialization / non applicable | -| desktop | adaptateur / logique réutilisable résiduelle / absent | -| final status | `implement`, `decode-only`, `deprecated`, `unavailable`, `not-applicable`, `deferred` | +| Dimension | Valeur attendue | +|---|---| +| decoder | actif / réservé / absent | +| materializer | actif / state-only / réservé / non applicable | +| executor | actif / decode-only / deprecated / réservé / absent | +| synthetic | présent / absent / non applicable | +| reusable scenario | présent / absent / unavailable / non applicable | +| simulation | prouvée / non exécutée / unavailable | +| submission | confirmed / non exécutée / unsafe / unavailable | +| postcondition | stateful / replay/materialization / non applicable | +| desktop | adaptateur / logique réutilisable résiduelle / absent | +| final status | `implement`, `decode-only`, `deprecated`, `unavailable`, `not-applicable`, `deferred` | ### Classification actuelle de départ diff --git a/prompts/029_v0_5_0_foundation_restructuring_plan.md b/olddocs/archivekbot3/prompts/029_v0_5_0_foundation_restructuring_plan.md similarity index 100% rename from prompts/029_v0_5_0_foundation_restructuring_plan.md rename to olddocs/archivekbot3/prompts/029_v0_5_0_foundation_restructuring_plan.md diff --git a/prompts/001.README.md b/prompts/001.README.md index 96412bb..269822e 100644 --- a/prompts/001.README.md +++ b/prompts/001.README.md @@ -1,8 +1,8 @@ - + # Prompts actifs Ce répertoire contient uniquement les prompts nécessaires aux prochaines versions fonctionnelles. Les prompts clôturés sont archivés sous `olddocs/archivekbot3/prompts/`. -- [`029_v0_5_0_foundation_restructuring_plan.md`](029_v0_5_0_foundation_restructuring_plan.md) : cadrage de la fondation `0.5.x`, planification des restructurations configuration, wallet, store et scénarios. +- [`030_v0_5_1_khadhroony_solana_namespace_and_config.md`](030_v0_5_1_khadhroony_solana_namespace_and_config.md) : migration des bibliothèques généralistes vers `ks-*` / `ks_*`, namespace `KS_*`, identités `ks-lib-*` et restructuration sûre de la configuration/logging. diff --git a/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md b/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md new file mode 100644 index 0000000..72513bf --- /dev/null +++ b/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md @@ -0,0 +1,466 @@ + + + +# Khadhroony Bot3 — `0.5.1` — migration Khadhroony Solana et configuration sûre + +## Mission + +Reprendre `khadhroony-bot3` après la clôture validée de `0.5.0` et exécuter la première migration structurelle de la fondation `0.5.x`. + +`0.5.1` doit accomplir deux objectifs liés : + +1. séparer explicitement le domaine des bibliothèques Solana généralistes du domaine applicatif Khadhroony Bot en migrant les bibliothèques vers les namespaces `ks-*` / `ks_*` ; +2. restructurer la configuration sur cette nouvelle fondation, avec namespace d'environnement `KS_*`, séparation du logging et politique stricte de non-divulgation des secrets. + +Cette version est une migration de fondation. Elle ne doit pas ouvrir de nouveau programme Anchor/DEX et ne doit pas absorber prématurément les chantiers `ks-wallet`, `ks-store` ou de complétude des scénarios réservés respectivement à `0.5.2`, `0.5.3` et `0.5.4`. + +## Base validée à préserver + +La release `0.5.0` est une version de cadrage sans restructuration runtime majeure. Elle a établi : + +- la séparation de domaine entre `khadhroony-solana` et `khadhroony-bot` ; +- l'inventaire des frontières de configuration, logging, wallet, store, scénarios et desktop ; +- la cible de renommage des dix crates Solana généralistes ; +- la convention d'environnement `KS_*` ; +- le split obligatoire de la configuration généraliste et de la configuration logging ; +- la nécessité de séparer configuration source, runtime résolue et surfaces publiques/diagnostiques ; +- la migration future des identités techniques `kb-lib.*` vers le domaine `ks-lib-*` ; +- la migration SQL `kb_sol_*` → `k_sol_*` réservée à `0.5.3` ; +- le maintien de `kb-app-demo-desktop` côté Bot ; +- le maintien de l'exception ElGamal dans son statut synthétique actuel tant qu'aucune nouvelle preuve réseau n'est disponible. + +La politique normative est : + +```text +docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md +``` + +Elle doit être lue avant toute proposition de code. + +## Positionnement des projets à conserver + +`khadhroony-project` est une umbrella de projets de trading et/ou de crypto. Elle n'est pas limitée à Solana ni même à la crypto. Des projets futurs pourront par exemple viser XTB ou MetaTrader sans dépendre de Solana. + +`khadhroony-solana` regroupe les bibliothèques généralistes dédiées à Solana. + +`khadhroony-bot` / bot3 est le domaine applicatif du futur robot de trading consommant les composants Khadhroony Solana, avec à terme analyse/création de stratégies et exécution de trading automatique. + +`kb-app-demo-desktop` reste dans le domaine Bot. Il sert actuellement surtout de banc de validation des composants Solana généralistes, mais pourra aussi accueillir des démonstrations spécifiques au bot. + +## Lectures obligatoires avant toute proposition + +1. `README.md`, `ROADMAP.md`, `CHANGELOG.md`, `RULES.md` et ce prompt ; +2. `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md` ; +3. 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` ; +4. `docs/architecture/PROJECT_OBJECTIVES.md`, `CRATE_MAP.md`, `ARCHITECTURE.md`, `PIPELINE_ARCHITECTURE.md`, `STORAGE_ARCHITECTURE.md` et `SURFACE_CRATE_MATRIX.md` ; +5. `README.md`, `USAGE.md`, `TODO.md` et `CHANGELOG.md` des dix crates à renommer et de `kb-app-demo-desktop` ; +6. `config/example.config.json`, `config/schema.config.json`, `.env.example` et tous les exemples/configurations de test ; +7. les tests d'API externe, tests TS-RS, scripts d'audit et références de noms de crates/targets/identités ; +8. les documents archivés `0.5.0` uniquement comme historique, jamais comme source prioritaire face à la politique active et au code courant. + +Avant de modifier un nom public, rechercher son usage réel dans les onze crates, les tests, scripts, fixtures, documentation et contrats persistés. + +## Première prerelease obligatoire de `0.5.1` + +La première prerelease de `0.5.1` est consacrée au plan détaillé de migration. Elle ne doit pas commencer par renommer des répertoires à l'aveugle. + +Elle doit produire au minimum : + +- la table exhaustive des dix crates et identifiants Rust à migrer ; +- la table des dépendances workspace et ordre de renommage ; +- l'inventaire des noms de packages, bins, libs, imports, exports, tests externes, scripts et documentation concernés ; +- l'inventaire exhaustif des variables d'environnement actuellement utilisées et leur nouveau nom `KS_*` ; +- la classification de chaque variable en `KS_SECRET_*`, `KS_PUBLIC_*` ou `KS_*` interne ; +- l'inventaire des identités runtime/persistées et targets techniques à migrer ; +- l'inventaire des payloads Tauri/TS-RS pouvant actuellement transporter de la configuration résolue ; +- l'inventaire des structures dupliquées entre configuration et logging ; +- la stratégie de migration des fichiers de configuration et schémas ; +- les tests de caractérisation nécessaires avant changement ; +- un plan temporaire `0.5.1` sous `docs/plans/`, à archiver à la dernière prerelease de la version. + +Le plan doit être validé avant le premier renommage massif. + +## Migration obligatoire des crates vers `ks-*` + +Les dix crates généralistes doivent migrer ainsi : + +```text +kb-core -> ks-core +kb-config -> ks-config +kb-lib -> ks-lib +kb-logging -> ks-logging +kb-program-ids -> ks-program-ids +kb-pipeline -> ks-pipeline +kb-pipeline-demo-scenarios -> ks-pipeline-demo-scenarios +kb-onchain-transport -> ks-onchain-transport +kb-store -> ks-store +kb-wallet -> ks-wallet +``` + +Les identifiants Rust correspondants migrent de `kb_*` vers `ks_*`. + +`kb-app-demo-desktop` conserve son nom. + +La migration doit couvrir de manière cohérente : + +- noms de répertoires ; +- `Cargo.toml` workspace et manifests des crates ; +- noms de package, library et binary lorsqu'ils appartiennent au domaine Solana généraliste ; +- dépendances workspace ; +- chemins Rust ; +- imports et réexports ; +- tests d'API externe ; +- scripts Python ; +- fixtures et matrices lorsque le nom fait partie d'un contrat actif ; +- documentation active ; +- configuration Tauri uniquement là où elle référence les crates renommées ; +- TS-RS à la source, sans livrer artificiellement les bindings générés. + +La migration ne doit pas créer de dépendance d'une crate `ks-*` vers `kb-app-demo-desktop` ou une future application Bot. + +## Identités runtime, tracing et persistance + +La migration de namespace inclut les identités techniques généralistes actuellement préfixées par `kb-lib`. + +La cible comprend notamment : + +```text +kb-lib.decoder.* -> ks-lib-decoder.* +kb-lib.materializer.* -> ks-lib-materializer.* +kb-lib.executor.* -> ks-lib-executor.* +``` + +Avant remplacement, établir une matrice exhaustive des catégories concernées : + +- tracing targets ; +- `processor_name` ; +- identités de replay ; +- identités d'idempotence ; +- clés de provenance ; +- valeurs persistées dans les tests/fixtures ; +- diagnostics et matrices contractuelles ; +- tout autre identifiant stable contenant un préfixe historique `kb-*` ou `kb-lib.*`. + +La base peut encore être reconstruite ou migrée avant `0.6.x`. Il est donc acceptable de casser proprement une identité historique si elle appartient réellement à Khadhroony Solana, à condition que la migration soit explicite, testée et documentée. + +Ne pas renommer arbitrairement les segments métier `solana`, `spl`, protocoles, surfaces ou opérations lorsqu'ils expriment déjà une sémantique stable. + +## Tables SQL : ne pas anticiper `0.5.3` + +La cible durable des tables Solana est : + +```text +kb_sol_* -> k_sol_* +``` + +et les éventuelles tables réellement spécifiques au domaine Bot utiliseront : + +```text +kb_* +``` + +Cependant, le renommage physique des tables et la normalisation des migrations appartiennent à `0.5.3` avec `ks-store`, car ce chantier doit être traité avec `block_time`, provenance, idempotence, index et contrats de replay. + +`0.5.1` peut mettre à jour les identités techniques persistées `ks-lib-*`, mais ne doit pas transformer la migration SQL en chantier secondaire dispersé. + +## Namespace obligatoire des variables d'environnement + +Après migration, toute variable d'environnement appartenant au workspace doit commencer par `KS_`. + +La convention retenue est : + +```text +KS_SECRET_* secret absolu +KS_PUBLIC_* valeur explicitement candidate à une surface publique +KS_* valeur interne/diagnostique +``` + +Une ancienne variable `KB_*` ou une variable projet sans préfixe `KS_` ne doit pas subsister dans le code, les exemples, tests ou documentation après fermeture de la migration. + +Les variables du système d'exploitation ou de dépendances tierces ne sont pas renommées artificiellement si elles ne constituent pas un contrat de configuration Khadhroony. + +### `KS_SECRET_*` + +Une valeur issue de `KS_SECRET_*` : + +- peut être utilisée côté backend lorsque nécessaire ; +- ne doit jamais apparaître dans les logs ; +- ne doit jamais apparaître dans une erreur publique ; +- ne doit jamais être sérialisée vers Tauri ; +- ne doit jamais être exposée dans un diagnostic, même debug ; +- ne doit jamais être exportée par TS-RS comme valeur résolue ; +- doit rester secrète lorsqu'elle est incorporée dans une URL, DSN ou autre valeur composée. + +Un diagnostic peut indiquer qu'un secret est configuré ou absent sans exposer sa valeur. + +### `KS_PUBLIC_*` + +Le préfixe `KS_PUBLIC_*` classe la variable comme publiable, mais ne constitue pas une autorisation automatique de parcourir l'environnement et de l'envoyer au frontend. + +L'exposition doit être explicitement définie par un DTO ou une API publique. + +### autres `KS_*` + +Les autres variables `KS_*` sont internes. Elles ne sont pas exposées par les payloads normaux. Elles peuvent apparaître dans un diagnostic explicitement demandé lorsque leur sémantique n'est pas sensible. + +Le simple fait de compiler en mode debug ne doit pas automatiquement exposer toutes les valeurs internes. + +## Split obligatoire de la configuration + +`0.5.1` doit extraire la configuration logging du document généraliste. + +La cible minimale est conceptuellement : + +```text +configuration générale + schéma général +configuration logging + schéma logging +``` + +Les profils généralistes et logging sont indépendants. Il ne doit plus être nécessaire de recopier un bloc logging complet dans chaque profil réseau/applicatif. + +D'autres documents spécialisés sont autorisés seulement si l'audit démontre qu'ils réduisent réellement le couplage et possèdent une responsabilité ou validation indépendante. + +Ne pas découper arbitrairement la configuration en un fichier par sous-structure. + +## Propriété des contrats de logging + +`0.5.0` a constaté une duplication des structures `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig` entre la configuration et le runtime logging. + +`0.5.1` doit définir un propriétaire clair du contrat source de logging sans créer de cycle de dépendances. + +La solution retenue doit : + +- éviter une duplication de DTO identiques ; +- éviter que `ks-config` dépende du runtime `ks-logging` uniquement pour réutiliser un type ; +- éviter une nouvelle crate de contrat si elle n'a pas de responsabilité autonome suffisante ; +- supprimer les conversions manuelles du desktop lorsque la nouvelle frontière le permet. + +## Configuration source, runtime et publique + +La restructuration doit empêcher qu'une configuration résolue complète puisse être envoyée au frontend par commodité. + +Distinguer au minimum : + +1. représentation source : fichiers, placeholders et références `${KS_*}` ; +2. représentation runtime : valeurs validées et résolues nécessaires au backend ; +3. représentation publique/diagnostique : DTO explicitement construits pour l'UI, les diagnostics ou une API externe. + +Une valeur runtime contenant un secret ne doit pas redevenir une `String` publique sans classification ni contrôle. + +Éviter le modèle : + +```text +runtime complet -> sérialisation -> suppression/redaction après coup +``` + +Préférer : + +```text +runtime -> construction explicite d'un DTO public sûr +``` + +## Résolution d'environnement et `.env` + +Auditer et tester : + +- `${NAME}` ; +- `${NAME:-fallback}` ; +- erreurs de variable absente ; +- valeurs vides ; +- substitutions multiples ; +- valeurs composées ; +- détection et propagation de la sensibilité ; +- priorité environnement / `.env` / valeur par défaut selon le contrat actuel ; +- absence de fuite dans les messages d'erreur ; +- comportement des profils. + +Le mécanisme final doit accepter uniquement les noms de variables conformes au nouveau contrat lorsqu'ils appartiennent au workspace. + +## Payloads Tauri et TS-RS + +Le risque prioritaire identifié en `0.5.0` est l'exposition de `AppConfig` / `ProfileConfig` résolus au frontend. + +`0.5.1` doit supprimer cette possibilité par construction. + +Les commandes Tauri restent des adaptateurs minces : + +- aucune logique métier nouvelle dans `tauri.rs` ; +- aucun `?` ni unwrap dans les commandes Tauri ; +- DTO publics dédiés ; +- aucun secret résolu dans les bindings ou réponses ; +- diagnostics séparés des payloads normaux ; +- tests négatifs avec valeurs sentinelles secrètes. + +## Tests de sécurité obligatoires + +Ajouter des tests prouvant notamment que : + +- une sentinelle issue de `KS_SECRET_*` n'apparaît dans aucune sérialisation publique ; +- elle n'apparaît pas dans les erreurs publiques ; +- elle n'apparaît pas dans les diagnostics debug ; +- une URL ou DSN composée avec un secret est entièrement traitée comme sensible ; +- `KS_PUBLIC_*` n'est exposé que par une surface explicitement autorisée ; +- une variable `KS_*` interne n'apparaît pas dans le payload normal ; +- les anciens noms d'environnement sont absents après migration ; +- les schémas JSON général et logging valident leurs documents respectifs ; +- le choix d'un profil logging est indépendant du profil général ; +- les tests d'API externe compilent avec les nouveaux noms `ks_*`. + +Ne pas figer par test un comportement `0.5.0` connu comme dangereux uniquement pour préserver la compatibilité. + +## Ordre approximatif des prereleases + +Le détail doit être confirmé par `0.5.1-pre.001`, mais la trajectoire cible est : + +### `0.5.1-pre.001` — plan de migration + +- inventaires exhaustifs ; +- table de renommage ; +- matrice d'identités ; +- matrice des variables d'environnement ; +- stratégie config/logging ; +- tests de caractérisation ; +- plan temporaire. + +### `0.5.1-pre.002` — migration mécanique `ks-*` / `ks_*` + +- renommer les dix crates ; +- manifests, imports, exports, scripts et tests ; +- maintenir un workspace compilable et auditable ; +- conserver `kb-app-demo-desktop`. + +### `0.5.1-pre.003` — identités techniques et environnement `KS_*` + +- migrer les targets/processor identities généralistes ; +- migrer les variables d'environnement ; +- mettre en place la classification Secret/Public/Internal ; +- mettre à jour exemples et tests sans encore réinventer le store SQL. + +### `0.5.1-pre.004` — split configuration/logging + +- documents et schémas indépendants ; +- profils logging indépendants ; +- propriété unique des contrats logging ; +- migration/compatibilité explicite des fichiers `0.5.0`. + +### `0.5.1-pre.005` — runtime/public et Tauri sûr + +- séparer source/runtime/public ; +- supprimer les payloads de config complète ; +- diagnostics sûrs ; +- tests de non-divulgation ; +- TS-RS aligné. + +### `0.5.1-pre.006` — réconciliation et clôture + +- audit exhaustif des anciens préfixes ; +- documentation finale ; +- TODO/changelogs ; +- validations workspace ; +- archivage du plan/prompt ; +- préparation de `0.5.2`. + +Ce découpage peut évoluer si `pre.001` démontre qu'une étape doit être scindée pour garder chaque prerelease compilable et bornée. + +## 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 `ks-*` 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 : + +```text +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 : + +```bash +cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json +``` + +Le build de release est piloté par : + +```bash +cargo tauri build -c kb-app-demo-desktop/tauri.conf.json +``` + +Tauri déclenche lui-même les scripts frontend configurés. + +## Discipline des scénarios et validations + +Le renommage de `kb-pipeline-demo-scenarios` vers `ks-pipeline-demo-scenarios` ne change pas son rôle : les scénarios sont des validations réutilisables des composants Solana, pas de la logique spécifique au bot. + +Les campagnes déjà qualifiées ne doivent pas être rejouées automatiquement uniquement parce qu'une crate ou un identifiant a changé de nom. Les tests contractuels, compilations et chemins de preuve doivent être vérifiés ; un rerun réseau n'est requis que si une frontière réellement couverte par la preuve a changé. + +ElGamal reste une exception connue et ne doit pas devenir une tâche implicite de `0.5.1`. + +## 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 ; +- 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. + +Un renommage mécanique massif doit rester traçable dans `delta.md` et ne doit pas masquer des changements fonctionnels sans rapport. + +## Dernière prerelease obligatoire + +La dernière prerelease de `0.5.1` devra : + +- exécuter les validations finales ; +- vérifier qu'aucun ancien nom de crate ou variable projet interdit ne subsiste hors archives/historique explicitement autorisé ; +- vérifier les identités runtime/persistées migrées ; +- vérifier la non-divulgation des secrets ; +- finaliser README, ROADMAP, changelogs, TODO, règles, guides et schémas 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 `0.5.2` consacré à `ks-wallet` ; +- préparer la release finale sans introduire un nouveau chantier structurel majeur. + +## Contrôles de référence + +```bash +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é : + +```bash +cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json +``` + +Pour une validation de release desktop : + +```bash +cargo tauri build -c kb-app-demo-desktop/tauri.conf.json +```