Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.3-pre.005

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-15 20:22:02 +02:00
parent 29660fd9f0
commit 063b24ee1c
17 changed files with 957 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/plans/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/000-README.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Plans KSP
@@ -13,7 +13,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
- [`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 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`.
- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan actif de `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, complété par `pre.001-fix.002` pour le registre `file_id`/bootstrap/non-régression Logging, puis regranularisé par `pre.001-fix.003` pour séparer le bootstrap, le registre et les deux tranches Logging avant développement fonctionnel de `ksp-config-lib`.
- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan actif de `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, complété par `pre.001-fix.002` pour le registre `file_id`/bootstrap/non-régression Logging, regranularisé par `pre.001-fix.003`, puis rescindé pendant `pre.005` pour traiter séparément le routing structuré `domain` avant le premier schema Logging.
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.

25
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Séquence des releases fonctionnelles KSP
@@ -198,22 +198,23 @@ Le `pre.001` ne scinde pas Config : `0.1.3` reste une release unique et `0.1.4`
Cette décision repose sur l'absence volontaire de documents Transport/Wallet/Store/Execution et de watcher générique dans le premier cycle. Si une tranche ultérieure révèle une contrainte technique majeure réellement non bornable, la séquence peut encore être corrigée par un delta explicite plutôt que de comprimer artificiellement le périmètre.
Prévision souple regranularisée par `pre.001-fix.003` :
Prévision souple regranularisée par `pre.001-fix.003`, puis scindée à nouveau pendant `pre.005` afin de traiter `domain` comme un champ structuré distinct :
```text
pre.002 crate Config + bootstrap cfgpath/schemapath
pre.003 registre file_id -> filename + --filemap
pre.004 Logging : contrats/settings multi-output
pre.005 Logging : runtime multi-sink + routing/filter
pre.006 JSON/JSON Schema + std.logging.json
pre.007 globals + profils + default_profile
pre.008 compositions génériques par file_id
pre.009 .env + process env + resolver ${...}
pre.010 sensibilité + real/safe/provenance
pre.011 adapter Config -> Logging
pre.012 management + persistence JSON/.env
pre.013 ownership audits + robustesse
pre.014 clôture
pre.005 Logging : runtime multi-sink + level/target/formats
pre.006 Logging : routing structuré domain
pre.007 JSON/JSON Schema + std.logging.json
pre.008 globals + profils + default_profile
pre.009 compositions génériques par file_id
pre.010 .env + process env + resolver ${...}
pre.011 sensibilité + real/safe/provenance
pre.012 adapter Config -> Logging
pre.013 management + persistence JSON/.env
pre.014 ownership audits + robustesse
pre.015 clôture
```
Cette prévision n'est pas un plafond : chaque prerelease doit rester une petite tranche, avec scission explicite si l'objectif dépasse environ 15–20 minutes de travail effectif.

151
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
View File

@@ -1,11 +1,11 @@
<!-- file: docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Plan `0.1.3` — Configuration foundation
## 1. Statut et objectif
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, et `pre.004` étend maintenant les contrats publics de `ksp-logging-lib` nécessaires au futur `std.logging.json` sans ouvrir encore le runtime multi-sink complet.
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, `pre.004` les contrats publics multi-output de Logging, et `pre.005` active le runtime multi-sink sur niveau/target/formats. Le routing structuré `domain` est scindé en `pre.006` avant le gel du premier schema Logging.
La base auditée reste la release stable `v0.1.2`.
@@ -230,25 +230,25 @@ La complétion Logging n'ouvre ni une nouvelle façade ni une dépendance invers
## 5. Matrice de responsabilités
| Responsabilité | Propriétaire | Consommateurs | Interdit |
|---|---|---|---|
| Définir les `file_id` connus et leur mapping par défaut | `ksp-config-lib` | bootstrap Config | noms physiques codés dans les consumers |
| Résoudre `file_id -> filename` | `ksp-config-lib` | session Config | référence inter-document par filename |
| Interpréter `--cfgpath`, `--schemapath` et overrides de mapping KSP | `ksp-config-lib` | applications qui transmettent argv/options | parser ces options différemment dans chaque binaire |
| Lire un document Config JSON | `ksp-config-lib` | crates/apps via API Config | lecture directe par consumer |
| Valider JSON Schema | `ksp-config-lib` | orchestration/management | validation divergente dans chaque crate |
| Résoudre globals/profils/compositions | `ksp-config-lib` | orchestration | résolution locale dans un binaire |
| Lire `KSP_*` / `KSPB_*` du processus | `ksp-config-lib` | crates/apps via API Config | `std::env::var*` applicatif hors Config |
| Lire `.env` | `ksp-config-lib` | crates/apps via API Config | loader dotenv direct hors Config |
| Résoudre `${...}` et fallback | `ksp-config-lib` | tous les consumers | interpolation locale dans les consumers |
| Classer sensibilité et construire une valeur sûre | `ksp-config-lib` | runtime/logging/diagnostics | redaction ad hoc dans chaque crate |
| Modifier/sauvegarder JSON Config | `ksp-config-lib` | management explicite | écriture directe par application |
| Créer/modifier/supprimer une entrée `.env` | `ksp-config-lib` | management explicite | édition directe par application |
| Modifier l'environnement externe du shell/systemd/parent | propriétaire externe de ce processus | Config le lit seulement | prétendre qu'un child process peut administrer son parent |
| Posséder les settings/sinks/routing Logging | `ksp-logging-lib` | Config construit les contrats publics | logique de routing dupliquée dans Config |
| Posséder `LoggingGuard` | orchestration/application | lifecycle Logging | singleton Config global |
| Initialiser/recharger Logging | orchestration | Config fournit settings/changement | Logging lisant Config |
| DTO/bindings Tauri | application Tauri | frontend | TS-RS automatique dans Config |
| Responsabilité | Propriétaire | Consommateurs | Interdit |
|---------------------------------------------------------------------|--------------------------------------|--------------------------------------------|-----------------------------------------------------------|
| Définir les `file_id` connus et leur mapping par défaut | `ksp-config-lib` | bootstrap Config | noms physiques codés dans les consumers |
| Résoudre `file_id -> filename` | `ksp-config-lib` | session Config | référence inter-document par filename |
| Interpréter `--cfgpath`, `--schemapath` et overrides de mapping KSP | `ksp-config-lib` | applications qui transmettent argv/options | parser ces options différemment dans chaque binaire |
| Lire un document Config JSON | `ksp-config-lib` | crates/apps via API Config | lecture directe par consumer |
| Valider JSON Schema | `ksp-config-lib` | orchestration/management | validation divergente dans chaque crate |
| Résoudre globals/profils/compositions | `ksp-config-lib` | orchestration | résolution locale dans un binaire |
| Lire `KSP_*` / `KSPB_*` du processus | `ksp-config-lib` | crates/apps via API Config | `std::env::var*` applicatif hors Config |
| Lire `.env` | `ksp-config-lib` | crates/apps via API Config | loader dotenv direct hors Config |
| Résoudre `${...}` et fallback | `ksp-config-lib` | tous les consumers | interpolation locale dans les consumers |
| Classer sensibilité et construire une valeur sûre | `ksp-config-lib` | runtime/logging/diagnostics | redaction ad hoc dans chaque crate |
| Modifier/sauvegarder JSON Config | `ksp-config-lib` | management explicite | écriture directe par application |
| Créer/modifier/supprimer une entrée `.env` | `ksp-config-lib` | management explicite | édition directe par application |
| Modifier l'environnement externe du shell/systemd/parent | propriétaire externe de ce processus | Config le lit seulement | prétendre qu'un child process peut administrer son parent |
| Posséder les settings/sinks/routing Logging | `ksp-logging-lib` | Config construit les contrats publics | logique de routing dupliquée dans Config |
| Posséder `LoggingGuard` | orchestration/application | lifecycle Logging | singleton Config global |
| Initialiser/recharger Logging | orchestration | Config fournit settings/changement | Logging lisant Config |
| DTO/bindings Tauri | application Tauri | frontend | TS-RS automatique dans Config |
## 6. Registre de fichiers, bootstrap, arborescence et nomenclature
@@ -580,23 +580,23 @@ Décisions :
### 8.1 Écart `ksp-logging-lib 0.1.2` à fermer
| Capacité | `0.1.2` | Requise par `std.logging.json` |
|---|---:|---:|
| filtre global | oui | oui |
| overrides par target | oui | oui |
| lifecycle spans | oui | oui |
| console stdout/stderr | oui | oui |
| console enabled | via `Option` | oui explicite |
| console ANSI configurable | non | oui |
| format console configurable | non | oui |
| plusieurs fichiers | non | oui |
| rotation par fichier | un seul fichier | oui par sink |
| format par fichier | non | oui |
| filtre par sink/target | non | oui |
| filtre par sink/domain | non | oui |
| filtre par sink/niveau | non indépendant | oui |
| hot reload transactionnel | oui | à conserver |
| non-blocking/guards/drop counters | oui | à conserver et généraliser par sinks |
| Capacité | `0.1.2` | Requise par `std.logging.json` |
|-----------------------------------|----------------:|-------------------------------------:|
| filtre global | oui | oui |
| overrides par target | oui | oui |
| lifecycle spans | oui | oui |
| console stdout/stderr | oui | oui |
| console enabled | via `Option` | oui explicite |
| console ANSI configurable | non | oui |
| format console configurable | non | oui |
| plusieurs fichiers | non | oui |
| rotation par fichier | un seul fichier | oui par sink |
| format par fichier | non | oui |
| filtre par sink/target | non | oui |
| filtre par sink/domain | non | oui |
| filtre par sink/niveau | non indépendant | oui |
| hot reload transactionnel | oui | à conserver |
| non-blocking/guards/drop counters | oui | à conserver et généraliser par sinks |
Ce tableau est un **gap identifié**, pas une invitation à déplacer Logging dans Config. La tranche qui le ferme modifie `ksp-logging-lib` uniquement dans son domaine propriétaire.
@@ -1646,37 +1646,68 @@ Implémentation candidate livrée par `pre.004` :
- jusqu'à `pre.005`, `initialize/reinitialize` refusent explicitement les nouvelles capacités qu'ils ne savent pas encore appliquer (plusieurs fichiers actifs, formats enrichis, ANSI console ou routing par output) plutôt que de les ignorer silencieusement ;
- aucune dépendance Config n'entre dans Logging et aucune dépendance externe supplémentaire n'est ajoutée.
La validation utilisateur de `pre.004` reste requise avant l'ouverture de `pre.005`.
`pre.004` a été validée par l'utilisateur le 2026-08-15 avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, `cargo test --workspace` et les trois vues `cargo tree -p ksp-logging-lib` demandées, sans warning ni échec.
### `0.1.3-pre.005` — `ksp-logging-lib` : runtime multi-sink + routing
### `0.1.3-pre.005` — `ksp-logging-lib` : runtime multi-sink + routing metadata
Objectif unique : implémenter derrière les contrats de `pre.004` le comportement runtime manquant.
Objectif unique : activer derrière les contrats de `pre.004` les capacités runtime bornées aux métadonnées directement disponibles par output.
- 0..N fichiers simultanés ;
- console indépendante ;
- routing/filter par output, level, target et domain ;
- rotation/format/ANSI selon settings ;
- writers non bloquants et guards ;
- conserver subscriber unique et takeover ;
- routing/filter par output sur level + target ;
- rotation/format `Human/Compact/Pretty/Json` ;
- ANSI console configurable, jamais persisté dans les fichiers ;
- writers non bloquants et guards indépendants ;
- compteurs agrégés conservés + compteur cumulatif fichier par `output_id` ;
- conserver subscriber unique et takeover global KSP ;
- conserver `initialize/reinitialize` transactionnel ;
- conserver drop counters et comportement de saturation ;
- tests de non-régression et hot reload.
- conserver le comportement de saturation ;
- tests multi-sink, formats, routing metadata et hot reload.
Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent pas proprement ensemble dans le budget, `pre.005` est scindée avant implémentation ; le numéro de clôture est alors décalé explicitement.
Décision de scission prise pendant l'implémentation : `domain` est un champ structuré et ne doit être ni assimilé au target ni filtré approximativement au niveau du writer. `pre.005` refuse donc explicitement tout output actif avec `domains != ["*"]`.
### `0.1.3-pre.006` — JSON/JSON Schema + premier document Logging
Implémentation candidate de `pre.005` :
- chaque formatter possède son writer routé par `OutputFilter.level` + `OutputFilter.targets` ;
- la politique globale `default_filter` + `TargetFilter` reste composée devant tout le groupe de sinks ;
- les layers reloadables ne deviennent pas des `Filtered`, afin de préserver la composition/hot reload stabilisée en `0.1.2` ;
- `tracing-subscriber` active ses features `json` et `ansi` pour les formats publics déjà décidés en `pre.004` ;
- `LoggingGuard::dropped_file_lines(output_id)` expose le compteur cumulatif d'un fichier à travers les reloads ;
- `DroppedLines` conserve la vue agrégée console/fichier ;
- JSON + ANSI console est refusé comme combinaison incohérente ;
- aucune dépendance Config n'entre dans Logging.
La validation utilisateur de `pre.005` est requise avant l'ouverture de `pre.006`.
### `0.1.3-pre.006` — `ksp-logging-lib` : routing structuré `domain`
Objectif unique : fermer proprement la dimension `OutputFilter.domains[]` avant que Config ne fige le schema Logging.
- extraire le champ structuré `domain` des events/spans ;
- définir la sémantique d'un event portant son propre `domain` ;
- définir l'héritage depuis le span courant lorsqu'un event ne porte pas de `domain` ;
- définir le comportement des spans sans domain et des spans imbriqués ;
- appliquer les selectors domain par output sans casser level/target ;
- conserver les événements lifecycle `SpanEvents` cohérents avec le domain du span ;
- préserver les champs formatés requis par les différents formatters ;
- conserver hot reload, takeover et non-blocking ;
- tests unitaires/intégration sur events, spans, héritage et plusieurs sinks.
Une solution qui réduirait `domain` à une convention de target est interdite : il s'agit d'une dimension structurée distincte.
### `0.1.3-pre.007` — JSON/JSON Schema + premier document Logging
- `serde`/`serde_json`/`jsonschema` au workspace avec versions revérifiées ;
- infrastructure générique de lecture JSON ;
- association descriptor -> schema par `file_id` ;
- validation JSON Schema ;
- `config/`, `config/schemas/`, `config/examples/` ;
- `std.logging.schema.json` aligné sur les contrats Logging réellement stabilisés en `pre.004/.005` ;
- `std.logging.schema.json` aligné sur les contrats Logging réellement stabilisés en `pre.004/.005/.006` ;
- runtime `config/std.logging.json` ;
- exemple Logging ;
- parse/schema/validation sémantique de base.
### `0.1.3-pre.007` — globals + profils + `default_profile`
### `0.1.3-pre.008` — globals + profils + `default_profile`
- paramètres globaux hors profils ;
- `profile_id` unique ;
@@ -1686,7 +1717,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- provenance document/global/profile ;
- tests sur `std.logging.json`.
### `0.1.3-pre.008` — compositions génériques par `file_id`
### `0.1.3-pre.009` — compositions génériques par `file_id`
- contrat composite générique ;
- schema/example composite ;
@@ -1695,7 +1726,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- résolution composition -> document -> profil/global ;
- aucun composite runtime fictif obligatoire.
### `0.1.3-pre.009` — `.env` + process env + resolver `${...}`
### `0.1.3-pre.010` — `.env` + process env + resolver `${...}`
- lecture process env ;
- lecture `.env` sans écrasement process ;
@@ -1706,7 +1737,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- namespaces KSP/KSPB ;
- tests d'isolation process env.
### `0.1.3-pre.010` — sensibilité + valeurs real/safe/provenance
### `0.1.3-pre.011` — sensibilité + valeurs real/safe/provenance
- `Public/Internal/Secret` ;
- propagation de sensibilité par chaîne composée ;
@@ -1716,7 +1747,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- interdiction des secrets dans logs/diagnostics ordinaires ;
- tests canary de non-divulgation.
### `0.1.3-pre.011` — adapter Config -> Logging
### `0.1.3-pre.012` — adapter Config -> Logging
- `ResolvedLoggingConfig` ;
- conversion explicite vers les contrats publics `ksp_logging_lib::*` ;
@@ -1726,7 +1757,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- tests de mapping multi-output/filter/domain ;
- vérification qu'aucune valeur secrète n'est utilisée dans les diagnostics Logging.
### `0.1.3-pre.012` — management + persistence JSON/.env
### `0.1.3-pre.013` — management + persistence JSON/.env
- lecture management ;
- reveal secret explicite ;
@@ -1736,7 +1767,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- desired/effective/shadow report ;
- refus des mutations non autorisées.
### `0.1.3-pre.013` — ownership audits + robustesse
### `0.1.3-pre.014` — ownership audits + robustesse
- audits interdisant les accès Config/env directs ailleurs ;
- invalid documents/env/placeholders/file mappings ;
@@ -1745,7 +1776,7 @@ Si l'audit de `pre.004` montre que multi-sink et routing/hot-reload ne tiennent
- robustesse des diagnostics sans fuite ;
- vérification de la granularité réelle des responsabilités publiques.
### `0.1.3-pre.014` — clôture
### `0.1.3-pre.015` — clôture
- validations finales ;
- documentation durable ;
@@ -1832,9 +1863,9 @@ Le `pre.001-fix.003` est validable lorsque les décisions suivantes sont accept
- l'écart de capacités de `ksp-logging-lib 0.1.2` est reconnu et sera fermé dans Logging, pas contourné par Config ;
- le lifecycle/ownership Logging `initialize/reinitialize/LoggingGuard` reste inchangé ;
- persistence JSON et `.env` atomique ;
- `0.1.3` reste une release unique bornée avec clôture prévisionnelle en `pre.014`, sous réserve de nouvelles scissions explicites si une tranche dépasse le budget 15–20 minutes ;
- `0.1.3` reste une release unique bornée avec clôture prévisionnelle désormais en `pre.015`, sous réserve de nouvelles scissions explicites si une tranche dépasse le budget 15–20 minutes ;
- `pre.002` est limitée à la création de la crate et au bootstrap `cfgpath`/`schemapath`; le registre `file_id` commence en `pre.003` ;
- les évolutions `ksp-logging-lib` sont explicites en `pre.004` (contrats/settings multi-output) puis `pre.005` (runtime multi-sink/routing), avant gel du schema Logging ;
- les évolutions `ksp-logging-lib` sont explicites en `pre.004` (contrats/settings), `pre.005` (runtime multi-sink + level/target/formats) puis `pre.006` (routing structuré domain), avant gel du schema Logging ;
- chaque prerelease vise environ 15–20 minutes de travail effectif et doit être scindée si ce budget devient manifestement irréaliste ;
- aucune implémentation `pre.002` ne commence avant validation utilisateur de ce plan corrigé.