# Prompt de démarrage KSP 0.1.2 **Statut : Final — à utiliser après validation et publication stable de `0.1.1`.** ## 1. Identité Release fonctionnelle : ```text 0.1.2 — Logging foundation ``` Deuxième release fonctionnelle de Khadhroony Solana Project. ## 2. Mission Introduire et stabiliser `ksp-logging-lib` comme façade KSP commune et propriétaire du logging/tracing runtime. Cette crate doit être la seule crate KSP qui importe directement et configure la stack `tracing` nécessaire à la politique générale de logs. Les autres crates comportementales KSP doivent consommer la façade de `ksp-logging-lib` plutôt que définir chacune leur propre initialisation ou leur propre politique de tracing. La release doit établir une surface assez générale pour Logging lui-même et pour les prochaines crates N1, sans ouvrir `ksp-config-lib`, Tauri, Transport, Wallet, Program, Store ou les autres couches supérieures. ## 3. Base requise Base attendue : ```text 0.1.1 stable ``` La session commence uniquement après validation de la dernière prerelease de `0.1.1`, publication du delta final `rel.001` et tag stable : ```text v0.1.1 ``` Dans le workflow KSP, une archive Gitea nommée `khadhroony-solana-project-v0.1.1.zip` provient directement du tag correspondant et constitue une base stable suffisante pour la session. ## 4. État validé à préserver `ksp-core-lib` fournit désormais la fondation N1 commune, notamment : ```text ksp_core_lib::ErrorCode ksp_core_lib::ErrorContext ksp_core_lib::Error ksp_core_lib::Result ksp_core_lib::Pubkey ``` ainsi que la propriété KSP des Program IDs fondamentaux et leur registre descriptif. Logging peut dépendre de `ksp-core-lib` pour `Error` / `Result`. La relation inverse reste interdite : Core ne dépend pas de Logging. La politique Cargo établie dans `0.1.1` doit être conservée : - toute dépendance externe est déclarée au `Cargo.toml` racine sous `[workspace.dependencies]` ; - une crate membre consomme ces dépendances avec `.workspace = true` ; - les versions sont exprimées avec une génération compatible explicite telle que `^M.m`, sauf pin justifié ; - les features et `default-features` sont activées uniquement lorsqu'un besoin concret le démontre. ## 5. Sources de vérité internes Relire en priorité les fichiers réellement présents dans la base, notamment : - `ROADMAP.md` ; - `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` ; - `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md` ; - `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md` ; - `docs/architecture/003-COMPONENT_CONTRACTS.md` ; - `docs/architecture/004-COMPONENT_INVENTORY.md` ; - `docs/architecture/005-DEPENDENCY_GRAPH.md` ; - `docs/rules/RULES_DEPENDENCIES.md` ; - `docs/rules/RULES_KSP.md` ; - `docs/rules/RULES_RUST.md` ; - `docs/rules/VERSION_WORKFLOW.md` ; - `docs/IDEAS.md` ; - les deltas `deltas/0.1.1/*`. Relire aussi les règles/index racine supplémentaires présents au moment de la session. Ne jamais inventer un document absent de la base. ## 6. Sources externes normatives Avant d'ajouter `tracing`, `tracing-subscriber`, `tracing-appender` ou toute crate liée : - vérifier les versions publiées actuelles depuis les sources officielles Tokio/tracing et crates.io/docs.rs ; - examiner leurs features et dépendances réelles ; - identifier le MSRV/toolchain pertinent ; - éviter d'activer les default features ou features optionnelles uniquement par commodité ; - examiner `cargo tree` et `cargo tree -e features` après intégration. La première prerelease doit choisir les dépendances réellement nécessaires à l'API retenue ; la présence architecturale d'une crate candidate n'oblige pas à l'ajouter si la surface finale n'en a pas besoin. ## 7. Première prerelease obligatoire : `0.1.2-pre.001` `pre.001` est d'abord une prerelease de **brainstorming, audit et planification**. Elle doit au minimum : 1. inventorier l'état réel du workspace et confirmer la création/absence actuelle de `ksp-logging-lib` ; 2. auditer la stack `tracing` officielle actuelle, ses versions, features et dépendances ; 3. définir précisément la frontière entre façade KSP, initialisation et backend/subscriber ; 4. déterminer si l'API publique principale doit utiliser des macros, des fonctions ou une combinaison ; 5. préserver les callsites/source locations réels pour les événements de logging ; 6. définir les niveaux KSP `error`, `warn`, `info`, `debug`, `trace` ; 7. définir les champs structurés communs utiles maintenant, notamment `target`, `domain`, `component` ou équivalents sans inventer une taxonomie trop rigide ; 8. définir le contrat de settings runtime de Logging sans dépendre de Config ; 9. définir le lifecycle d'initialisation, les erreurs d'initialisation et le comportement d'une initialisation répétée ; 10. étudier console, fichiers, filtering, appender non bloquant et rotation uniquement selon les besoins de la première surface ; 11. traiter explicitement la durée de vie/ownership des guards nécessaires aux writers non bloquants si cette voie est retenue ; 12. définir la stratégie de prévention des secrets dans les logs ; 13. proposer l'API publique et les crate-root reexports ; 14. proposer les tests unitaires/intégration et audits de dépendances ; 15. dimensionner les prereleases suivantes ; 16. confirmer les hors-scope. Ne pas transformer `pre.001` en une grosse phase de développement avant validation du plan. ## 8. Responsabilité de `ksp-logging-lib` La direction acquise est : ```text ksp-logging-lib -> ksp-core-lib -> tracing stack réellement retenue ``` `ksp-logging-lib` doit être la façade commune de logging/tracing du projet et le propriétaire de la politique runtime correspondante. Les crates comportementales KSP pourront dépendre directement de `ksp-logging-lib` et utiliser sa surface KSP pour : ```text error warn info debug trace ``` avec les champs structurés réellement retenus par `pre.001`. Les crates `*-api` purement déclaratives restent sans dépendance logging par défaut lorsqu'elles n'ont aucun comportement réel à tracer. ## 9. Callsite et macros L'audit doit porter une attention particulière à la préservation du callsite réel. Une simple fonction wrapper autour d'une macro `tracing::*` peut enregistrer le fichier/module/ligne du wrapper plutôt que ceux de l'appelant. La surface KSP doit donc être conçue pour préserver correctement les métadonnées de callsite, quitte à exposer des macros KSP qui délèguent aux macros `tracing` au point d'appel. Le design exact des macros/fonctions et leurs noms sont décidés dans `pre.001`, puis testés avant stabilisation. ## 10. Settings et Config `ksp-logging-lib` ne dépend pas de `ksp-config-lib`. Logging possède les settings runtime strictement nécessaires à son initialisation. `ksp-config-lib`, lorsqu'il sera développé en `0.1.3`, pourra lire/résoudre ses documents puis convertir explicitement la configuration obtenue vers les settings publics de Logging. Ne pas introduire de document JSON/TOML de configuration global dans Logging uniquement pour anticiper Config. ## 11. Sorties et lifecycle Le `pre.001` doit déterminer la première surface réellement utile parmi : - console/stdout/stderr ; - fichiers ; - filtrage global et/ou par target/domain ; - format lisible et/ou structuré ; - rotation ; - writer non bloquant ; - flush/shutdown propre. Lorsque `tracing-appender::non_blocking` ou un mécanisme équivalent est retenu, la durée de vie du guard doit être possédée par un objet/lifecycle KSP explicite afin d'éviter une perte silencieuse de logs à la fin du scope d'initialisation. Une capacité non nécessaire à la première validation n'est pas ajoutée par anticipation. ## 12. Erreurs Les erreurs Logging utilisent le contrat Core : ```text ksp_core_lib::Error ksp_core_lib::Result ``` `ksp-logging-lib` définit ses propres constantes `ErrorCode` dans son domaine sans ajouter de variante ou de connaissance Logging à `ksp-core-lib`. Les causes externes utiles sont conservées via le contrat `source` Core lorsqu'elles satisfont les bornes prévues. Aucun `unwrap`, `expect`, `panic` production ou opérateur `?` n'est utilisé. ## 13. Secrets et données sensibles Logging ne doit pas devenir un canal de fuite de secrets. `pre.001` doit au minimum définir : - quels champs sont interdits par politique ; - comment les settings sensibles sont exclus ; - quelles données doivent être explicitement redacted/omises par les appelants ; - si des helpers de redaction génériques sont réellement nécessaires maintenant. Ne pas logger automatiquement les contenus de clés privées, seeds, passwords, tokens d'API ou autres secrets. ## 14. Dépendances et propriété Interdictions : ```text ksp-core-lib -X-> ksp-logging-lib ksp-logging-lib -X-> ksp-config-lib ksp-logging-lib -X-> wallet/transport/program/store/workers/jobs/apps ``` `ksp-logging-lib` est la seule crate KSP qui doit normalement importer directement `tracing` et réaliser la configuration du subscriber/appender retenu. Une application Tauri future peut exceptionnellement devoir intégrer une crate/plugin tracing imposée par son framework. Cette exception reste au niveau adaptateur/application et ne crée pas une seconde politique de logging parallèle à `ksp-logging-lib`. ## 15. Hors scope strict de `0.1.2` - `ksp-config-lib` et documents/profils Config ; - application Tauri ; - wallet/keypair/signer ; - RPC/WS/providers ; - Program decoding/execution ; - Store/PostgreSQL ; - materializers ; - workers/jobs/pipelines ; - scenarios ; - trading/ML ; - OpenTelemetry ou export réseau de traces, sauf besoin concret explicitement revalidé et borné ; - observability distribuée complète. ## 16. Règles Rust et Cargo Préserver les règles workspace, notamment : - Rust 2024 ; - async-first pour les I/O futures lorsque pertinent, sans rendre artificiellement async les appels de logging synchrones ; - `unsafe` interdit ; - `unwrap` / `expect` interdits ; - `panic` interdit en production ; - opérateur `?` interdit ; - returns explicites, y compris dans les closures lorsque Clippy l'exige ; - `unreachable_pub = deny` ; - `missing_docs = warn` ; - imports de traits seulement lorsque nécessaire ; - réexports crate-root explicites ; - pas de `mod.rs` ; - pas de `pub(super)` / `pub(in ...)` ; - code/Rustdoc en anglais ; - tests unitaires externes au `src` selon la convention du dépôt ; - dépendances externes centralisées sous `[workspace.dependencies]`. ## 17. Git et deltas À partir de `0.1.x`, chaque delta est commité : ```text pre.NNN pre.NNN-fix.NNN rel.NNN ``` Une erreur est corrigée par le delta suivant ; l'historique n'est pas réécrit. Seul le commit final validé comme stable reçoit : ```text v0.1.2 ``` ## 18. Dimensionnement indicatif Le nombre réel de prereleases est décidé dans `pre.001`. Trajectoire candidate uniquement : ```text pre.001 audit + brainstorming + plan pre.002 crate/settings + façade levels/callsites pre.003 initialisation + console/filtering pre.004 fichiers/appender/rotation/lifecycle si retenus pre.005 intégration/tests/audits pre.006 validation finale/docs/cleanup/prompt 0.1.3 ``` Scinder une tranche si son périmètre devient trop large. Supprimer/réorganiser une tranche si le `pre.001` démontre qu'une capacité candidate n'est pas nécessaire. ## 19. Validations attendues Lorsque les commandes sont applicables : ```bash cargo fmt --all cargo check --workspace cargo test --workspace cargo clippy --workspace --all-targets cargo tree -p ksp-logging-lib cargo tree -p ksp-logging-lib -d cargo tree -p ksp-logging-lib -e features ``` Exécuter également les scripts/audits réellement présents dans le dépôt. Aucune validation non exécutée ne doit être déclarée réussie. ## 20. Critères de sortie `0.1.2` peut être publiée stable lorsque : - la façade Logging et son ownership sont clairs ; - les callsites sont préservés par tests ; - les cinq niveaux KSP nécessaires sont utilisables ; - l'initialisation choisie est déterministe et testée ; - console/fichiers/filtering/lifecycle retenus sont validés ; - les erreurs utilisent Core sans dépendance inverse ; - aucune dépendance Config ou domaine supérieur n'a été introduite ; - les secrets sont protégés par une politique documentée/testable ; - le graphe de dépendances/features est audité ; - les validations workspace sont propres ; - la documentation finale et le prompt de la release suivante sont prêts. ## 21. Release suivante La release suivante prévue est : ```text 0.1.3 — ksp-config-lib ``` Son périmètre concret reste soumis au `pre.001` correspondant et peut être scindé si Config s'avère trop large pour une seule release.