Sasedev/khadhroony-solana-project

Fork 0

Files

SinuS Von SifriduS 77f6eaf487 v0.1.2-pre.006-fix.001

2026-08-14 20:34:54 +02:00

15 KiB

Raw Blame History

Prompt de démarrage KSP 0.1.3

1. Contexte de reprise

Projet : khadhroony-solana-project (KSP).

Base requise avant ouverture de cette session :

v0.1.2 stable

La release 0.1.2 a introduit ksp-logging-lib comme façade KSP unique de logging/tracing runtime. 0.1.3 ne doit pas rouvrir cette architecture ; Config doit consommer ses contrats publics.

Release à développer :

0.1.3 — Configuration foundation

2. Mission

Introduire ksp-config-lib comme propriétaire unique KSP de la configuration applicative : documents de configuration unitaires et composites, résolution des profils, variables d'environnement, validation, lecture et modifications/persistences explicitement autorisées.

Les autres crates et applications KSP ne doivent pas lire, résoudre ou modifier directement les fichiers de configuration ni les variables d'environnement. Elles consomment les contrats de ksp-config-lib. Une application dédiée au management de configuration utilise donc Config comme unique frontière, y compris lorsqu'elle doit afficher ou modifier des valeurs sensibles explicitement autorisées.

La première prerelease est obligatoirement une tranche de brainstorming, audit et planification. Ne pas commencer directement par une implémentation large de Config.

3. Base architecturale à préserver

Dépendances candidates de la nouvelle crate :

ksp-config-lib
    -> ksp-core-lib
    -> ksp-logging-lib

Relations interdites :

ksp-core-lib    -X-> ksp-config-lib
ksp-logging-lib -X-> ksp-config-lib

ksp-logging-lib possède toujours ses propres LoggingSettings et son lifecycle initialize / reinitialize. Config lit/résout ses documents puis construit explicitement les settings publics Logging ; Logging ne lit aucun document Config et ne connaît aucun profil.

4. Première prerelease obligatoire : `0.1.3-pre.001`

Cette tranche doit produire un plan détaillé avant développement fonctionnel.

Elle doit notamment :

auditer l'état réel du workspace stable 0.1.2 ;
réauditer les règles Config déjà présentes dans le dépôt et les archives historiques pertinentes sans les copier aveuglément ;
inventorier les documents de configuration unitaires nécessaires à court terme et les fichiers composites qui les assemblent pour un exécutable/application ;
distinguer valeurs globales, valeurs profilées, sélection du profil, documents unitaires réutilisables et composition propre aux exécutables ;
fixer la politique de résolution document unitaire -> composition -> profil -> env override -> valeur effective ;
fixer la validation, les diagnostics et les erreurs Core nécessaires ;
fixer les opérations de modification/sauvegarde autorisées et leurs garanties d'atomicité ;
fixer la frontière secrets/public/debug et les droits explicites permettant à une application de management Config d'accéder aux secrets lorsqu'elle doit les consulter ou les modifier ;
définir la relation exacte avec LoggingSettings et le hot reload Logging ;
décider si le périmètre Config tient proprement dans une seule release 0.1.3 ou doit être scindé ;
produire docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md et le plan souple des prereleases suivantes.

Le pre.001 reste une tranche de planification : ne pas ajouter de dépendance fonctionnelle inutilisée et ne pas créer une large surface de code avant validation du plan.

5. Documents spécialisés

La configuration KSP doit être pensée comme plusieurs documents spécialisés plutôt qu'un unique fichier global monolithique lorsque les responsabilités sont distinctes.

Le point déjà fixé est notamment :

logging.config.json

séparé de la configuration applicative générale.

Le pre.001 doit inventorier les autres documents réellement nécessaires au premier cycle et éviter de créer prématurément des fichiers pour des composants non développés.

La structure doit conserver la séparation déjà utile dans khadhroony-bot3 entre documents unitaires et fichiers composites :

un document unitaire possède une responsabilité spécialisée et reste réutilisable indépendamment des exécutables ;
un fichier composite assemble les documents requis par un exécutable/application et peut sélectionner ou remplacer les profils nécessaires sans dupliquer les documents spécialisés.

Les vrais fichiers de configuration runtime appartiennent sous :

config/

Les schemas appartiennent sous :

config/schemas/

Les exemples ne doivent pas être mélangés aux fichiers runtime réels et appartiennent sous :

config/examples/

Les noms exacts, la nomenclature des fichiers composites et leur format restent à valider dans le plan Config pre.001.

6. Valeurs globales et profils

Une valeur qui ne varie pas selon le profil reste hors profils.

Exemples historiques déjà retenus comme principe :

logging.logs_directory
wallets_directory

Le default_profile est autonome : il sélectionne un profil par défaut mais ne doit pas être artificiellement imbriqué dans chacun des profils.

