v0.1.2-rel.001

This commit is contained in:
2026-08-14 20:41:23 +02:00
parent 77f6eaf487
commit 3a7219fa59
7 changed files with 252 additions and 32 deletions

View File

@@ -1,12 +1,12 @@
# file: Cargo.toml
# version: 38
# version: 39
[workspace]
resolver = "3"
members = ["crates/ksp-core-lib", "crates/ksp-logging-lib"]
[workspace.package]
version = "0.1.2-pre.6"
version = "0.1.2"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

View File

@@ -32,7 +32,7 @@ Regrouper les releases consacrées aux fondations N1. Chaque release concrète e
### Releases concrètes
- [X] `0.1.1` — Stabiliser `ksp-core-lib` : `Error`/`Result`, Program IDs fondamentaux et primitives réellement N1.
- [/] `0.1.2` — Introduire `ksp-logging-lib` comme façade KSP de `tracing`, `tracing-appender` et `tracing-subscriber`.
- [X] `0.1.2` — Introduire `ksp-logging-lib` comme façade KSP de `tracing`, `tracing-appender` et `tracing-subscriber`.
- [ ] `0.1.3` — Introduire `ksp-config-lib` : documents, profils, résolution, validation et modifications autorisées.
- [ ] `0.1.4` — Introduire `ksp-app-config-desk` pour valider réellement Config et la frontière Tauri.

193
deltas/0.1.2/rel.001.md Normal file
View File

