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

Delta 0.1.2-pre.001

Base requise

Release stable/taguée attendue :

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 :

0.1.1

à :

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 :

workspace members
└── crates/ksp-core-lib

ksp-logging-lib n'existe pas encore.

Core fournit déjà les contrats nécessaires à Logging :

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

ainsi que les Program IDs fondamentaux et leur registre descriptif.

La relation retenue reste unidirectionnelle :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

logging

Codes conceptuels initiaux :

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

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 :

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.