v0.1.2-pre.005

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: 11 -->
+<!-- version: 12 -->
 
 # 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`, concrétisé par la façade de `0.1.2-pre.002`, étendu au runtime subscriber par `0.1.2-pre.003`/`pre.003-fix.001`, puis complété par les sorties non bloquantes de `0.1.2-pre.004`. `pre.004-fix.001` a rendu explicite l'ordre de retrait des layers et des `WorkerGuard`; `pre.004-fix.002` corrige ensuite l'interaction entre la sanitization ANSI native de `tracing-subscriber 0.3.23` et le stripping fichier KSP.
+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`, étendu au runtime subscriber par `0.1.2-pre.003`/`pre.003-fix.001`, puis complété et corrigé par `pre.004`/`pre.004-fix.001..004`. `pre.005` ouvre la phase d'intégration/robustesse : saturation déterministe, concurrence pendant hot reload, audit de takeover, validation des spans de timing, documentation de crate et probe d'overhead grossier.
 
-`pre.003-fix.001` a été validé dans l'environnement de développement avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres sur la version Cargo `0.1.2-pre.3.fix.1`. `pre.004` ajoute `tracing-appender`, remplace la console synchrone par un writer non bloquant, introduit le fichier `Never/Hourly/Daily`, possède les `WorkerGuard`, expose des compteurs cumulés de dropped lines, déporte le stripping ANSI côté worker fichier et conserve le hot reload transactionnel des sinks. `pre.004-fix.001` a rendu explicite le retrait des anciens layers avant leurs `WorkerGuard`, mais la validation utilisateur après `cargo clean` a reproduit exactement le même échec du marqueur fichier. Cette seconde validation a invalidé l'hypothèse selon laquelle ce défaut précis provenait du drain. La cause réelle est la sanitization ANSI native de `tracing-subscriber 0.3.23`, activée par défaut dans `fmt::Layer` : elle transforme les séquences de contrôle présentes dans les valeurs avant qu'elles n'atteignent le writer. `pre.004-fix.002` la conserve pour la console mais la désactive sur le formatter fichier afin que le `StripAnsiWriter` KSP, placé côté worker, reçoive les séquences ANSI originales et les supprime réellement. Le lifecycle explicite de `fix.001` est conservé car il reste correct pour le retrait des sinks non bloquants. La validation de `pre.004-fix.002` confirme ensuite que l'écriture fichier et le stripping ANSI fonctionnent, mais révèle que le target externe `sqlx` est encore persisté. La cause est la composition du filtre global comme enfant frère des formatters dans un `Vec<Layer>` : le `Vec` agrège l'intérêt de callsite en conservant l'intérêt le plus élevé de ses enfants, de sorte qu'un formatter intéressé peut masquer le `Interest::never()` du `Targets`. `pre.004-fix.003` compose donc `Targets` devant le `Vec` des sinks avec `Layer::and_then`; le filtre redevient global pour tout le groupe de sorties sans utiliser `with_filter`/`Filtered`. La validation de `pre.004-fix.003` confirme que tous les tests workspace passent, y compris le takeover externe et le fichier non bloquant, mais `cargo clippy --workspace --all-targets` signale encore `vec_init_then_push` dans la construction du composite reloadable. `pre.004-fix.004` applique uniquement cette correction de forme sans modifier le comportement runtime.
+`pre.003-fix.001` a été validé dans l'environnement de développement avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres sur la version Cargo `0.1.2-pre.3.fix.1`. `pre.004` ajoute `tracing-appender`, remplace la console synchrone par un writer non bloquant, introduit le fichier `Never/Hourly/Daily`, possède les `WorkerGuard`, expose des compteurs cumulés de dropped lines, déporte le stripping ANSI côté worker fichier et conserve le hot reload transactionnel des sinks. `pre.004-fix.001` a rendu explicite le retrait des anciens layers avant leurs `WorkerGuard`, mais la validation utilisateur après `cargo clean` a reproduit exactement le même échec du marqueur fichier. Cette seconde validation a invalidé l'hypothèse selon laquelle ce défaut précis provenait du drain. La cause réelle est la sanitization ANSI native de `tracing-subscriber 0.3.23`, activée par défaut dans `fmt::Layer` : elle transforme les séquences de contrôle présentes dans les valeurs avant qu'elles n'atteignent le writer. `pre.004-fix.002` la conserve pour la console mais la désactive sur le formatter fichier afin que le `StripAnsiWriter` KSP, placé côté worker, reçoive les séquences ANSI originales et les supprime réellement. Le lifecycle explicite de `fix.001` est conservé car il reste correct pour le retrait des sinks non bloquants. La validation de `pre.004-fix.002` confirme ensuite que l'écriture fichier et le stripping ANSI fonctionnent, mais révèle que le target externe `sqlx` est encore persisté. La cause est la composition du filtre global comme enfant frère des formatters dans un `Vec<Layer>` : le `Vec` agrège l'intérêt de callsite en conservant l'intérêt le plus élevé de ses enfants, de sorte qu'un formatter intéressé peut masquer le `Interest::never()` du `Targets`. `pre.004-fix.003` compose donc `Targets` devant le `Vec` des sinks avec `Layer::and_then`; le filtre redevient global pour tout le groupe de sorties sans utiliser `with_filter`/`Filtered`. La validation de `pre.004-fix.003` confirme que tous les tests workspace passent, y compris le takeover externe et le fichier non bloquant, mais `cargo clippy --workspace --all-targets` signale encore `vec_init_then_push` dans la construction du composite reloadable. `pre.004-fix.004` applique uniquement cette correction de forme sans modifier le comportement runtime. La validation utilisateur finale de `pre.004-fix.004` sur `0.1.2-pre.4.fix.4` confirme `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres ; le test runtime global passe avec takeover, fichier non bloquant, stripping ANSI et hot reload. Le graphe Cargo exécuté durant `pre.004` ne présentait aucun doublon et aucune activation KSP de `tracing-attributes`, `tracing-log`, `env-filter`, JSON/Serde ou ANSI formatter ; les dépendances n'ayant pas changé depuis, `pre.005` doit néanmoins refaire ces commandes avant validation de tranche.
 
 ## Base auditée
 
