v0.1.2-pre.006

docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md

@@ -1,11 +1,11 @@
 <!-- file: docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->
 
 # 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é 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.005-fix.001` corrige uniquement la pollution console du stress test concurrent : le runtime est désormais placé sur la configuration console silencieuse avant la libération des producteurs, puis les 32 reloads concurrents restent inchangés.
+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` a fermé 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.005-fix.001` a supprimé la pollution console du stress test concurrent sans réduire la pression de reload. `pre.006` est la prerelease finale : elle ajoute une validation async sur executor Tokio réel uniquement en dev-dependency, consolide la documentation durable et prépare le prompt `0.1.3 — ksp-config-lib`.
 
 `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.
 
@@ -986,7 +986,7 @@ La saturation déterministe des queues, les reloads concurrents et l'audit compl
 
 ### `0.1.2-pre.005` — intégration + concurrence + tests + audits
 
-Statut : implémenté dans le delta `pre.005`, validations Cargo à exécuter.
+Statut : validé après `pre.005-fix.001`. 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.5.fix.1`. Le probe d'overhead ignoré a également été exécuté explicitement sur 200000 itérations et a passé son garde-fou grossier (`baseline=19.658553ms`, `reload=28.807958ms`).
 
 Réalisé :
 
@@ -999,32 +999,41 @@ Réalisé :
 - 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` :
+Les validations de `pre.005-fix.001` sont closes. 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 finale, 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
+
+Statut : implémenté dans le delta `pre.006`, validations Cargo finales à exécuter dans l'environnement de développement.
+
+Réalisé :
+
+- Tokio est centralisé dans `[workspace.dependencies]` sous `^1.53` avec uniquement `rt`, `rt-multi-thread` et `macros` ;
+- `ksp-logging-lib` le consomme uniquement sous `[dev-dependencies]`, de sorte que son API/runtime de production reste executor-agnostic ;
+- un test `#[tokio::test(flavor = "current_thread")]` instrumente une vraie future comportant plusieurs `yield_now().await` et vérifie plusieurs couples `enter/exit`, ce qui confirme la ré-entrée du span à chaque reprise réelle de polling ;
+- un test `#[tokio::test(flavor = "multi_thread", worker_threads = 2)]` exécute deux futures instrumentées via `tokio::spawn`, avec suspensions répétées, et vérifie leur terminaison ainsi que l'équilibre `enter/exit` ;
+- la documentation de crate précise que Tokio est un outil de test uniquement et n'est pas imposé aux consumers ;
+- le TODO final est ramené aux validations `pre.006`, au contrôle du graphe normal/dev et à la future livraison `rel.001` ;
+- le prompt `prompts/003-V0_1_3_START_PROMPT.md` est préparé pour ouvrir Config après la stable `v0.1.2`, avec relation Config -> `LoggingSettings`, profils/default_profile, env namespaces et politique secrets/public/debug ;
+- l'index des prompts est synchronisé ;
+- aucun changelog général n'existe actuellement dans le dépôt, donc aucun fichier de ce type n'est créé artificiellement en clôture.
+
+Validations finales attendues :
 
 ```bash
 cargo fmt --all
 cargo check --workspace
-cargo test --workspace
+cargo build -p ksp-logging-lib
 cargo clippy --workspace --all-targets
+cargo test --workspace
 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
+cargo tree -p ksp-logging-lib -e normal
+cargo tree -p ksp-logging-lib -e dev
 ```
 
-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
-
-Objectifs :
-
-- exécuter les validations workspace finales ;
-- fermer les écarts résiduels ;
-- consolider la documentation durable ;
-- synchroniser roadmap/index/changelog général s'il existe alors ;
-- nettoyer/archive uniquement ce que les règles demandent ;
-- préparer le prompt final `0.1.3 — ksp-config-lib` en documentant la conversion Config -> `LoggingSettings` et le hot reload ;
-- préparer la livraison finale avant `rel.001` et tag stable.
+Le contrôle spécifique de cette tranche est que Tokio soit visible dans le graphe dev des tests mais absent du graphe normal de `ksp-logging-lib`.
 
 Le découpage reste souple. Une tranche trop large est scindée ; une tranche devenue inutile est supprimée par correction explicite du plan.
 
@@ -1060,6 +1069,7 @@ La release peut être stabilisée lorsque :
 - les crates comportementales de test utilisent exclusivement la façade KSP pour événements et spans ;
 - les cinq macros événements fonctionnent avec target KSP explicite et callsite réel ;
 - la surface de spans sync/async fonctionne sans exposer une dépendance `tracing` directe aux consumers ;
+- l'instrumentation async est validée sur un executor réel current-thread et multi-thread sans ajouter d'executor aux dépendances runtime de Logging ;
 - `NEW | CLOSE` permet d'obtenir rapidement début/fin et temps busy/idle lorsque demandé ;
 - les settings sont indépendants de Config ;
 - les targets externes sont silencieux par défaut et les détails utiles sont réémis explicitement par leur propriétaire KSP ;
@@ -1075,7 +1085,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.005`
+## Questions ouvertes après `pre.006`
 
 Les deux questions d'API propres à `pre.002` sont résolues :
 
@@ -1084,10 +1094,8 @@ 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.
 
-`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.
+`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. `pre.006` complète cette couverture par deux tests Tokio réels sans faire de Tokio une dépendance runtime de Logging.
 
-Reste à confirmer pendant la validation finale sans remettre en cause le contrat :
+Aucune question architecturale bloquante ne reste ouverte pour la stable `0.1.2`. Le détail visuel exact du formatter humain reste volontairement non contractuel : sa ponctuation peut évoluer ultérieurement tant que les informations et garanties publiques documentées sont préservées.
 
-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`.
+La prochaine action après validation de `pre.006` est la livraison `0.1.2-rel.001`, le passage de `workspace.package.version` à `0.1.2`, les validations de publication puis le tag stable `v0.1.2`. La session fonctionnelle suivante est `0.1.3 — ksp-config-lib` avec le prompt `prompts/003-V0_1_3_START_PROMPT.md`.