diff --git a/CHANGELOG.md b/CHANGELOG.md index 08d820d..7653b99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,42 @@ - + # 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.1 — namespaces Khadhroony Solana et configuration sûre + +### Namespace et ownership + +- migration des dix bibliothèques Solana généralistes vers `ks-*` / `ks_*`, avec maintien de `kb-app-demo-desktop` dans le domaine applicatif Bot ; +- migration des 255 identités techniques actives vers `ks-lib-decoder.*`, `ks-lib-executor.*` et `ks-lib-materializer.*` ; +- adoption du namespace `KS_*` pour les contrats Solana, de `KB_*` pour les contrats réellement possédés par le Bot et des classes `*_SECRET_*`, `*_PUBLIC_*` et internes ; +- conservation explicite du workspace, du dépôt et du répertoire racine sous le nom `khadhroony-bot3`. + +### Configuration et composition + +- remplacement du document applicatif monolithique par des documents spécialisés `logging`, `transport`, `listeners`, `store`, `wallet` et `execution`, chacun validé par son schéma et doté de defaults autonomes ; +- composition propre aux binaires via `.default.config.json`, avec sélection et validation des documents/profils partagés par `ks-config` ; +- sortie de `logs_directory` et `wallets_directory` des profils, avec overrides d’environnement dédiés ; +- déplacement de `auto_reconnect` vers les defaults WebSocket du transport et des autorisations d’envoi vers la politique d’exécution ; +- rangement des exemples conformes sous `config/exemples/` et des schémas actifs sous `config/schemas/`. + +### Sécurité et frontières publiques + +- distinction explicite entre configuration source, runtime backend-only et DTO publics/diagnostiques ; +- propagation de sensibilité selon `Secret > Internal > Public`, y compris dans les valeurs composées après substitution d’environnement ; +- retrait de `Serialize`/`Debug` des contrats de configuration sensibles et suppression des URLs résolues des snapshots transport exposables ; +- remplacement des retours Tauri directs par des DTO desktop sanitisés, sans URL RPC/WS, DSN PostgreSQL, chemins wallet/SQLite ni secrets ; +- durcissement des erreurs HTTP/WS et de validation afin de ne pas recopier de corps distant, message RPC ou valeur rejetée susceptible de contenir un secret ; +- retrait de TS-RS de `ks-config` et `ks-lib`, les bindings TypeScript devenant une responsabilité des applications Tauri via wrappers explicites. + +### Validation et suite + +- validations `cargo fmt`, `cargo check --workspace`, `cargo clippy --all-targets`, audit workspace, `cargo test --workspace` et démarrage Tauri réussies sur la frontière `0.5.1-pre.008` clôturée ; +- conservation des préfixes SQL `kb_sol_*` jusqu’au chantier cohérent `0.5.3` ; +- préparation de `0.5.2`, dédiée à la restructuration de `ks-wallet`, sans ouvrir de nouvelle surface protocolaire. + ## 0.5.0 — cadrage de la fondation `0.5.x` ### Architecture et namespaces diff --git a/Cargo.toml b/Cargo.toml index 008bdda..12417d7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,5 +1,5 @@ # file: Cargo.toml -# version: 52 +# version: 53 [workspace] resolver = "3" @@ -18,7 +18,7 @@ members = [ ] [workspace.package] -version = "0.5.1-pre.8" +version = "0.5.1-pre.9" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-bot3" diff --git a/README.md b/README.md index 573fb54..7b4bda4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # Khadhroony Bot3 @@ -21,9 +21,9 @@ Le workspace contient onze crates : - `ks-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`. Depuis `0.5.1-pre.002`, les dix crates généralistes utilisent les noms `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` conserve son nom et reste une application du workspace Bot. Le workspace, le dépôt et le répertoire racine restent nommés `khadhroony-bot3` pendant cette migration et ne doivent pas être renommés avant `1.0` ou une version ultérieure explicitement dédiée. La politique de migration est définie dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). +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`. Depuis `0.5.1`, les dix crates généralistes utilisent les noms `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` conserve son nom et reste une application du workspace Bot. Le workspace, le dépôt et le répertoire racine restent nommés `khadhroony-bot3` pendant cette migration et ne doivent pas être renommés avant `1.0` ou une version ultérieure explicitement dédiée. La politique de migration est définie dans [`docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md). -Depuis `0.5.1-pre.008`, les contrats de configuration source/runtime susceptibles de contenir des secrets restent backend-only et ne sont ni sérialisables ni `Debug` par défaut. Les crates `ks-config` et `ks-lib` ne génèrent plus de bindings TS-RS ; les surfaces TypeScript/Tauri sont possédées par les applications via des DTO explicites. +Depuis `0.5.1`, les contrats de configuration source/runtime susceptibles de contenir des secrets restent backend-only et ne sont ni sérialisables ni `Debug` par défaut. Les crates `ks-config` et `ks-lib` ne génèrent plus de bindings TS-RS ; les surfaces TypeScript/Tauri sont possédées par les applications via des DTO explicites. Références : diff --git a/ROADMAP.md b/ROADMAP.md index 4026471..02c2507 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # ROADMAP — khadhroony-bot3 @@ -82,24 +82,17 @@ Cadrage clôturé avant toute restructuration majeure : ### 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. +Version clôturée : les frontières de namespace et de configuration prévues par le cadrage `0.5.0` sont désormais actives. -- renommer les dix crates généralistes : `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` 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 `KS_*` aux variables possédées par les composants Solana généralistes et réserver `KB_*` aux variables réellement possédées par `kb-app-demo-desktop` ou de futures crates spécifiques au Bot ; -- appliquer symétriquement les classes `*_SECRET_*`, `*_PUBLIC_*` et internes aux namespaces `KS_*` et `KB_*`, avec exposition publique uniquement via une surface explicitement autorisée ; -- préserver la sensibilité après substitution : toute valeur composée contenant un `KS_SECRET_*` ou `KB_SECRET_*` reste secrète ; -- remplacer la configuration monolithique par des compositions propres aux binaires (`.default.config.json`) qui sélectionnent des documents/profils spécialisés partageables ; -- séparer au minimum logging, transport, listeners, store, wallet et politiques d’exécution selon leur ownership réel ; `logs_directory` appartient au logging, `wallets_directory` au wallet et les permissions d’envoi à la politique d’exécution ; -- permettre des sélections de profils logging, transport et listeners indépendantes de la composition active du binaire ; -- permettre aux futurs workers et applications de réutiliser les documents généralistes `ks-*` tout en ajoutant une configuration dédiée sans enregistrer leur identité dans `ks-config` ; -- 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 dix crates Solana généralistes sont nommées `ks-*` / `ks_*`, tandis que `kb-app-demo-desktop` reste dans le domaine Bot ; +- les identités techniques généralistes utilisent `ks-lib-decoder.*`, `ks-lib-materializer.*` et `ks-lib-executor.*` ; +- les variables possédées par Khadhroony Solana utilisent `KS_*`, avec `KS_SECRET_*`, `KS_PUBLIC_*` et valeurs internes, tandis que `KB_*` est réservé aux contrats réellement applicatifs ; +- les configurations partagées sont séparées en logging, transport, listeners, store, wallet et execution, avec schémas sous `config/schemas/`, exemples sous `config/exemples/` et defaults autonomes ; +- les binaires peuvent composer ces documents via `.default.config.json` sans que `ks-config` connaisse leur structure applicative ; +- les contrats runtime sensibles restent backend-only et les DTO Tauri sont construits explicitement, sans URL résolue, DSN, chemin wallet/SQLite ou autre secret ; +- TS-RS appartient aux applications consommatrices et n’est plus généré par `ks-config` ou `ks-lib`. -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`. +Les préfixes SQL historiques `kb_sol_*` restent volontairement inchangés jusqu’à `0.5.3`, qui traitera leur migration avec les contrats temporels, de provenance, d’idempotence et d’index. ### 0.5.2 — `ks-wallet` diff --git a/config/README.md b/config/README.md index 81fa1f0..3d68997 100644 --- a/config/README.md +++ b/config/README.md @@ -1,5 +1,5 @@ - + # Configuration locale @@ -122,7 +122,7 @@ Une valeur composée hérite de la sensibilité la plus forte de ses placeholder Les composants `ks-*` utilisent `KS_SECRET_*`, `KS_PUBLIC_*` ou `KS_*`. Les besoins réellement spécifiques à une application `kb-*` utilisent `KB_SECRET_*`, `KB_PUBLIC_*` ou `KB_*`. -Les secrets ne sont jamais écrits en clair dans le dépôt. Depuis `0.5.1-pre.008`, les contrats source/runtime sensibles restent backend-only, tandis que les applications exposent uniquement des DTO publics ou diagnostics explicitement bornés. +Les secrets ne sont jamais écrits en clair dans le dépôt. Depuis `0.5.1`, les contrats source/runtime sensibles restent backend-only, tandis que les applications exposent uniquement des DTO publics ou diagnostics explicitement bornés. ## Exemples et schémas diff --git a/docs/README.md b/docs/README.md index c8965de..ab53650 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@ - + # Documentation active de Khadhroony Bot3 @@ -95,6 +95,7 @@ Les onze crates possèdent `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` - [Validation Metaplex Token Metadata 0.4.7](validation/V0_4_7_METAPLEX_TOKEN_METADATA_VALIDATION_REPORT.md) ; - [Validation Metadata on-chain et clôture 0.4.8](validation/V0_4_8_METADATA_VALIDATION_REPORT.md) ; +- [Validation de fondation et clôture 0.5.1](validation/V0_5_1_FOUNDATION_VALIDATION_REPORT.md) ; - [`validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md`](validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md) ; - [`validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md`](validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md). @@ -102,12 +103,10 @@ Les preuves détaillées de `0.4.8-pre.*` restent accessibles sous `../olddocs/a ## 10. Plans de version actifs -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/`. +Les plans temporaires `0.5.0` et `0.5.1` sont clôturés et archivés sous `../olddocs/archivekbot3/docs/plans/`. -Plan actif de `0.5.1` : - -- [`V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md`](plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md) — inventaire de migration `ks-*` / `ks_*` / `KS_*`, configuration sûre et découpage borné des prereleases. +Le plan détaillé de `0.5.2` sera créé dans sa première prerelease conformément au cycle de développement ; aucun plan temporaire `0.5.2` n’est préécrit avant cet inventaire. ## 11. Prompt de reprise -- [`Prompt actif 0.5.1`](../prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md). +- [`Prompt actif 0.5.2`](../prompts/031_v0_5_2_ks_wallet_restructuring.md). diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 4a2825e..24610e2 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 `ks-lib`, des données de `ks-store` et des capacité - `ks-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 `ks-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 à `ks-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`. -- `ks-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`. +- `ks-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Son namespace `ks-*` est stabilisé depuis `0.5.1` et 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 `ks-program-ids`. - Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `ks-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 à `ks-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`. +- Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `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 à `ks-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,6 @@ 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. +`0.5.1` stabilise le domaine Khadhroony Solana sous `ks-*` / `KS_*` et remplace la configuration monolithique par des documents spécialisés composables, avec une frontière backend/public explicitement sanitisée. + 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 35d2b79..6c4058f 100644 --- a/docs/architecture/CRATE_MAP.md +++ b/docs/architecture/CRATE_MAP.md @@ -1,5 +1,5 @@ - + # Carte des crates @@ -8,7 +8,7 @@ | Crate | Type | Responsabilité principale | État documentaire | |------------------------------|------------------------|--------------------------------------------------------------------------------------|------------------------------------------| | `ks-core` | bibliothèque | erreurs, résultat et identité de module partagés | README/TODO/USAGE/CHANGELOG présents | -| `ks-config` | bibliothèque | compositions binaires, documents JSON partagés, environnement, validation et profils | migration/restructuration en `0.5.1` | +| `ks-config` | bibliothèque | compositions binaires, documents JSON partagés, environnement, validation et profils | fondation stabilisée depuis `0.5.1` | | `ks-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | README/TODO/USAGE/CHANGELOG présents | | `ks-logging` | bibliothèque | initialisation du logging et du tracing | README/TODO/USAGE/CHANGELOG présents | | `ks-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | README/TODO/USAGE/CHANGELOG présents | @@ -19,7 +19,7 @@ | `ks-wallet` | bibliothèque | wallet temporaire et frontière de signataire | nom `ks-*` actif ; 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 actifs depuis `0.5.1-pre.002`. La migration a renommé 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). +La table décrit les noms physiques stabilisés par `0.5.1`. La migration a renommé 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 diff --git a/docs/architecture/PIPELINE_ARCHITECTURE.md b/docs/architecture/PIPELINE_ARCHITECTURE.md index 82758d2..ccd33bb 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 `ks-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 à `ks-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 `ks-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`. +`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 à `ks-pipeline-demo-scenarios`, dont le namespace `ks-*` est stabilisé depuis `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 `ks-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 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. +- La réconciliation finale des scénarios encore dupliqués entre le desktop et `ks-pipeline-demo-scenarios` est planifiée en `0.5.4`. +- 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 88d13ce..11bc4f2 100644 --- a/docs/architecture/PROJECT_OBJECTIVES.md +++ b/docs/architecture/PROJECT_OBJECTIVES.md @@ -1,5 +1,5 @@ - + # Objectifs du projet Khadhroony Bot3 @@ -69,7 +69,7 @@ Le noyau livré jusqu’à `0.4.8` couvre notamment : Ne sont pas considérés comme achevés : - 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 ; +- la réconciliation complète des scénarios réutilisables entre `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 804bfd8..c62f6bb 100644 --- a/docs/architecture/STORAGE_ARCHITECTURE.md +++ b/docs/architecture/STORAGE_ARCHITECTURE.md @@ -1,5 +1,5 @@ - + # Architecture du stockage @@ -59,7 +59,7 @@ 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` 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 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 `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. diff --git a/docs/guides/CONFIGURATION.md b/docs/guides/CONFIGURATION.md index 9ad0499..8cfa1d4 100644 --- a/docs/guides/CONFIGURATION.md +++ b/docs/guides/CONFIGURATION.md @@ -1,5 +1,5 @@ - + # Guide de configuration @@ -145,7 +145,7 @@ appartiennent à `execution.config.json`, avec les limites de dépense, frais, s ## Contrat runtime transitoire -Pendant `0.5.1`, `ks-config` reconstruit encore `AppConfig/ProfileConfig` afin de préserver les consommateurs backend existants. Il s'agit d'une projection runtime, pas d'un document source ni d'une surface de sortie. Depuis `pre.008`, ces contrats et les documents spécialisés susceptibles de contenir des valeurs résolues ne dérivent ni `serde::Serialize` ni `Debug`. +`ks-config` reconstruit encore `AppConfig/ProfileConfig` comme projection runtime transitoire afin de préserver les consommateurs backend existants. Il s'agit d'une projection runtime, pas d'un document source ni d'une surface de sortie. Depuis `0.5.1`, ces contrats et les documents spécialisés susceptibles de contenir des valeurs résolues ne dérivent ni `serde::Serialize` ni `Debug`. Les fixtures de compatibilité sont sous `test-fixtures/config/`. Elles ne doivent pas être chargées en production. @@ -163,11 +163,11 @@ La section `application` d'une composition est opaque à `ks-config`. Le desktop ## Frontière TS-RS -Depuis `pre.008`, `ks-config` et `ks-lib` ne dépendent plus de TS-RS et ne possèdent plus de bindings TypeScript générés. Les DTO traversant Tauri appartiennent à `kb-app-demo-desktop` ou à la future application concernée. Une exception dans une crate `ks-*` exige un contrat TypeScript générique indépendant de Tauri explicitement justifié et audité. +Depuis `0.5.1`, `ks-config` et `ks-lib` ne dépendent plus de TS-RS et ne possèdent plus de bindings TypeScript générés. Les DTO traversant Tauri appartiennent à `kb-app-demo-desktop` ou à la future application concernée. Une exception dans une crate `ks-*` exige un contrat TypeScript générique indépendant de Tauri explicitement justifié et audité. ## Étape suivante -`pre.009` est une prerelease de clôture : réconciliation documentaire, audits finaux, nettoyage des TODO, archivage du plan/prompt et préparation de `0.5.2`. +`0.5.1` clôt cette architecture de configuration. Les changements fonctionnels de wallet appartiennent à `0.5.2`, la normalisation SQL à `0.5.3` et l’audit final des scénarios/exécuteurs à `0.5.4`. ## Invariants diff --git a/docs/validation/V0_5_1_FOUNDATION_VALIDATION_REPORT.md b/docs/validation/V0_5_1_FOUNDATION_VALIDATION_REPORT.md new file mode 100644 index 0000000..b28e0e3 --- /dev/null +++ b/docs/validation/V0_5_1_FOUNDATION_VALIDATION_REPORT.md @@ -0,0 +1,131 @@ + + + +# Validation de fondation — clôture 0.5.1 + +## Périmètre + +La version `0.5.1` ferme la première restructuration de fondation décidée pendant `0.5.0` : namespaces Khadhroony Solana, configuration composable, séparation source/runtime/public et réduction de la surface TS-RS aux applications. + +Elle ne modifie volontairement ni le préfixe SQL historique `kb_sol_*`, ni la structure fonctionnelle profonde de `ks-wallet`, ni la couverture protocolaire Solana/DEX. + +## Namespace et ownership + +La cible validée est : + +- dix bibliothèques Solana généralistes sous `ks-*` / `ks_*` ; +- `kb-app-demo-desktop` conservé dans le domaine applicatif Bot ; +- identités techniques actives sous `ks-lib-decoder.*`, `ks-lib-executor.*` et `ks-lib-materializer.*` ; +- variables Solana sous `KS_*`, avec `KS_SECRET_*`, `KS_PUBLIC_*` et internes ; +- `KB_*` réservé aux contrats réellement possédés par une application Bot. + +Le workspace, le dépôt et le répertoire racine restent volontairement nommés `khadhroony-bot3`. + +## Configuration composable + +La configuration source est répartie entre : + +```text +config/ +├── kb-app-demo-desktop.default.config.json +├── logging.config.json +├── transport.config.json +├── listeners.config.json +├── store.config.json +├── wallet.config.json +├── execution.config.json +├── exemples/ +└── schemas/ +``` + +Les documents spécialisés possèdent leurs defaults et profils indépendants. La composition d’un binaire sélectionne les documents et profils qu’il consomme sans obliger `ks-config` à connaître la structure métier de l’application. + +`logs_directory` et `wallets_directory` sont globaux à leurs domaines respectifs. Les autorisations d’envoi appartiennent à la politique d’exécution. Les defaults de reconnexion WebSocket appartiennent au transport et peuvent être surchargés par endpoint. + +## Frontières de sensibilité + +La classification appliquée est : + +```text +Secret > Internal > Public +``` + +Elle s’applique aussi aux valeurs composées après substitution des placeholders d’environnement. + +Les contrats source/runtime susceptibles de contenir des valeurs résolues sensibles restent backend-only et ne dérivent ni `serde::Serialize` ni `Debug` par défaut. + +Les snapshots de transport exposables ne transportent plus les URLs résolues. Les erreurs HTTP/WS et de validation ne recopient plus les valeurs rejetées, les corps HTTP distants ni les messages JSON-RPC distants susceptibles de réinjecter un credential. + +## Tauri et TS-RS + +`ks-config` et `ks-lib` ne produisent plus de bindings TS-RS. + +Les contrats TypeScript/Tauri appartiennent à l’application consommatrice. `kb-app-demo-desktop` construit explicitement ses DTO publics et diagnostiques et ne retourne plus directement les contrats runtime `ks-*`. + +Les canaris desktop et transport vérifient notamment : + +- absence d’URL RPC/WS résolue dans les payloads ; +- absence de DSN PostgreSQL ; +- absence de chemin wallet/SQLite dans les payloads fonctionnels ; +- absence de secret canari dans les projections publiques/diagnostiques ; +- `Debug` sanitisé pour les clients/sessions transport. + +## Validation opérateur du 10 août 2026 + +Après `0.5.1-pre.008-delta-fix-003`, l’opérateur a validé : + +- `cargo fmt --all` ; +- `cargo check --workspace` ; +- `cargo clippy --all-targets` sans warning ; +- `python3 scripts/audit_rust_workspace_rules.py` avec audit Rust général propre, export completeness à zéro candidat et audit Khadhroony propre ; +- `cargo test --workspace` ; +- `cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json` avec chargement de la composition et initialisation des transports/store. + +Les principales cibles unitaires observées après le dernier correctif comprennent : + +- `kb-app-demo-desktop` : 165 tests ; +- `ks-config` : 31 tests, plus 2 tests d’API externe ; +- `ks-core` : 2 tests ; +- `ks-lib` : 606 tests, plus 9 tests d’intégration/API externe ; +- `ks-logging` : 25 tests ; +- `ks-onchain-transport` : 124 tests ; +- `ks-pipeline` : 109 tests, plus 3 tests d’API externe Metadata ; +- `ks-pipeline-demo-scenarios` : 105 tests bibliothèque, 1 test CLI et 1 test d’API externe ; +- `ks-program-ids` : 6 tests ; +- `ks-store` : 84 tests ; +- `ks-wallet` : 6 tests. + +## Validation finale de `pre.009` + +`0.5.1-pre.009` ne doit introduire aucun nouveau comportement fonctionnel. Après application du delta de clôture, la campagne standard doit être rejouée : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --all-targets +python3 scripts/audit_rust_workspace_rules.py +cargo test --workspace +``` + +Avant publication finale de `0.5.1`, le build desktop de release est recommandé afin de vérifier également TypeScript/Vite par la chaîne Tauri : + +```bash +cargo tauri build -c kb-app-demo-desktop/tauri.conf.json +``` + +Ce rapport ne prétend pas que ce build de release a déjà été exécuté pour `0.5.1`. + +## Reports + +- restructuration fonctionnelle profonde du wallet : `0.5.2` ; +- migration `kb_sol_*` vers `k_sol_*` et normalisation temporelle/provenance : `0.5.3` ; +- centralisation finale des scénarios et audit des exécuteurs : `0.5.4` ; +- nouvelle qualification réseau ElGamal uniquement si une possibilité technique nouvelle apparaît. + +## Traçabilité + +Le plan temporaire `0.5.1` et le prompt de session `030` sont archivés sous `olddocs/archivekbot3/`. Les décisions durables restent dans le ROADMAP, les guides, les règles et la politique de namespace active. + +## Statut + +**Fondation fonctionnelle `0.5.1` prête pour la validation finale de la prerelease de clôture.** diff --git a/ks-config/CHANGELOG.md b/ks-config/CHANGELOG.md index 1c231a7..2a37f84 100644 --- a/ks-config/CHANGELOG.md +++ b/ks-config/CHANGELOG.md @@ -1,8 +1,13 @@ - + # CHANGELOG — ks-config +## `0.5.1-pre.009` + +- réconcilie schémas, exemples sous `config/exemples/`, guide de configuration et documentation de crate avant archivage du plan `0.5.1` ; +- retire du TODO la tâche de clôture `pre.009` désormais terminée, sans modifier les contrats runtime. + ## `0.5.1-pre.008` - Fix: use `Result::is_err()` for execution and wallet schema validation checks, removing the Clippy redundant-pattern warnings without changing fail-closed behavior. diff --git a/ks-config/README.md b/ks-config/README.md index 212c8fd..2bb1870 100644 --- a/ks-config/README.md +++ b/ks-config/README.md @@ -1,5 +1,5 @@ - + # ks-config @@ -56,7 +56,7 @@ Les valeurs globales telles que `logs_directory` et `wallets_directory` ne sont `ks-onchain-transport` peut consommer directement `TransportProfileConfig`. -Depuis `0.5.1-pre.008`, `ks-config` ne dépend plus de TS-RS et ne produit plus de bindings TypeScript. Ses contrats source/runtime peuvent contenir des secrets résolus : ils ne dérivent donc ni `serde::Serialize` ni `Debug`. Les applications propriétaires construisent leurs DTO publics et diagnostics bornés champ par champ. +Depuis `0.5.1`, `ks-config` ne dépend plus de TS-RS et ne produit plus de bindings TypeScript. Ses contrats source/runtime peuvent contenir des secrets résolus : ils ne dérivent donc ni `serde::Serialize` ni `Debug`. Les applications propriétaires construisent leurs DTO publics et diagnostics bornés champ par champ. La section `application` d'une composition est volontairement opaque pour `ks-config`. Chaque binaire propriétaire définit son schéma et le valide avec `validate_json_value_against_schema`; le desktop utilise `config/schemas/kb-app-demo-desktop.application.config.schema.json`. diff --git a/ks-config/TODO.md b/ks-config/TODO.md index 221a6d9..8a59cfc 100644 --- a/ks-config/TODO.md +++ b/ks-config/TODO.md @@ -1,9 +1,8 @@ - + # TODO — ks-config ## Série `0.5.x` -- [ ] `0.5.1-pre.009` - réconcilier une dernière fois schémas, exemples, guide de configuration et contrat d'API externe avant archivage du plan. - [ ] Contrat - maintenir l’identité entre chaque schéma embarqué et son fichier sous `config/schemas/`. diff --git a/olddocs/archivekbot3/001.README.md b/olddocs/archivekbot3/001.README.md index 7c91903..39028f7 100644 --- a/olddocs/archivekbot3/001.README.md +++ b/olddocs/archivekbot3/001.README.md @@ -1,5 +1,5 @@ - + # Archive documentaire de khadhroony-bot3 @@ -36,3 +36,7 @@ Le plan `0.4.8`, le prompt de session `028`, les audits `V0_4_8_PRE_*` et les ra ## 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`. + +## Clôture 0.5.1 + +Le plan de namespace/configuration `0.5.1` et le prompt de session `030` sont archivés sous `docs/plans/` et `prompts/`. Les décisions durables restent dans le ROADMAP, les guides de configuration, la politique de namespace et le rapport actif `docs/validation/V0_5_1_FOUNDATION_VALIDATION_REPORT.md`. diff --git a/docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md b/olddocs/archivekbot3/docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md similarity index 98% rename from docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md rename to olddocs/archivekbot3/docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md index 75e7171..e02fcf1 100644 --- a/docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md +++ b/olddocs/archivekbot3/docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md @@ -1,13 +1,13 @@ - - + + -# Plan temporaire `0.5.1` — namespace Khadhroony Solana et configuration sûre +# Plan archivé `0.5.1` — namespace Khadhroony Solana et configuration sûre -## 1. Statut et règle de cette prerelease +## 1. Statut de clôture -Ce document est le plan temporaire de `0.5.1`. Les prereleases `pre.001` à `pre.004` ont fermé l'inventaire puis migré crates, identités techniques et variables d'environnement. `pre.005` à `pre.007` ont terminé le split logging/transport/listeners/store/wallet/execution, les compositions de binaires et les defaults autonomes. `pre.008` ferme maintenant les frontières source/runtime/public/diagnostic, la non-divulgation et TS-RS. `kb-app-demo-desktop` et le workspace racine restent nommés comme avant. +Ce document a servi de plan temporaire à `0.5.1` et est archivé lors de `0.5.1-pre.009`. Les prereleases `pre.001` à `pre.004` ont fermé l’inventaire puis migré crates, identités techniques et variables d’environnement ; `pre.005` à `pre.007` ont terminé le split logging/transport/listeners/store/wallet/execution ; `pre.008` et ses correctifs ont fermé les frontières source/runtime/public/diagnostic, TS-RS et la non-divulgation. `kb-app-demo-desktop` et le workspace racine ont conservé leur nom. -Après `pre.007-delta-fix-002`, l'opérateur a validé `cargo fmt`, `cargo check --workspace`, `cargo clippy --all-targets`, l'audit workspace, `cargo test --workspace` et le démarrage Tauri le 10 août 2026. `pre.008` peut donc modifier uniquement les frontières de sortie/configuration sans rouvrir le split structurel déjà validé. +Le 10 août 2026, après `pre.008-delta-fix-003`, l’opérateur a validé `cargo fmt`, `cargo check --workspace`, `cargo clippy --all-targets`, l’audit workspace, `cargo test --workspace` et le démarrage Tauri. Les décisions durables ont été transférées au ROADMAP, aux guides, à la politique de namespace, aux TODO et au rapport de validation `0.5.1`. Ce plan n’est plus normatif. ## 2. Invariant du workspace racine diff --git a/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md b/olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md similarity index 99% rename from prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md rename to olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md index 5c3bffe..784f472 100644 --- a/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md +++ b/olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md @@ -1,5 +1,5 @@ - - + + # Khadhroony Bot3 — `0.5.1` — migration Khadhroony Solana et configuration sûre diff --git a/prompts/001.README.md b/prompts/001.README.md index 269822e..99fe0cb 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/`. -- [`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. +- [`031_v0_5_2_ks_wallet_restructuring.md`](031_v0_5_2_ks_wallet_restructuring.md) : restructuration de `ks-wallet`, format persistant versionné, séparation identité/secret/signature, migration legacy et sécurité des futurs consommateurs. diff --git a/prompts/031_v0_5_2_ks_wallet_restructuring.md b/prompts/031_v0_5_2_ks_wallet_restructuring.md new file mode 100644 index 0000000..9e3adca --- /dev/null +++ b/prompts/031_v0_5_2_ks_wallet_restructuring.md @@ -0,0 +1,291 @@ + + + +# Khadhroony Bot3 — `0.5.2` — restructuration de `ks-wallet` + +## Mission + +Reprendre `khadhroony-bot3` après la clôture validée de `0.5.1` et restructurer `ks-wallet` comme composant Solana généraliste réutilisable par les futurs exécuteurs, workers et applications. + +`0.5.2` doit stabiliser les frontières entre : + +1. identité publique d’un wallet ; +2. matériau secret persistant ; +3. état verrouillé/déverrouillé ; +4. capacité de signature ; +5. sélection/configuration d’un wallet par les consommateurs ; +6. migration du format legacy déjà utilisé par le workspace. + +Cette version est un chantier wallet/sécurité. Elle ne doit pas ouvrir `0.5.3` sur `ks-store`, `0.5.4` sur les scénarios/exécuteurs, ni une nouvelle couverture Anchor/DEX. + +## Base validée héritée de `0.5.1` + +La base attendue possède notamment : + +- les dix crates Solana généralistes sous `ks-*` / `ks_*` ; +- `kb-app-demo-desktop` dans le domaine Bot ; +- variables Solana sous `KS_*` et contrats applicatifs Bot sous `KB_*` ; +- documents spécialisés `logging.config.json`, `transport.config.json`, `listeners.config.json`, `store.config.json`, `wallet.config.json` et `execution.config.json` ; +- exemples conformes sous `config/exemples/` et schémas sous `config/schemas/` ; +- composition propre au desktop via `config/kb-app-demo-desktop.default.config.json` ; +- classification `Secret > Internal > Public` ; +- contrats source/runtime sensibles backend-only ; +- TS-RS absent de `ks-config` et `ks-lib`, avec DTO Tauri possédés par les applications ; +- URLs résolues retirées des snapshots transport et des surfaces Tauri. + +Ne pas réintroduire un type `ks-wallet` directement sérialisable vers le frontend par commodité. + +## Invariants de namespace + +Le workspace, le dépôt et le répertoire racine restent `khadhroony-bot3`. + +`ks-wallet` appartient au domaine Khadhroony Solana. Ses variables utilisent donc `KS_*`. Une future application Bot peut utiliser `KB_*` uniquement pour ses propres choix applicatifs, jamais pour renommer artificiellement un contrat wallet généraliste. + +Les secrets wallet ne doivent jamais être placés dans : + +- un fichier de configuration source ; +- `KS_PUBLIC_*` ou `KB_PUBLIC_*` ; +- un payload Tauri ; +- un diagnostic normal ; +- un log ou une erreur ; +- un `Debug` automatique ; +- un binding TS-RS générique. + +## Première prerelease obligatoire : plan et caractérisation + +`0.5.2-pre.001` doit être un plan/brainstorm/inventaire. Ne pas commencer par introduire un nouveau format chiffré. + +La première prerelease doit au minimum : + +- relire `ks-wallet/README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md` et tout son code ; +- inventorier tous les consommateurs de `ks-wallet` dans le workspace ; +- inventorier les chemins de configuration wallet et variables d’environnement ; +- caractériser exactement le format legacy `.json` actuellement utilisé ; +- caractériser les permissions de fichier et comportements Unix actuels ; +- inventorier création temporaire, persistance, lecture, validation, signature et erreurs ; +- relever toutes les dérivations `Clone`, `Debug`, `Serialize`, conversions ou getters pouvant copier/afficher du matériau sensible ; +- inventorier les usages directs de `solana_keypair`, `solana_signer::Signer`, `Arc` ou équivalents ; +- définir les besoins réels multi-wallets et multi-profils sans inventer une UI non demandée ; +- définir un contrat de migration et de rollback avant toute écriture du nouveau format ; +- proposer un découpage borné des prereleases de `0.5.2` ; +- créer un plan temporaire `0.5.2` sous `docs/plans/`, qui sera archivé dans la dernière prerelease. + +Le plan doit être validé avant la première migration de format. + +## Format legacy à préserver comme entrée de migration + +Le workspace possède actuellement un format persistant legacy basé sur le tableau JSON standard d’octets du keypair Solana. + +Avant de le remplacer : + +- écrire des tests de caractérisation à partir d’une fixture synthétique ; +- vérifier le nommage `.json` et les contraintes d’alias ; +- vérifier les permissions de fichier existantes ; +- vérifier le comportement en cas de fichier absent, corrompu, incomplet ou déjà présent ; +- vérifier que la clé publique obtenue après import correspond exactement à l’ancienne ; +- interdire toute réécriture destructive sans preuve que la migration est complète. + +Ne jamais utiliser une vraie clé privée de l’opérateur comme fixture. + +## Cible conceptuelle du nouveau contrat + +La solution exacte doit être décidée après audit, mais les frontières suivantes doivent être explicites. + +### Identité publique + +Une identité publique peut contenir par exemple : + +- alias logique ; +- clé publique ; +- type/source de wallet ; +- état disponible/verrouillé ; +- métadonnées non sensibles strictement nécessaires. + +Elle ne contient jamais les octets secrets. + +### Matériau secret + +Le matériau secret : + +- reste encapsulé ; +- n’implémente pas `Debug` en clair ; +- n’est pas sérialisé arbitrairement ; +- doit pouvoir être zéroïsé lorsque le type et les dépendances le permettent ; +- n’est jamais exposé par getter de bytes public sans justification explicite. + +### Capacité de signature + +Les consommateurs doivent dépendre d’une capacité de signature bornée plutôt que d’un accès aux octets privés. + +Évaluer notamment : + +- trait propre à `ks-wallet` ou adaptation stricte à `solana_signer::Signer` ; +- ownership et thread-safety ; +- passage vers les exécuteurs sans rendre le secret clonable ; +- session déverrouillée de durée bornée si un chiffrement persistant est introduit. + +### État verrouillé/déverrouillé + +Si le stockage chiffré est retenu, définir explicitement : + +- état verrouillé ; +- opération de déverrouillage ; +- durée ou portée de la session ; +- invalidation/lock ; +- changement de secret ; +- comportement après erreur ; +- absence de secret dans les erreurs et logs. + +Ne pas faire du booléen `is_unlocked` une preuve suffisante si la capacité de signature peut être désynchronisée. + +## Chiffrement persistant + +Ne choisir l’algorithme, le KDF, le nonce et le format de conteneur qu’après inventaire des dépendances déjà présentes et vérification des exigences de sécurité. + +Le workspace possède déjà notamment `argon2`, `chacha20poly1305` et `zeroize` dans ses dépendances. Cela ne signifie pas qu’ils doivent être utilisés aveuglément ni avec des paramètres arbitraires. + +Le format persistant, s’il change, doit être : + +- versionné ; +- auto-identifiable ; +- strictement validé ; +- extensible sans ambiguïté ; +- écrit atomiquement ; +- compatible avec une stratégie de migration/rollback ; +- documenté avant d’être considéré stable. + +Ne pas stocker le secret de chiffrement dans `wallet.config.json` ni dans un fichier versionné. + +## Import, export, backup et restore + +Ces capacités ne sont pas automatiquement obligatoires dans la première tranche de code. Leur besoin et leur surface doivent être décidés dans le plan. + +Si elles sont retenues : + +- distinguer import legacy, import du nouveau conteneur et export public ; +- éviter toute exportation privée implicite ; +- définir les permissions de fichiers et écriture atomique ; +- refuser l’écrasement silencieux ; +- définir les collisions d’alias et de pubkey ; +- tester rollback et corruption ; +- ne jamais écrire de keypair secret dans les logs ou diagnostics. + +## Multi-wallets et profils + +`wallet.config.json` possède déjà une racine globale et des profils. + +`0.5.2` doit décider proprement : + +- si un profil sélectionne un alias unique ou un ensemble de wallets ; +- comment un futur worker choisit son wallet sans dépendre de `kb-app-demo-desktop` ; +- comment un exécuteur demande un signer sans connaître le stockage ; +- comment plusieurs wallets sont listés et sélectionnés sans exposer leur matériau secret ; +- comment les wallets temporaires et persistants coexistent. + +Ne pas transformer `ks-config` en gestionnaire de secrets. `ks-config` peut sélectionner des identités/aliases publics ou internes, mais le matériau secret appartient à `ks-wallet` et/ou à la source de secret dédiée retenue. + +## Tauri et surfaces publiques + +`ks-wallet` ne doit pas reprendre TS-RS simplement parce que le desktop souhaite afficher une liste de wallets. + +Si le desktop a besoin d’une surface UI : + +```text +ks-wallet runtime + -> wrapper/DTO kb-app-demo-desktop + -> TS-RS + -> frontend +``` + +Les DTO applicatifs peuvent exposer uniquement les informations explicitement sûres, par exemple alias, pubkey et état logique. + +Prévoir des canaris de non-divulgation semblables à ceux de `0.5.1`. + +## Erreurs, logs et diagnostics + +Toute nouvelle erreur liée au wallet doit être conçue pour être utile sans révéler : + +- octets de secret ; +- phrase/password ; +- contenu chiffré ; +- chemin local complet si ce chemin n’est pas explicitement un diagnostic interne ; +- valeur d’une variable `KS_SECRET_*` ; +- représentation `Debug` d’un keypair/signer. + +Les logs peuvent identifier une opération et un alias/public key lorsque cette donnée est autorisée, mais ne doivent pas concaténer les structures runtime sensibles. + +## Tests minimums à prévoir + +Le plan `pre.001` doit définir précisément les tranches, mais `0.5.2` devra couvrir au minimum : + +- caractérisation du format legacy ; +- import legacy préservant la pubkey ; +- corruption/troncature/version inconnue ; +- permissions privées ; +- écriture atomique et refus d’écrasement ; +- collisions d’alias/pubkey ; +- persistance et réouverture ; +- état verrouillé/déverrouillé si applicable ; +- signature correcte sans exposition des bytes ; +- absence de secret dans `Debug`, `Display`, erreurs, logs et DTO ; +- concurrence/thread-safety des signers réellement utilisés ; +- API externe crate-root de `ks-wallet` ; +- intégration avec `ks-config` sans dépendance inverse vers une application. + +Les tests avec fichiers doivent utiliser des répertoires temporaires et des clés synthétiques. Aucun secret réel ne doit être requis. + +## Découpage indicatif à confirmer par `pre.001` + +Le numéro exact peut évoluer après inventaire, mais l’ordre conceptuel attendu est : + +1. `pre.001` — plan, caractérisation legacy, threat model et inventaire des consommateurs ; +2. tranche de contrats publics/identité/signature avant modification du stockage ; +3. tranche de conteneur persistant versionné et migration legacy ; +4. tranche chiffrement/verrouillage si retenue après validation du format ; +5. tranche multi-wallet/import-export/backup uniquement si confirmée par le plan ; +6. intégration `ks-config` / consommateurs / desktop via DTO sûrs ; +7. dernière prerelease — documentation, audits, TODO, archivage du plan/prompt et préparation de `0.5.3`. + +Un correctif `fix-XXX` conserve le numéro de prerelease et sa numérotation recommence à `fix-001` pour chaque prerelease. + +## Hors périmètre de `0.5.2` + +- migration SQL `kb_sol_*` -> `k_sol_*` ; +- refonte temporelle/provenance de `ks-store` ; +- centralisation générale des scénarios `0.5.4` ; +- ajout de protocoles Anchor/DEX ; +- stockage d’un secret wallet dans PostgreSQL sans décision architecturale dédiée ; +- hardware wallets, remote signers, KMS/HSM ou Ledger tant qu’ils ne sont pas explicitement priorisés ; +- mécanisme universel de secret manager pour toutes les crates. + +## Validation de référence + +Après chaque delta Rust ou contractuel : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --all-targets +python3 scripts/audit_rust_workspace_rules.py +cargo test --workspace +``` + +Lorsque le desktop est modifié : + +```bash +cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json +``` + +Les scripts npm de build/dev ne sont jamais lancés directement. + +## Dernière prerelease de `0.5.2` + +La dernière prerelease doit : + +- réconcilier tous les contrats wallet et consommateurs ; +- finaliser README/USAGE/TODO/changelogs/guides ; +- supprimer les TODO réellement fermés et reporter les autres vers une version identifiée ; +- exécuter les validations finales ; +- reprendre les décisions durables dans le ROADMAP et les documents normatifs ; +- archiver le plan `0.5.2` et ce prompt sous `olddocs/archivekbot3/` ; +- préparer le prompt de `0.5.3` pour l’audit/normalisation de `ks-store`.