v0.1.2-pre.003

docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md

@@ -1,13 +1,13 @@
 <!-- file: docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Plan KSP 0.1.2 — Logging foundation
 
 ## Statut
 
-Plan actif de `0.1.2`, établi par `0.1.2-pre.001`, corrigé par `0.1.2-pre.001-fix.001` puis concrétisé par la première surface fonctionnelle de `0.1.2-pre.002`.
+Plan actif de `0.1.2`, établi par `0.1.2-pre.001`, corrigé par `0.1.2-pre.001-fix.001`, concrétisé par la façade de `0.1.2-pre.002` puis étendu au runtime subscriber par `0.1.2-pre.003`.
 
-`pre.002` crée `ksp-logging-lib`, ses settings runtime, sa façade d'événements/spans et son instrumentation async. Le subscriber runtime, le takeover effectif, les sorties et le hot reload restent réservés aux tranches suivantes.
+`pre.002-fix.001` a été validé dans l'environnement de développement avec `cargo fmt`, `cargo check`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres sur la version Cargo `0.1.2-pre.2.fix.1`. `pre.003` ajoute le subscriber global, le takeover/filtering KSP, la console initiale et le hot reload des layers. Les writers non bloquants, le fichier, les guards et le stripping ANSI restent réservés à `pre.004`.
 
 ## Base auditée
 
@@ -147,9 +147,15 @@ tracing-appender = { version = "^0.2", default-features = false }
 
 ### Politique d'ajout au manifest
 
-`pre.002` ajoute uniquement `tracing` sous `[workspace.dependencies]`, car la façade événements/spans et l'instrumentation async l'utilisent réellement. `crates/ksp-logging-lib/Cargo.toml` l'hérite avec `tracing.workspace = true`.
+`pre.002` ajoute `tracing` sous `[workspace.dependencies]`, car la façade événements/spans et l'instrumentation async l'utilisent réellement. `crates/ksp-logging-lib/Cargo.toml` l'hérite avec `tracing.workspace = true`.
 
-`tracing-subscriber` et `tracing-appender` restent absents jusqu'aux prereleases qui utilisent effectivement leurs APIs.
+`pre.003` revérifie `tracing-subscriber 0.3.23` et ajoute :
+
+```toml
+tracing-subscriber = { version = "^0.3", default-features = false, features = ["fmt"] }
+```
+
+La feature `fmt` apporte `registry` et `std`, nécessaires à la composition des layers, `Targets`, `reload` et au formatter console. `env-filter`, `ansi`, `tracing-log`, `json`, `time` et les autres features optionnelles ne sont pas activées. `tracing-appender` reste absent jusqu'à `pre.004`, où il sera réellement consommé.
 
 Après chaque ajout réel :
 
@@ -920,15 +926,24 @@ Objectifs :
 
 ### `0.1.2-pre.003` — subscriber + takeover + console + reload foundation
 
-Objectifs :
+Statut : implémenté dans la tranche `pre.003`, sous réserve des validations Cargo à exécuter dans l'environnement de développement.
 
-- revérifier puis ajouter `tracing-subscriber` ;
-- implémenter le mapping `LogFilterLevel` ;
-- implémenter le silence externe + default KSP + overrides ;
-- implémenter la couche console ;
-- installer le subscriber global avec API fallible ;
-- introduire l'infrastructure reloadable et les premiers tests de hot reload ;
-- intégrer les événements lifecycle de spans `Off/NewAndClose/Full`.
+Réalisé :
+
+- `tracing-subscriber` ajouté avec uniquement la feature `fmt` ;
+- mapping complet `LogFilterLevel -> LevelFilter` ;
+- `Targets` configuré avec default externe `OFF`, préfixe KSP `ksp-` au niveau global demandé et overrides par target prefix ;
+- console stdout/stderr initiale avec ANSI explicitement désactivé ;
+- subscriber global installé par `initialize()` avec API fallible et erreur `logging.already_initialized` ;
+- `LoggingGuard` public possédant le handle de reload et les settings actifs ;
+- `reinitialize(&mut LoggingGuard, &LoggingSettings)` remplaçant le `Vec` de layers sans réinstaller le subscriber global ;
+- configuration sans sink supportée à l'initialisation afin de permettre une activation ultérieure par hot reload ;
+- mapping `SpanEvents::Off/NewAndClose/Full` vers `FmtSpan::NONE`, `NEW | CLOSE` et `FULL` ;
+- tests du takeover, des overrides, du démarrage sans sink, de l'activation à chaud, du refus d'un second `initialize()` et de la persistance du silence des targets externes.
+
+La console de `pre.003` utilise encore directement `stdout`/`stderr` comme writer synchrone. C'est un état transitoire volontaire : `pre.004` remplace ces writers par `tracing-appender::non_blocking`, introduit les `WorkerGuard`/`ErrorCounter`, puis ajoute le fichier et le stripping ANSI. La release stable `0.1.2` ne sera pas déclarée conforme tant que ce remplacement n'est pas terminé.
+
+Le runtime reloadable est un `Vec<Box<dyn Layer<Registry>>>` placé derrière une unique `reload::Layer`. Cette composition permet de changer à chaud le nombre et le type des sinks tout en conservant un seul subscriber global et prépare directement l'ajout du layer fichier de `pre.004`.
 
 ### `0.1.2-pre.004` — non-blocking console/fichier + guards + ANSI + reload sinks
 
@@ -1016,17 +1031,19 @@ La release peut être stabilisée lorsque :
 - les validations workspace et audits présents sont propres ;
 - la documentation finale et le prompt `0.1.3` sont prêts.
 
-## Questions ouvertes après `pre.002`
+## Questions ouvertes après `pre.003`
 
 Les deux questions d'API propres à `pre.002` sont résolues :
 
 1. les macros KSP délèguent aux macros `tracing` au point d'appel via un bridge interne caché et exigent un `target:` explicite ;
 2. la surface span publique est `Span::in_scope(...)` pour le synchrone et `instrument(span, future)` pour l'async, avec type de future retourné opaque.
 
-Restent à confirmer par les prereleases runtime sans remettre en cause ce contrat :
+La composition de reload est désormais fixée pour cette release à un `Vec` de layers boxed derrière une `reload::Layer`, ce qui autorise l'activation/désactivation des sinks et le remplacement de leurs paramètres sans second subscriber global.
 
-1. la composition interne la moins coûteuse pour le hot reload (reload de filters/layers ciblés ou routing dynamique KSP), tout en conservant un seul subscriber global ;
-2. l'API publique exacte d'observation des dropped lines ;
-3. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public.
+Restent à confirmer par les prereleases suivantes sans remettre en cause ce contrat :
 
-La prochaine action après validation de `pre.002` est `0.1.2-pre.003` : subscriber, takeover, filtering, console initiale et fondation du hot reload.
+1. l'API publique exacte d'observation des dropped lines ;
+2. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public ;
+3. le comportement de flush/rotation et le swap transactionnel des `WorkerGuard` lorsque les sinks non bloquants seront introduits.
+
+La prochaine action après validation de `pre.003` est `0.1.2-pre.004` : `tracing-appender`, console/fichier non bloquants, guards, rotation, stripping ANSI et reload des sinks.