v0.1.1-pre.005
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
@@ -21,4 +21,5 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par
|
||||
|
||||
## Documents
|
||||
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt final ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3`.
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt historique ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3` ;
|
||||
- [`002-V0_1_2_START_PROMPT.md`](002-V0_1_2_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.2 — Logging foundation` après publication stable de `0.1.1`.
|
||||
|
||||
335
prompts/002-V0_1_2_START_PROMPT.md
Normal file
335
prompts/002-V0_1_2_START_PROMPT.md
Normal file
@@ -0,0 +1,335 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user