@@ -0,0 +1,193 @@
<!-- file: deltas/0.1.2/rel.001.md -->
<!-- version: 1 -->
# Delta `0.1.2-rel.001` — publication stable Logging
## Base requise
`0.1.2-pre.006` avec le correctif documentaire `0.1.2-pre.006-fix.001`, au sens des commits de livraison correspondants, avec :
```text
workspace.package.version = "0.1.2-pre.6"
```
Le correctif `pre.006-fix.001` ne modifie pas la version Cargo.
## Objectif
Publier la release stable `0.1.2`, clôturer `Logging foundation` et préparer l'ouverture de `0.1.3 — Configuration foundation` sans modifier la surface fonctionnelle de `ksp-logging-lib`.
## Version Cargo
`workspace.package.version` passe de :
```text
0.1.2-pre.6
```
à :
```text
0.1.2
```
Le header de `Cargo.toml` passe de version 38 à 39.
Les contraintes de dépendances restent inchangées :
```toml
[workspace.dependencies]
solana-pubkey = { version = "^4.3", default-features = false }
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 }
tokio = { version = "^1.53", default-features = false, features = ["rt", "rt-multi-thread", "macros"] }
```
Tokio reste uniquement une dev-dependency de `ksp-logging-lib` et n'appartient pas à son graphe normal.
## Validations finales exécutées par le user
Commandes exécutées avec succès le 2026-08-14 sur `0.1.2-pre.6` :
```bash
cargo fmt --all
cargo check --workspace
cargo build -p ksp-logging-lib
cargo clippy --workspace --all-targets
cargo test --workspace
cargo test -p ksp-logging-lib --test overhead -- --ignored --nocapture
cargo tree -p ksp-logging-lib
cargo tree -p ksp-logging-lib -d
cargo tree -p ksp-logging-lib -e features
cargo tree -p ksp-logging-lib -e normal
cargo tree -p ksp-logging-lib -e dev
```
Résultats communiqués :
- `cargo check --workspace` : succès ;
- `cargo build -p ksp-logging-lib` : succès sur le graphe normal ;
- `cargo clippy --workspace --all-targets` : succès sans warning communiqué ;
- `cargo test --workspace` : tous les tests exécutés réussissent, dont les tests de takeover, saturation non bloquante, hot reload concurrent, lifecycle span et les deux tests Tokio réels ;
- probe d'overhead explicite : succès sur 200000 itérations, `baseline=16.959425ms`, `reload=24.942444ms` ;
- `cargo tree -p ksp-logging-lib -d` : aucun doublon ;
- `cargo tree -p ksp-logging-lib -e normal` : Tokio absent ;
- `cargo tree -p ksp-logging-lib -e dev` : Tokio présent comme seule dev-dependency directe ;
- features Tokio observées : `macros`, `rt`, `rt-multi-thread`, sans feature `full`.
Le correctif documentaire `pre.006-fix.001` appliqué après ces validations ne modifie ni Rust, ni manifest, ni runtime.
## Surface stable publiée
`0.1.2` stabilise notamment :
- `ksp-logging-lib` comme façade runtime KSP unique de logging/tracing ;
- les macros `error!`, `warn!`, `info!`, `debug!`, `trace!` avec target KSP explicite et callsite consommateur préservé ;
- les spans KSP synchrones et `instrument(span, future)` pour l'async sans dépendance `tracing` directe chez les consumers ;
- `LoggingSettings`, `LogFilterLevel`, `TargetFilter`, `SpanEvents`, `ConsoleSettings`, `FileSettings` et `FileRotation` ;
- `initialize()` unique, `reinitialize()` à chaud et `LoggingGuard` ;
- takeover KSP avec silence externe par défaut et overrides par préfixe `ksp-*` ;
- console et fichier non bloquants avec `WorkerGuard` possédés par Logging ;
- mode lossy sans backpressure sur le hot path et observation cumulée des lignes abandonnées via `DroppedLines` ;
- rotation fichier `Never`, `Hourly`, `Daily` ;
- suppression des séquences ANSI avant persistence fichier ;
- reconfiguration transactionnelle conservant l'ancienne configuration si la nouvelle préparation échoue ;
- lifecycle spans `Off`, `NewAndClose`, `Full`, avec `busy`/`idle` lorsque demandé ;
- tests de concurrence/reload, saturation, ownership de la stack tracing, callsites et instrumentation Tokio current-thread/multi-thread ;
- ownership exclusif de `tracing`, `tracing-subscriber` et `tracing-appender` par `ksp-logging-lib` dans le workspace KSP.
Aucune nouvelle primitive ou API n'est ajoutée par le présent delta de publication.
## Documentation de clôture
Le présent delta :
- marque `0.1.2` réalisée dans `ROADMAP.md` ;
- conserve `004-V0_1_2_LOGGING_FOUNDATION_PLAN.md` comme plan historique clôturé ;
- ajoute ce plan aux index de documentation/plans ;
- remplace le périmètre candidat Logging dans la séquence fonctionnelle par la surface réellement stabilisée ;
- réaligne la section Config de la séquence fonctionnelle sur les décisions de `pre.006-fix.001` : `KSP_*`/`KSPB_*`, `config/examples/`, documents unitaires + composites, ownership exclusif de Config et accès explicite aux secrets pour les surfaces autorisées ;
- conserve `prompts/003-V0_1_3_START_PROMPT.md` comme prompt final d'ouverture de `0.1.3`.
Aucun changelog général n'existe dans la base actuelle ; aucun changelog artificiel n'est créé.
## Fichiers ajoutés
```text
deltas/0.1.2/rel.001.md
```
## Fichiers modifiés
```text
Cargo.toml
ROADMAP.md
docs/000-README.md
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md
```
## Fichiers supprimés
Aucun.
## Décisions
Aucune nouvelle décision fonctionnelle concernant Logging.
La publication stable confirme les décisions, contrats et corrections stabilisés pendant les prereleases `0.1.2` et leurs fixes.
La synchronisation de la documentation Config en clôture ne remplace pas le brainstorming `0.1.3-pre.001`; elle ne fait qu'enregistrer les décisions déjà prises dans `pre.006-fix.001`.
## Validations non exécutées dans cette livraison
L'environnement de génération du delta ne dispose pas de Cargo/Rust. Les commandes Cargo ne sont donc pas réexécutées ici sur la version finale `0.1.2`.
Après application du delta, le user doit exécuter au minimum :
```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
```
Le build normal et les graphes Cargo peuvent également être rejoués pour confirmer une dernière fois l'absence de Tokio dans le graphe runtime.
## Publication Git
Après application et validation de ce delta :
1. vérifier que le working tree ne contient que les modifications attendues ;
2. exécuter les validations finales sur `workspace.package.version = "0.1.2"` ;
3. créer le commit de release :
```text
v0.1.2-rel.001
```
4. marquer ce commit comme release stable avec le tag :
```text
v0.1.2
```
Aucun tag supplémentaire n'est requis pour les prereleases/fixes historiques.
## Suite
Après le tag stable `v0.1.2`, ouvrir :
```text
0.1.3-pre.001
```
avec :
```text
prompts/003-V0_1_3_START_PROMPT.md
```
La première prerelease de `0.1.3` reste une phase de brainstorming, audit et planification avant développement fonctionnel de `ksp-config-lib`.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Documentation KSP
@@ -35,7 +35,8 @@ docs/
│ ├── 000-README.md
│ ├── 001-V0_0_3_PLAN.md
│ ├── 002-FUNCTIONAL_RELEASE_SEQUENCE.md
── 003-V0_1_1_CORE_FOUNDATION_PLAN.md
── 003-V0_1_1_CORE_FOUNDATION_PLAN.md
│ └── 004-V0_1_2_LOGGING_FOUNDATION_PLAN.md
└── rules/
├── FILE_CONTRACTS.md
├── PROMPT_STRUCTURE.md
@@ -52,7 +53,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é
## Documents de planification
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md).
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md).
`IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.

View File

@@ -12,7 +12,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
- [`001-V0_0_3_PLAN.md`](001-V0_0_3_PLAN.md) — plan historique de la phase fondatrice `0.0.3`, clôturée ;
- [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence active de référence des premières releases fonctionnelles ;
- [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.1`, établi par `0.1.1-pre.001` puis consolidé jusqu'à `0.1.1-rel.001`.
- [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan actif de la release `0.1.2` Logging foundation, établi par `0.1.2-pre.001`.
- [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.2`, établi par `0.1.2-pre.001` puis consolidé jusqu'à `0.1.2-rel.001`.
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Séquence des releases fonctionnelles KSP
@@ -100,7 +100,26 @@ rel.001 publication stable validée de 0.1.1
## `0.1.2` — Logging foundation
### Dépendances
### Mission
Faire de `ksp-logging-lib` la façade KSP unique de logging/tracing pour les composants runtime.
### Surface stabilisée
`0.1.2` stabilise :
- les macros KSP `error!`, `warn!`, `info!`, `debug!`, `trace!` avec `target:` KSP explicite et callsite consommateur préservé ;
- les spans KSP synchrones et l'instrumentation de futures async sans exposer `tracing` aux consumers ;
- `LoggingSettings`, niveaux, overrides par préfixe de target et lifecycle de spans ;
- `initialize()` unique et `reinitialize()` à chaud avec `LoggingGuard` ;
- le takeover des targets : targets externes silencieux par défaut, targets `ksp-*` gouvernés par la politique KSP ;
- console et fichier non bloquants, rotation, ownership des `WorkerGuard` et compteurs cumulés de lignes abandonnées ;
- stripping ANSI avant persistence fichier ;
- reconfiguration transactionnelle conservant l'ancien runtime en cas d'échec ;
- tests de saturation, concurrence/reload, lifecycle spans et instrumentation Tokio réelle ;
- audit d'ownership empêchant les autres crates workspace de dépendre directement de la stack `tracing*`.
### Dépendances runtime
```text
ksp-logging-lib
@@ -110,26 +129,29 @@ ksp-logging-lib
-> tracing-subscriber
```
### Mission
Tokio est uniquement une dev-dependency de `ksp-logging-lib` pour les tests async réels et n'appartient pas à son graphe normal.
Faire de `ksp-logging-lib` la façade KSP unique de logging/tracing pour les composants runtime.
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`. Config pourra convertir ses documents résolus en `LoggingSettings` puis utiliser le lifecycle public de Logging.
### Périmètre candidat
### Lifecycle de la release
- initialisation ;
- settings runtime propres au logging ;
- `error`, `warn`, `info`, `debug`, `trace` ;
- target/domain/component/champs structurés selon API validée ;
- fonctions, macros ou combinaison permettant de préserver correctement les callsites ;
- console/fichiers ;
- filtering ;
- appender/rotation selon besoin concret ;
- tests ;
- protection contre logging de secrets.
Trajectoire réellement suivie :
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`.
Config pourra plus tard convertir ses documents résolus en settings de Logging.
```text
pre.001 brainstorming + audit + plan détaillé
pre.001-fix.001 corrections de cadrage takeover/reload/spans
pre.002 crate + settings + façade événements/spans
pre.002-fix.001 corrections tests/lints
pre.003 subscriber + takeover + console + reload
pre.003-fix.001 correction du montage reload/filter
pre.004 console/fichier non bloquants + guards + ANSI
pre.004-fix.001..004 corrections lifecycle, ANSI, takeover et Clippy
pre.005 robustesse, concurrence, saturation, audits
pre.005-fix.001 suppression du bruit console du stress test
pre.006 validation finale, Tokio dev-only, docs, prompt 0.1.3
pre.006-fix.001 correction documentaire du prompt Config
rel.001 publication stable validée de 0.1.2
```
## `0.1.3` — Configuration foundation
@@ -154,11 +176,13 @@ Périmètre candidat à revalider dans son `pre.001` :
- résolution ;
- validation ;
- modification/sauvegarde ;
- variables d'environnement `KS_*` / `KB_*` ;
- variables d'environnement `KSP_*` / `KSPB_*` ;
- secret/public/debug exposure policy ;
- `logging.config.json` séparé ;
- schemas sous `config/schemas/` ;
- examples sous `config/`.
- vrais fichiers runtime sous `config/`, schemas sous `config/schemas/` et exemples sous `config/examples/` ;
- documents unitaires spécialisés + fichiers composites par application/exécutable ;
- ownership exclusif de `ksp-config-lib` sur lecture/résolution/validation/mutation des fichiers Config et variables d'environnement ;
- accès explicite aux secrets pour les surfaces de management autorisées.
### Règle de scission

View File

@@ -1,13 +1,15 @@
<!-- file: docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md -->
<!-- version: 15 -->
<!-- version: 16 -->
# Plan KSP 0.1.2 — Logging foundation
## Statut
Plan actif de `0.1.2`, établi par `0.1.2-pre.001`, corrigé par `0.1.2-pre.001-fix.001`, concrétisé par la façade de `0.1.2-pre.002`, étendu au runtime subscriber par `0.1.2-pre.003`/`pre.003-fix.001`, puis complété et corrigé par `pre.004`/`pre.004-fix.001..004`. `pre.005` a fermé la phase d'intégration/robustesse : saturation déterministe, concurrence pendant hot reload, audit de takeover, validation des spans de timing, documentation de crate et probe d'overhead grossier. `pre.005-fix.001` a supprimé la pollution console du stress test concurrent sans réduire la pression de reload. `pre.006` est la prerelease finale : elle ajoute une validation async sur executor Tokio réel uniquement en dev-dependency, consolide la documentation durable et prépare le prompt `0.1.3 — ksp-config-lib`. Les validations utilisateur de `pre.006` sont propres, y compris le build normal de `ksp-logging-lib`, les deux tests Tokio, le probe d'overhead et les graphes Cargo confirmant que Tokio est uniquement une dev-dependency. `pre.006-fix.001` corrige ensuite uniquement le prompt Config : vrais fichiers sous `config/`, exemples sous `config/examples/`, namespaces `KSP_*`/`KSPB_*`, documents unitaires + composites, ownership exclusif de Config sur fichiers/env et accès explicite aux secrets pour les surfaces de management autorisées.
Plan historique **clôturé** par `0.1.2-rel.001`.
`pre.003-fix.001` a été validé dans l'environnement de développement avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres sur la version Cargo `0.1.2-pre.3.fix.1`. `pre.004` ajoute `tracing-appender`, remplace la console synchrone par un writer non bloquant, introduit le fichier `Never/Hourly/Daily`, possède les `WorkerGuard`, expose des compteurs cumulés de dropped lines, déporte le stripping ANSI côté worker fichier et conserve le hot reload transactionnel des sinks. `pre.004-fix.001` a rendu explicite le retrait des anciens layers avant leurs `WorkerGuard`, mais la validation utilisateur après `cargo clean` a reproduit exactement le même échec du marqueur fichier. Cette seconde validation a invalidé l'hypothèse selon laquelle ce défaut précis provenait du drain. La cause réelle est la sanitization ANSI native de `tracing-subscriber 0.3.23`, activée par défaut dans `fmt::Layer` : elle transforme les séquences de contrôle présentes dans les valeurs avant qu'elles n'atteignent le writer. `pre.004-fix.002` la conserve pour la console mais la désactive sur le formatter fichier afin que le `StripAnsiWriter` KSP, placé côté worker, reçoive les séquences ANSI originales et les supprime réellement. Le lifecycle explicite de `fix.001` est conservé car il reste correct pour le retrait des sinks non bloquants. La validation de `pre.004-fix.002` confirme ensuite que l'écriture fichier et le stripping ANSI fonctionnent, mais révèle que le target externe `sqlx` est encore persisté. La cause est la composition du filtre global comme enfant frère des formatters dans un `Vec<Layer>` : le `Vec` agrège l'intérêt de callsite en conservant l'intérêt le plus élevé de ses enfants, de sorte qu'un formatter intéressé peut masquer le `Interest::never()` du `Targets`. `pre.004-fix.003` compose donc `Targets` devant le `Vec` des sinks avec `Layer::and_then`; le filtre redevient global pour tout le groupe de sorties sans utiliser `with_filter`/`Filtered`. La validation de `pre.004-fix.003` confirme que tous les tests workspace passent, y compris le takeover externe et le fichier non bloquant, mais `cargo clippy --workspace --all-targets` signale encore `vec_init_then_push` dans la construction du composite reloadable. `pre.004-fix.004` applique uniquement cette correction de forme sans modifier le comportement runtime. La validation utilisateur finale de `pre.004-fix.004` sur `0.1.2-pre.4.fix.4` confirme `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test --workspace` propres ; le test runtime global passe avec takeover, fichier non bloquant, stripping ANSI et hot reload. Le graphe Cargo exécuté durant `pre.004` ne présentait aucun doublon et aucune activation KSP de `tracing-attributes`, `tracing-log`, `env-filter`, JSON/Serde ou ANSI formatter ; les dépendances n'ayant pas changé depuis, `pre.005` doit néanmoins refaire ces commandes avant validation de tranche.
La release stable `0.1.2` publie `ksp-logging-lib` comme façade KSP unique de logging/tracing runtime. Toutes les tranches prévues ont été réalisées puis validées jusqu'à `0.1.2-pre.6`; le correctif documentaire `pre.006-fix.001` a finalisé le prompt Config sans modifier le code ni la version Cargo. Aucune question architecturale bloquante ne reste ouverte pour cette release.
Les détails ci-dessous sont conservés comme historique de conception et de validation de `0.1.2`; ils ne constituent pas un plan actif pour `0.1.3`.
## Base auditée
@@ -1125,4 +1127,4 @@ La composition de reload est désormais fixée pour cette release à un `Vec` de
Aucune question architecturale bloquante ne reste ouverte pour la stable `0.1.2`. Le détail visuel exact du formatter humain reste volontairement non contractuel : sa ponctuation peut évoluer ultérieurement tant que les informations et garanties publiques documentées sont préservées.
La prochaine action après validation de `pre.006` est la livraison `0.1.2-rel.001`, le passage de `workspace.package.version` à `0.1.2`, les validations de publication puis le tag stable `v0.1.2`. La session fonctionnelle suivante est `0.1.3 — ksp-config-lib` avec le prompt `prompts/003-V0_1_3_START_PROMPT.md`.
La release est clôturée par `0.1.2-rel.001` avec `workspace.package.version = "0.1.2"`. Après validation du delta de publication, le commit stable reçoit le tag `v0.1.2`. La session fonctionnelle suivante est `0.1.3 — ksp-config-lib` avec le prompt `prompts/003-V0_1_3_START_PROMPT.md`.