khadhroony-solana-project/deltas/0.1.2/pre.002.md

Delta 0.1.2-pre.002

Base requise

Livraison précédente validée :

0.1.2-pre.001-fix.001

Cette tranche applique le plan corrigé de pre.001 et ouvre le développement fonctionnel de ksp-logging-lib sans encore installer le subscriber runtime.

Objectif

Créer la première surface fonctionnelle de Logging :

• créer crates/ksp-logging-lib et l'ajouter au workspace ;
• dépendre de ksp-core-lib pour le contrat commun d'erreur ;
• ajouter uniquement tracing parmi les dépendances de la stack de logging ;
• définir les settings runtime propres à Logging, indépendants de Config ;
• exposer les cinq niveaux d'événements par macros KSP avec target: explicite ;
• exposer les cinq niveaux de spans KSP ;
• fournir une abstraction Span KSP pour les scopes synchrones ;
• fournir instrument(span, future) pour l'instrumentation async sans demander au consumer d'utiliser tracing::Instrument ;
• vérifier par tests la préservation du callsite événement/span et le cycle enter/exit d'une future instrumentée.

Le subscriber global, le takeover effectif, le filtering runtime, les sorties console/fichier non bloquantes, les guards et le hot reload restent réservés aux prereleases suivantes conformément au plan.

Version Cargo

workspace.package.version passe de :

0.1.2-pre.1

à :

0.1.2-pre.2

L'identifiant de livraison reste :

0.1.2-pre.002

Le header du Cargo.toml racine passe de version 26 à 27.

Dépendances

tracing est ajouté à la racine sous [workspace.dependencies] :

tracing = { version = "^0.1", default-features = false, features = ["std"] }

ksp-logging-lib le consomme avec :

tracing.workspace = true

L'audit de la publication actuelle retient tracing 0.1.44. Les default features ne sont pas activées : attributes n'est pas nécessaire à cette tranche, car KSP n'utilise pas #[instrument]. La feature std suffit à la façade retenue et aux tests de subscriber local.

tracing-subscriber et tracing-appender ne sont pas ajoutés dans pre.002 : ils ne sont pas encore consommés par du code runtime.

Settings runtime

La surface publique introduit :

LogFilterLevel
TargetFilter
SpanEvents
ConsoleOutput
ConsoleSettings
FileRotation
FileSettings
LoggingSettings

Ces types :

• appartiennent à ksp-logging-lib ;
• ne lisent aucun document Config ;
• ne consultent aucune variable d'environnement ;
• ne dépendent pas de ksp-config-lib ;
• utilisent des champs privés et une construction/getters explicites.

Une configuration sans console ni fichier est valide et représente un logging KSP désactivé. Les validations actuelles rejettent uniquement les ambiguïtés propres au contrat déjà fixé, notamment les préfixes de target vides/externes et un préfixe de fichier vide.

Façade événements

Les macros crate-root suivantes sont introduites :

ksp_logging_lib::error!
ksp_logging_lib::warn!
ksp_logging_lib::info!
ksp_logging_lib::debug!
ksp_logging_lib::trace!

Leur syntaxe KSP exige target: explicitement. Elles délèguent directement aux macros tracing au point d'expansion afin que les métadonnées file, module_path et line correspondent au callsite consumer et non à une fonction wrapper dans Logging.

Un bridge tracing public mais caché de la documentation est nécessaire à l'expansion des macros depuis les crates consommatrices. Il est réservé à l'implémentation des macros ; DEP-LOG-009 interdit son usage direct comme API consumer.

Spans synchrones et async

Les macros suivantes sont introduites :

ksp_logging_lib::error_span!
ksp_logging_lib::warn_span!
ksp_logging_lib::info_span!
ksp_logging_lib::debug_span!
ksp_logging_lib::trace_span!

Elles exigent également target: explicitement et retournent ksp_logging_lib::Span.

Pour le synchrone :

Span::in_scope(operation)

entre dans le span pendant le scope puis en sort à la fin du scope.

Pour l'async :

ksp_logging_lib::instrument(span, future)

retourne une Future opaque instrumentée. Le span est entré pendant chaque poll de la future et quitté lorsque ce poll rend la main ; aucun enter guard KSP n'est destiné à être conservé à travers .await.

Cette surface prépare les diagnostics de durée NEW/CLOSE, busy et idle qui seront activés par le formatter/subscriber dans les tranches runtime suivantes.

Erreurs

