v0.1.2-pre.002

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: 2 -->
+<!-- version: 3 -->
 
 # Plan KSP 0.1.2 — Logging foundation
 
 ## Statut
 
-Plan actif de `0.1.2`, établi par `0.1.2-pre.001` et corrigé par `0.1.2-pre.001-fix.001`.
+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`.
 
-`pre.001` et son fix restent une tranche de brainstorming, audit et planification. Aucun développement fonctionnel de `ksp-logging-lib` n'est commencé avant validation de ce plan corrigé.
+`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.
 
 ## Base auditée
 
@@ -93,13 +93,13 @@ tracing-appender    0.2.5    MSRV annoncé : rustc 1.63+
 
 Ces exigences restent inférieures au MSRV déjà imposé indirectement par la génération Solana retenue dans `0.1.1` (`solana-pubkey 4.3.0` / workspace Solana SDK auditée à Rust 1.89.0). Logging ne relève donc pas le plancher observé du workspace.
 
-Les versions doivent néanmoins être revérifiées au moment exact de leur ajout effectif au manifest.
+Les versions sont revérifiées au moment exact de leur ajout effectif au manifest. Pour `pre.002`, `tracing` reste à `0.1.44`, publié dans la génération `^0.1`; `tracing-subscriber` et `tracing-appender` ne sont pas encore ajoutés.
 
 ### `tracing`
 
 `tracing 0.1.44` active par défaut `attributes` et `std` ; la feature `attributes` tire `tracing-attributes`.
 
-La première surface KSP n'utilise ni `#[instrument]` ni autre macro attribut procédurale. La dépendance candidate est donc :
+La première surface KSP n'utilise ni `#[instrument]` ni autre macro attribut procédurale. `pre.002` retient donc :
 
 ```toml
 tracing = { version = "^0.1", default-features = false, features = ["std"] }
@@ -147,9 +147,9 @@ tracing-appender = { version = "^0.2", default-features = false }
 
 ### Politique d'ajout au manifest
 
-Aucune de ces trois dépendances n'est ajoutée par `pre.001`, car aucun code de `ksp-logging-lib` ne les consomme encore.
+`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`.
 
-Elles seront ajoutées sous `[workspace.dependencies]` uniquement dans la prerelease qui les utilise effectivement, puis héritées dans `crates/ksp-logging-lib/Cargo.toml` avec `.workspace = true`.
+`tracing-subscriber` et `tracing-appender` restent absents jusqu'aux prereleases qui utilisent effectivement leurs APIs.
 
 Après chaque ajout réel :
 
@@ -429,7 +429,7 @@ FileRotation
 
 Aucun `Default` implicite de `LoggingSettings` n'est requis dans la première surface.
 
-Le caller choisit explicitement son niveau KSP global et ses sorties. Le niveau global des targets externes reste `Off` par politique et n'est pas rendu configurable dans cette première surface.
+Le caller choisit explicitement son niveau KSP global et ses sorties. Une configuration sans console ni fichier est valide et représente un logging KSP désactivé. Le niveau global des targets externes reste `Off` par politique et n'est pas rendu configurable dans cette première surface.
 
 `ConsoleSettings` pourra offrir des constructeurs explicites `stdout()` / `stderr()` si cela simplifie l'API sans ambiguïté.
 
@@ -437,7 +437,6 @@ Le caller choisit explicitement son niveau KSP global et ses sorties. Le niveau
 
 `initialize()` et `reinitialize()` doivent refuser au minimum :
 
-- une configuration sans aucune sortie active ;
 - un préfixe de target vide ;
 - un override de target qui ne correspond pas à la convention KSP retenue ;
 - un préfixe de fichier vide si le backend retenu ne peut pas le traiter sans ambiguïté.
@@ -708,7 +707,7 @@ La feature `tracing-log` de `tracing-subscriber` n'est pas activée.
 
 Cette décision participe au takeover : KSP ne cherche pas à aspirer automatiquement le bruit de dépendances instrumentées avec la crate `log`. Une information utile est réémise explicitement par la crate KSP propriétaire sous son propre target.
 
-## API publique candidate
+## API publique
 
 La façade crate-root visée à la fin de la release est :
 
@@ -728,7 +727,8 @@ ksp_logging_lib::trace_span!
 ksp_logging_lib::LogFilterLevel
 ksp_logging_lib::TargetFilter
 ksp_logging_lib::SpanEvents
-ksp_logging_lib::<KSP span abstraction/helpers>
+ksp_logging_lib::Span
+ksp_logging_lib::instrument
 ksp_logging_lib::ConsoleOutput
 ksp_logging_lib::ConsoleSettings
 ksp_logging_lib::FileRotation
@@ -741,9 +741,9 @@ ksp_logging_lib::reinitialize
 ksp_logging_lib::<ErrorCode constants owned by Logging>
 ```
 
