| `ks-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | nom `ks-*` actif ; normalisation `0.5.3` |
| `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).
Les identifiants Rust correspondants migrent dans le même delta vers `ks_*` : par exemple `kb_config` devient `ks_config` et `kb_pipeline_demo_scenarios` devient `ks_pipeline_demo_scenarios`.
Chaque document possède un exemple `example.*.config.json`. Les schémas correspondants résident sous `config/schemas/`.
Chaque document possède un exemple sous `config/exemples/` avec un nom `example.*.config.json`. Les schémas correspondants résident sous `config/schemas/`.
`.env`, ou le fichier sélectionné par `KS_ENV_FILE`, fournit les valeurs non versionnées.
@@ -145,22 +145,29 @@ 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 existants. Il s'agit d'une projection runtime, pas d'un document source.
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`.
Les fixtures de compatibilité sont sous `test-fixtures/config/`. Elles ne doivent pas être chargées en production.
## Frontière publique et diagnostic
Une application ne transmet jamais `AppConfig/ProfileConfig` directement. Elle construit :
- une projection publique explicitement typée, limitée aux champs autorisés ;
- un diagnostic borné contenant au plus des états tels que `configured`/`missing` pour les URLs, DSN et chemins sensibles ;
- aucune projection construite par sérialisation du runtime suivie d'un masquage a posteriori.
La sensibilité suit `Secret > Internal > Public`. Une valeur composée hérite de la sensibilité la plus forte des placeholders qu'elle contient ; une URL incorporant `${KS_SECRET_HELIUS_API_KEY}` est donc secrète même si son champ final est simplement `url`.
La section `application` d'une composition est opaque à `ks-config`. Le desktop la valide avec son schéma `config/schemas/kb-app-demo-desktop.application.config.schema.json`; un futur worker pourra posséder son propre schéma sans modifier `ks-config`.
## Frontière TS-RS
L'audit`pre.007` confirme que le frontend du desktop n'importe directement aucun binding généré depuis`ks-config`ou`ks-lib`. Les dérivations TS-RS des crates généralistes seront donc réévaluées dans la prerelease suivante : les DTO réellement destinés à Tauri doivent être définis/wrappés dans l'application, sauf contrat TypeScript générique explicitement justifié.
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é.
- suppression de l'exposition Tauri de la configuration runtime complète ;
- réduction des bindings TS-RS dans les crates généralistes et wrappers applicatifs nécessaires.
`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`.
# Plan temporaire `0.5.1` — namespace Khadhroony Solana et configuration sûre
## 1. Statut et règle de cette prerelease
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`a séparé le logging, `pre.006` a introduit les compositions de binaires et extrait transport/listeners, et`pre.007`termine maintenant la décomposition des responsabilités partagées avec store/wallet/execution, valeurs globales hors profils et defaults autonomes. `kb-app-demo-desktop` et le workspace racine restent nommés comme avant.
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.
Les contrôles Rust et le démarrage Tauri de `pre.006` ont été validés par l'opérateur le 10 août 2026. Le démarrage confirme le chargement de `kb-app-demo-desktop.default.config.json`, du document logging séparé, des profils transport et du store, avec DSN PostgreSQL masqué dans les logs. `pre.007`doit préserver le comportement runtime tout en changeant l'ownership source des paramètres.
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é.
## 2. Invariant du workspace racine
@@ -32,18 +32,18 @@ Les bibliothèques internes Solana utilisent `ks-*` / `ks_*` et leurs variables
`kb-app-demo-desktop` est adapté en dernier, mais garde son package, son répertoire et ses identifiants applicatifs.
@@ -58,18 +58,18 @@ bin : kb-pipeline-demo-scenarios-cli -> ks-pipeline-demo-scenarios-cli
Les valeurs suivantes sont des métriques d'orientation sur les fichiers actifs, hors archives et artefacts générés. Elles montrent qu'un renommage massif en une seule opération serait difficile à diagnostiquer.
La cible `KB_APP_DEMO_DESKTOP_CONFIG_PATH` remplace la transition `KS_CONFIG_PATH` de `pre.004` : une composition appartient au binaire qui la charge, alors que les documents qu’elle référence restent possédés par les crates `ks-*`.
## 8. Décomposition des documents de configuration
@@ -595,7 +595,7 @@ Le transport possède des classes WebSocket de defaults nommées. Chaque endpoin
Lorsqu'une composition référence un profil, `ks-config` doit prouver son existence avant de construire le runtime. Lorsqu'aucune composition n'est fournie, les noms des `default_profile` n'ont pas besoin d'être identiques : chaque document est résolu indépendamment. La composition ne devient pas une seconde surface de paramètres : les overrides de champ restent dans le contrat spécialisé qui les possède, et les globals explicitement configurables utilisent leurs variables d'environnement dédiées.
`AppConfig/ProfileConfig` demeure provisoirement un **contrat runtime résolu** pour préserver les consommateurs pendant la migration. Les champs applicatifs `app`/`demo` restent dans la composition exclusive du desktop pendant cette transition ; leur ownership Rust/public est traité avec les DTO applicatifs de `pre.008`, sans réintroduire un document généraliste monolithique.
`AppConfig/ProfileConfig` demeure provisoirement un **contrat runtime résolu backend-only** pour préserver les consommateurs pendant la migration. Depuis `pre.008`, il ne contient plus les champs propres au desktop, ne dérive plus `serde::Serialize`/`Debug` et ne traverse plus Tauri. La section `application` de la composition est opaque à `ks-config`; le desktop la valide avec son propre schéma sans réintroduire un document généraliste monolithique.
## 9. Source, runtime, public et diagnostic
@@ -606,38 +606,34 @@ La configuration doit distinguer explicitement :
3.**public** : DTO explicitement construit et strictement borné pour Tauri/TS-RS/UI ;
4.**diagnostic** : surface explicitement demandée, pouvant montrer des valeurs `KS_*` internes non sensibles mais jamais une valeur `KS_SECRET_*`.
### 9.1 Fuite actuelle à éliminer
### 9.1 Frontière appliquée en `pre.008`
`kb-app-demo-desktop/src/demo_config.rs` transporte actuellement dans `DemoConfigPayload` :
`kb-app-demo-desktop/src/demo_config.rs` ne transporte plus `AppConfig` ni `ProfileConfig`. Il construit explicitement :
```text
AppConfig complet
ProfileConfig actif complet
schema_json
runtime backend-only
-> DemoConfigPublicPayload
-> DemoConfigDiagnosticPayload
```
La configuration est déjà résolue avant la construction du payload, puis le frontend affiche les objets via JsonViewer. Cette frontière permet donc à un secret résolu d'atteindre Tauri/UI.
La projection publique exclut URLs, DSN, chemins de stockage/wallet et politiques internes non destinées à l'UI. Le diagnostic borné ne transmet pour les valeurs sensibles que des états tels que `configured`/`missing`, plus les métadonnées internes explicitement autorisées.
La correction ne doit jamais suivre le modèle :
La correction interdit le modèle :
```text
serialize(runtime_config) -> supprimer quelques champs -> exposer
```
La seule direction admise est :
Les contrats source/runtime de `ks-config` susceptibles de contenir des secrets résolus ne dérivent ni `serde::Serialize` ni `Debug`, et les sérialiseurs publics historiques de `AppConfig` sont supprimés. La sensibilité des placeholders est classée selon `Secret > Internal > Public`; une chaîne composée contenant un placeholder `KS_SECRET_*`/`KB_SECRET_*` hérite de `Secret`.
```text
runtime_config -> construction explicite d'un PublicConfig / ConfigDiagnostics
```
Les types contenant des secrets ne doivent pas être exportés en TS-RS simplement parce qu'ils sont sérialisables côté backend.
TS-RS est désormais une frontière applicative : `ks-config` et `ks-lib` ne dépendent plus de `ts-rs` et ne génèrent plus de bindings. `kb-app-demo-desktop` possède les DTO TS-RS nécessaires à ses commandes Tauri.
## 10. Tests de caractérisation avant et pendant migration
Avant chaque changement structurel correspondant, conserver ou ajouter des tests qui vérifient :
- la topologie des dix crates et leurs dépendances attendues ;
- les 13 tests d'API externe et leurs imports par crate root ;
- les 14 tests d'API externe et leurs imports par crate root ;
- l'inventaire exact des identités runtime ;
- l'absence de `kb-*` / `kb_*` résiduel dans les dix crates après leur prerelease de renommage, hors exceptions explicitement listées ;
- le maintien de `khadhroony-bot3` comme nom racine ;
@@ -730,13 +726,14 @@ Le split partagé est considéré terminé après cette prerelease. Les champs a
### `0.5.1-pre.008` — surfaces publiques sûres, TS-RS et camouflage
-séparer types source/runtime/public/diagnostic ;
-déplacer les DTO réellement destinés à Tauri/TypeScript vers `kb-app-demo-desktop` ou des wrappers applicatifs dédiés ;
-supprimer les dérivations/export TS-RS de `ks-config` qui n'ont aucun consommateur frontend générique et auditer les 100 exports de `ks-lib` au cas par cas ;
-propager la classification secret/public/internal lors de la résolution des placeholders et valeurs composées ;
-retirer `AppConfig`/`ProfileConfig` résolus du payload Tauri public ;
-borner les DTO TS-RS et diagnostics ;
-valider qu'aucun secret ne traverse logs/UI/erreurs/sérialisation.
-**implémenté** : `AppConfig/ProfileConfig` et les documents source/runtime sensibles restent backend-only, sans `serde::Serialize` ni `Debug` ;
-**implémenté** : le fragment `application` devient opaque pour `ks-config` et est validé par le schéma possédé par `kb-app-demo-desktop` ;
-**implémenté** : `DemoConfigPayload` remplace la configuration résolue complète par des DTO public/diagnostic construits champ par champ ;
-**implémenté** : URLs RPC/WS, DSN PostgreSQL et chemins sensibles ne traversent pas le payload configuration ; les diagnostics n'exposent que des états bornés ;
-**implémenté** : classification `Secret > Internal > Public` des variables et chaînes composées, avec canaris de non-divulgation et erreurs de validation qui n'échoent plus les valeurs rejetées ;
-**implémenté** : suppression de `ts-rs` de `ks-config` et `ks-lib`, suppression de leurs dérivations/export et de leurs bindings générés historiques ;
-**implémenté** : audit workspace empêchant la réintroduction de TS-RS dans `ks-*` et de `Serialize`/`Debug` sur les contrats de configuration sensibles sans décision explicite ;
- **implémenté** : test d'API externe de la classification/camouflage et canaris desktop empêchant la fuite de secrets dans les projections Tauri.
@@ -12,7 +12,7 @@ Toute divergence avec une règle générale doit être explicitement documentée
- Tous les noms de fichiers et de répertoires doivent être écrits en anglais.
- Les noms de fichiers et de répertoires ne doivent contenir aucun accent, espace ou caractère spécial inutile.
- Les noms internes doivent utiliser le format `snake_case` lorsque c'est applicable.
- Les packages Rust utilisent le préfixe `kb-`; leur identifiant Rust correspondant utilise automatiquement`kb_`.
- Les bibliothèques généralistes Khadhroony Solana utilisent le préfixe Cargo `ks-`et l’identifiant Rust `ks_`; les applications et futures crates réellement propres au domaine Bot utilisent `kb-` /`kb_`.
- Les décodeurs, matérialisateurs et exécuteurs sont des modules de `ks-lib`, pas des crates séparées.
- Le crate de journalisation s'appelle `ks-logging`.
- Les réexports sont regroupés par visibilité : le bloc `pub use` précède le bloc séparé `pub(crate) use`, sans ligne vide interne à un bloc ; leur ordre naturel doit rester compatible avec `cargo fmt`.
@@ -26,6 +26,8 @@ Toute divergence avec une règle générale doit être explicitement documentée
- Les types Rust exportés vers TypeScript doivent utiliser des noms stables et explicites.
- Les bindings générés doivent être produits dans un dossier dédié, généralement `../frontend/ts/bindings` ou `#[ts(export, export_to = "../frontend/ts/bindings/MyStruct.ts")]`.
- Les types purement internes au backend ne doivent pas être exportés vers TypeScript par défaut.
- Dans l’état courant, les crates généralistes `ks-*` ne possèdent ni dépendance `ts-rs`, ni dérivation/export TS-RS, ni dossier de bindings générés. Une exception future exige un contrat TypeScript générique indépendant de Tauri, explicitement documenté et ajouté à l’audit workspace.
- Les types source/runtime de `ks-config` susceptibles de contenir des secrets ou valeurs internes ne dérivent ni `serde::Serialize` ni `Debug`. Une surface publique ou diagnostic est construite champ par champ dans l’application propriétaire ; il est interdit de sérialiser un runtime complet puis de le redacter a posteriori.
- Corriger le type Rust/TS-rs source puis régénérer les bindings ; ne pas considérer une modification manuelle isolée d’un fichier généré comme un correctif durable.
-`kb-app-demo-desktop/src/tauri.rs` contient les attributs `#[tauri::command]`, l’enregistrement des commandes et des wrappers privés minces ; la logique complète doit vivre dans le module fonctionnel correspondant sous une fonction `pub(crate)` testable.
- Un wrapper Tauri ne doit effectuer que l’adaptation des handles/states/arguments, l’appel de la fonction de module et le retour du résultat ; toute validation métier, orchestration ou construction de payload doit rester hors de `tauri.rs`.
@@ -247,8 +249,8 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
- Les endpoints WebSocket doivent sélectionner une classe de defaults nommée ; leurs timeouts, capacités et politique `auto_reconnect` peuvent être remplacés explicitement au niveau de l'endpoint.
- Les autorisations `*_send_enabled` appartiennent à la politique d'exécution, pas au contrat d'identité/stockage wallet.
- Les schémas JSON actifs sont conservés exclusivement sous `config/schemas/`. Les documents source spécialisés possèdent chacun leur schéma ; `resolved.app.config.schema.json` décrit uniquement le contrat runtime transitoire reconstruit par `ks-config`.
- Les exemples conformes restent sous `config/` avec un nom distinct des fichiers runtime. Les fixtures d'un contrat runtime résolu appartiennent à `test-fixtures/` et ne doivent pas être chargées en production.
- Les fichiers historiques `config/app.config.json`, `config/example.app.config.json`, `config/schemas/app.config.schema.json`, `config/example.config.json`, `config/schema.config.json` et `config/ks-pipeline-demo-scenarios.default.config.json` sont interdits dans l'état courant.
- Les exemples conformes résident exclusivement sous `config/exemples/` avec un nom distinct des fichiers runtime. Les fixtures d'un contrat runtime résolu appartiennent à `test-fixtures/` et ne doivent pas être chargées en production.
- Les fichiers historiques `config/app.config.json`, `config/example.app.config.json`, `config/schemas/app.config.schema.json`, `config/example.config.json`, les fichiers `config/example.*.config.json` hors `config/exemples/`,`config/schema.config.json` et `config/ks-pipeline-demo-scenarios.default.config.json` sont interdits dans l'état courant.
- Le chemin de composition desktop peut être remplacé par `KB_APP_DEMO_DESKTOP_CONFIG_PATH`. `KS_DEVNET_CONFIG_PATH` est uniquement un override facultatif vers une composition explicite pour les scénarios Devnet ; sans cet override, les scénarios utilisent les defaults partagés. `KS_LOGGING_CONFIG_PATH` reste un override explicite du document logging.
- Les fichiers JSON de configuration ne doivent pas contenir de commentaires.
- Les secrets ne doivent pas être écrits en clair dans le dépôt.
@@ -256,7 +258,13 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
- Les variables possédées par les composants généralistes `ks-*` utilisent obligatoirement `KS_SECRET_*`, `KS_PUBLIC_*` ou `KS_*` ; les variables réellement spécifiques à `kb-app-demo-desktop` ou à de futures crates `kb-*` utilisent `KB_SECRET_*`, `KB_PUBLIC_*` ou `KB_*`.
- Le namespace est déterminé par le propriétaire fonctionnel du contrat et non par son consommateur.
- Les sous-préfixes `SECRET` sont toujours non exposables ; les sous-préfixes `PUBLIC` ne sont exposables que par une surface explicitement autorisée ; les autres variables du domaine sont internes.
- Les bindings TS-RS sont prioritairement une frontière d'application Tauri. Une crate `ks-*` ne conserve une dérivation/export TypeScript que si le type constitue un contrat externe générique explicitement justifié ; sinon l'application définit un DTO/wrapper dédié.
- La sensibilité d’une valeur composée suit `Secret > Internal > Public` : une URL, un DSN ou toute autre chaîne incorporant un placeholder `KS_SECRET_*`/`KB_SECRET_*` hérite de la sensibilité `Secret`, quel que soit le nom du champ final.
- Une valeur `Secret` ne doit jamais apparaître en clair dans une sérialisation, un `Debug`, une erreur, un log, un diagnostic, un payload Tauri ou l’UI. Une valeur interne n’apparaît que dans un diagnostic explicitement borné et sémantiquement autorisé.
- La section `application` d’une composition est opaque pour `ks-config`; le binaire propriétaire définit et valide son propre schéma sous `config/schemas/` avant usage.
- Les bindings TS-RS sont une frontière d'application Tauri. Une crate `ks-*` ne conserve une dérivation/export TypeScript que si le type constitue un contrat externe générique explicitement justifié et audité ; sinon l'application définit un DTO/wrapper dédié.
- Une commande Tauri ne retourne jamais directement un contrat `ks-*` susceptible de contenir des valeurs runtime ; elle retourne un DTO appartenant à l’application et construit explicitement la projection autorisée.
- Les snapshots/runtime transport contenant une URL résolue restent backend-only : ils ne sont pas sérialisables directement, leur `Debug` est sanitisé, les DTO Tauri ne contiennent pas `endpoint_url`, et les erreurs/logs de transport ne recopient ni corps HTTP non-success ni message JSON-RPC distant susceptible de réinjecter un credential.
- Les chemins dérivés du stockage wallet sont internes ; un payload fonctionnel Tauri ne transporte pas un chemin de fixture. Seule une surface de diagnostic explicitement bornée peut exposer un chemin interne autorisé.
## Ordre de développement cible
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
