diff --git a/deltas/0.1.3/pre.001-fix.003.md b/deltas/0.1.3/pre.001-fix.003.md new file mode 100644 index 0000000..81342b1 --- /dev/null +++ b/deltas/0.1.3/pre.001-fix.003.md @@ -0,0 +1,165 @@ + + + +# Delta 0.1.3-pre.001-fix.003 + +## Base requise + +Livraison précédente appliquée et commitée : + +```text +0.1.3-pre.001-fix.002 +``` + +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.003.zip +``` + +## Objectif + +Corriger le dimensionnement du plan `0.1.3` afin que les prereleases prévues restent compatibles avec la règle KSP de petites tranches d'environ 15–20 minutes de travail effectif, et rendre explicites les prereleases qui modifient `ksp-logging-lib` pour la non-régression multi-sink/routing. + +Aucune décision fonctionnelle validée dans `pre.001-fix.001/.002` n'est annulée. + +## 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.003 +``` + +## Fichiers ajoutés + +- `deltas/0.1.3/pre.001-fix.003.md` + +## Fichiers modifiés + +- `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md` — version documentaire 3 -> 4 ; +- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` — version documentaire 8 -> 9 ; +- `docs/plans/000-README.md` — version documentaire 10 -> 11. + +## Correction de `pre.002` + +`pre.002` n'agrège plus le bootstrap et le registre de fichiers. + +Elle est limitée à : + +```text +création ksp-config-lib +ConfigBootstrapOptions +default cfgpath = config +default schemapath = config/schemas +--cfgpath +--schemapath +validation/tests bootstrap +``` + +Le registre logique est déplacé en `pre.003`. + +## Nouvelle `pre.003` — registre `file_id` + +Cette tranche possède exclusivement : + +```text +ConfigFileId +ConfigFileKind +ConfigFileDescriptor +ConfigFileRegistry +file_id -> filename +--filemap== +validation des overrides +``` + +Aucune lecture JSON/schema n'est requise dans cette tranche. + +## Tranches `ksp-logging-lib` explicites + +Les ajouts/modifications Logging nécessaires ne sont plus regroupés dans une seule prerelease vague. + +### `pre.004` — contrats/settings multi-output + +- console configurable ; +- plusieurs outputs fichier ; +- `output_id` unique ; +- level/targets/domains par output ; +- format/ANSI/rotation ; +- validation publique des settings ; +- aucune dépendance Logging -> Config. + +### `pre.005` — runtime multi-sink + routing + +- création réelle de 0..N sinks fichier ; +- console indépendante ; +- routing/filter par output, level, target, domain ; +- non-blocking/guards ; +- conservation du subscriber unique, takeover et hot reload transactionnel ; +- tests de non-régression. + +Le schema `std.logging.json` n'est gelé qu'ensuite, en `pre.006`, sur la surface Logging effectivement stabilisée. + +## Découpage révisé + +```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 +``` + +Le nombre de prereleases n'est pas une cible à minimiser. Toute tranche qui devient manifestement supérieure au budget d'environ 15–20 minutes doit être scindée explicitement. + +## Invariants conservés + +- `ksp-config-lib` reste l'unique manager KSP des fichiers Config et variables applicatives ; +- `cfgpath`/`schemapath` restent bootstrap-only ; +- `file_id` reste l'identité logique stable, filename reste remplaçable ; +- process env > `.env` > fallback ; +- `${KSP_VAR}` / `${KSP_VAR:-fallback}` restent le modèle d'interpolation ; +- secrets conservent valeur réelle + représentation sûre/redacted ; +- Config construit les contrats Logging sans posséder le routing Logging ; +- `ksp-logging-lib` conserve subscriber/layers/writers/lifecycle/guards ; +- `LoggingGuard` reste orchestration-owned ; +- `0.1.4` reste la release prévue pour `ksp-app-config-desk`. + +## Validations exécutées + +Sur le delta documentaire : + +- contrôle des headers `file:` / `version:` ; +- contrôle que les versions documentaires progressent d'une unité ; +- contrôle que `pre.002` ne contient plus le registre `file_id` ; +- contrôle que `pre.003` possède le registre et `--filemap` ; +- contrôle que `pre.004` et `pre.005` mentionnent explicitement les modifications `ksp-logging-lib` ; +- contrôle que `std.logging.json`/son schema arrivent après ces tranches Logging ; +- contrôle du nouveau découpage jusqu'à `pre.014` ; +- contrôle que `Cargo.toml` n'est pas livré par ce fix. + +## Validations non exécutées + +Aucune commande Cargo n'est déclarée réussie pour ce correctif documentaire. Aucun code Rust, manifest ou fichier runtime n'est modifié. + +## Question ouverte avant `pre.002` + +Aucune question bloquante n'est conservée par défaut. Le plan regranularisé doit être validé par le user avant ouverture de `pre.002`. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index 48aca3f..2608ecf 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # 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`, 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`. +- [`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`. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index 2548759..a700483 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # Séquence des releases fonctionnelles KSP @@ -167,7 +167,7 @@ ksp-config-lib Introduire la configuration générale KSP. -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`. +Le `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, `pre.001-fix.002` puis `pre.001-fix.003`, 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 : @@ -198,6 +198,26 @@ 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` : + +```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 +``` + +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. + ## `0.1.4` — Config desktop par défaut La décision `0.1.3-pre.001` conserve cette release comme étape suivante par défaut. @@ -267,7 +287,7 @@ La première prerelease ne doit pas se transformer automatiquement en une grosse Chaque prerelease porte un objectif borné et cohérent. -Une tranche de travail de planification/développement manifestement trop grosse est scindée. +Une tranche de travail de planification/développement manifestement trop grosse est scindée. La cible de dimensionnement KSP est d'environ 15–20 minutes de travail effectif par prerelease ; ce budget est un garde-fou de granularité, pas une raison pour comprimer le périmètre. ## Dernière prerelease diff --git a/docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md b/docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md index 957c60e..4441916 100644 --- a/docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md +++ b/docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md @@ -1,11 +1,11 @@ - + # 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`, puis complété par `0.1.3-pre.001-fix.002` 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`, complété par `0.1.3-pre.001-fix.002`, puis regranularisé par `0.1.3-pre.001-fix.003` avant tout développement fonctionnel de Config. La base auditée reste la release stable `v0.1.2`. @@ -40,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.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. +`0.1.3-pre.001-fix.003` 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` @@ -1404,7 +1404,7 @@ 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`. +Cette liste n'impose pas de tout créer dans `pre.002`. Le découpage des prereleases doit respecter la règle KSP de petites tranches : une prerelease estimée au-delà d'environ 15–20 minutes de travail effectif doit être scindée avant ou pendant son exécution plutôt que comprimée artificiellement. ## 26. Audits et tests à introduire @@ -1538,7 +1538,9 @@ Tester : ## 27. Découpage souple des prereleases -### `0.1.3-pre.001` + `pre.001-fix.001/.002` — audit, brainstorming et plan corrigé +Le découpage ci-dessous applique explicitement la règle KSP de granularité : chaque tranche vise un objectif cohérent réalisable en environ 15–20 minutes de travail effectif. Si l'audit ou l'implémentation montre qu'une tranche dépasse sensiblement ce budget, elle doit être scindée par un delta explicite plutôt que compressée. + +### `0.1.3-pre.001` + `pre.001-fix.001/.002/.003` — audit, brainstorming et plan corrigé - audit `v0.1.2` ; - audit historique ciblé ; @@ -1550,86 +1552,153 @@ Tester : - 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 ; +- regranularisation du développement pour respecter le budget des petites tranches ; - aucune crate/dépendance fonctionnelle Config ajoutée. -### `0.1.3-pre.002` — bootstrap Config + registre de fichiers +### `0.1.3-pre.002` — crate Config + bootstrap des racines + +Objectif unique : créer la crate et fixer comment Config trouve ses deux racines avant toute lecture de document. - créer `ksp-config-lib` ; -- dépendances minimales réellement utilisées ; -- erreurs initiales ; +- dépendances KSP minimales réellement utilisées ; +- erreurs Config initiales strictement nécessaires ; - `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. +- parsing/contrat `--cfgpath` et `--schemapath` ; +- validation des deux paths ; +- tests unitaires du bootstrap ; +- **aucun registre `file_id` dans cette tranche**. -### `0.1.3-pre.003` — complétion bornée du contrat Logging +### `0.1.3-pre.003` — registre logique `file_id -> filename` -- é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. +Objectif unique : rendre les noms physiques remplaçables sans modifier l'identité logique des fichiers. -### `0.1.3-pre.004` — JSON/JSON Schema + `std.logging.json` +- `ConfigFileId` ; +- `ConfigFileKind` ; +- `ConfigFileDescriptor` ; +- `ConfigFileRegistry` ; +- mappings par défaut des documents/schemas connus ; +- parsing/contrat répétable `--filemap==` ; +- lookup/résolution/override du filename ; +- validation d'unicité, kind/racine, filename relatif et traversal ; +- tests du registre et des overrides ; +- aucune lecture JSON/schema encore nécessaire. + +### `0.1.3-pre.004` — `ksp-logging-lib` : modèle public multi-output + +Objectif unique : compléter les **contrats/settings publics** de Logging sans encore implémenter tout le routing runtime. + +- représenter une console configurable ; +- représenter zéro/un/plusieurs outputs fichier ; +- `output_id` unique ; +- level/filter par output ; +- sélection target et domain ; +- format/ANSI/rotation selon la nature du sink ; +- validation publique des settings ; +- préserver la façade/lifecycle existants ; +- aucun accès Config depuis Logging ; +- tests des contrats/settings. + +Cette tranche ne doit pas être gonflée par le runtime multi-sink complet. Si même le modèle public dépasse le budget, il est scindé avant de poursuivre. + +### `0.1.3-pre.005` — `ksp-logging-lib` : runtime multi-sink + routing + +Objectif unique : implémenter derrière les contrats de `pre.004` le comportement runtime manquant. + +- 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 ; +- conserver `initialize/reinitialize` transactionnel ; +- conserver drop counters et comportement de saturation ; +- tests de non-régression 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. + +### `0.1.3-pre.006` — 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` ; +- `std.logging.schema.json` aligné sur les contrats Logging réellement stabilisés en `pre.004/.005` ; - runtime `config/std.logging.json` ; - exemple Logging ; -- pipeline parse/schema/semantic ; -- `default_profile`, `profile_id`, globals et outputs Logging. +- parse/schema/validation sémantique de base. -### `0.1.3-pre.005` — profils + composition +### `0.1.3-pre.007` — globals + profils + `default_profile` + +- paramètres globaux hors profils ; +- `profile_id` unique ; +- `default_profile` autonome ; +- sélection/résolution d'un profil spécialisé ; +- héritage/usage des paramètres globaux par les profils selon le contrat retenu ; +- provenance document/global/profile ; +- tests sur `std.logging.json`. + +### `0.1.3-pre.008` — compositions génériques par `file_id` -- 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 ; +- références de documents exclusivement par `file_id` ; +- sélection/remplacement de profils documentaires ; +- résolution composition -> document -> profil/global ; - aucun composite runtime fictif obligatoire. -### `0.1.3-pre.006` — `.env` + resolver `${...}` +### `0.1.3-pre.009` — `.env` + process env + resolver `${...}` - lecture process env ; - lecture `.env` sans écrasement process ; - priorité process > `.env` > fallback ; - `${NAME}` / `${NAME:-fallback}` ; +- fallback appliqué seulement si la variable est absente ; - missing diagnostics + warning ; - namespaces KSP/KSPB ; - tests d'isolation process env. -### `0.1.3-pre.007` — sensibilité + valeurs real/safe + Logging adapter +### `0.1.3-pre.010` — sensibilité + valeurs real/safe/provenance - `Public/Internal/Secret` ; -- propagation par chaîne composée ; +- propagation de sensibilité par chaîne composée ; - redaction par segment ; - contrat `ResolvedValue` ou équivalent ; -- adaptation `ResolvedLoggingConfig ->` contrats publics Logging ; -- tests canary de non-divulgation ; -- démonstration `initialize/reinitialize` avec guard orchestration-owned. +- valeur réelle + représentation sûre + provenance ; +- interdiction des secrets dans logs/diagnostics ordinaires ; +- tests canary de non-divulgation. -### `0.1.3-pre.008` — management + persistence JSON/.env +### `0.1.3-pre.011` — adapter Config -> Logging + +- `ResolvedLoggingConfig` ; +- conversion explicite vers les contrats publics `ksp_logging_lib::*` ; +- aucune dépendance inverse ; +- démonstration `initialize/reinitialize` ; +- `LoggingGuard` orchestration-owned ; +- 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 - lecture management ; - reveal secret explicite ; -- mutation typed de `std.logging.json` ; +- mutation typée de `std.logging.json` ; - create/update/remove `.env` ; - persistence atomique ; -- desired/effective/shadow report. +- desired/effective/shadow report ; +- refus des mutations non autorisées. -### `0.1.3-pre.009` — ownership audits + robustesse +### `0.1.3-pre.013` — ownership audits + robustesse - audits interdisant les accès Config/env directs ailleurs ; - invalid documents/env/placeholders/file mappings ; - graphe dépendances/features ; - corrections de surface publique ; -- robustesse des diagnostics sans fuite. +- robustesse des diagnostics sans fuite ; +- vérification de la granularité réelle des responsabilités publiques. -### `0.1.3-pre.010` — clôture +### `0.1.3-pre.014` — clôture - validations finales ; - documentation durable ; @@ -1638,7 +1707,7 @@ Tester : - prompt `0.1.4 — ksp-app-config-desk` ; - préparation `rel.001` puis tag stable après validation utilisateur. -Le découpage reste souple et peut être corrigé par delta explicite. +Le découpage reste souple. Tout dépassement du budget de tranche est corrigé par une nouvelle scission explicite ; le nombre de prereleases n'est pas une cible à minimiser. ## 28. Hors scope confirmé @@ -1679,7 +1748,7 @@ 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.002` est validable lorsque les décisions suivantes sont acceptées : +Le `pre.001-fix.003` est validable lorsque les décisions suivantes sont acceptées : - `ksp-config-lib` est l'unique manager KSP des documents Config et variables applicatives ; - Config possède un registre logique de fichiers avec `file_id` globalement unique ; @@ -1716,6 +1785,9 @@ Le `pre.001-fix.002` 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.010` ; +- `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 ; +- `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 ; +- 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é.