# Plan KSP 0.1.2 — Logging foundation ## Statut Plan actif de `0.1.2`, établi par `0.1.2-pre.001`. `pre.001` reste une tranche de brainstorming, audit et planification. Aucun développement fonctionnel de `ksp-logging-lib` n'est commencé avant validation de ce plan. ## Base auditée Base fournie : ```text 0.1.1 stable ``` Constats sur l'archive `khadhroony-solana-project-v0.1.1.zip` reçue : - `workspace.package.version = "0.1.1"` ; - le workspace contient uniquement `crates/ksp-core-lib` ; - `ksp-logging-lib` n'existe pas encore ; - `ksp-core-lib` expose déjà `ErrorCode`, `ErrorContext`, `Error`, `Result` et `Pubkey` ainsi que les Program IDs fondamentaux et leur registre ; - `ksp-core-lib` dépend uniquement de `solana-pubkey` au runtime ; - le delta final `deltas/0.1.1/rel.001.md` enregistre la validation finale de `0.1.1` ; - le prompt `prompts/002-V0_1_2_START_PROMPT.md` présent dans la base ouvre bien la release Logging. Dans le workflow KSP, l'archive fournie provient directement du tag Gitea correspondant et constitue la base stable/taguée `v0.1.1` attendue. L'absence normale de `.git` dans l'archive ne crée pas une vérification Git supplémentaire pour cette session. ## Mission bornée `0.1.2` introduit `ksp-logging-lib` comme façade KSP commune de logging/tracing et propriétaire de la politique runtime correspondante. La release doit fournir : 1. une surface d'émission KSP pour `error`, `warn`, `info`, `debug` et `trace` ; 2. des settings runtime propres à Logging, indépendants de Config ; 3. une initialisation globale déterministe ; 4. une sortie console ; 5. une sortie fichier optionnelle avec rotation bornée et writer non bloquant ; 6. un filtrage global et par préfixe de `target` ; 7. un lifecycle explicite conservant les guards nécessaires aux writers non bloquants ; 8. un contrat d'erreurs basé sur `ksp-core-lib` ; 9. une politique documentée contre les fuites de secrets ; 10. les tests de callsite, settings, filtering, initialisation, fichiers et façade publique nécessaires à la stabilisation. La release ne lit aucun document JSON/TOML et n'introduit aucune dépendance vers Config ou une couche supérieure. ## Frontière de propriété La frontière retenue reste : ```text ksp-logging-lib -> ksp-core-lib -> tracing -> tracing-subscriber -> tracing-appender ``` Règles : - `ksp-logging-lib` est le seul propriétaire KSP de l'initialisation et de la politique de subscriber/appender ; - `ksp-core-lib` ne dépend pas de Logging ; - `ksp-logging-lib` ne dépend pas de `ksp-config-lib` ; - `ksp-logging-lib` ne dépend pas de Wallet, Transport, Program, Store, workers, jobs, pipelines ou applications ; - les crates comportementales KSP peuvent plus tard dépendre directement de `ksp-logging-lib` ; - les crates `*-api` purement déclaratives restent sans Logging par défaut ; - une future intégration Tauri imposée par un plugin reste un adaptateur d'application et ne redéfinit pas la politique KSP. ## Audit de la stack `tracing` au 2026-08-14 L'audit a été réalisé à partir des publications/docs officielles Tokio `tracing` et des manifests publiés sur docs.rs/crates.io. ### Versions observées ```text tracing 0.1.44 MSRV annoncé : rustc 1.65+ tracing-subscriber 0.3.23 MSRV annoncé : rustc 1.65+ 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. ### `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 : ```toml tracing = { version = "^0.1", default-features = false, features = ["std"] } ``` Aucune feature `attributes`, `log`, `valuable` ou filtre compile-time n'est activée par anticipation. ### `tracing-subscriber` `tracing-subscriber 0.3.23` active par défaut notamment `ansi`, `fmt`, `smallvec`, `std` et `tracing-log`. La première surface KSP a besoin de `fmt`, qui entraîne déjà `registry` et `std`. Elle n'a pas de besoin concret pour : - `ansi` ; - `tracing-log` ; - `env-filter` ; - `json` ; - `chrono` ; - `time` ; - `local-time` ; - `serde` ; - `parking_lot`. La dépendance candidate est donc : ```toml tracing-subscriber = { version = "^0.3", default-features = false, features = ["fmt"] } ``` Le filtrage initial utilisera `tracing_subscriber::filter::Targets`, disponible sans `env-filter` et conçu pour les niveaux par préfixe de target. ### `tracing-appender` `tracing-appender 0.2.5` n'active aucune feature par défaut et ne propose qu'une feature optionnelle `parking_lot`. Son manifest publié dépend déjà de `tracing-subscriber` avec `default-features = false` et `features = ["fmt", "std"]`. Il tire également les dépendances nécessaires à son appender, notamment `crossbeam-channel`, `time`, `symlink` et `thiserror`. Aucun besoin de `parking_lot` n'est identifié. La dépendance candidate est donc : ```toml 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. 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`. Après chaque ajout réel : ```bash cargo tree -p ksp-logging-lib cargo tree -p ksp-logging-lib -d cargo tree -p ksp-logging-lib -e features ``` sera utilisé pour vérifier la résolution et l'unification réelles. ## Instrumentation : macros pour préserver le callsite ### Décision Les cinq points d'émission publics seront des macros KSP : ```text ksp_logging_lib::error! ksp_logging_lib::warn! ksp_logging_lib::info! ksp_logging_lib::debug! ksp_logging_lib::trace! ``` Une fonction wrapper qui appellerait elle-même `tracing::info!` ou équivalent déplacerait les métadonnées source vers le wrapper. Les événements ne seront donc pas émis par des fonctions publiques de ce type. Les macros KSP resteront minces et délégueront aux macros `tracing` au point d'appel. Leur implémentation exacte — wrapper `macro_rules!` transparent ou réexport suffisamment direct — sera choisie par le plus petit mécanisme qui réussit les tests de callsite sans exposer une seconde API `tracing` aux consommateurs. ### Syntaxe La surface doit conserver une syntaxe structurée proche de `tracing` plutôt que créer une grammaire KSP parallèle. Exemple conceptuel : ```rust ksp_logging_lib::info!( target: "ksp.wallet", domain = "wallet", component = "repository", slot = slot, "wallet state updated" ); ``` Les tests publics fixeront uniquement la syntaxe réellement retenue avant stabilisation. ### Callsite à tester Un test d'intégration extérieur au `src` doit capturer les `Metadata` d'un événement émis par une macro KSP et vérifier au minimum : - le fichier source est celui du consommateur/test et non un fichier de `ksp-logging-lib` ; - le module path correspond au consommateur ; - le numéro de ligne correspond à l'invocation ; - le target implicite reste celui du callsite/module lorsque le caller n'en fournit pas ; - un `target:` explicite est conservé tel quel. La macro n'est pas considérée stabilisée avant réussite de ce test. ## Niveaux KSP Les cinq niveaux d'événements publics sont exactement : ```text error warn info debug trace ``` Ils correspondent aux niveaux homonymes de `tracing`. Le filtrage a en plus besoin d'un état désactivé. Le plan prévoit un type KSP distinct, conceptuellement : ```text LogFilterLevel Off Error Warn Info Debug Trace ``` `Off` n'est pas un sixième niveau d'événement ; il appartient uniquement au contrat de filtering. Aucun type `tracing::Level` ou `tracing_subscriber::filter::LevelFilter` n'est exposé dans l'API publique KSP. ## `target`, `domain`, `component` et champs structurés ### `target` `target` reste la métadonnée native de routage/filtering de `tracing`. Politique initiale : - sans override, conserver le target naturel correspondant au module/callsite Rust ; - permettre un `target:` statique explicite lorsque le caller a besoin d'une identité de routage durable ; - ne pas imposer dès `0.1.2` une taxonomie globale de targets pour toutes les futures crates ; - filtrer les targets par préfixe. ### `domain` `domain` est un **champ structuré KSP optionnel** décrivant le domaine fonctionnel lorsque cette information ajoute de la valeur. Il n'est pas automatiquement injecté et n'est pas une clé de filtrage dans la première surface. ### `component` `component` est un **champ structuré KSP optionnel** décrivant le composant logique à l'intérieur d'un domaine lorsque nécessaire. Il n'est ni obligatoire ni déduit du nom de crate. ### Autres champs Les callers peuvent émettre d'autres champs structurés utiles au contexte : slot, signature publique, Program ID public, opération, état, compteur, durée, etc., sous réserve de la politique secrets. Aucune liste fermée de champs n'est introduite. ## Filtering retenu ### Première surface Le filtering initial comprend : 1. un niveau global/default ; 2. zéro ou plusieurs overrides par préfixe de target. Exemple conceptuel : ```text default = Info ksp_program_lib = Debug ksp_program_lib::decoder = Trace noisy_dependency = Off ``` La sémantique s'appuiera sur `tracing_subscriber::filter::Targets`. ### Pourquoi pas `EnvFilter` `EnvFilter` permet une syntaxe et un filtrage plus dynamiques, notamment par span/champs, mais active des dépendances/features supplémentaires (`matchers`, `regex-automata`, `once_cell`, etc.). Aucun besoin de cette puissance n'est démontré pour la fondation `0.1.2`. Conséquences : - pas de parsing de `RUST_LOG` par Logging ; - pas de directive textuelle `EnvFilter` dans les settings ; - pas de filtre sur `domain`/`component` en tant que champs ; - pas de reload dynamique du filtre dans cette release. Config pourra ultérieurement convertir sa propre représentation validée vers les settings typés de Logging sans rendre `EnvFilter` public. ## Settings runtime ### Principes Les settings appartiennent à `ksp-logging-lib` et représentent uniquement ce dont son runtime a besoin. Ils ne : - lisent aucun fichier ; - ne consultent aucune variable d'environnement ; - ne connaissent aucun profil Config ; - ne contiennent aucun secret ; - n'exposent aucun type `tracing*` public. Les structures publiques utilisent des champs privés avec constructeurs/getters/builder methods explicites, conformément à la direction déjà utilisée dans Core. ### Surface conceptuelle La surface de `pre.002`/`pre.003` doit rester proche de : ```text LoggingSettings default_filter: LogFilterLevel target_filters: Vec console: Option file: Option TargetFilter target_prefix: String level: LogFilterLevel ConsoleSettings output: ConsoleOutput ConsoleOutput Stdout Stderr FileSettings directory: PathBuf file_name_prefix: String rotation: FileRotation FileRotation Never Hourly Daily ``` Les noms exacts peuvent être ajustés pendant l'implémentation uniquement pour respecter l'ergonomie Rust et les règles du dépôt ; les responsabilités ne doivent pas dériver sans correction du plan. ### Defaults Aucun `Default` implicite de `LoggingSettings` n'est requis dans la première surface. Le caller choisit explicitement son niveau global et ses sorties. Cela évite qu'une application obtienne silencieusement une politique de production non décidée. `ConsoleSettings` pourra offrir des constructeurs explicites `stdout()` / `stderr()` si cela simplifie l'API sans ambiguïté. ### Validation `initialize()` doit refuser au minimum : - une configuration sans aucune sortie active ; - un préfixe de target vide lorsqu'il est fourni comme override ; - un préfixe de fichier vide si le backend retenu ne peut pas le traiter sans ambiguïté. Les autres invariants seront ajoutés uniquement s'ils correspondent à une erreur réelle du backend ou à une ambiguïté de contrat. ## Console La première surface retient une sortie console synchrone via le writer standard choisi : ```text Stdout Stderr ``` Raisons : - aucune thread dédiée n'est nécessaire pour le terminal dans la première fondation ; - l'ownership de `WorkerGuard` reste alors réservé à la sortie fichier non bloquante ; - stdout reste disponible pour les applications qui le souhaitent ; - stderr permet aux futurs exécutables de ne pas mélanger diagnostics et sortie de données sur stdout. Le format initial est un format humain unique, sans JSON ni ANSI obligatoire. Il doit inclure au minimum : - timestamp fourni par le formatter standard retenu ; - niveau ; - target ; - message/champs structurés ; - source file/line lorsque la configuration `fmt` retenue le permet sans dépendance supplémentaire. Le texte exact d'une ligne n'est pas un protocole de sérialisation stable. Les tests doivent contrôler les informations nécessaires, pas figer inutilement tous les espaces/ponctuations du formatter externe. ## Fichiers, rotation et writer non bloquant ### Capacité retenue `0.1.2` retient une sortie fichier **optionnelle** afin que les futurs exécutables/workers disposent d'un backend durable sans réinventer cette responsabilité hors de Logging. La première surface reste volontairement étroite : ```text rotation = Never | Hourly | Daily ``` Sont différés : - rotation minutely/weekly ; - rotation par taille ; - compression ; - politique complexe de rétention ; - symlink `latest` ; - multiples routes fichier indépendantes ; - formats fichier distincts par route. Une limite de rétention pourra être ajoutée ultérieurement si l'exploitation réelle le justifie ; elle ne fait pas partie du contrat `0.1.2`. ### Construction sans panic L'implémentation doit utiliser la forme builder de `RollingFileAppender` qui retourne un `Result` en cas d'échec d'initialisation, et non une API qui panique. L'erreur externe utile est enveloppée dans `ksp_core_lib::Error` et conservée comme `source` lorsque ses bornes le permettent. ### Non-blocking La sortie fichier utilise `tracing_appender::non_blocking::NonBlockingBuilder` afin de déplacer les écritures ordinaires hors du thread appelant. Le mode retenu pour la première surface est **non-lossy** : ```text lossy(false) ``` Ainsi, une saturation de la file applique de la backpressure au lieu de supprimer silencieusement des événements. Cette décision évite d'introduire immédiatement un compteur de lignes perdues et rend le comportement de fiabilité explicite. La taille de file reste celle du backend tant qu'un besoin réel ne justifie pas de l'exposer dans `LoggingSettings`. Si les mesures futures démontrent que cette backpressure est inacceptable pour certains workloads, un mode lossy explicite et observable pourra être ajouté dans une release ultérieure ; il ne doit pas être activé silencieusement. ## Lifecycle et ownership du guard `tracing-appender` retourne un `WorkerGuard` dont la durée de vie contrôle le flush de la file non bloquante. KSP possédera ce guard dans un type public de lifecycle : ```text LoggingGuard ``` Contrat : - `initialize(&LoggingSettings) -> ksp_core_lib::Result` ; - si seule la console est active, `LoggingGuard` reste un objet valide sans worker fichier ; - si le fichier est actif, le guard interne est conservé pendant toute la durée de vie de `LoggingGuard` ; - l'appelant conserve `LoggingGuard` jusqu'à la fin ordonnée du processus ; - sa destruction effectue le flush/shutdown fourni par le `WorkerGuard` ; - aucun `WorkerGuard` n'est stocké dans une variable locale d'initialisation qui serait détruite au retour de `initialize()` ; - aucune fuite volontaire (`mem::forget`, global mutable caché, etc.) n'est utilisée pour prolonger sa durée de vie. Le subscriber global de `tracing` n'est pas désinstallable/restartable comme un service ordinaire. Le lifecycle de `0.1.2` est donc volontairement à sens unique : ```text uninitialized -> initialized -> process shutdown ``` Une destruction anticipée de `LoggingGuard` est considérée comme une fin du backend fichier, pas comme une possibilité de réinitialiser Logging ensuite. ## Initialisation globale ### API La fonction publique principale retenue est conceptuellement : ```rust pub fn initialize(settings: &LoggingSettings) -> ksp_core_lib::Result ``` Elle reste synchrone : installer un subscriber et construire des writers locaux ne constitue pas un workflow I/O async justifiant artificiellement une API `async`. ### Réinitialisation L'installation globale doit utiliser une API fallible (`try_init`/équivalent), jamais `init()` lorsqu'elle peut paniquer. Comportement : - premier appel valide avec subscriber global libre : succès ; - second appel après succès : erreur KSP déterministe ; - appel lorsqu'un autre subscriber global a déjà été installé : erreur KSP ; - aucune tentative silencieuse de remplacer le subscriber existant ; - aucune comparaison complexe de settings pour rendre un second appel « idempotent » ; - aucune reconfiguration globale dynamique dans `0.1.2`. Les tests globaux doivent éviter de se gêner entre eux, par exemple en isolant la validation de l'initialisation globale dans un test/processus dédié et en testant les composants internes avec des subscribers locaux lorsque possible. ## Erreurs Logging Logging utilise : ```text ksp_core_lib::Error ksp_core_lib::ErrorCode ksp_core_lib::Result ``` Le domaine stable appartient à Logging : ```text logging ``` Premiers codes conceptuels : ```text logging.invalid_settings logging.already_initialized logging.file_output_initialization_failed ``` Un code supplémentaire n'est ajouté que si une erreur réellement distincte apparaît pendant l'implémentation. Règles : - les constantes `ErrorCode` sont définies dans `ksp-logging-lib` ; - Core n'ajoute aucune variante/connaissance Logging ; - les causes externes utiles sont conservées avec `Error::with_source(...)` lorsqu'elles satisfont `Error + Send + Sync + 'static` ; - le contexte n'embarque aucun secret ; - aucun `unwrap`, `expect`, `panic` production ni opérateur `?` n'est introduit. ## Politique secrets et données sensibles ### Valeurs interdites dans les logs Ne jamais émettre en clair : - clé privée ou bytes secrets de keypair ; - seed/seed phrase/mnemonic ; - password/passphrase/PIN ; - token API, bearer token, session token ou cookie d'authentification ; - header `Authorization` complet ; - clé de chiffrement ou secret de signature ; - DSN/URL de connexion contenant des credentials ; - contenu futur de `KS_SECRET_*` / `KB_SECRET_*` ou équivalent sensible ; - tout objet `Debug` susceptible d'embarquer indirectement l'une de ces valeurs. Les adresses publiques, signatures publiques, Program IDs, slots et identifiants publics peuvent être loggés lorsqu'ils sont utiles. ### Settings Logging `LoggingSettings` ne possède aucun champ de secret. Une future Config peut lui transmettre des chemins, niveaux, targets et paramètres de sortie, mais jamais les secrets de son propre document. ### Responsabilité des callers La façade ne peut pas détecter de façon fiable qu'un arbitraire `Debug`/`Display` contient un secret. La règle est donc : - omission par défaut ; - redaction explicite par le caller avant émission si la présence d'un champ est réellement nécessaire ; - ne jamais logger un objet de configuration complet uniquement par commodité ; - ne pas considérer le filtrage de niveau comme une protection de secret. ### Helper de redaction Aucun helper générique de redaction n'est ajouté dans `0.1.2`. Un helper donnant une impression de protection automatique sans contrôler le contenu des objets serait trompeur. Une future nécessité concrète pourra introduire un type/helper explicitement borné. ## Format, spans et compatibilité `log` ### Format `0.1.2` stabilise un format humain exploitable, pas une sérialisation machine publique. Sont hors de la première surface : - JSON ; - pretty/compact/human comme enum publique de formats ; - choix arbitraire de formatter par le caller ; - sérialisation Serde des événements. ### Spans La crate est propriétaire de la stack tracing, mais `0.1.2` ne crée pas encore une façade publique KSP pour : - `span!` ; - `#[instrument]` ; - OpenTelemetry ; - contexte distribué. Les cinq macros d'événements suffisent à la première fondation. Une surface spans sera ajoutée uniquement au premier besoin concret d'une crate async/runtime supérieure. ### Compatibilité `log` La feature `tracing-log` de `tracing-subscriber` n'est pas activée maintenant. KSP ne possède encore aucune dépendance runtime supérieure démontrant un besoin de récupérer des événements provenant de la crate `log`. Cette compatibilité pourra être activée ultérieurement dans Logging si un transport/provider concret l'exige. ## API publique candidate La façade crate-root visée à la fin de la release est : ```text ksp_logging_lib::error! ksp_logging_lib::warn! ksp_logging_lib::info! ksp_logging_lib::debug! ksp_logging_lib::trace! ksp_logging_lib::LogFilterLevel ksp_logging_lib::TargetFilter ksp_logging_lib::ConsoleOutput ksp_logging_lib::ConsoleSettings ksp_logging_lib::FileRotation ksp_logging_lib::FileSettings ksp_logging_lib::LoggingSettings ksp_logging_lib::LoggingGuard ksp_logging_lib::initialize ksp_logging_lib:: ``` Les modules d'implémentation restent privés. Les types externes `tracing*` ne deviennent pas le contrat public KSP. Arborescence candidate : ```text crates/ksp-logging-lib/ ├── Cargo.toml ├── README.md ├── TODO.md ├── USAGE.md ├── src/ │ ├── lib.rs │ ├── error.rs │ ├── macros.rs │ ├── settings.rs │ └── runtime.rs ├── unit_tests/ │ ├── settings.rs │ └── runtime.rs └── tests/ ├── callsite.rs └── public_api.rs ``` Cette arborescence reste ajustable si une séparation plus petite suffit. Aucun `mod.rs`, `pub mod`, `pub(super)` ou `pub(in ...)` n'est introduit. ## Tests prévus ### Façade/macros - les cinq macros sont accessibles depuis crate-root ; - message simple ; - champs structurés ; - target explicite ; - callsite file/module/line réel ; - target implicite du caller ; - absence de dépendance directe `tracing` dans une crate consommatrice de test si un fixture workspace est nécessaire. ### Settings - constructeurs/getters ; - niveaux `Off/Error/Warn/Info/Debug/Trace` ; - target filters ; - console stdout/stderr ; - fichier Never/Hourly/Daily ; - validation sans sortie ; - validation des chaînes vides retenues. ### Filtering - niveau default ; - override de target exact ; - override par préfixe ; - target explicitement Off ; - priorité d'un préfixe plus spécifique selon la sémantique `Targets` retenue. ### Runtime - initialisation valide ; - réinitialisation refusée ; - subscriber déjà occupé ; - console reçoit les événements attendus ; - file output écrit les événements attendus ; - rotation choisie est transmise au backend ; - erreurs d'initialisation fichier remontent sous `ksp_core_lib::Error` avec code Logging ; - guard conservé jusqu'au flush final. ### Secrets Aucun test ne peut prouver qu'un caller futur ne loggera jamais un secret arbitraire. Les validations testables portent sur : - l'absence de champs sensibles dans `LoggingSettings` ; - l'absence de dump automatique des settings/configurations ; - les exemples/docs qui utilisent uniquement des valeurs publiques ; - l'absence de helper présenté comme redaction automatique universelle. ## Audits de dépendances À chaque tranche ajoutant une dépendance : ```bash cargo tree -p ksp-logging-lib cargo tree -p ksp-logging-lib -d cargo tree -p ksp-logging-lib -e features ``` Contrôles particuliers : - pas de `tracing-attributes` tant que `attributes` n'est pas nécessaire ; - pas de `nu-ansi-term` par activation KSP de `ansi` ; - pas de `tracing-log` par default feature ; - pas de stack `env-filter`/regex ; - pas de stack JSON/Serde ; - pas de dépendance Config ; - aucune seconde version évitable de la stack tracing ; - `tracing-appender` peut tirer `time` pour son fonctionnement propre sans justifier d'activer la feature `time` de `tracing-subscriber`. ## Référence historique bot3 L'archive bot3 fournie contient un ancien `ks-logging` plus large. Éléments utiles comme expérience historique : - possession des `WorkerGuard` par un objet `LoggingGuard` ; - composition console + fichier ; - filtering par routes/targets ; - rotation file ; - importance d'un lifecycle explicite pour le non-blocking. Éléments explicitement non migrés tels quels : - dépendance directe Logging -> Config ; - parsing/validation de document Logging dans la crate ; - JSON schema ; - Serde/Serde JSON uniquement pour la configuration ; - formats/routes multiples non requis ; - surface de configuration historique plus large que le besoin KSP `0.1.2`. Cette archive reste une référence historique et non une source normative KSP. ## Prereleases prévues ### `0.1.2-pre.001` — audit + brainstorming + plan Objectifs : - auditer la base `0.1.1` ; - auditer la stack tracing actuelle ; - fixer ownership, macros/callsites, settings, filtering, console, fichier, lifecycle, erreurs et secrets ; - dimensionner la suite ; - ne pas créer encore la crate fonctionnelle ni ajouter de dépendance inutilisée. ### `0.1.2-pre.002` — crate + settings + façade d'émission Objectifs : - créer `crates/ksp-logging-lib` et l'ajouter au workspace ; - dépendre de `ksp-core-lib` ; - revérifier puis ajouter `tracing` au workspace ; - implémenter les types de settings indépendants de Config ; - implémenter les cinq macros KSP ; - ajouter les premiers tests publics de façade ; - établir le test de callsite, en ajoutant `tracing-subscriber` à cette tranche seulement si le test l'utilise réellement ; sinon le fixer au début de `pre.003` avant de considérer les macros stabilisées. ### `0.1.2-pre.003` — subscriber + console + filtering Objectifs : - revérifier puis ajouter `tracing-subscriber` si ce n'est pas déjà fait ; - implémenter le mapping `LogFilterLevel` ; - implémenter `Targets` default + overrides ; - implémenter la couche console ; - installer le subscriber global avec API fallible ; - stabiliser le comportement de réinitialisation ; - achever les tests de callsite avant toute poursuite vers le fichier. ### `0.1.2-pre.004` — fichier + non-blocking + lifecycle Objectifs : - revérifier puis ajouter `tracing-appender` ; - implémenter `FileSettings` et Never/Hourly/Daily ; - utiliser le builder fallible du file appender ; - utiliser le non-blocking en mode non-lossy ; - introduire/achever `LoggingGuard` ; - tester flush/lifetime et erreurs de fichier ; - vérifier le graphe/features après unification de la stack complète. ### `0.1.2-pre.005` — intégration + tests + audits Objectifs : - compléter les tests settings/filtering/runtime/façade ; - vérifier la politique secrets dans docs/exemples ; - 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 ; - corriger les écarts sans ouvrir Config. ### `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` ; - préparer la livraison finale avant `rel.001` et tag stable. Le découpage reste souple. Une tranche trop large est scindée ; une tranche devenue inutile est supprimée par correction explicite du plan. ## Hors scope confirmé - `ksp-config-lib` et documents/profils Config ; - parsing JSON/TOML de configuration ; - Tauri ; - wallet/keypair/signer ; - RPC/WS/providers ; - Program decoding/execution ; - Store/PostgreSQL ; - materializers ; - workers/jobs/pipelines ; - scenarios ; - trading/ML ; - OpenTelemetry/export réseau ; - observabilité distribuée ; - public span API/`#[instrument]` ; - hot reload dynamique des filtres ; - JSON log format ; - field-based/domain filtering ; - rotation par taille/compression ; - multi-route avancé ; - politique de rétention complexe ; - compatibilité `log` tant qu'aucun besoin concret ne l'impose. ## Critères de sortie de `0.1.2` La release peut être stabilisée lorsque : - `ksp-logging-lib` est la façade runtime unique KSP ; - les cinq macros KSP fonctionnent sans dépendance `tracing` directe chez les consumers ; - les tests prouvent le callsite réel ; - les settings sont indépendants de Config ; - le filtering default/target est déterministe ; - console et fichier optionnel sont validés ; - le file writer non bloquant est non-lossy et son guard est possédé explicitement ; - la répétition d'initialisation retourne une erreur KSP au lieu de paniquer ; - les erreurs utilisent Core sans dépendance inverse ; - aucune fuite automatique de secret n'est introduite par la façade/settings ; - le graphe/features respecte le besoin minimal retenu ; - 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` Aucune question architecturale bloquante ne justifie du développement supplémentaire dans `pre.001`. Restent volontairement à confirmer par implémentation/tests : 1. le mécanisme Rust exact des macros KSP (wrapper transparent ou réexport) qui préserve le callsite avec la plus petite surface ; 2. le détail visuel exact du formatter humain, sans transformer sa ponctuation en contrat public ; 3. l'utilité future d'une rétention bornée, d'ANSI, JSON, `tracing-log`, `EnvFilter`, spans ou reload, tous explicitement hors de la première surface tant qu'un besoin concret n'apparaît pas. La prochaine action après validation de ce plan est `0.1.2-pre.002`, pas l'ouverture de Config.