ksp-logging-lib utilise :

ksp_core_lib::Result<T>
ksp_core_lib::Error
ksp_core_lib::ErrorCode

Le premier code propre à Logging est :

logging.invalid_settings

Core ne reçoit aucune connaissance de Logging et aucune dépendance inverse n'est introduite.

Tests ajoutés

Unitaires

• distinction des niveaux ;
• construction/getters des target filters ;
• console stdout/stderr ;
• settings fichier/rotation ;
• conservation des settings explicites ;
• logging désactivé sans sink ;
• rejet des target prefixes vides ou externes ;
• rejet du préfixe fichier vide ;
• scope synchrone d'un span ;
• propagation du résultat d'une future instrumentée.

Intégration

• surface publique des settings sans Config ;
• disponibilité des cinq macros événements ;
• disponibilité des cinq macros spans ;
• usage sync et async sans import consumer de tracing::Span ou tracing::Instrument ;
• préservation de target, file, module_path et line au callsite événement ;
• préservation de target, file, module_path et line au callsite span ;
• entrée puis sortie du span lors du poll d'une future instrumentée.

Règles ajustées

DEP-LOG-009 documente explicitement que le bridge tracing caché nécessaire aux macros est un détail d'implémentation de ksp-logging-lib, jamais une surface utilisable par une crate consommatrice.

Le plan 004-V0_1_2_LOGGING_FOUNDATION_PLAN.md est synchronisé avec l'API effectivement retenue dans pre.002 et avec la validité d'un logging entièrement désactivé.

Fichiers ajoutés

• crates/ksp-logging-lib/Cargo.toml
• crates/ksp-logging-lib/src/error.rs
• crates/ksp-logging-lib/src/lib.rs
• crates/ksp-logging-lib/src/macros.rs
• crates/ksp-logging-lib/src/settings.rs
• crates/ksp-logging-lib/src/span.rs
• crates/ksp-logging-lib/unit_tests/settings.rs
• crates/ksp-logging-lib/unit_tests/span.rs
• crates/ksp-logging-lib/tests/callsite.rs
• crates/ksp-logging-lib/tests/public_api.rs
• deltas/0.1.2/pre.002.md

Fichiers modifiés

• Cargo.toml
• docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md
• docs/rules/RULES_DEPENDENCIES.md

Fichiers supprimés

Aucun.

Validations exécutées

Validations statiques exécutées dans l'environnement de préparation :

• parsing TOML des manifests ;
• contrôle des headers file: / version: des fichiers livrés ;
• contrôle de l'absence de Cargo.lock dans le delta ;
• contrôle de l'absence de tracing-subscriber et tracing-appender dans les manifests ;
• contrôle de la centralisation de tracing sous [workspace.dependencies] ;
• contrôle que les usages directs de tracing restent bornés à ksp-logging-lib ;
• contrôle des patterns Rust interdits par les règles workspace dans le code production ajouté ;
• contrôle des liens Markdown locaux du plan modifié ;
• contrôle du contenu de l'archive selon VER-ARCHIVE-004.

Validations non exécutées

L'environnement de préparation ne fournit pas cargo, rustc ou rustfmt. Les validations suivantes ne sont donc pas déclarées réussies :

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

Elles doivent être exécutées sur le workspace de développement avant validation de la tranche. Toute erreur sera corrigée par le delta suivant conformément au workflow KSP.

Décisions prises

• tracing est la seule dépendance de la stack ajoutée en pre.002 ;
• les macros KSP exigent target: ;
• le callsite est préservé par expansion de macro et testé ;
• l'abstraction publique de span est ksp_logging_lib::Span ;
• le synchrone utilise Span::in_scope(...) ;
• l'async utilise instrument(span, future) ;
• une configuration sans sink est valide et représente Logging désactivé ;
• aucune initialisation/subscriber global n'est introduit prématurément dans cette tranche.

Questions ouvertes

Aucune question bloquante pour pre.002.

Restent à choisir/tester dans les tranches runtime suivantes :

• la composition interne reloadable la moins coûteuse ;
• l'API exacte d'observation des lignes abandonnées ;
• les détails finaux du formatter console/fichier ;
• la stratégie de swap des sinks garantissant le maintien de l'ancienne configuration si une reconfiguration échoue.

Après validation de cette tranche, la prochaine étape est 0.1.2-pre.003 : subscriber, takeover, filtering, console initiale et fondation du hot reload.