Les fichiers composites propres à un binaire/application sélectionnent les documents unitaires utilisés et peuvent remplacer les profils choisis lorsqu'un besoin concret l'exige. Cette composition doit rester possédée et résolue par ksp-config-lib, pas par chaque exécutable séparément.

7. Variables d'environnement

Toutes les variables d'environnement applicatives doivent être namespacées selon leur propriétaire fonctionnel.

Pour les composants génériques KSP / ksp-* :

KSP_*
KSP_PUBLIC_*
KSP_SECRET_*

Pour les futures applications/composants bot du projet :

KSPB_*
KSPB_PUBLIC_*
KSPB_SECRET_*

ksp-config-lib est le propriétaire unique de la lecture, de la résolution, de la validation et de l'écriture éventuelle des variables d'environnement KSP. Les autres crates/applications ne doivent pas contourner cette frontière par des lectures directes de l'environnement applicatif.

Le pre.001 doit formaliser précisément la correspondance entre document, clé de configuration et override d'environnement.

Aucune variable applicative sans préfixe propriétaire ne doit être introduite.

8. Secrets, public et debug

La classification Config doit distinguer les valeurs publiques, ordinaires et secrètes, mais secret ne signifie pas interdiction absolue de lecture.

Direction déjà retenue :

KSP_SECRET_* / KSPB_SECRET_* : valeurs sensibles, jamais exposées accidentellement dans les logs, diagnostics ordinaires ou surfaces publiques génériques ;
KSP_PUBLIC_* / KSPB_PUBLIC_* : valeurs explicitement exposables ;
autres valeurs : politique d'exposition à fixer selon le contrat applicatif et le contexte debug ;
les composants runtime qui ont légitimement besoin d'un secret doivent pouvoir l'obtenir via un contrat Config explicite ;
une application possédant une fonctionnalité de management de configuration doit pouvoir, via une surface Config explicitement prévue et contrôlée, consulter et modifier les secrets nécessaires. Cela couvre notamment la future ksp-app-config-desk et, plus tard, la partie Config d'une éventuelle application générale.

La surface Config doit donc formaliser une politique d'accès aux secrets, et non une règle simpliste « jamais exposé ». Le pre.001 doit décider les contrats distincts de lecture runtime, consultation de management, mutation et exposition Tauri/DTO afin d'éviter toute fuite implicite tout en permettant l'administration légitime.

Cela ne change pas la responsabilité de Logging concernant le contenu des messages : ksp-logging-lib ne scanne ni ne redacte automatiquement les secrets fournis par ses callers.

9. Relation Config -> Logging

Config peut produire un ksp_logging_lib::LoggingSettings à partir de sa configuration effective puis appeler le lifecycle Logging au niveau d'orchestration approprié.

Séquence conceptuelle :

documents Config
    -> résolution/profil/env
    -> configuration Logging effective
    -> LoggingSettings
    -> ksp_logging_lib::initialize(...) ou reinitialize(...)

Le mécanisme qui détecte un changement de fichier, s'il est introduit plus tard, appartient à Config/application/orchestration ; Logging fournit uniquement sa reconfiguration runtime.

0.1.3-pre.001 doit préciser qui possède le LoggingGuard dans les premières compositions concrètes sans créer de singleton global Config inutile.

10. Validation et erreurs

ksp-config-lib doit réutiliser :

ksp_core_lib::Error
ksp_core_lib::ErrorCode
ksp_core_lib::ErrorContext
ksp_core_lib::Result<T>

Les codes propres à Config appartiennent au domaine Config et ne doivent pas être ajoutés comme connaissance métier à Core.

Les diagnostics doivent distinguer autant que nécessaire :

document absent lorsque obligatoire ;
syntaxe invalide ;
schema/contrainte invalide ;
profil demandé absent ;
valeur effective invalide ;
override d'environnement invalide ;
opération de sauvegarde/modification impossible.

La nomenclature exacte des ErrorCode est décidée dans le plan puis ajoutée seulement quand chaque erreur devient nécessaire.

11. Mutation et persistence

La configuration n'est pas uniquement un lecteur statique : le périmètre candidat de 0.1.3 comprend les modifications/sauvegardes explicitement autorisées.

Le pre.001 doit décider :

quels documents peuvent être modifiés par API ;
quelles valeurs sont read-only ;
comment préserver format/version/schema ;
comment éviter un fichier partiellement écrit ;
comment représenter une modification rejetée ;
comment distinguer configuration souhaitée et configuration effective lorsqu'un composant runtime ne peut pas appliquer immédiatement une valeur.

Si cette surface rend la release trop large, elle doit être scindée plutôt que comprimée artificiellement.

12. Frontière application/Tauri

0.1.3 reste une release de bibliothèque Config.

La validation desktop complète est prévue ensuite, par défaut dans :

