v0.1.3-pre.001-fix.002
This commit is contained in:
213
deltas/0.1.3/pre.001-fix.002.md
Normal file
213
deltas/0.1.3/pre.001-fix.002.md
Normal file
@@ -0,0 +1,213 @@
|
||||
<!-- file: deltas/0.1.3/pre.001-fix.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.1.3-pre.001-fix.002
|
||||
|
||||
## Base requise
|
||||
|
||||
Livraison précédente appliquée et commitée :
|
||||
|
||||
```text
|
||||
0.1.3-pre.001-fix.001
|
||||
```
|
||||
|
||||
Ce correctif reste documentaire et doit être validé avant toute ouverture de `pre.002`.
|
||||
|
||||
## Type de livraison
|
||||
|
||||
```text
|
||||
ksp-doc-0.1.3-pre.001-fix.002.zip
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Compléter le plan Config avec les décisions de bootstrap/fichiers et corriger le modèle Logging trop pauvre du fix précédent.
|
||||
|
||||
Le correctif fixe notamment :
|
||||
|
||||
- un registre KSP des fichiers connus avec `file_id` unique et mapping `file_id -> filename` ;
|
||||
- des mappings distincts pour documents Config et schemas, tous identifiés dans un namespace logique unique ;
|
||||
- des filenames par défaut codés dans `ksp-config-lib` mais surchargeables au démarrage ;
|
||||
- deux chemins bootstrap non récursifs avec défauts codés en dur : `config` et `config/schemas` ;
|
||||
- surcharge de ces chemins uniquement par `--cfgpath` / `--schemapath` ou options programmatiques explicites ;
|
||||
- surcharge répétable d'un filename connu par `--filemap=<file_id>=<filename>` ;
|
||||
- références des composites par `file_id` et jamais par filename ;
|
||||
- sélection/remplacement indépendant du filename d'un schema ;
|
||||
- choix de `serde`, `serde_json` et `jsonschema` comme base candidate du moteur JSON/schema ;
|
||||
- modèle `std.logging.json` enrichi avec profils identifiés, console configurable et plusieurs sinks fichier ;
|
||||
- routing Logging attendu par niveau, target et domain, avec rotation/format/ANSI selon le sink ;
|
||||
- constat explicite que `ksp-logging-lib 0.1.2` ne couvre pas encore toute cette surface ;
|
||||
- décision de compléter cette surface dans `ksp-logging-lib` sans déplacer le routing dans Config et sans créer de dépendance Logging -> Config.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Ce correctif modifie uniquement la documentation de planification.
|
||||
|
||||
Conformément à `VER-ID-008`, `workspace.package.version` reste :
|
||||
|
||||
```text
|
||||
0.1.3-pre.1
|
||||
```
|
||||
|
||||
Identifiant de livraison/commit :
|
||||
|
||||
```text
|
||||
0.1.3-pre.001-fix.002
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `deltas/0.1.3/pre.001-fix.002.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md` — version documentaire 2 -> 3 ;
|
||||
- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` — version documentaire 7 -> 8 ;
|
||||
- `docs/plans/000-README.md` — version documentaire 9 -> 10.
|
||||
|
||||
## Registre logique des fichiers
|
||||
|
||||
Le plan retient un namespace unique de `file_id` :
|
||||
|
||||
```text
|
||||
cfg.std.logging
|
||||
schema.std.logging
|
||||
schema.composite
|
||||
cfg.composite.<consumer>
|
||||
```
|
||||
|
||||
Premier mapping :
|
||||
|
||||
```text
|
||||
cfg.std.logging -> std.logging.json
|
||||
schema.std.logging -> std.logging.schema.json
|
||||
schema.composite -> composite.schema.json
|
||||
```
|
||||
|
||||
Un override ne change jamais le `file_id`, uniquement son filename physique.
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
--filemap=cfg.std.logging=my.logging.json
|
||||
--filemap=schema.std.logging=my.logging.schema.json
|
||||
```
|
||||
|
||||
Un composite référence donc :
|
||||
|
||||
```text
|
||||
cfg.std.logging
|
||||
```
|
||||
|
||||
et continue de fonctionner sans modification si le filename est remplacé au bootstrap.
|
||||
|
||||
## Bootstrap hors documents Config
|
||||
|
||||
Les seules racines nécessaires avant le chargement de Config sont :
|
||||
|
||||
```text
|
||||
cfgpath = config
|
||||
schemapath = config/schemas
|
||||
```
|
||||
|
||||
Elles ne sont résolues ni depuis JSON, ni depuis `.env`, ni depuis `KSP_*`/`KSPB_*`.
|
||||
|
||||
Seules les interfaces bootstrap suivantes peuvent les remplacer :
|
||||
|
||||
```text
|
||||
--cfgpath=/path/to/configs
|
||||
--schemapath=/path/to/schemas
|
||||
```
|
||||
|
||||
ou leur équivalent programmatique explicite possédé par `ksp-config-lib`.
|
||||
|
||||
## Audit Logging
|
||||
|
||||
L'audit du code stable `v0.1.2` confirme actuellement :
|
||||
|
||||
```text
|
||||
1 console optionnelle
|
||||
1 fichier optionnel
|
||||
rotation never/hourly/daily
|
||||
filtre global
|
||||
TargetFilter par préfixe de target
|
||||
initialize/reinitialize + LoggingGuard
|
||||
```
|
||||
|
||||
Il ne fournit pas encore :
|
||||
|
||||
```text
|
||||
plusieurs fichiers simultanés
|
||||
console_ansi configurable
|
||||
format configurable par sink
|
||||
routing indépendant par sink/target/domain/level
|
||||
```
|
||||
|
||||
La configuration historique bot3 possédait déjà plusieurs sorties console/fichier, niveaux, targets, rotation, format et ANSI.
|
||||
|
||||
`0.1.3` ne doit pas figer une configuration Logging régressive. Les capacités manquantes sont donc prévues comme une complétion bornée du domaine `ksp-logging-lib` avant gel du schema Logging. La propriété du subscriber, des layers, writers, settings, guard et du lifecycle reste intégralement dans Logging.
|
||||
|
||||
## Dépendances candidates vérifiées
|
||||
|
||||
Vérification documentaire effectuée le 15 août 2026 :
|
||||
|
||||
```text
|
||||
serde 1.0.229 -> ^1.0
|
||||
serde_json 1.0.151 -> ^1.0
|
||||
jsonschema 0.49.6 -> ^0.49
|
||||
```
|
||||
|
||||
Aucune de ces dépendances n'est ajoutée par ce correctif. Elles devront être revérifiées au delta qui les introduit réellement puis déclarées sous `[workspace.dependencies]`.
|
||||
|
||||
## Découpage révisé
|
||||
|
||||
La prévision devient :
|
||||
|
||||
```text
|
||||
pre.002 bootstrap Config + registre file_id
|
||||
pre.003 complétion bornée du contrat Logging
|
||||
pre.004 serde/serde_json/jsonschema + std.logging.json
|
||||
pre.005 profils + composition par file_id
|
||||
pre.006 .env + resolver ${...}
|
||||
pre.007 secrets real/safe + adapter Logging
|
||||
pre.008 management + persistence JSON/.env
|
||||
pre.009 audits ownership + robustesse
|
||||
pre.010 clôture
|
||||
```
|
||||
|
||||
Le découpage reste souple ; aucune tranche fonctionnelle n'est ouverte avant validation du plan corrigé.
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
Sur le delta documentaire :
|
||||
|
||||
- comparaison statique avec `pre.001-fix.001` ;
|
||||
- contrôle des headers `file:` / `version:` des quatre fichiers livrés ;
|
||||
- contrôle de la présence du nouveau delta ;
|
||||
- contrôle que l'archive ne contient que les trois documents modifiés et le delta ajouté ;
|
||||
- contrôle que `Cargo.toml` n'est pas livré par ce fix ;
|
||||
- contrôle des références `file_id`, `cfgpath`, `schemapath`, `--filemap` et du découpage `pre.002` -> `pre.010` dans le plan ;
|
||||
- contrôle de l'absence de secret réel dans le delta.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
Aucune commande Cargo n'est déclarée réussie pour ce correctif documentaire :
|
||||
|
||||
- le delta ne modifie ni code Rust, ni manifest, ni configuration runtime ;
|
||||
- `cargo` n'est pas disponible dans le sandbox de préparation utilisé pour cette livraison.
|
||||
|
||||
Les validations Cargo restent obligatoires dès les tranches fonctionnelles applicables.
|
||||
|
||||
## Décisions prises
|
||||
|
||||
- `file_id` est l'identité logique stable d'un fichier Config/schema ;
|
||||
- le filename est une localisation physique remplaçable ;
|
||||
- les composites dépendent de `file_id`, pas d'un nom de fichier ;
|
||||
- `cfgpath`/`schemapath` sont des paramètres bootstrap hors graphe Config ;
|
||||
- `serde_json` + `jsonschema` seront utilisés pour éviter une validation JSON maison ;
|
||||
- le modèle Logging doit rester au moins aussi expressif que les besoins utiles déjà présents dans bot3 ;
|
||||
- Config ne compense jamais un manque du backend Logging par un routing parallèle.
|
||||
|
||||
## Questions ouvertes avant `pre.002`
|
||||
|
||||
Aucune question bloquante n'est conservée par défaut. Le plan corrigé doit néanmoins être validé par le user avant ouverture de `pre.002`.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 9 -->
|
||||
<!-- version: 10 -->
|
||||
|
||||
# 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` puis corrigé par `pre.001-fix.001` 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`, puis complété par `pre.001-fix.002` avec le registre `file_id`, le bootstrap de chemins et la non-régression Logging avant développement fonctionnel de `ksp-config-lib`.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 7 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -167,10 +167,13 @@ ksp-config-lib
|
||||
|
||||
Introduire la configuration générale KSP.
|
||||
|
||||
Le `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, a revalidé ce périmètre et décidé qu'il tient dans une seule release à condition de limiter le premier cycle au socle générique, au document Logging, à la composition, à l'environnement KSP/KSPB, aux surfaces d'accès et à la persistence autorisée. Le plan normatif détaillé est `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`.
|
||||
Le `0.1.3-pre.001`, corrigé par `pre.001-fix.001` puis `pre.001-fix.002`, a revalidé ce périmètre et décidé qu'il tient dans une seule release à condition de limiter le premier cycle au socle générique, au document Logging, à la composition, à l'environnement KSP/KSPB, aux surfaces d'accès et à la persistence autorisée. Le plan normatif détaillé est `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`.
|
||||
|
||||
Périmètre retenu :
|
||||
|
||||
- registre logique `file_id -> filename` des fichiers Config/schemas connus, avec mappings par défaut surchargeables au bootstrap ;
|
||||
- bootstrap non récursif `--cfgpath` / `--schemapath` avec défauts codés en dur `config` / `config/schemas` ;
|
||||
- override répétable des filenames par `--filemap=<file_id>=<filename>` ;
|
||||
- documents spécialisés ;
|
||||
- profils ;
|
||||
- `default_profile` autonome ;
|
||||
@@ -182,11 +185,12 @@ Périmètre retenu :
|
||||
- priorité process env > `.env` > fallback `${NAME:-fallback}` ;
|
||||
- propagation de la sensibilité et représentation sûre/redacted des valeurs dérivées de `*_SECRET_*` ;
|
||||
- secret/public/debug exposure policy ;
|
||||
- premier document spécialisé concret `config/std.logging.json` ;
|
||||
- premier document spécialisé concret `config/std.logging.json`, identifié logiquement par `cfg.std.logging` et validé par `schema.std.logging` ;
|
||||
- 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 ;
|
||||
- documents unitaires spécialisés + fichiers composites par application/exécutable, avec références inter-document par `file_id` et non par filename ;
|
||||
- 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.
|
||||
- accès explicite aux secrets pour les surfaces de management autorisées ;
|
||||
- modèle Logging non régressif : console configurable et plusieurs sinks fichier/routings ; les capacités manquantes de `ksp-logging-lib 0.1.2` sont complétées dans Logging sans dépendance inverse vers Config.
|
||||
|
||||
### Décision de scission
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
<!-- file: docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Plan `0.1.3` — Configuration foundation
|
||||
|
||||
## 1. Statut et objectif
|
||||
|
||||
Ce plan a été établi par `0.1.3-pre.001`, puis corrigé par `0.1.3-pre.001-fix.001` avant tout développement fonctionnel de Config.
|
||||
Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001`, puis complété par `0.1.3-pre.001-fix.002` avant tout développement fonctionnel de Config.
|
||||
|
||||
La base auditée reste la release stable `v0.1.2`.
|
||||
|
||||
@@ -23,6 +23,8 @@ Elles passent par les contrats publics de `ksp-config-lib`.
|
||||
|
||||
`ksp-config-lib` doit fournir le moteur commun nécessaire à :
|
||||
|
||||
- un registre logique interne `file_id -> filename` pour tous les fichiers Config/schemas connus, avec identifiants uniques et mappings par défaut surchargeables au bootstrap ;
|
||||
- deux chemins bootstrap non récursifs (`cfgpath` et `schemapath`) possédés par Config, avec défauts codés en dur et surcharge uniquement par argument/paramètre de démarrage ;
|
||||
- la lecture des documents spécialisés JSON ;
|
||||
- la validation JSON Schema ;
|
||||
- les paramètres globaux hors profils ;
|
||||
@@ -38,7 +40,7 @@ Elles passent par les contrats publics de `ksp-config-lib`.
|
||||
- la création/modification/suppression des entrées du `.env` ;
|
||||
- la construction des contrats runtime nécessaires aux consommateurs, en commençant par `ksp_logging_lib::LoggingSettings`.
|
||||
|
||||
`0.1.3-pre.001-fix.001` reste une tranche documentaire de conception. Il ne crée pas encore `ksp-config-lib`, ne crée aucun fichier runtime Config et n'ajoute aucune dépendance fonctionnelle.
|
||||
`0.1.3-pre.001-fix.002` reste une tranche documentaire de conception. Il ne crée pas encore `ksp-config-lib`, ne crée aucun fichier runtime Config et n'ajoute aucune dépendance fonctionnelle.
|
||||
|
||||
## 2. Audit de la base stable `0.1.2`
|
||||
|
||||
@@ -89,7 +91,29 @@ initialize(...)
|
||||
reinitialize(...)
|
||||
```
|
||||
|
||||
Config ne redéfinit pas ces contrats. Il lit et résout sa configuration Logging, puis construit explicitement un `ksp_logging_lib::LoggingSettings`.
|
||||
L'audit réel du code `v0.1.2` montre cependant que cette surface est **plus étroite** que la configuration Logging historique de bot3 :
|
||||
|
||||
- une seule sortie console optionnelle ;
|
||||
- un seul sink fichier optionnel ;
|
||||
- rotation fichier `never/hourly/daily` ;
|
||||
- filtre par défaut + overrides par préfixe de target ;
|
||||
- formatter actuellement fixé par Logging ;
|
||||
- pas de sélection `console_ansi` publique ;
|
||||
- pas de plusieurs fichiers simultanés ;
|
||||
- pas de format `human/compact/pretty/json` sélectionnable par sink ;
|
||||
- pas de routage d'un sink par combinaison `target/domain/level` ;
|
||||
- `domain` reste aujourd'hui un champ structuré émis par le caller mais n'est pas un sélecteur public de routing.
|
||||
|
||||
La référence bot3 possédait déjà plusieurs sinks console/fichier, des niveaux et targets par sink, des formats, ANSI et rotation. KSP ne doit donc pas figer un `std.logging.json` qui constituerait une régression fonctionnelle par rapport à cette surface utile.
|
||||
|
||||
Décision :
|
||||
|
||||
- Config ne réimplémente jamais le routing Logging ;
|
||||
- `ksp-logging-lib` reste propriétaire de `LoggingSettings`, du subscriber, des layers, des writers et du lifecycle `initialize/reinitialize` ;
|
||||
- avant gel de `std.logging.schema.json`, la surface publique de Logging doit être complétée de manière bornée pour représenter les sinks/routings retenus par ce plan ;
|
||||
- cette complétion ne change ni la direction de dépendance ni la propriété du lifecycle Logging et n'introduit aucune lecture Config dans Logging.
|
||||
|
||||
Config lit/résout le document puis construit uniquement des contrats publics `ksp_logging_lib::*` suffisamment expressifs.
|
||||
|
||||
La direction de dépendance reste :
|
||||
|
||||
@@ -122,9 +146,12 @@ La référence historique bot3 utilisait déjà :
|
||||
- des placeholders comme `${KS_LOGS_DIRECTORY:-logs}` ;
|
||||
- des URLs composées contenant `${KS_SECRET_HELIUS_API_KEY}` ;
|
||||
- des compositions applicatives ;
|
||||
- une classification de sensibilité dérivée des placeholders.
|
||||
- une classification de sensibilité dérivée des placeholders ;
|
||||
- un document Logging avec `logs_directory`, `default_profile` et une liste de profils nommés ;
|
||||
- plusieurs sorties Logging par profil, chacune avec identifiant, activation, sink console/fichier, niveau, chemin, rotation, format, ANSI et liste de targets ;
|
||||
- plusieurs fichiers simultanés permettant notamment de séparer debug/info/error et des targets spécialisées.
|
||||
|
||||
Cette référence reste utile, mais KSP ne copie pas ses structures ni ses APIs aveuglément.
|
||||
Cette référence reste utile, mais KSP ne copie pas ses structures ni ses APIs aveuglément. En particulier, KSP utilise maintenant un target propriétaire égal au nom Cargo de la crate et des champs structurés comme `domain`; le nouveau modèle doit donc permettre un routing plus propre par `target` **et/ou** `domain` sans ressusciter artificiellement les anciens pseudo-targets hiérarchiques.
|
||||
|
||||
### 3.1 Principes conservés et renforcés
|
||||
|
||||
@@ -141,7 +168,8 @@ KSP conserve :
|
||||
- classification nominale des variables ;
|
||||
- propagation de la sensibilité la plus forte dans une valeur composée ;
|
||||
- distinction entre valeur réelle et représentation diagnostic sûre ;
|
||||
- DTO Tauri possédés par l'application et non par `ksp-config-lib`.
|
||||
- DTO Tauri possédés par l'application et non par `ksp-config-lib` ;
|
||||
- richesse de configuration Logging au moins équivalente aux besoins utiles de bot3, sans recopier ses limites de conception.
|
||||
|
||||
### 3.2 Corrections par rapport au plan `pre.001` initial
|
||||
|
||||
@@ -151,7 +179,8 @@ Le plan initial de `pre.001` avait retenu à tort :
|
||||
- une grammaire d'environnement KSP spéciale ;
|
||||
- l'interdiction de l'interpolation `${...}` ;
|
||||
- des bindings d'environnement prédéclarés clé Config -> variable ;
|
||||
- une lecture limitée aux variables enregistrées par ces bindings.
|
||||
- une lecture limitée aux variables enregistrées par ces bindings ;
|
||||
- un exemple `std.logging.json` réduit à une console + un fichier, alors que cette surface ne représente pas les besoins Logging déjà connus.
|
||||
|
||||
Ces décisions sont annulées.
|
||||
|
||||
@@ -161,22 +190,26 @@ La règle corrigée est :
|
||||
|
||||
Config peut également exposer une API explicite de lecture d'une variable par nom avec fallback optionnel pour les rares usages qui ne proviennent pas d'un document JSON, mais les consumers ne lisent jamais directement `std::env`.
|
||||
|
||||
Le nom physique d'un fichier Config ou schema n'est pas non plus son identité logique : toute référence inter-document passe par un `file_id` stable connu du registre Config.
|
||||
|
||||
## 4. Décision de périmètre : `0.1.3` reste une seule release
|
||||
|
||||
Le périmètre reste compatible avec une seule release si la première implémentation concrète reste bornée.
|
||||
Le périmètre reste compatible avec une seule release si l'implémentation reste découpée et si la complétion Logging est strictement bornée à la représentation/routage nécessaire au premier document Config réel.
|
||||
|
||||
La release construit le moteur générique nécessaire à :
|
||||
|
||||
1. documents JSON spécialisés ;
|
||||
2. schémas ;
|
||||
3. paramètres globaux ;
|
||||
4. profils et `default_profile` ;
|
||||
5. compositions ;
|
||||
6. `.env` + environnement du processus ;
|
||||
7. interpolation/fallback ;
|
||||
8. provenance/sensibilité/redaction ;
|
||||
9. mutation/persistence ;
|
||||
10. adaptation Logging.
|
||||
1. bootstrap Config non récursif (`cfgpath`, `schemapath`) ;
|
||||
2. registre logique des fichiers `file_id -> filename` et overrides de mapping au démarrage ;
|
||||
3. documents JSON spécialisés ;
|
||||
4. schémas ;
|
||||
5. paramètres globaux ;
|
||||
6. profils et `default_profile` ;
|
||||
7. compositions ;
|
||||
8. `.env` + environnement du processus ;
|
||||
9. interpolation/fallback ;
|
||||
10. provenance/sensibilité/redaction ;
|
||||
11. mutation/persistence ;
|
||||
12. adaptation Logging sans perte de capacités nécessaires.
|
||||
|
||||
Mais le seul document spécialisé runtime créé et exercé concrètement en `0.1.3` est :
|
||||
|
||||
@@ -189,34 +222,153 @@ Aucun `std.store.json`, `std.wallet.json`, `std.onchain-transport.json` ou autre
|
||||
La séquence reste :
|
||||
|
||||
```text
|
||||
0.1.3 ksp-config-lib
|
||||
0.1.3 ksp-config-lib + complétion bornée du contrat Logging nécessaire
|
||||
0.1.4 ksp-app-config-desk
|
||||
```
|
||||
|
||||
La complétion Logging n'ouvre ni une nouvelle façade ni une dépendance inverse : elle enrichit uniquement les contrats publics déjà possédés par `ksp-logging-lib` afin que Config puisse exprimer sans régression le document Logging.
|
||||
|
||||
## 5. Matrice de responsabilités
|
||||
|
||||
| Responsabilité | Propriétaire | Consommateurs | Interdit |
|
||||
|----------------------------------------------------------|--------------------------------------|------------------------------------|-----------------------------------------------------------|
|
||||
| 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 `LoggingSettings` | `ksp-logging-lib` | Config le construit | copie du type 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. Arborescence et nomenclature
|
||||
## 6. Registre de fichiers, bootstrap, arborescence et nomenclature
|
||||
|
||||
### 6.1 Documents runtime
|
||||
### 6.1 Identité logique : `file_id`
|
||||
|
||||
Les vrais documents JSON runtime appartiennent sous :
|
||||
`ksp-config-lib` possède un registre des fichiers qu'il sait interpréter. Un fichier n'est jamais identifié par son nom physique dans les contrats inter-documentaires.
|
||||
|
||||
Chaque entrée possède au minimum :
|
||||
|
||||
```text
|
||||
file_id unique
|
||||
kind = config_document | schema
|
||||
filename par défaut
|
||||
racine = cfgpath | schemapath
|
||||
schema_file_id éventuel pour un document Config
|
||||
```
|
||||
|
||||
Les `file_id` sont uniques dans **un même namespace global Config**, y compris entre documents et schemas. Préfixes retenus :
|
||||
|
||||
```text
|
||||
cfg.std.logging
|
||||
schema.std.logging
|
||||
schema.composite
|
||||
cfg.composite.<consumer>
|
||||
```
|
||||
|
||||
Premier mapping codé dans `ksp-config-lib` :
|
||||
|
||||
```text
|
||||
cfg.std.logging -> std.logging.json
|
||||
schema.std.logging -> std.logging.schema.json
|
||||
schema.composite -> composite.schema.json
|
||||
```
|
||||
|
||||
Le descriptor `cfg.std.logging` référence logiquement `schema.std.logging`; il ne contient pas le nom physique du schema.
|
||||
|
||||
Un futur consumer pourra introduire par le registre KSP :
|
||||
|
||||
```text
|
||||
cfg.composite.ksp-app-wallet-desk -> composite.ksp-app-wallet-desk.json
|
||||
```
|
||||
|
||||
avec validation par `schema.composite` tant qu'un schema plus spécialisé n'est pas nécessaire.
|
||||
|
||||
Un override change uniquement le **filename résolu**, jamais le `file_id`. Ainsi un composite continue de référencer `cfg.std.logging` même si l'utilisateur sélectionne `my-logging.local.json` au démarrage.
|
||||
|
||||
Par défaut, un override CLI d'un `file_id` inconnu est refusé : il ne doit pas permettre de contourner le type/schema que Config sait gérer.
|
||||
|
||||
### 6.2 Bootstrap non récursif : `cfgpath` et `schemapath`
|
||||
|
||||
Deux valeurs seulement doivent exister avant toute lecture de document Config :
|
||||
|
||||
```text
|
||||
DEFAULT_CFG_PATH = "config"
|
||||
DEFAULT_SCHEMA_PATH = "config/schemas"
|
||||
```
|
||||
|
||||
Ces défauts sont codés en dur dans `ksp-config-lib`.
|
||||
|
||||
Ils **ne peuvent pas** être définis ou remplacés par :
|
||||
|
||||
```text
|
||||
std.*.json
|
||||
composite.*.json
|
||||
.env
|
||||
KSP_*
|
||||
KSPB_*
|
||||
```
|
||||
|
||||
sinon Config aurait besoin de charger Config pour savoir où charger Config.
|
||||
|
||||
Ils peuvent changer uniquement au bootstrap par :
|
||||
|
||||
```text
|
||||
--cfgpath=/path/to/configs
|
||||
--schemapath=/path/to/schemas
|
||||
```
|
||||
|
||||
ou par l'équivalent programmatique explicite de `ConfigBootstrapOptions` lorsqu'un caller embarque Config sans CLI.
|
||||
|
||||
`ksp-config-lib` doit posséder l'interprétation de ces options. Un binaire peut lui transmettre les arguments bruts ou construire explicitement le type public prévu, mais ne doit pas réimplémenter leur sémantique.
|
||||
|
||||
Les deux chemins sont indépendants : remplacer `cfgpath` ne remplace pas implicitement `schemapath`.
|
||||
|
||||
### 6.3 Override des mappings physiques au bootstrap
|
||||
|
||||
Le registre utilise ses filenames par défaut sauf surcharge explicite au démarrage.
|
||||
|
||||
Syntaxe CLI retenue pour le plan, répétable :
|
||||
|
||||
```text
|
||||
--filemap=<file_id>=<filename>
|
||||
```
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
--filemap=cfg.std.logging=my.logging.json
|
||||
--filemap=schema.std.logging=my.logging.schema.json
|
||||
--filemap=cfg.composite.ksp-app-wallet-desk=wallet-desk.local.json
|
||||
```
|
||||
|
||||
Équivalent conceptuel programmatique :
|
||||
|
||||
```text
|
||||
ConfigBootstrapOptions
|
||||
.with_file_mapping(file_id, filename)
|
||||
```
|
||||
|
||||
Garanties :
|
||||
|
||||
- dernier override explicite d'un même `file_id` gagne ou duplication est refusée selon la règle qui sera figée avec le parser CLI ;
|
||||
- filename absolu interdit dans un mapping : la racine reste possédée par `cfgpath`/`schemapath` ;
|
||||
- traversal hors racine (`..`) refusé ;
|
||||
- le mapping final est consultable via diagnostics/management sans exposer de secret ;
|
||||
- les compositions référencent des `file_id`, jamais les filenames résolus.
|
||||
|
||||
### 6.4 Documents runtime
|
||||
|
||||
Les vrais documents JSON runtime appartiennent par défaut sous :
|
||||
|
||||
```text
|
||||
config/
|
||||
@@ -225,7 +377,7 @@ config/
|
||||
Nomenclature retenue pour les documents spécialisés/unitaires :
|
||||
|
||||
```text
|
||||
config/std.<domain>.json
|
||||
std.<domain>.json
|
||||
```
|
||||
|
||||
Premier fichier concret :
|
||||
@@ -242,9 +394,9 @@ config/std.wallet.json
|
||||
config/std.onchain-transport.json
|
||||
```
|
||||
|
||||
### 6.2 Compositions
|
||||
### 6.5 Compositions
|
||||
|
||||
Les compositions propres à un exécutable/application utilisent :
|
||||
Les compositions propres à un exécutable/application utilisent par défaut :
|
||||
|
||||
```text
|
||||
config/composite.<consumer>.json
|
||||
@@ -256,11 +408,13 @@ Exemple futur :
|
||||
config/composite.ksp-app-wallet-desk.json
|
||||
```
|
||||
|
||||
Leur identité logique reste `cfg.composite.<consumer>`; le filename peut être remplacé par `--filemap` sans modifier leur contenu logique.
|
||||
|
||||
Aucun composite runtime fictif n'est créé avant l'existence d'un consumer concret. Le moteur et le schéma génériques peuvent néanmoins être testés dans `0.1.3` par fixtures/examples.
|
||||
|
||||
### 6.3 Schémas
|
||||
### 6.6 Schémas
|
||||
|
||||
Les schémas appartiennent sous :
|
||||
Les schémas appartiennent par défaut sous :
|
||||
|
||||
```text
|
||||
config/schemas/
|
||||
@@ -273,14 +427,16 @@ config/schemas/std.logging.schema.json
|
||||
config/schemas/composite.schema.json
|
||||
```
|
||||
|
||||
La nomenclature d'un futur document suit la même famille :
|
||||
Chaque schema possède également un `file_id` et son filename peut être surchargé indépendamment :
|
||||
|
||||
```text
|
||||
std.store.json
|
||||
std.store.schema.json
|
||||
schema.std.logging
|
||||
schema.composite
|
||||
```
|
||||
|
||||
### 6.4 Exemples
|
||||
Le choix du schema applicable provient du descriptor Config, pas d'un filename construit par convention à chaque lecture.
|
||||
|
||||
### 6.7 Exemples
|
||||
|
||||
Les exemples appartiennent sous :
|
||||
|
||||
@@ -297,23 +453,21 @@ config/examples/composite.example.json
|
||||
|
||||
Les exemples ne contiennent aucun vrai secret.
|
||||
|
||||
### 6.5 `.env`
|
||||
### 6.8 `.env`
|
||||
|
||||
Le fichier d'environnement local par défaut est le fichier conventionnel :
|
||||
Le fichier d'environnement local par défaut reste le fichier conventionnel :
|
||||
|
||||
```text
|
||||
.env
|
||||
```
|
||||
|
||||
à la racine runtime/workspace fournie à Config.
|
||||
à la racine de lancement du processus (`./.env`) capturée au bootstrap. `0.1.3` n'introduit pas de troisième path configurable pour `.env`; il n'est ni un substitut de `cfgpath` ni de `schemapath`.
|
||||
|
||||
Il reste ignoré par Git. Un éventuel `.env.example` peut être versionné plus tard lorsqu'une première variable concrète doit être documentée.
|
||||
|
||||
La racine runtime et les chemins Config doivent être fournis explicitement à la session/locator Config ; `ksp-config-lib` ne doit pas rendre son comportement dépendant d'un current working directory implicite.
|
||||
|
||||
## 7. Contrat commun des documents JSON
|
||||
|
||||
Chaque document JSON KSP possède une version de format :
|
||||
Chaque document JSON KSP est chargé à partir de son `file_id` résolu par le registre, puis possède une version de format :
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -326,7 +480,7 @@ Politique :
|
||||
- `format_version` obligatoire ;
|
||||
- version inconnue refusée ;
|
||||
- JSON syntaxiquement invalide refusé ;
|
||||
- validation par le schéma correspondant avant utilisation runtime ;
|
||||
- validation par le schema référencé par le descriptor du `file_id` avant utilisation runtime ;
|
||||
- invariants sémantiques supplémentaires après validation schema ;
|
||||
- document source modifiable représenté par un type sérialisable ;
|
||||
- configuration effective contenant potentiellement des secrets non sérialisable aveuglément ;
|
||||
@@ -341,42 +495,110 @@ Le schéma source doit donc autoriser explicitement une valeur littérale ou une
|
||||
|
||||
Logging est le seul composant runtime existant qui justifie aujourd'hui un document Config réel.
|
||||
|
||||
Structure conceptuelle candidate :
|
||||
Le modèle ne doit pas être réduit à la surface actuelle « une console + un fichier » de `LoggingSettings 0.1.2`. Il doit conserver les besoins déjà connus : plusieurs profils, console configurable, plusieurs sorties fichier simultanées et routing par target/domain/niveau.
|
||||
|
||||
Structure conceptuelle candidate révisée :
|
||||
|
||||
```json
|
||||
{
|
||||
"format_version": 1,
|
||||
"logs_directory": "${KSP_LOGS_DIRECTORY:-logs}",
|
||||
"default_profile": "default",
|
||||
"default_profile": "local_dev",
|
||||
"profiles": [
|
||||
{
|
||||
"name": "default",
|
||||
"default_filter": "info",
|
||||
"profile_id": "local_dev",
|
||||
"default_filter": "warn",
|
||||
"span_events": "new_and_close",
|
||||
"console": {
|
||||
"output": "stdout"
|
||||
},
|
||||
"file": {
|
||||
"file_name_prefix": "ksp",
|
||||
"rotation": "daily"
|
||||
"enabled": true,
|
||||
"output": "stderr",
|
||||
"ansi": true,
|
||||
"format": "compact",
|
||||
"filter": {
|
||||
"level": "debug",
|
||||
"targets": ["*"],
|
||||
"domains": ["*"]
|
||||
}
|
||||
},
|
||||
"files": [
|
||||
{
|
||||
"output_id": "file.all.debug",
|
||||
"enabled": true,
|
||||
"path": "debug.log",
|
||||
"rotation": "daily",
|
||||
"format": "human",
|
||||
"ansi": false,
|
||||
"filter": {
|
||||
"level": "debug",
|
||||
"targets": ["*"],
|
||||
"domains": ["*"]
|
||||
}
|
||||
},
|
||||
{
|
||||
"output_id": "file.config.error",
|
||||
"enabled": true,
|
||||
"path": "config/error.jsonl",
|
||||
"rotation": "daily",
|
||||
"format": "json",
|
||||
"ansi": false,
|
||||
"filter": {
|
||||
"level": "error",
|
||||
"targets": ["ksp-config-lib"],
|
||||
"domains": ["config"]
|
||||
}
|
||||
}
|
||||
],
|
||||
"target_filters": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Ce JSON reste **conceptuel** jusqu'à validation du contrat public Logging correspondant. Il fixe néanmoins les capacités attendues.
|
||||
|
||||
Décisions :
|
||||
|
||||
- `logs_directory` est global, hors profils ;
|
||||
- son fallback est exprimé dans le document au point d'usage ;
|
||||
- `default_profile` est global et référence un profil existant ;
|
||||
- les noms de profils sont uniques ;
|
||||
- `file` ne duplique pas le répertoire global ;
|
||||
- console/file peuvent être désactivés selon le schéma final ;
|
||||
- `target_filters` conserve l'ordre source ;
|
||||
- Config valide le document puis construit `LoggingSettings` ;
|
||||
- `LoggingSettings::validate()` reste l'ultime validation du contrat Logging.
|
||||
- `default_profile` est global et référence un `profile_id` existant ;
|
||||
- `profile_id` est obligatoire et unique dans le document ;
|
||||
- `default_filter` gouverne le comportement général du profil ;
|
||||
- la console est un sink spécialisé avec `enabled`, `output`, `ansi`, `format` et son filtre ;
|
||||
- `files[]` peut contenir zéro, un ou plusieurs sinks fichier ;
|
||||
- chaque sink fichier possède un `output_id` unique dans le profil ;
|
||||
- le nom `output_id` est volontairement distinct du `file_id` global de Config afin de ne pas confondre identité d'un document Config et identité d'une sortie Logging ;
|
||||
- `path` d'un sink fichier est relatif à `logs_directory` sauf contrat futur explicite ;
|
||||
- chaque sink peut filtrer au minimum par niveau et par target ;
|
||||
- KSP doit également pouvoir sélectionner par `domain` puisque les macros KSP utilisent déjà ce champ structuré ;
|
||||
- wildcard `*` signifie « tous » dans la dimension concernée ;
|
||||
- `rotation` doit au moins conserver `never/hourly/daily`; d'autres politiques ne sont ajoutées qu'après vérification du backend ;
|
||||
- `format` doit au moins couvrir les formats utiles retenus (`human`, `compact`, `pretty`, `json`) si Logging peut les offrir proprement ;
|
||||
- `ansi` doit être configurable pour la console et doit rester `false`/sans séquences persistées pour les fichiers ;
|
||||
- `target_filters` reste disponible pour la politique générale de takeover/overrides et n'est pas remplacé par les filtres de sink ;
|
||||
- Config valide le document puis construit des settings/sinks publics Logging ;
|
||||
- la validation propre à Logging reste l'ultime validation de son contrat runtime.
|
||||
|
||||
### 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 |
|
||||
|
||||
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.
|
||||
|
||||
`std.logging.json` sert de premier test réel du moteur générique, mais son modèle ne doit pas enfermer Config dans Logging.
|
||||
|
||||
@@ -413,7 +635,7 @@ Un `default_profile` absent peut être autorisé uniquement pour un type de docu
|
||||
|
||||
## 10. Contrat de composition générique
|
||||
|
||||
Une composition assemble plusieurs documents spécialisés sans dupliquer leur contenu.
|
||||
Une composition assemble plusieurs documents spécialisés sans dupliquer leur contenu et les référence par **`file_id` logique**, jamais par filename.
|
||||
|
||||
Structure conceptuelle :
|
||||
|
||||
@@ -423,15 +645,15 @@ Structure conceptuelle :
|
||||
"default_profile": "default",
|
||||
"documents": {
|
||||
"logging": {
|
||||
"source": "std.logging.json"
|
||||
"file_id": "cfg.std.logging"
|
||||
}
|
||||
},
|
||||
"profiles": [
|
||||
{
|
||||
"name": "default",
|
||||
"profile_id": "default",
|
||||
"documents": {
|
||||
"logging": {
|
||||
"profile": "default"
|
||||
"profile_id": "local_dev"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -441,17 +663,19 @@ Structure conceptuelle :
|
||||
|
||||
Principes :
|
||||
|
||||
- la composition référence des documents spécialisés ;
|
||||
- la composition référence des documents spécialisés par `file_id` ;
|
||||
- le registre résout ensuite ce `file_id` vers le filename effectif ;
|
||||
- un `--filemap=cfg.std.logging=...` remplace donc le fichier physique sans modifier le composite ;
|
||||
- chaque document conserve ses globals ;
|
||||
- une composition peut choisir le profil d'un document ;
|
||||
- sans choix explicite, le `default_profile` du document est utilisé ;
|
||||
- le composite ne recopie pas les paramètres spécialisés ;
|
||||
- un profil composite assemble donc les **paramètres globaux** du document et le **profil sélectionné** de ce document ;
|
||||
- un document référencé est toujours lu et résolu par Config ;
|
||||
- profil/document inexistant = erreur ;
|
||||
- un document référencé est toujours lu, validé et résolu par Config ;
|
||||
- `file_id`/profil inexistant = erreur ;
|
||||
- aucun JSON patch générique n'est introduit en `0.1.3` sans besoin concret.
|
||||
|
||||
Cette structure répond au besoin « un composite pioche dans les documents et leurs profils/paramètres » sans dupliquer les valeurs.
|
||||
Cette structure répond au besoin « un composite pioche dans les documents et leurs profils/paramètres » tout en rendant les filenames remplaçables au bootstrap.
|
||||
|
||||
Les références cross-document à une propriété individuelle ne sont pas ouvertes tant qu'un cas concret ne les exige pas.
|
||||
|
||||
@@ -907,11 +1131,13 @@ La stratégie exacte d'écriture atomique et la dépendance éventuelle sont aud
|
||||
|
||||
### 19.4 Chemins
|
||||
|
||||
Les documents sous `config/` sont bornés par un `ConfigRoot` explicite.
|
||||
Les documents Config sont bornés par le `cfgpath` effectif et les schemas par le `schemapath` effectif.
|
||||
|
||||
Les compositions ne doivent pas pouvoir sortir de cette frontière par un chemin absolu ou `..` non autorisé.
|
||||
Un mapping `file_id -> filename` ne peut pas transformer un filename en chemin absolu ni sortir de sa racine par `..`.
|
||||
|
||||
Le `.env` est une source distincte, localisée par un chemin de session Config explicite avec défaut workspace/runtime `.env`.
|
||||
Les compositions ne fournissent aucun chemin physique : elles référencent uniquement des `file_id`.
|
||||
|
||||
Le `.env` est une source distincte fixée à `./.env` pour `0.1.3`; il ne sert pas à relocaliser `cfgpath` ou `schemapath`.
|
||||
|
||||
## 20. Surface runtime, diagnostic et management
|
||||
|
||||
@@ -1042,6 +1268,12 @@ config.schema_validation_failed
|
||||
config.invalid_document
|
||||
config.profile_not_found
|
||||
config.invalid_composition
|
||||
config.invalid_bootstrap_option
|
||||
config.invalid_config_path
|
||||
config.invalid_schema_path
|
||||
config.unknown_file_id
|
||||
config.duplicate_file_id
|
||||
config.invalid_file_mapping
|
||||
config.path_outside_root
|
||||
config.invalid_environment_name
|
||||
config.dotenv_read_failed
|
||||
@@ -1061,17 +1293,29 @@ Une erreur liée à `KSP_SECRET_*` peut contenir le **nom** de variable et son o
|
||||
|
||||
## 24. Dépendances externes candidates
|
||||
|
||||
Aucune dépendance n'est ajoutée dans `pre.001-fix.001`.
|
||||
Aucune dépendance n'est ajoutée dans `pre.001-fix.002`.
|
||||
|
||||
Les besoins prévisibles sont :
|
||||
Le choix de base est désormais clair :
|
||||
|
||||
- `serde` : source typed sérialisable/désérialisable ;
|
||||
- `serde_json` : JSON ;
|
||||
- moteur JSON Schema ;
|
||||
- éventuellement une primitive d'écriture atomique ;
|
||||
- `serde` pour les structures source typées et la serialization/deserialization ;
|
||||
- `serde_json` pour le JSON source, les valeurs intermédiaires et la persistence ;
|
||||
- `jsonschema` pour la validation JSON Schema ;
|
||||
- éventuellement une primitive d'écriture atomique lorsque la tranche de persistence l'introduit ;
|
||||
- éventuellement une bibliothèque dotenv **uniquement si** elle permet la lecture sans mutation globale du processus et si sa sémantique est compatible avec le contrat KSP.
|
||||
|
||||
Les versions courantes et les features sont vérifiées uniquement au delta qui introduit réellement la dépendance, puis déclarées sous `[workspace.dependencies]` avec la contrainte de génération retenue par les règles KSP.
|
||||
Vérification effectuée pendant `pre.001-fix.002` le 15 août 2026 :
|
||||
|
||||
```text
|
||||
serde 1.0.229 -> génération candidate ^1.0
|
||||
serde_json 1.0.151 -> génération candidate ^1.0
|
||||
jsonschema 0.49.6 -> génération candidate ^0.49
|
||||
```
|
||||
|
||||
Ces versions ne sont pas ajoutées par ce fix documentaire. Elles doivent être revérifiées au delta qui introduit réellement chaque dépendance, conformément aux règles Cargo KSP.
|
||||
|
||||
`jsonschema` est retenu comme moteur candidat principal plutôt qu'une validation maison. Son API actuelle sait construire des validators réutilisables et gérer les drafts JSON Schema ; `std.logging.schema.json` devra déclarer explicitement le draft KSP retenu.
|
||||
|
||||
Les dépendances externes communes sont déclarées uniquement sous `[workspace.dependencies]`, puis consommées avec `.workspace = true`.
|
||||
|
||||
### 24.1 Parser dotenv
|
||||
|
||||
@@ -1100,6 +1344,8 @@ Structure interne candidate :
|
||||
```text
|
||||
src/lib.rs
|
||||
src/error.rs
|
||||
src/bootstrap.rs
|
||||
src/file_registry.rs
|
||||
src/document.rs
|
||||
src/schema.rs
|
||||
src/profile.rs
|
||||
@@ -1119,7 +1365,14 @@ Les modules restent privés ; l'API utile est réexportée au crate-root.
|
||||
Types conceptuels à faire émerger au besoin :
|
||||
|
||||
```text
|
||||
ConfigRoot
|
||||
ConfigBootstrapOptions
|
||||
ConfigPath
|
||||
SchemaPath
|
||||
ConfigFileId
|
||||
ConfigFileKind
|
||||
ConfigFileDescriptor
|
||||
ConfigFileRegistry
|
||||
ResolvedConfigFile
|
||||
ConfigSession
|
||||
ConfigDocumentKind
|
||||
ConfigSource
|
||||
@@ -1136,9 +1389,21 @@ ConfigChangeReport
|
||||
ConfigManagementAccess
|
||||
LoggingConfigDocument
|
||||
LoggingProfileConfig
|
||||
LoggingOutputConfig
|
||||
LoggingOutputFilterConfig
|
||||
ResolvedLoggingConfig
|
||||
```
|
||||
|
||||
Le registre doit exposer au minimum :
|
||||
|
||||
```text
|
||||
lookup(file_id)
|
||||
resolve_filename(file_id)
|
||||
override_filename(file_id, filename)
|
||||
```
|
||||
|
||||
avec validation du kind/racine et refus d'un `file_id` inconnu.
|
||||
|
||||
Cette liste n'impose pas de tout créer dans `pre.002`.
|
||||
|
||||
## 26. Audits et tests à introduire
|
||||
@@ -1150,16 +1415,28 @@ Empêcher les accès applicatifs directs hors Config :
|
||||
- `std::env::var`, `var_os`, `vars` pour `KSP_*`/`KSPB_*` ;
|
||||
- loaders dotenv directs ;
|
||||
- lecture/écriture directe des documents `config/std.*.json` et `config/composite.*.json` ;
|
||||
- filenames Config/schema codés dans les consumers au lieu d'un `file_id` ;
|
||||
- parsing divergent de `--cfgpath`, `--schemapath` ou `--filemap` hors de la surface Config prévue ;
|
||||
- dépendance directe `tracing*` depuis Config ;
|
||||
- dépendance inverse Logging -> Config ;
|
||||
- Tauri/TS-RS dans Config sans décision explicite.
|
||||
|
||||
L'audit doit être ciblé afin de ne pas interdire des usages système de `std::env` sans rapport avec la configuration applicative.
|
||||
|
||||
### 26.2 Documents/schemas
|
||||
### 26.2 Bootstrap/registre/documents/schemas
|
||||
|
||||
Tester :
|
||||
|
||||
- défauts `config` et `config/schemas` ;
|
||||
- `--cfgpath` seul n'altère pas `schemapath` ;
|
||||
- `--schemapath` seul n'altère pas `cfgpath` ;
|
||||
- aucune variable env/`.env`/JSON ne peut changer ces deux paths ;
|
||||
- lookup d'un `file_id` connu ;
|
||||
- `file_id` inconnu refusé ;
|
||||
- override de filename connu ;
|
||||
- override de schema filename indépendant ;
|
||||
- filename absolu/traversal refusé ;
|
||||
- composite inchangé lorsque le mapping physique est remplacé ;
|
||||
- JSON invalide ;
|
||||
- schema invalide ;
|
||||
- format version absent/inconnu ;
|
||||
@@ -1167,8 +1444,7 @@ Tester :
|
||||
- `default_profile` ;
|
||||
- profils dupliqués ;
|
||||
- profil absent ;
|
||||
- composition valide/invalide ;
|
||||
- chemin hors `ConfigRoot`.
|
||||
- composition valide/invalide.
|
||||
|
||||
### 26.3 Environnement
|
||||
|
||||
@@ -1237,22 +1513,32 @@ Tester :
|
||||
- failure avant commit conserve ancien contenu ;
|
||||
- chemins gérés respectés.
|
||||
|
||||
### 26.6 Logging adapter
|
||||
### 26.6 Logging adapter et non-régression
|
||||
|
||||
Tester :
|
||||
|
||||
- `logs_directory` global avec fallback ;
|
||||
- unicité des `profile_id` ;
|
||||
- sélection de profil ;
|
||||
- conversion de chaque enum ;
|
||||
- console/file ;
|
||||
- target filters ;
|
||||
- `LoggingSettings::validate()` ;
|
||||
- console enabled/output/ANSI/format ;
|
||||
- zéro/un/plusieurs sinks fichier ;
|
||||
- unicité des `output_id` ;
|
||||
- rotation/format de chaque fichier ;
|
||||
- routing par target ;
|
||||
- routing par domain ;
|
||||
- niveau par sink ;
|
||||
- target filters globaux ;
|
||||
- combinaison wildcard/spécialisation ;
|
||||
- hot reload conservé ;
|
||||
- writers/guards/drop counters conservés ou généralisés proprement ;
|
||||
- validation publique Logging ;
|
||||
- changement Config sans reconfiguration implicite ;
|
||||
- `LoggingGuard` reste orchestration-owned.
|
||||
- `LoggingGuard` reste orchestration-owned ;
|
||||
- canary démontrant qu'aucun comportement utile déjà offert par la configuration bot3 n'est perdu silencieusement.
|
||||
|
||||
## 27. Découpage souple des prereleases
|
||||
|
||||
### `0.1.3-pre.001` + `pre.001-fix.001` — audit, brainstorming et plan corrigé
|
||||
### `0.1.3-pre.001` + `pre.001-fix.001/.002` — audit, brainstorming et plan corrigé
|
||||
|
||||
- audit `v0.1.2` ;
|
||||
- audit historique ciblé ;
|
||||
@@ -1260,37 +1546,53 @@ Tester :
|
||||
- correction vers `.env` conventionnel ;
|
||||
- interpolation `${...}` + fallback ;
|
||||
- modèle real/safe/provenance/sensitivity ;
|
||||
- aucune crate/dépendance fonctionnelle Config.
|
||||
- registre `file_id -> filename` + schemas ;
|
||||
- bootstrap `cfgpath`/`schemapath` non récursif ;
|
||||
- audit de non-régression Logging et modèle `std.logging.json` enrichi ;
|
||||
- choix `serde`/`serde_json`/`jsonschema` comme base candidate ;
|
||||
- aucune crate/dépendance fonctionnelle Config ajoutée.
|
||||
|
||||
### `0.1.3-pre.002` — fondation de crate + contrats source
|
||||
### `0.1.3-pre.002` — bootstrap Config + registre de fichiers
|
||||
|
||||
- créer `ksp-config-lib` ;
|
||||
- dépendances minimales réellement utilisées ;
|
||||
- erreurs initiales ;
|
||||
- `ConfigRoot`/session/locator ;
|
||||
- contrat commun document/version ;
|
||||
- premiers types `std.logging` source ;
|
||||
- tests initiaux.
|
||||
- `ConfigBootstrapOptions` ;
|
||||
- défauts hardcodés `config` / `config/schemas` ;
|
||||
- parsing/contrat `--cfgpath`, `--schemapath`, `--filemap` ;
|
||||
- `ConfigFileId`/descriptors/registre/mappings ;
|
||||
- tests bootstrap sans ouvrir encore le moteur complet.
|
||||
|
||||
### `0.1.3-pre.003` — JSON Schema + `std.logging.json`
|
||||
### `0.1.3-pre.003` — complétion bornée du contrat Logging
|
||||
|
||||
- étendre les settings publics Logging uniquement où l'audit `0.1.2` montre un gap ;
|
||||
- plusieurs sinks fichier ;
|
||||
- console ANSI/format selon faisabilité du backend ;
|
||||
- filters de sink par niveau/target/domain ;
|
||||
- préserver subscriber unique, takeover, hot reload transactionnel, non-blocking, guards et compteurs ;
|
||||
- aucun accès Config depuis Logging.
|
||||
|
||||
### `0.1.3-pre.004` — JSON/JSON Schema + `std.logging.json`
|
||||
|
||||
- `serde`/`serde_json`/`jsonschema` au workspace avec versions revérifiées ;
|
||||
- `config/`, `config/schemas/`, `config/examples/` ;
|
||||
- `std.logging.schema.json` ;
|
||||
- runtime `config/std.logging.json` ;
|
||||
- exemple Logging ;
|
||||
- pipeline parse/schema/semantic ;
|
||||
- `default_profile` et globals.
|
||||
- `default_profile`, `profile_id`, globals et outputs Logging.
|
||||
|
||||
### `0.1.3-pre.004` — profils + composition
|
||||
### `0.1.3-pre.005` — profils + composition
|
||||
|
||||
- résolution de profils spécialisés ;
|
||||
- contrat composite générique ;
|
||||
- schema/example composite ;
|
||||
- références de documents par `file_id` ;
|
||||
- sélection de profils documentaires ;
|
||||
- provenance document/global/profile ;
|
||||
- aucun composite runtime fictif obligatoire.
|
||||
|
||||
### `0.1.3-pre.005` — `.env` + resolver `${...}`
|
||||
### `0.1.3-pre.006` — `.env` + resolver `${...}`
|
||||
|
||||
- lecture process env ;
|
||||
- lecture `.env` sans écrasement process ;
|
||||
@@ -1300,17 +1602,17 @@ Tester :
|
||||
- namespaces KSP/KSPB ;
|
||||
- tests d'isolation process env.
|
||||
|
||||
### `0.1.3-pre.006` — sensibilité + valeurs real/safe + Logging adapter
|
||||
### `0.1.3-pre.007` — sensibilité + valeurs real/safe + Logging adapter
|
||||
|
||||
- `Public/Internal/Secret` ;
|
||||
- propagation par chaîne composée ;
|
||||
- redaction par segment ;
|
||||
- contrat `ResolvedValue` ou équivalent ;
|
||||
- adaptation `ResolvedLoggingConfig -> LoggingSettings` ;
|
||||
- adaptation `ResolvedLoggingConfig ->` contrats publics Logging ;
|
||||
- tests canary de non-divulgation ;
|
||||
- démonstration `initialize/reinitialize` avec guard orchestration-owned.
|
||||
|
||||
### `0.1.3-pre.007` — management + persistence JSON/.env
|
||||
### `0.1.3-pre.008` — management + persistence JSON/.env
|
||||
|
||||
- lecture management ;
|
||||
- reveal secret explicite ;
|
||||
@@ -1319,15 +1621,15 @@ Tester :
|
||||
- persistence atomique ;
|
||||
- desired/effective/shadow report.
|
||||
|
||||
### `0.1.3-pre.008` — ownership audits + robustesse
|
||||
### `0.1.3-pre.009` — ownership audits + robustesse
|
||||
|
||||
- audits interdisant les accès Config/env directs ailleurs ;
|
||||
- invalid documents/env/placeholders ;
|
||||
- invalid documents/env/placeholders/file mappings ;
|
||||
- graphe dépendances/features ;
|
||||
- corrections de surface publique ;
|
||||
- robustesse des diagnostics sans fuite.
|
||||
|
||||
### `0.1.3-pre.009` — clôture
|
||||
### `0.1.3-pre.010` — clôture
|
||||
|
||||
- validations finales ;
|
||||
- documentation durable ;
|
||||
@@ -1377,17 +1679,27 @@ Une commande non exécutée n'est jamais déclarée réussie.
|
||||
|
||||
## 30. Critères de validation du plan avant `pre.002`
|
||||
|
||||
Le `pre.001-fix.001` est validable lorsque les décisions suivantes sont acceptées :
|
||||
Le `pre.001-fix.002` est validable lorsque les décisions suivantes sont acceptées :
|
||||
|
||||
- `ksp-config-lib` est l'unique manager KSP des documents Config et variables applicatives ;
|
||||
- premier document réel : `config/std.logging.json` ;
|
||||
- Config possède un registre logique de fichiers avec `file_id` globalement unique ;
|
||||
- les documents et schemas connus disposent d'un mapping par défaut `file_id -> filename` ;
|
||||
- les composites référencent les documents par `file_id`, jamais par filename ;
|
||||
- les mappings physiques peuvent être remplacés au bootstrap, y compris pour les schemas ;
|
||||
- `cfgpath` et `schemapath` ont les défauts hardcodés `config` et `config/schemas` ;
|
||||
- ces deux paths ne peuvent être remplacés ni par JSON, ni `.env`, ni `KSP_*`/`KSPB_*` ;
|
||||
- ils ne changent qu'au bootstrap via `--cfgpath`/`--schemapath` ou options programmatiques explicites ;
|
||||
- `--filemap=<file_id>=<filename>` est le mécanisme de sélection d'un filename alternatif ;
|
||||
- premier document réel : `config/std.logging.json` identifié par `cfg.std.logging` ;
|
||||
- futurs documents : `config/std.<domain>.json` ;
|
||||
- futurs composites : `config/composite.<consumer>.json` ;
|
||||
- JSON validé par schema avant usage ;
|
||||
- JSON validé par `jsonschema` contre le schema associé au descriptor du `file_id` ;
|
||||
- `serde` + `serde_json` constituent la base de parsing/manipulation/persistence ;
|
||||
- globals hors profils ;
|
||||
- `default_profile` autonome ;
|
||||
- profils identifiés par `profile_id` unique ;
|
||||
- composite assemble documents + globals + profils sans recopier les valeurs ;
|
||||
- `.env` conventionnel à la racine runtime/workspace ;
|
||||
- `.env` conventionnel `./.env` à la racine de lancement, sans troisième path Config dans `0.1.3` ;
|
||||
- environnement du processus > `.env` > fallback ;
|
||||
- fallback déclaré par `${KSP_VAR:-fallback}` ;
|
||||
- fallback utilisé seulement lorsque la variable est absente ; une chaîne vide compte comme définie ;
|
||||
@@ -1400,7 +1712,10 @@ Le `pre.001-fix.001` est validable lorsque les décisions suivantes sont accept
|
||||
- une chaîne composée conserve valeur réelle + valeur sûre + provenance + sensibilité ;
|
||||
- `ksp-app-config-desk` pourra révéler/modifier les secrets via une surface management privilégiée ;
|
||||
- même cette application ne logge jamais les secrets ;
|
||||
- Config construit `LoggingSettings` et l'orchestration possède `LoggingGuard` ;
|
||||
- `std.logging.json` supporte conceptuellement une console configurable et plusieurs sinks fichier avec identifiants uniques, niveaux, targets, domains, rotation, format et ANSI selon la nature du sink ;
|
||||
- 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 ;
|
||||
- `0.1.3` reste une release unique bornée avec clôture prévisionnelle en `pre.010` ;
|
||||
- aucune implémentation `pre.002` ne commence avant validation utilisateur de ce plan corrigé.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user