v0.1.2-pre.001
This commit is contained in:
375
deltas/0.1.2/pre.001.md
Normal file
375
deltas/0.1.2/pre.001.md
Normal file
@@ -0,0 +1,375 @@
|
||||
<!-- file: deltas/0.1.2/pre.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.2-pre.001
|
||||
|
||||
## Base requise
|
||||
|
||||
Release stable/taguée attendue :
|
||||
|
||||
```text
|
||||
v0.1.1
|
||||
```
|
||||
|
||||
L'archive Gitea fournie `khadhroony-solana-project-v0.1.1.zip` contient bien :
|
||||
|
||||
- `workspace.package.version = "0.1.1"` ;
|
||||
- le delta final `deltas/0.1.1/rel.001.md` ;
|
||||
- le prompt final `prompts/002-V0_1_2_START_PROMPT.md` ;
|
||||
- la surface Core stabilisée attendue.
|
||||
|
||||
Dans le workflow KSP, cette archive provient directement du tag correspondant et constitue la base stable suffisante pour ouvrir `0.1.2`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ouvrir `0.1.2` par la prerelease obligatoire de brainstorming, audit et planification, sans développement fonctionnel Logging.
|
||||
|
||||
Cette tranche :
|
||||
|
||||
- inventorie l'état réel du workspace et confirme l'absence actuelle de `ksp-logging-lib` ;
|
||||
- audite la stack `tracing` officielle actuelle ;
|
||||
- fixe la frontière façade/instrumentation/runtime subscriber ;
|
||||
- retient les macros KSP pour préserver les callsites ;
|
||||
- définit les niveaux et settings runtime candidats ;
|
||||
- borne la sémantique de `target`, `domain` et `component` ;
|
||||
- retient le filtering global + target-prefix via `Targets` ;
|
||||
- retient console + fichier optionnel ;
|
||||
- retient un writer fichier non bloquant non-lossy avec guard possédé explicitement ;
|
||||
- définit le lifecycle d'initialisation/réinitialisation ;
|
||||
- fixe la stratégie d'erreurs Core et de protection des secrets ;
|
||||
- dimensionne `pre.002` à `pre.006` ;
|
||||
- confirme les hors-scope.
|
||||
|
||||
Le détail est consigné dans `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe de :
|
||||
|
||||
```text
|
||||
0.1.1
|
||||
```
|
||||
|
||||
à :
|
||||
|
||||
```text
|
||||
0.1.2-pre.1
|
||||
```
|
||||
|
||||
L'identifiant Cargo respecte SemVer sans zéro initial ; l'identifiant de livraison reste `0.1.2-pre.001`.
|
||||
|
||||
Le header de `Cargo.toml` passe de version 25 à 26.
|
||||
|
||||
Aucune dépendance `tracing*` n'est ajoutée par cette tranche de planification : elles seront introduites uniquement lorsque le code/tests de `ksp-logging-lib` les consommeront réellement.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`
|
||||
- `deltas/0.1.2/pre.001.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `ROADMAP.md`
|
||||
- `docs/plans/000-README.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Inventaire du workspace
|
||||
|
||||
État de la base stable auditée :
|
||||
|
||||
```text
|
||||
workspace members
|
||||
└── crates/ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-logging-lib` n'existe pas encore.
|
||||
|
||||
Core fournit déjà les contrats nécessaires à Logging :
|
||||
|
||||
```text
|
||||
ksp_core_lib::ErrorCode
|
||||
ksp_core_lib::ErrorContext
|
||||
ksp_core_lib::Error
|
||||
ksp_core_lib::Result<T>
|
||||
ksp_core_lib::Pubkey
|
||||
```
|
||||
|
||||
ainsi que les Program IDs fondamentaux et leur registre descriptif.
|
||||
|
||||
La relation retenue reste unidirectionnelle :
|
||||
|
||||
```text
|
||||
ksp-logging-lib -> ksp-core-lib
|
||||
ksp-core-lib -X-> ksp-logging-lib
|
||||
```
|
||||
|
||||
## Audit externe tracing
|
||||
|
||||
Audit effectué le 2026-08-14 sur les publications/docs officielles Tokio `tracing`, docs.rs/crates.io et les manifests publiés.
|
||||
|
||||
Versions observées :
|
||||
|
||||
```text
|
||||
tracing 0.1.44 rustc 1.65+
|
||||
tracing-subscriber 0.3.23 rustc 1.65+
|
||||
tracing-appender 0.2.5 rustc 1.63+
|
||||
```
|
||||
|
||||
Contraintes candidates à revérifier au moment de l'ajout effectif :
|
||||
|
||||
```toml
|
||||
tracing = { version = "^0.1", default-features = false, features = ["std"] }
|
||||
tracing-subscriber = { version = "^0.3", default-features = false, features = ["fmt"] }
|
||||
tracing-appender = { version = "^0.2", default-features = false }
|
||||
```
|
||||
|
||||
Décisions de features :
|
||||
|
||||
- pas de `tracing-attributes`/`attributes` ;
|
||||
- pas de `ansi` ;
|
||||
- pas de `tracing-log` ;
|
||||
- pas d'`env-filter` ;
|
||||
- pas de JSON/Serde ;
|
||||
- pas de chrono/time formatter via `tracing-subscriber` ;
|
||||
- pas de `parking_lot` appender ;
|
||||
- `tracing-appender` tire lui-même `tracing-subscriber` avec `default-features = false`, `fmt` et `std` ainsi que les dépendances internes nécessaires à son fonctionnement.
|
||||
|
||||
Aucune dépendance n'est ajoutée uniquement parce qu'elle figure dans l'architecture candidate.
|
||||
|
||||
## Décisions de planification
|
||||
|
||||
### Façade et callsites
|
||||
|
||||
La surface d'émission KSP sera :
|
||||
|
||||
```text
|
||||
ksp_logging_lib::error!
|
||||
ksp_logging_lib::warn!
|
||||
ksp_logging_lib::info!
|
||||
ksp_logging_lib::debug!
|
||||
ksp_logging_lib::trace!
|
||||
```
|
||||
|
||||
Les événements ne seront pas émis par de simples fonctions wrappers qui déplaceraient les métadonnées source.
|
||||
|
||||
L'implémentation exacte des macros doit réussir un test d'intégration prouvant que file/module/line et target implicite restent ceux du consommateur.
|
||||
|
||||
### Champs structurés
|
||||
|
||||
- `target` : métadonnée native de routage/filtering, naturelle au callsite ou explicitement overridable ;
|
||||
- `domain` : champ structuré KSP optionnel ;
|
||||
- `component` : champ structuré KSP optionnel ;
|
||||
- autres champs : ouverts selon besoin, sans taxonomie fermée.
|
||||
|
||||
`domain` et `component` ne deviennent pas des filtres dans `0.1.2`.
|
||||
|
||||
### Filtering
|
||||
|
||||
Première surface :
|
||||
|
||||
```text
|
||||
default filter level
|
||||
+ zero or more target-prefix overrides
|
||||
```
|
||||
|
||||
`tracing_subscriber::filter::Targets` est retenu comme mécanisme initial.
|
||||
|
||||
`EnvFilter`, `RUST_LOG`, field-based filtering et hot reload restent hors scope.
|
||||
|
||||
### Settings runtime
|
||||
|
||||
Surface conceptuelle retenue :
|
||||
|
||||
```text
|
||||
LogFilterLevel
|
||||
TargetFilter
|
||||
ConsoleOutput
|
||||
ConsoleSettings
|
||||
FileRotation
|
||||
FileSettings
|
||||
LoggingSettings
|
||||
LoggingGuard
|
||||
initialize(...)
|
||||
```
|
||||
|
||||
Les settings ne lisent ni fichier, ni environnement, ni profil Config et ne contiennent aucun secret.
|
||||
|
||||
### Console
|
||||
|
||||
Sortie console avec choix explicite stdout/stderr.
|
||||
|
||||
Le formatter initial reste humain, sans JSON ni ANSI obligatoire.
|
||||
|
||||
### Fichier
|
||||
|
||||
Sortie fichier optionnelle retenue avec :
|
||||
|
||||
```text
|
||||
Never | Hourly | Daily
|
||||
```
|
||||
|
||||
Le builder fallible du `RollingFileAppender` doit être utilisé afin de remonter les erreurs au lieu de paniquer.
|
||||
|
||||
Le writer fichier utilise `NonBlockingBuilder` en mode :
|
||||
|
||||
```text
|
||||
lossy(false)
|
||||
```
|
||||
|
||||
La saturation applique donc de la backpressure plutôt que de supprimer silencieusement des logs.
|
||||
|
||||
### Lifecycle
|
||||
|
||||
`LoggingGuard` possède le ou les `WorkerGuard` nécessaires au backend non bloquant.
|
||||
|
||||
L'appelant conserve le guard jusqu'à la fin ordonnée du processus.
|
||||
|
||||
Le lifecycle global est volontairement :
|
||||
|
||||
```text
|
||||
uninitialized -> initialized -> process shutdown
|
||||
```
|
||||
|
||||
Une initialisation répétée échoue avec une erreur KSP ; elle ne remplace pas silencieusement un subscriber existant et ne panique pas.
|
||||
|
||||
### Erreurs
|
||||
|
||||
Les erreurs Logging utilisent le contrat Core et restent dans le domaine :
|
||||
|
||||
```text
|
||||
logging
|
||||
```
|
||||
|
||||
Codes conceptuels initiaux :
|
||||
|
||||
```text
|
||||
logging.invalid_settings
|
||||
logging.already_initialized
|
||||
logging.file_output_initialization_failed
|
||||
```
|
||||
|
||||
Les causes externes utiles sont conservées via `Error::with_source(...)` lorsque possible.
|
||||
|
||||
### Secrets
|
||||
|
||||
Sont explicitement interdits dans les logs : clés privées, seeds/mnemonics, passwords/passphrases/PIN, tokens API/bearer/session, cookies/auth headers, secrets de chiffrement/signature, credentials de connexion et futurs `*_SECRET_*`.
|
||||
|
||||
Aucun helper de redaction universel n'est introduit : le caller doit omettre ou redacter explicitement la valeur avant émission.
|
||||
|
||||
Les settings Logging ne contiennent eux-mêmes aucun secret.
|
||||
|
||||
### Surface différée
|
||||
|
||||
Ne pas ajouter dans `0.1.2` sans nouveau besoin validé :
|
||||
|
||||
- spans KSP/`#[instrument]` ;
|
||||
- OpenTelemetry ;
|
||||
- JSON ;
|
||||
- ANSI ;
|
||||
- compatibilité `log` ;
|
||||
- `EnvFilter` ;
|
||||
- reload de filtre ;
|
||||
- filtering par fields/domain ;
|
||||
- rotation minutely/weekly/by-size ;
|
||||
- compression/rétention complexe/latest symlink ;
|
||||
- routes multiples avancées.
|
||||
|
||||
## Référence historique bot3
|
||||
|
||||
L'ancien `ks-logging` de l'archive bot3 fournie a été relu comme référence historique uniquement.
|
||||
|
||||
Éléments conservés comme leçons utiles :
|
||||
|
||||
- objet de lifecycle possédant les `WorkerGuard` ;
|
||||
- console + fichier ;
|
||||
- rotation ;
|
||||
- filtering par targets.
|
||||
|
||||
Éléments non migrés :
|
||||
|
||||
- dépendance Logging -> Config ;
|
||||
- document/schema JSON propre à Logging ;
|
||||
- Serde/JSON pour la configuration ;
|
||||
- routes/formats multiples non nécessaires à la première surface KSP.
|
||||
|
||||
## Prereleases prévues
|
||||
|
||||
```text
|
||||
pre.001 audit + brainstorming + plan
|
||||
pre.002 crate + settings + macros/façade
|
||||
pre.003 subscriber + console + filtering + callsite final
|
||||
pre.004 fichier + non-blocking + lifecycle
|
||||
pre.005 intégration + tests + audits
|
||||
pre.006 validation finale + docs/cleanup + prompt 0.1.3
|
||||
```
|
||||
|
||||
Le découpage reste souple ; une tranche trop large sera scindée plutôt que surchargée.
|
||||
|
||||
## Hors scope confirmé
|
||||
|
||||
- Config/documents/profils ;
|
||||
- Tauri ;
|
||||
- Wallet/signing ;
|
||||
- RPC/WS/providers ;
|
||||
- Program decoding/execution ;
|
||||
- Store/PostgreSQL ;
|
||||
- Materializer ;
|
||||
- workers/jobs/pipelines ;
|
||||
- scenarios ;
|
||||
- trading/ML ;
|
||||
- observabilité distribuée/OpenTelemetry.
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
Dans l'environnement de préparation de ce delta :
|
||||
|
||||
- lecture/audit de l'archive complète `0.1.1` fournie ;
|
||||
- vérification statique de `workspace.package.version = "0.1.1"` ;
|
||||
- vérification de la présence du delta `0.1.1/rel.001` et du prompt final `0.1.2` ;
|
||||
- inventaire des membres workspace et confirmation de l'absence de `ksp-logging-lib` ;
|
||||
- lecture des règles, plans, indexes et documents d'architecture demandés par le prompt ;
|
||||
- lecture de `ksp-core-lib` et de son contrat Error/Result ;
|
||||
- audit de l'ancien `ks-logging` bot3 fourni comme référence historique, sans le traiter comme source de vérité KSP ;
|
||||
- vérification des versions/features/MSRV actuels de `tracing`, `tracing-subscriber` et `tracing-appender` depuis leurs sources de publication officielles ;
|
||||
- audit du manifest publié de `tracing-appender` pour ses dépendances/features ;
|
||||
- audit de `Targets`, `EnvFilter`, du non-blocking, du mode lossy/backpressure, de `WorkerGuard`, du builder fallible et de la rotation ;
|
||||
- parsing TOML statique du manifest modifié ;
|
||||
- contrôle statique des headers `file:` / `version:` des fichiers ajoutés/modifiés ;
|
||||
- contrôle statique des liens Markdown locaux après modification ;
|
||||
- contrôle du contenu de l'archive delta selon `VER-ARCHIVE-004`.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
L'environnement de préparation ne contient ni `cargo` ni `rustc`.
|
||||
|
||||
Les commandes suivantes n'ont donc pas pu être exécutées ici :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Les trois commandes `cargo tree -p ksp-logging-lib` ne sont de toute façon applicables qu'après création effective de la crate.
|
||||
|
||||
Aucun succès Cargo n'est déclaré par ce delta.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Aucune question architecturale bloquante ne justifie de poursuivre le développement dans `pre.001`.
|
||||
|
||||
À confirmer par tests dans les tranches suivantes :
|
||||
|
||||
- mécanisme exact de macro KSP préservant le callsite avec la plus petite surface ;
|
||||
- format visuel exact des lignes humaines sans le figer comme protocole ;
|
||||
- nécessité future de capacités volontairement différées comme rétention, ANSI, JSON, `tracing-log`, `EnvFilter`, spans ou reload.
|
||||
|
||||
La prochaine tranche après validation de ce plan est `0.1.2-pre.002`.
|
||||
Reference in New Issue
Block a user