0.1.4 — ksp-app-config-desk

Les DTO/bindings Tauri n'appartiennent donc pas automatiquement à ksp-config-lib. TS-RS reste principalement une frontière des applications Tauri et ne doit être dérivé dans une crate générique que pour un contrat externe réellement générique et indépendant de Tauri. Une application Config desktop pourra toutefois exposer, par des commandes/DTO applicatifs dédiés, les opérations privilégiées de consultation/modification de secrets que ksp-config-lib autorise explicitement ; elle ne doit jamais contourner Config en lisant les fichiers ou l'environnement directement.

13. Règles Rust et Cargo à conserver

Conserver les règles normatives du dépôt, notamment :

Rust 2024 ;
unsafe interdit ;
pas de unwrap, expect, panic dans le code production ;
pas d'opérateur ? ;
retours explicites selon les règles Clippy du workspace ;
imports de traits seulement lorsque nécessaire, chemins pleinement qualifiés sinon ;
pas de mod.rs ;
pas de pub(super) / pub(in ...) ;
code et Rustdoc en anglais ;
documentation Markdown en français ;
tests unitaires hors src selon la convention du dépôt ;
dépendances externes communes déclarées uniquement sous [workspace.dependencies] puis consommées avec .workspace = true ;
versions externes sous contraintes caret de génération compatibles, après vérification de la version actuelle au moment de l'ajout ;
ne pas versionner Cargo.lock.

14. Logging dans Config

ksp-config-lib contient du comportement runtime et doit normalement dépendre de ksp-logging-lib pour ses propres événements utiles.

Elle ne doit jamais importer directement :

tracing
tracing-subscriber
tracing-appender

Ses targets KSP explicites utilisent le nom Cargo :

ksp-config-lib

Les détails d'une bibliothèque tierce utilisés par Config sont silencieux par défaut ; Config réémet sous son propre target les informations réellement utiles au diagnostic KSP.

15. Hors scope initial

Sauf décision explicite du pre.001, ne pas ouvrir dans 0.1.3 :

application desktop Config ;
Tauri comme dépendance de ksp-config-lib ;
Wallet ;
Store/PostgreSQL ;
RPC/WS/provider ;
Program/decoder/execution ;
workers/jobs/pipelines ;
trading/ML ;
watcher générique de tous les fichiers du projet ;
service distribué de configuration ;
secrets manager distant ;
configuration spécifique à des composants qui n'existent pas encore.

16. Git, versions et deltas

Chaque livraison est un delta commité :

pre.NNN
pre.NNN-fix.NNN
rel.NNN

Cargo utilise les identifiants SemVer sans zéros de tête :

0.1.3-pre.1
0.1.3-pre.1.fix.1

Les noms de deltas/documents peuvent conserver la représentation pre.001 / fix.001.

Une correction ultérieure ne réécrit pas un delta déjà livré.

Seul le commit final stable reçoit :

v0.1.3

17. Première action de la session

Commencer par 0.1.3-pre.001 : audit, brainstorming et plan de travail.

Ne pas traiter ce pre.001 comme un simple audit passif. Il doit produire les décisions nécessaires au développement des tranches suivantes et une matrice claire des responsabilités Config.

18. Dernière prerelease

La dernière prerelease de 0.1.3 devra :

exécuter les validations finales ;
consolider la documentation durable ;
nettoyer/archiver uniquement ce que les règles exigent ;
préparer le prompt de la release suivante ;
vérifier le graphe de dépendances/features ;
fermer les TODO de release ou les reporter explicitement ;
préparer la livraison rel.001 et le tag stable après validation utilisateur.

19. Validations minimales attendues

Lorsque les commandes sont applicables :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
cargo tree -p ksp-config-lib
cargo tree -p ksp-config-lib -d
cargo tree -p ksp-config-lib -e features

Exécuter également tout script d'audit réellement présent dans le dépôt au moment de la validation.

Aucune commande non exécutée ne doit être déclarée réussie.

20. Critère de succès du `pre.001`

Le pre.001 est terminé lorsque nous savons précisément :

quels documents existent dans la première surface Config ;
ce qui est global et ce qui est profilé ;
comment fonctionne default_profile ;
comment se résolvent les overrides KSP_*/KSPB_* ;
comment documents unitaires et fichiers composites sont séparés puis résolus ;
comment les secrets/public/debug sont classifiés et quels contrats autorisent leur lecture/mutation ;
quels contrats de lecture/résolution/validation/mutation sont publics ou privilégiés, et comment ksp-config-lib reste l'unique manager des fichiers Config et variables d'environnement ;
comment Config construit LoggingSettings sans dépendance inverse ;
quelles dépendances externes sont réellement nécessaires ;
si 0.1.3 reste une seule release ou doit être scindée ;
quel est le découpage des prereleases de développement.

15 KiB Raw Blame History