-Les noms exacts de l'abstraction de span et de l'API d'instrumentation async sont figés pendant l'implémentation après tests de callsite/type leakage.
+`pre.002` fixe l'abstraction de span publique à `ksp_logging_lib::Span`. `Span::in_scope(...)` couvre les scopes synchrones et `ksp_logging_lib::instrument(span, future)` retourne une `Future` opaque instrumentée sans demander au consumer d'importer `tracing::Span` ou `tracing::Instrument`.
 
-Les modules d'implémentation restent privés. Les types externes `tracing*` ne deviennent pas le contrat public KSP.
+Les macros utilisent un bridge `tracing` caché de la documentation uniquement pour permettre leur expansion depuis une crate consommatrice tout en conservant le callsite réel. Ce bridge est un détail d'implémentation réservé aux macros et ne constitue pas une API KSP consommable. Les modules d'implémentation restent privés.
 
 Arborescence candidate :
 
@@ -905,6 +905,8 @@ Objectifs :
 
 ### `0.1.2-pre.002` — crate + settings + façade événements/spans
 
+Statut : implémenté dans la tranche `pre.002`, sous réserve des validations Cargo à exécuter dans l'environnement de développement.
+
 Objectifs :
 
 - créer `crates/ksp-logging-lib` et l'ajouter au workspace ;
@@ -1013,17 +1015,17 @@ 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.001-fix.001`
+## Questions ouvertes après `pre.002`
 
-Aucune question architecturale bloquante ne justifie du développement fonctionnel dans `pre.001`.
+Les deux questions d'API propres à `pre.002` sont résolues :
 
-Restent à confirmer par implémentation/tests sans remettre en cause le contrat :
+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.
 
-1. le mécanisme Rust exact des macros KSP événements/spans qui préserve le callsite et masque les types `tracing` ;
-2. la forme exacte de l'abstraction KSP permettant d'instrumenter proprement les futures async ;
-3. 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 ;
-4. l'API publique exacte d'observation des dropped lines ;
-5. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public.
+Restent à confirmer par les prereleases runtime sans remettre en cause ce contrat :
 
+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.
 
-La prochaine action après validation de ce plan est `0.1.2-pre.002`, pas l'ouverture de Config.
+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.

docs/rules/RULES_DEPENDENCIES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_DEPENDENCIES.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->
 
 # Règles des dépendances KSP
 
@@ -51,6 +51,7 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
 - **DEP-LOG-006** — Le subscriber KSP rend silencieux par défaut les targets externes ; une information tierce utile est réémise explicitement par la crate KSP propriétaire sous son propre target au lieu de renommer/réécrire l'événement tiers.
 - **DEP-LOG-007** — Une application/framework peut exceptionnellement intégrer directement un plugin/dépendance tracing imposé par son framework, notamment Tauri, sans créer une seconde politique de logging parallèle à `ksp-logging-lib`; les événements KSP restent émis via la façade KSP.
 - **DEP-LOG-008** — `ksp-logging-lib` possède ses settings runtime et son hot reload ; `ksp-config-lib` peut plus tard construire ces settings et demander une reconfiguration sans créer de dépendance inverse Logging -> Config.
+- **DEP-LOG-009** — Tout bridge `tracing` public mais caché de la documentation rendu techniquement nécessaire par l’expansion des macros de `ksp-logging-lib` est un détail d’implémentation réservé à ces macros ; une crate consommatrice ne l’utilise jamais directement et reste limitée à la façade KSP documentée.
 
 ## Program / Execution