# Delta 0.1.2-pre.001-fix.001 ## Base requise Livraison précédente : ```text 0.1.2-pre.001 ``` Ce correctif est documentaire et corrige le plan de `pre.001` sans réécrire son delta historique. ## Objectif Corriger le cadrage Logging avant validation du plan afin de fixer : - le takeover complet du logging/tracing KSP par `ksp-logging-lib` ; - le target KSP explicite égal au nom Cargo de la crate propriétaire ; - le silence par défaut des targets tiers et la réémission explicite des informations utiles par le composant KSP propriétaire ; - console et fichier non bloquants avec guards et compteurs de lignes abandonnées ; - le stripping ANSI des fichiers ; - un `initialize` global unique suivi d'un hot reload via `reinitialize` sans second subscriber global ; - une surface de spans KSP synchrones et async avec diagnostic de durée `NEW/CLOSE`, `busy` et `idle` ; - la responsabilité des données loggées au caller, sans détection/redaction automatique par Logging. Aucun développement fonctionnel de `ksp-logging-lib` n'est introduit par ce fix. ## Décisions prises ### Takeover tracing `ksp-logging-lib` devient le seul propriétaire KSP direct de la stack tracing et la seule façade autorisée pour les événements/spans KSP. Le subscriber applique une politique de takeover : ```text external targets = Off by default ksp-* targets = configured KSP default specific ksp-* = optional override ``` KSP ne renomme pas un événement tiers. Lorsqu'un détail provenant d'une dépendance externe est utile, la crate KSP propriétaire le réémet sous son propre target. Exemple attendu pour Store : les logs SQLx natifs sont désactivés/silencieux ; les opérations SQL utiles sont journalisées explicitement par `ksp-store-lib`, typiquement au niveau `trace`. ### Targets Les macros événements et spans exigent un target explicite correspondant au nom Cargo de la crate propriétaire. `domain`, `component` et autres fields restent des subdivisions structurées, pas des remplacements du target. ### Settings runtime `LoggingSettings` reste propriétaire de Logging et indépendant de Config. Il couvre niveau KSP default, overrides de target, sorties console/fichier et politique d'événements de spans. Une future `ksp-config-lib` pourra construire ces settings puis appeler la façade Logging. ### Non-blocking Console et fichier utilisent des writers non bloquants avec leurs `WorkerGuard` possédés par `LoggingGuard`. Le mode retenu privilégie l'absence de backpressure sur le hot path : une saturation peut abandonner des lignes. Les `ErrorCounter` sont conservés afin que ces pertes restent observables. ### Stripping ANSI Les fichiers passent par un stripping ANSI générique avant persistence. Logging ne dépend pas de Tauri ; cette protection évite seulement de persister des séquences de terminal déjà présentes dans les données écrites. ### Initialisation et hot reload `initialize(settings)` installe le subscriber global une seule fois et retourne `LoggingGuard`. Après succès, `reinitialize(&mut guard, settings)` ou une méthode équivalente peut être appelée 0..N fois. Elle ne réinstalle pas le subscriber global ; elle modifie les filters/layers/sinks de l'infrastructure déjà installée. Le reload vise une sémantique transactionnelle : une nouvelle configuration invalide ou impossible à construire laisse l'ancienne configuration active. Le mécanisme interne exact (`tracing_subscriber::reload` ciblé ou routing KSP dynamique) sera choisi par implémentation/tests selon correction et overhead, sans modifier le contrat public. ### Spans sync/async et durée `0.1.2` inclut désormais une surface de spans KSP par niveau, sans dépendance directe `tracing` dans les crates consommatrices. Le code sync doit pouvoir exécuter un scope dans un span. Le code async doit instrumenter la `Future` elle-même et ne pas maintenir un enter guard à travers `.await`. Les settings permettent au minimum `Off` et `NewAndClose`; `NEW | CLOSE` fournit des repères de début/fin et, lorsque les timestamps sont actifs, le close fournit `busy`/`idle`. Cette capacité sert au diagnostic rapide de latence/blocage et n'est pas présentée comme un benchmark de précision absolue. ### Contenu sensible `ksp-logging-lib` n'essaie pas de détecter ou redacter automatiquement les données sensibles. La crate appelante est responsable du contenu qu'elle choisit de logger. ## Fichiers ajoutés - `deltas/0.1.2/pre.001-fix.001.md` ## Fichiers modifiés - `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md` - `docs/rules/RULES_DEPENDENCIES.md` - `docs/architecture/003-COMPONENT_CONTRACTS.md` - `docs/architecture/005-DEPENDENCY_GRAPH.md` ## Fichiers supprimés Aucun. ## Version Cargo Aucune modification de `Cargo.toml`. Ce fix est limité à la documentation et respecte `VER-ID-008` : `workspace.package.version` reste donc : ```text 0.1.2-pre.1 ``` L'identifiant de livraison est : ```text 0.1.2-pre.001-fix.001 ``` ## Validations exécutées - vérification du delta `pre.001` fourni et des règles de version/delta/archive de la base `0.1.1` ; - vérification de la documentation officielle `tracing` indiquant que le subscriber global ne peut être installé qu'une fois ; - vérification de `tracing-subscriber::reload` pour le remplacement runtime d'une Layer/Filter ; - vérification de l'avertissement officiel contre `Span::enter()` conservé à travers `.await` ; - vérification de l'instrumentation de `Future` fournie par `tracing::Instrument` ; - vérification de `FmtSpan::NEW | FmtSpan::CLOSE` et des champs `busy`/`idle` au close lorsque les timestamps sont actifs ; - vérification du writer non bloquant, de `WorkerGuard` et `ErrorCounter` dans `tracing-appender 0.2.5` ; - contrôle des headers `file:` / `version:` des fichiers livrés ; - contrôle de l'absence de modification Cargo dans ce fix documentaire ; - contrôle du contenu de l'archive selon `VER-ARCHIVE-004`. ## Validations non exécutées Aucune validation Cargo n'est applicable à ce correctif documentaire et aucun code fonctionnel Logging n'existe encore dans la livraison. Les commandes suivantes restent à exécuter dès que les tranches de développement les rendent 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 ``` ## Questions ouvertes Aucune question architecturale bloquante. Restent à trancher par implémentation/tests dans les prereleases suivantes : - mécanisme exact des macros spans/events préservant le callsite sans fuite de types `tracing` ; - abstraction KSP exacte pour instrumenter les futures async ; - composition reloadable interne la moins coûteuse ; - API exacte d'observation des dropped lines. Après validation de ce fix, la prochaine tranche reste `0.1.2-pre.002`.