v0.1.4-pre.016

crates/ksp-logging-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-logging-lib/USAGE.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Utilisation de ksp-logging-lib
 
@@ -92,6 +92,52 @@ let mut logging_guard = match initialize_result {
 
 Une configuration sans output actif est valide et installe une infrastructure initialement silencieuse qui pourra être activée plus tard par hot reload.
 
+
+
+## Identité de lancement et isolation des fichiers persistants
+
+Une application qui utilise des sorties fichiers persistantes peut attacher une identité stable au runtime :
+
+```rust
+let identity = ksp_logging_lib::LoggingRuntimeIdentity::new(
+    "ksp-app-config-desk",
+    "20260816-182519.123Z-p4242",
+);
+let identity = match identity {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+let initialize_result = ksp_logging_lib::initialize_with_identity(&settings, &identity);
+let mut logging_guard = match initialize_result {
+    std::result::Result::Ok(guard) => guard,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+Les composants de l'identité n'acceptent que des caractères ASCII alphanumériques et `._-`; les séparateurs de path et espaces sont refusés.
+
+Si un `FileSettings` configure `ksp-debug.log`, l'identité ci-dessus produit un prefix runtime :
+
+```text
+ksp-app-config-desk.20260816-182519.123Z-p4242.ksp-debug.log
+```
+
+Le `FileSettings` d'origine reste `ksp-debug.log`. `reinitialize(&mut logging_guard, ...)` réutilise automatiquement l'identité stockée dans le guard : un hot reload ne crée donc pas une fausse nouvelle identité de lancement.
+
+Les outputs réellement actifs sont inspectables sans exposer les writers :
+
+```rust
+for file in logging_guard.active_file_outputs() {
+    let output_id = file.output_id();
+    let directory = file.directory();
+    let prefix = file.file_name_prefix();
+    let rotation = file.rotation();
+}
+```
+
+`initialize()` reste disponible pour les consommateurs qui n'ont pas besoin d'identité de lancement. `initialize_with_identity()` est la forme attendue pour les applications KSP qui activent des logs persistants et doivent empêcher la fusion de plusieurs lancements dans le même fichier.
+
 ## Construction d'un runtime multi-output
 
 Le runtime peut activer plusieurs sorties ayant des formats et filtres niveau/target/domain distincts :