khadhroony-solana-project/deltas/0.1.4/pre.009.md

<!-- file: deltas/0.1.4/pre.009.md -->
<!-- version: 1 -->

# `0.1.4-pre.009` — Documents + diagnostics

## 1. Base validée

Cette tranche part de `0.1.4-pre.8.fix.3`, validée localement avec :

- `cargo fmt --all` ;
- `cargo check --workspace` ;
- `cargo clippy --workspace --all-targets` ;
- tests `ksp-app-config-desk` ;
- tests `ksp-config-lib` ;
- `cargo tree -p ksp-app-config-desk` ;
- lancement réel `cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json`.

Le runtime Logging utilise désormais le profil `local_dev`, résout `KSP_DESK_SPLASH_MINIMUM_MS=12000` et `KSP_DESK_SPLASH_FADE_MS=3000` depuis `.env`, puis mesure environ `15003 ms` de lifecycle backend avant destruction du splash. Les activations de vues sont visibles sous `ksp-app-config-desk.frontend.main`.

## 2. Version technique

```text
workspace.package.version = "0.1.4-pre.9"
```

## 3. Surface Documents backend

La nouvelle unité `src/documents.rs` reste une couche applicative au-dessus de `ksp-config-lib` et n'effectue aucun accès filesystem direct.

Elle fournit :

- inventaire de tous les descripteurs de kind `Config` issus de `ConfigFileRegistry::descriptors()` ;
- path résolu via le registre/bootstrap Config ;
- validation backend via `ConfigDocumentEngine::load_validated_document()` ;
- contrôle effective supplémentaire pour `cfg.std.logging` via `ConfigEnvironment` + `load_resolved_logging_config()` ;
- source brut via `ConfigManagement::read_source()` ;
- persistence/réparation via `ConfigManagement::save_source_candidate()` ;
- reload du détail après persistence.

Le frontend ne devient autorité ni du parsing JSON, ni du schema, ni des invariants sémantiques/effectifs.

## 4. Classification des diagnostics

Les diagnostics sont classifiés côté Rust avant projection vers le frontend :

| Étape       | Signification                                        |
|-------------|------------------------------------------------------|
| `read`      | document Config principal non lisible                |
| `json`      | syntaxe JSON du document principal invalide          |
| `schema`    | schema manquant/invalide ou instance non conforme    |
| `semantic`  | invariant KSP sémantique invalide                    |
| `effective` | environnement/placeholders/config effective invalide |
| `other`     | erreur non classée dans les catégories précédentes   |
| `valid`     | validation complète réussie                          |

Les DTO d'erreur n'exposent jamais les contextes arbitraires ni les sources d'erreur KSP.

## 5. DTO/commandes Tauri

DTO TS-RS introduits :

```text
ConfigDocumentSummaryDto
ConfigDocumentDetailDto
ConfigDocumentSaveResultDto
ConfigDocumentErrorDto
```

Commandes Tauri centralisées dans `tauri.rs` :

```text
get_config_documents
get_config_document_detail
save_config_document_source
```

Le contenu source n'est jamais inclus dans les logs frontend/backend de ces opérations.

## 6. DataTables 3 + Select 4

Le tableau Documents exige tri, filtre/recherche, pagination et sélection simple. Conformément au gabarit KSP, ces fonctions sont fournies par DataTables plutôt que réimplémentées.

Dépendances frontend ajoutées sous `dependencies` :

```text
datatables.net-bs5 = ^3.0
datatables.net-select-bs5 = ^4.0
```

DataTables 3 est la génération stable publiée en juillet 2026 ; Select 4 est la génération correspondante.

Le module `frontend/ts/documents.ts` gère :

- inventaire ;
- DataTable Bootstrap 5 ;
- sélection simple ;
- chargement du détail ;
- édition du source brut ;
- validation/sauvegarde ;
- diagnostics et état de persistence ;
- instrumentation `debug`/`trace` des clics, sélections, chargements et remplacements DOM.

## 7. Règles Logging ajoutées

Deux exigences durables sont formalisées :

1. les fichiers de log applicatifs persistants doivent être uniques par lancement et intégrer l'identité de l'application ainsi qu'un timestamp de démarrage ;
2. le niveau applicatif temporairement élevé à `debug`/`trace` pendant développement/correction doit revenir à `info` ou `warn` avant release.

L'implémentation du nom de fichier unique par lancement est planifiée dans la tranche runtime Logging `pre.016`; le retour du target `ksp-app-config-desk` à `info`/`warn` est une condition de clôture `pre.019`.

## 8. Installation frontend

Après application du delta, depuis la racine :

```bash
cd crates/ksp-app-config-desk
npm install
cd ../../
```

Cette commande est uniquement une opération de gestion des dépendances. Le développement/build normal reste piloté par Tauri depuis la racine du workspace.

## 9. Validation demandée

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-app-config-desk
cargo test -p ksp-config-lib
cargo tree -p ksp-app-config-desk
cargo tauri dev -c crates/ksp-app-config-desk/tauri.conf.json
```

Test manuel minimum :

1. ouvrir **Documents** ;
2. vérifier recherche/tri/sélection DataTables ;
3. sélectionner `cfg.std.logging` ;
4. vérifier `file_id`, filename, schema, path, état et source ;
5. introduire volontairement une erreur JSON puis cliquer **Valider et sauvegarder** : le candidat doit être refusé et le fichier existant rester intact ;
6. corriger le source puis sauvegarder : le backend doit accepter et recharger le détail ;
7. vérifier que les logs décrivent les opérations sans contenir le source édité.

## 10. Fichiers modifiés/ajoutés

| Fichier                                               |  Action |
|-------------------------------------------------------|--------:|
| `Cargo.toml`                                          | modifié |
| `docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`        | modifié |
| `docs/rules/RULES_KSP.md`                             | modifié |
| `crates/ksp-app-config-desk/package.json`             | modifié |
| `crates/ksp-app-config-desk/README.md`                | modifié |
| `crates/ksp-app-config-desk/TODO.md`                  | modifié |
| `crates/ksp-app-config-desk/USAGE.md`                 | modifié |
| `crates/ksp-app-config-desk/src/app_state.rs`         | modifié |
| `crates/ksp-app-config-desk/src/constants.rs`         | modifié |
| `crates/ksp-app-config-desk/src/documents.rs`         |  ajouté |
| `crates/ksp-app-config-desk/src/errors.rs`            | modifié |
| `crates/ksp-app-config-desk/src/lib.rs`               | modifié |
| `crates/ksp-app-config-desk/src/tauri.rs`             | modifié |
| `crates/ksp-app-config-desk/unit_tests/documents.rs`  |  ajouté |
| `crates/ksp-app-config-desk/frontend/main.html`       | modifié |
| `crates/ksp-app-config-desk/frontend/sass/_app.scss`  | modifié |
| `crates/ksp-app-config-desk/frontend/ts/main.ts`      | modifié |
| `crates/ksp-app-config-desk/frontend/ts/documents.ts` |  ajouté |
| `deltas/0.1.4/pre.009.md`                             |  ajouté |