@@ -964,7 +964,7 @@ Le runtime reloadable reste fondé sur un `Vec<Box<dyn Layer<Registry>>>` placé
 
 ### `0.1.2-pre.004` — non-blocking console/fichier + guards + ANSI + reload sinks
 
-Statut : implémenté, validations Cargo à exécuter.
+Statut : validé après `pre.004-fix.004`. Les validations utilisateur `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` sont propres sur `0.1.2-pre.4.fix.4`.
 
 Réalisé :
 
@@ -986,15 +986,33 @@ La saturation déterministe des queues, les reloads concurrents et l'audit compl
 
 ### `0.1.2-pre.005` — intégration + concurrence + tests + audits
 
-Objectifs :
+Statut : implémenté dans le delta `pre.005`, validations Cargo à exécuter.
 
-- compléter les tests settings/filtering/takeover/spans/runtime/reload ;
-- tester les reloads concurrents et l'absence de deadlock/panic ;
-- vérifier que les crates de fixture n'utilisent pas directement `tracing` ;
-- auditer les réexports crate-root ;
-- auditer la documentation de crate (`README.md`, `TODO.md`, `USAGE.md`) ;
-- exécuter les audits Cargo/features/doublons et scripts réellement présents ;
-- mesurer l'overhead grossier de la stratégie reload afin d'éviter une architecture inutilement coûteuse.
+Réalisé :
+
+- la construction `NonBlockingBuilder` de production est centralisée afin que le test unitaire puisse réutiliser exactement `lossy(true)` sans exposer la taille de queue dans `LoggingSettings` ;
+- un test de saturation déterministe utilise une queue de capacité 1 et un writer worker volontairement bloqué : le producer doit terminer sous timeout et `ErrorCounter::dropped_lines()` doit devenir non nul, ce qui détecterait une régression vers la backpressure ;
+- le test runtime global lance quatre producteurs façade KSP pendant 32 reloads alternant runtime silencieux et console présente avec niveau `Off`, afin d'exercer concurrence, création/retrait de workers et reload sans produire de bruit console ;
+- un test d'intégration de lifecycle span capture le formatter `New | Close` et vérifie la présence de `time.busy` et `time.idle` ;
+- un test d'ownership parcourt les crates workspace autres que Logging et refuse les dépendances directes `tracing`, `tracing-subscriber`, `tracing-appender` ainsi que leurs usages Rust directs ;
+- `README.md`, `USAGE.md` et `TODO.md` sont introduits dans la crate avec la responsabilité, les frontières, l'initialisation/reload, les spans sync/async et les capacités différées ;
+- un test diagnostic ignoré compare un subscriber local fixe à la même couche placée derrière `reload::Layer`; il utilise un garde-fou volontairement très large contre une régression grossière et doit être exécuté explicitement avec `cargo test -p ksp-logging-lib --test overhead -- --ignored --nocapture` ;
+- aucun nouveau backend, setting public, format ou dépendance n'est introduit dans cette tranche.
+
+Validations attendues avant clôture de `pre.005` :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-logging-lib --test overhead -- --ignored --nocapture
+cargo tree -p ksp-logging-lib
+cargo tree -p ksp-logging-lib -d
+cargo tree -p ksp-logging-lib -e features
+```
+
+Aucun répertoire `scripts/` n'était présent dans la base stable `0.1.1`; aucun audit script historique n'est donc déclaré exécuté par anticipation. Si un script existe dans le dépôt de développement au moment de la validation, il doit être exécuté selon les règles générales.
 
 ### `0.1.2-pre.006` — validation finale + docs + cleanup + prompt 0.1.3
 
@@ -1057,7 +1075,7 @@ 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.004`
+## Questions ouvertes après `pre.005`
 
 Les deux questions d'API propres à `pre.002` sont résolues :
 
