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

<!-- file: deltas/0.1.2/pre.001.md -->
<!-- version: 1 -->

# 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<T>
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`.