# Delta 0.1.2-pre.001 ## Base requise Release stable/taguée attendue : ```text v0.1.1 ``` L'archive Gitea fournie `khadhroony-solana-project-v0.1.1.zip` contient bien : - `workspace.package.version = "0.1.1"` ; - le delta final `deltas/0.1.1/rel.001.md` ; - le prompt final `prompts/002-V0_1_2_START_PROMPT.md` ; - la surface Core stabilisée attendue. Dans le workflow KSP, cette archive provient directement du tag correspondant et constitue la base stable suffisante pour ouvrir `0.1.2`. ## Objectif Ouvrir `0.1.2` par la prerelease obligatoire de brainstorming, audit et planification, sans développement fonctionnel Logging. Cette tranche : - inventorie l'état réel du workspace et confirme l'absence actuelle de `ksp-logging-lib` ; - audite la stack `tracing` officielle actuelle ; - fixe la frontière façade/instrumentation/runtime subscriber ; - retient les macros KSP pour préserver les callsites ; - définit les niveaux et settings runtime candidats ; - borne la sémantique de `target`, `domain` et `component` ; - retient le filtering global + target-prefix via `Targets` ; - retient console + fichier optionnel ; - retient un writer fichier non bloquant non-lossy avec guard possédé explicitement ; - définit le lifecycle d'initialisation/réinitialisation ; - fixe la stratégie d'erreurs Core et de protection des secrets ; - dimensionne `pre.002` à `pre.006` ; - confirme les hors-scope. Le détail est consigné dans `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`. ## Version Cargo `workspace.package.version` passe de : ```text 0.1.1 ``` à : ```text 0.1.2-pre.1 ``` L'identifiant Cargo respecte SemVer sans zéro initial ; l'identifiant de livraison reste `0.1.2-pre.001`. Le header de `Cargo.toml` passe de version 25 à 26. Aucune dépendance `tracing*` n'est ajoutée par cette tranche de planification : elles seront introduites uniquement lorsque le code/tests de `ksp-logging-lib` les consommeront réellement. ## Fichiers ajoutés - `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md` - `deltas/0.1.2/pre.001.md` ## Fichiers modifiés - `Cargo.toml` - `ROADMAP.md` - `docs/plans/000-README.md` ## Fichiers supprimés Aucun. ## Inventaire du workspace État de la base stable auditée : ```text workspace members └── crates/ksp-core-lib ``` `ksp-logging-lib` n'existe pas encore. Core fournit déjà les contrats nécessaires à Logging : ```text ksp_core_lib::ErrorCode ksp_core_lib::ErrorContext ksp_core_lib::Error ksp_core_lib::Result ksp_core_lib::Pubkey ``` ainsi que les Program IDs fondamentaux et leur registre descriptif. La relation retenue reste unidirectionnelle : ```text ksp-logging-lib -> ksp-core-lib ksp-core-lib -X-> ksp-logging-lib ``` ## Audit externe tracing Audit effectué le 2026-08-14 sur les publications/docs officielles Tokio `tracing`, docs.rs/crates.io et les manifests publiés. Versions observées : ```text tracing 0.1.44 rustc 1.65+ tracing-subscriber 0.3.23 rustc 1.65+ tracing-appender 0.2.5 rustc 1.63+ ``` Contraintes candidates à revérifier au moment de l'ajout effectif : ```toml tracing = { version = "^0.1", default-features = false, features = ["std"] } tracing-subscriber = { version = "^0.3", default-features = false, features = ["fmt"] } tracing-appender = { version = "^0.2", default-features = false } ``` Décisions de features : - pas de `tracing-attributes`/`attributes` ; - pas de `ansi` ; - pas de `tracing-log` ; - pas d'`env-filter` ; - pas de JSON/Serde ; - pas de chrono/time formatter via `tracing-subscriber` ; - pas de `parking_lot` appender ; - `tracing-appender` tire lui-même `tracing-subscriber` avec `default-features = false`, `fmt` et `std` ainsi que les dépendances internes nécessaires à son fonctionnement. Aucune dépendance n'est ajoutée uniquement parce qu'elle figure dans l'architecture candidate. ## Décisions de planification ### Façade et callsites La surface d'émission KSP sera : ```text ksp_logging_lib::error! ksp_logging_lib::warn! ksp_logging_lib::info! ksp_logging_lib::debug! ksp_logging_lib::trace! ``` Les événements ne seront pas émis par de simples fonctions wrappers qui déplaceraient les métadonnées source. L'implémentation exacte des macros doit réussir un test d'intégration prouvant que file/module/line et target implicite restent ceux du consommateur. ### Champs structurés - `target` : métadonnée native de routage/filtering, naturelle au callsite ou explicitement overridable ; - `domain` : champ structuré KSP optionnel ; - `component` : champ structuré KSP optionnel ; - autres champs : ouverts selon besoin, sans taxonomie fermée. `domain` et `component` ne deviennent pas des filtres dans `0.1.2`. ### Filtering Première surface : ```text default filter level + zero or more target-prefix overrides ``` `tracing_subscriber::filter::Targets` est retenu comme mécanisme initial. `EnvFilter`, `RUST_LOG`, field-based filtering et hot reload restent hors scope. ### Settings runtime Surface conceptuelle retenue : ```text LogFilterLevel TargetFilter ConsoleOutput ConsoleSettings FileRotation FileSettings LoggingSettings LoggingGuard initialize(...) ``` Les settings ne lisent ni fichier, ni environnement, ni profil Config et ne contiennent aucun secret. ### Console Sortie console avec choix explicite stdout/stderr. Le formatter initial reste humain, sans JSON ni ANSI obligatoire. ### Fichier Sortie fichier optionnelle retenue avec : ```text Never | Hourly | Daily ``` Le builder fallible du `RollingFileAppender` doit être utilisé afin de remonter les erreurs au lieu de paniquer. Le writer fichier utilise `NonBlockingBuilder` en mode : ```text lossy(false) ``` La saturation applique donc de la backpressure plutôt que de supprimer silencieusement des logs. ### Lifecycle `LoggingGuard` possède le ou les `WorkerGuard` nécessaires au backend non bloquant. L'appelant conserve le guard jusqu'à la fin ordonnée du processus. Le lifecycle global est volontairement : ```text uninitialized -> initialized -> process shutdown ``` Une initialisation répétée échoue avec une erreur KSP ; elle ne remplace pas silencieusement un subscriber existant et ne panique pas. ### Erreurs Les erreurs Logging utilisent le contrat Core et restent dans le domaine : ```text logging ``` Codes conceptuels initiaux : ```text logging.invalid_settings logging.already_initialized logging.file_output_initialization_failed ``` Les causes externes utiles sont conservées via `Error::with_source(...)` lorsque possible. ### Secrets Sont explicitement interdits dans les logs : clés privées, seeds/mnemonics, passwords/passphrases/PIN, tokens API/bearer/session, cookies/auth headers, secrets de chiffrement/signature, credentials de connexion et futurs `*_SECRET_*`. Aucun helper de redaction universel n'est introduit : le caller doit omettre ou redacter explicitement la valeur avant émission. Les settings Logging ne contiennent eux-mêmes aucun secret. ### Surface différée Ne pas ajouter dans `0.1.2` sans nouveau besoin validé : - spans KSP/`#[instrument]` ; - OpenTelemetry ; - JSON ; - ANSI ; - compatibilité `log` ; - `EnvFilter` ; - reload de filtre ; - filtering par fields/domain ; - rotation minutely/weekly/by-size ; - compression/rétention complexe/latest symlink ; - routes multiples avancées. ## Référence historique bot3 L'ancien `ks-logging` de l'archive bot3 fournie a été relu comme référence historique uniquement. Éléments conservés comme leçons utiles : - objet de lifecycle possédant les `WorkerGuard` ; - console + fichier ; - rotation ; - filtering par targets. Éléments non migrés : - dépendance Logging -> Config ; - document/schema JSON propre à Logging ; - Serde/JSON pour la configuration ; - routes/formats multiples non nécessaires à la première surface KSP. ## Prereleases prévues ```text pre.001 audit + brainstorming + plan pre.002 crate + settings + macros/façade pre.003 subscriber + console + filtering + callsite final pre.004 fichier + non-blocking + lifecycle pre.005 intégration + tests + audits pre.006 validation finale + docs/cleanup + prompt 0.1.3 ``` Le découpage reste souple ; une tranche trop large sera scindée plutôt que surchargée. ## Hors scope confirmé - Config/documents/profils ; - Tauri ; - Wallet/signing ; - RPC/WS/providers ; - Program decoding/execution ; - Store/PostgreSQL ; - Materializer ; - workers/jobs/pipelines ; - scenarios ; - trading/ML ; - observabilité distribuée/OpenTelemetry. ## Validations exécutées Dans l'environnement de préparation de ce delta : - lecture/audit de l'archive complète `0.1.1` fournie ; - vérification statique de `workspace.package.version = "0.1.1"` ; - vérification de la présence du delta `0.1.1/rel.001` et du prompt final `0.1.2` ; - inventaire des membres workspace et confirmation de l'absence de `ksp-logging-lib` ; - lecture des règles, plans, indexes et documents d'architecture demandés par le prompt ; - lecture de `ksp-core-lib` et de son contrat Error/Result ; - audit de l'ancien `ks-logging` bot3 fourni comme référence historique, sans le traiter comme source de vérité KSP ; - vérification des versions/features/MSRV actuels de `tracing`, `tracing-subscriber` et `tracing-appender` depuis leurs sources de publication officielles ; - audit du manifest publié de `tracing-appender` pour ses dépendances/features ; - audit de `Targets`, `EnvFilter`, du non-blocking, du mode lossy/backpressure, de `WorkerGuard`, du builder fallible et de la rotation ; - parsing TOML statique du manifest modifié ; - contrôle statique des headers `file:` / `version:` des fichiers ajoutés/modifiés ; - contrôle statique des liens Markdown locaux après modification ; - contrôle du contenu de l'archive delta selon `VER-ARCHIVE-004`. ## Validations non exécutées L'environnement de préparation ne contient ni `cargo` ni `rustc`. Les commandes suivantes n'ont donc pas pu être exécutées ici : ```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 ``` Les trois commandes `cargo tree -p ksp-logging-lib` ne sont de toute façon applicables qu'après création effective de la crate. Aucun succès Cargo n'est déclaré par ce delta. ## Questions ouvertes Aucune question architecturale bloquante ne justifie de poursuivre le développement dans `pre.001`. À confirmer par tests dans les tranches suivantes : - mécanisme exact de macro KSP préservant le callsite avec la plus petite surface ; - format visuel exact des lignes humaines sans le figer comme protocole ; - nécessité future de capacités volontairement différées comme rétention, ANSI, JSON, `tracing-log`, `EnvFilter`, spans ou reload. La prochaine tranche après validation de ce plan est `0.1.2-pre.002`.