khadhroony-solana-project/deltas/0.1.2/pre.001-fix.001.md

Delta 0.1.2-pre.001-fix.001

Base requise

Livraison précédente :

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 :

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 :

0.1.2-pre.1

L'identifiant de livraison est :

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 :

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.