@@ -1066,10 +1084,10 @@ Les deux questions d'API propres à `pre.002` sont résolues :
 
 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. Le takeover `Targets` est composé avec `Layer::and_then` devant le `Vec` des sinks afin que son `Interest::never()` gouverne réellement tout le groupe de sorties ; les layers de sortie reloadables ne sont pas des `Filtered` remplacés directement. Pour les changements de sinks, `pre.004-fix.001` utilise `Handle::modify` afin de récupérer le `Vec` retiré : les anciens layers sont détruits avant les `WorkerGuard` correspondants, ce qui fixe explicitement le lifecycle de drain des writers non bloquants. `pre.004-fix.002` distingue en outre la sanitization des valeurs : activée côté console, désactivée côté formatter fichier car le `StripAnsiWriter` KSP possède la responsabilité de suppression avant persistence. `pre.004-fix.003` ferme enfin la fuite des targets externes révélée par le test d'intégration fichier.
 
-Restent à confirmer par les prereleases suivantes sans remettre en cause ce contrat :
+`pre.005` ferme les deux points de robustesse restants de `pre.004` : la saturation est testée avec le builder de production et une queue bornée injectée uniquement dans le test ; la concurrence/reload est exercée par quatre producteurs pendant des reconfigurations répétées. Le probe d'overhead existe désormais comme test diagnostic explicitement ignoré par défaut.
 
-1. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public ;
-2. la stratégie de test déterministe de saturation des queues avec writer injecté, sans exposer la taille de queue dans `LoggingSettings` ;
-3. les mesures d'overhead et tests de concurrence/reload prévus pour `pre.005`.
+Reste à confirmer pendant la validation finale sans remettre en cause le contrat :
 
-La prochaine action après validation de `pre.004` est `0.1.2-pre.005` : intégration, concurrence, saturation déterministe, audits de façade/dépendances/features et mesure grossière de l'overhead de reload.
+1. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public.
+
+La prochaine action après validation de `pre.005` est `0.1.2-pre.006` : validation finale, documentation/cleanup, synchronisation des points d'entrée et préparation du prompt `0.1.3 — ksp-config-lib`.