336 lines
13 KiB
Markdown
336 lines
13 KiB
Markdown
<!-- file: prompts/002-V0_1_2_START_PROMPT.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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<T>
|
|
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 `<crate>.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<T>
|
|
```
|
|
|
|
`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.
|