Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
500b87ef57e2131a39f6ef032e655f05c1d62423
khadhroony-solana-project/docs/validation/024-V0_3_7_BACKFILL_DESK.md
SinuS Von SifriduS 500b87ef57 v0.3.7-pre.005
2026-09-02 12:01:35 +02:00

256 lines
20 KiB
Markdown
Raw Blame History

<!-- file: docs/validation/024-V0_3_7_BACKFILL_DESK.md -->
<!-- version: 6 -->
# Validation v0.3.7 — Backfill Desk
## 1. Gate pre.001
- [X] Archive KSP v0.3.6 testée intégralement avant travail.
- [X] Archive kbot3 testée intégralement et extraite dans un arbre séparé.
- [X] Aucune entrée ZIP absolue, traversal, séparateur inversé ou lien symbolique détecté.
- [X] `workspace.package.version = 0.3.6` confirmé sur la base.
- [X] `deltas/0.3.6/rel.001.md` confirmé.
- [X] `ksp-job-api`, `ksp-job-backfill-lib` et les trois Desks existants confirmés.
- [X] Règles générales, Rust, dépendances, documentation, file contracts, version workflow et prompt structure relus.
- [X] Architectures Layers/Dependencies/Components/Jobs/Apps relues.
- [X] README/USAGE/plan/validation/delta v0.3.6 relus.
- [X] Surfaces publiques Job/Backfill auditées depuis le code stable.
- [X] Config composite/Transport/Store audités.
- [X] Gabarits Config Desk, Wallet Desk et SOL Prices Desk audités.
- [X] Ports 1436/1437 confirmés libres dans les gabarits existants ; 1434/1435 appartiennent à SOL Prices.
- [X] kbot3 audité uniquement comme référence fonctionnelle/UX.
- [X] Matrice REPRENDRE/REDESSINER/REPORTER/REJETER produite.
- [X] Screen map, DTO/command map, Config/composition map et dependency map produits.
- [X] Threat model produit.
- [X] Single-run lifecycle, rôle HTTP, validation réseau et reprise in-session tranchés.
- [X] Gate Tauri/live tranché sans dépendance payante obligatoire.
- [X] Forecast scindé afin d'éviter une tranche Transport+Store manifestement trop large.
- [X] Aucun scaffold Tauri, code Rust/TS/HTML ou composite runtime ajouté en pre.001.
## 2. Preuve des archives
| Source | SHA-256 | Résultat | Usage |
|-----------------------------------------------------------|--------------------------------------------------------------------|---------------------------|--------------------------------|
| `khadhroony-solana-project-v0.3.6.zip` | `90eceb9fd28d87e580e3881cdd3eda935784532caac07d0ba3fb845be664c845` | 1 594 entrées, ZIP propre | source exclusive de code |
| `khadhroony-bot3_v0.5.3-pre.005-fix010-thelatest1(2).zip` | `ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318` | 2 501 entrées, ZIP propre | référence fonctionnelle isolée |
| `Texte collé(20260901-220002).txt` | `f70930be652d2532e2403f01227af9870fd31ec0603e64ddadca4a44d910d8cc` | journal opérateur | preuve externe baseline v0.3.6 |
Le journal opérateur fourni rapporte `cargo clean`, `cargo fmt`, audits Rust/Markdown, `cargo check --workspace`, Clippy, suites ciblées de toutes les crates, arbres Job/Backfill et `cargo tree --duplicates` sur v0.3.6. Cette preuve est conservée comme externe ; elle n'est pas assimilée à une exécution locale de pre.001.
## 3. Baseline locale
- [X] `python3 scripts/audit_rust_workspace_rules.py` : propre, zéro candidat d'export.
- [X] `python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas` : 295 tables / 652 fichiers propres avant modification.
- [ ] `cargo fmt --all` : non exécuté localement, exécutable `cargo` absent.
- [ ] `cargo check --workspace` : non exécuté localement, exécutable `cargo` absent.
- [ ] `cargo clippy --workspace --all-targets` : non exécuté localement, exécutable `cargo` absent.
## 4. Surface KSP acquise à préserver
- [X] `BackfillRequest` reste l'autorité des bornes et de la cohérence des scopes.
- [X] Latest/Before/After/Explicit restent les seuls scopes V1.
- [X] `BackfillJobRuntime` reste single-run.
- [X] `BackfillJobHandle` reste la primitive de contrôle.
- [X] `BackfillSnapshotSource` latest-value reste la primitive d'observation.
- [X] `BackfillCheckpoint` reste opaque et Rust-only.
- [X] Transport reste propriétaire retry/reroute/rate-limit/provider/endpoint.
- [X] Store reste propriétaire backend/persistence/idempotence.
- [X] Config reste propriétaire documents/env/secrets/composites.
## 5. Décisions de composition
- [X] Composite dédié `config/composite.ksp-app-backfill-desk.json` prévu.
- [X] Profils `devnet`, `mainnet`, `testnet` prévus avec couples Transport/Store de même réseau.
- [X] Default prévu : `devnet`.
- [X] Aucun `std.job_backfill.json` en V1.
- [X] Les rôles sont dérivés de Transport et validés pour `getSignaturesForAddress` + `getTransaction`.
- [X] Aucun rôle `history_backfill` n'est hardcodé ; la base standard actuelle expose `default`.
- [X] Une incohérence réseau est rejetée avant Start.
- [X] Le Desk ouvre Store via `ksp-store-lib`, jamais via backend direct.
## 6. Contrat IPC prévu
- [X] DTO applicatifs spécifiques au Desk ; aucune contrainte serde/TS-RS ajoutée aux crates Job.
- [X] Options DTO : réseau sûr, rôles, commitments, scopes, bornes, readiness.
- [X] Request DTO : inputs campagne uniquement.
- [X] Status DTO : lifecycle/phase/boundary/compteurs/checkpoint-present/contiguous/failure code.
- [X] Cancel/Resume responses sûres.
- [X] Aucun checkpoint opaque, Store, Transport, channel Tokio, URL, secret ou RAW payload ne traverse IPC.
- [X] Monitoring prévu via latest-value + événement Tauri, avec commande status de resynchronisation.
## 7. Threat model
- [X] URI Store et secrets Config restent backend-only.
- [X] Endpoint URLs/provider credentials restent backend-only.
- [X] Signatures et adresse ne sont pas loggées côté frontend.
- [X] RAW transaction data n'est pas projetée.
- [X] Bornes et signatures sont revalidées côté Rust.
- [X] Double Start est rejeté atomiquement.
- [X] Cancel/terminal race est résolue par lifecycle réel et handle installé avant spawn.
- [X] Checkpoint frontend forgé impossible : aucun checkpoint n'est sérialisé.
- [X] Capabilities Tauri prévues minimales : core + tracing seulement tant qu'aucun autre besoin n'est démontré.
## 8. Gates futures
- [X] Package Rust lib + bin conforme.
- [X] Ports Vite/HMR 1436/1437 stricts.
- [X] Splash/main + tracing conformes.
- [X] Composite Backfill Desk packagé et valide.
- [X] Transport readiness et role inventory sûrs.
- [ ] Store readiness et cohérence réseau.
- [ ] Quatre scopes + commitments + bornes mappés.
- [ ] Single active run + Start.
- [ ] Snapshot latest-value bridge.
- [ ] Cancel + races terminales.
- [ ] Checkpoint/frontier projection + Resume in-session.
- [ ] Frontend/security/composition tests verts.
- [ ] `cargo test --workspace` final vert.
- [ ] `(cd crates/ksp-app-backfill-desk && cargo tauri build)` final vert.
- [ ] Smoke live opt-in exécuté si environnement sûr disponible, sinon explicitement non requis.
- [ ] Réconciliation README/USAGE/plan/validation dans sa tranche dédiée.
- [ ] Prompt 0.3.8 + CHANGELOG + ROADMAP uniquement dans la lane de publication.
## 9. pre.002 — scaffold desktop
Le scaffold `ksp-app-backfill-desk` matérialise le gabarit Desk avant toute ouverture Transport/Store/Backfill : lib+bin, verrou single-instance, Config/Logging standard transitoire, splash commun, bridge Logging frontend, shell `Backfill / Diagnostics`, ports 1436/1437 et capabilities `core:default + tracing:default`.
Contraintes de gabarit vérifiées statiquement : mêmes assets splash/logo/DOS Amazigh que les trois Desk existantes, corps des cinq fichiers SASS partagés identique à SOL Prices Desk, splash HTML/SCSS identique hors identité Backfill et métadonnées de fichier, shell commun `header + sidebar + content + footer`, dépendances frontend minimales `@fltsci/tauri-plugin-tracing`, Font Awesome, Tauri API, Bootstrap, ResizeObserver polyfill et SimpleBar, plus les mêmes `devDependencies` que les trois Desk. Les clics, tabs, transitions de vue, refresh diagnostic et IPC sont instrumentés sans payload Backfill, adresse, signature, endpoint ou secret.
### Gate statique local
- [X] audit Rust workspace propre, zéro candidat d'export ;
- [X] audit Markdown propre : 270 tableaux / 149 fichiers ;
- [X] 4 manifests JSON et 2 manifests TOML parsés ;
- [X] 6 dépendances frontend minimales aux versions du gabarit ;
- [X] `devDependencies` strictement identiques dans Config Desk, Wallet Desk, SOL Prices Desk et Backfill Desk ;
- [X] 5 assets binaires strictement identiques dans les quatre Desk ;
- [X] 5 fichiers SASS partagés identiques à SOL Prices Desk hors header de propriété ;
- [X] splash commun et shell sidebar contrôlés ;
- [X] capabilities `core:default + tracing:default` seulement ;
- [X] aucune dépendance Transport/Store/Backfill ouverte en `pre.002` ;
- [X] audit frontend interaction/security propre ;
- [X] audit syntaxique TypeScript propre sur 5 fichiers ;
- [X] diff `pre.001 -> pre.002` borné à 46 ajouts, 3 modifications et aucune suppression ;
- [ ] `cargo fmt/check/clippy/test` : non exécutés, `cargo`/`rustfmt` absents du sandbox ;
- [ ] typecheck npm complet / build Tauri : non exécutés dans le sandbox.
Le contrôle TypeScript local est syntaxique avec le compilateur global disponible ; il ne remplace pas le typecheck complet avec dépendances npm et bindings TS-RS générés. Toute correction révélée par le gate opérateur reste dans la lane `pre.002-fix.NNN`.
## 10. pre.003 — composite Config et packaging
Le composite `cfg.composite.ksp-app-backfill-desk` est enregistré dans `ksp-config-lib` avec `devnet` par défaut. Il sélectionne `supertrace + devnet_public + devnet`, tandis que `mainnet` et `testnet` conservent des couples Transport/Store cohérents. Le bootstrap Backfill Desk valide les trois composants requis mais ne résout encore que Logging : aucun `HttpTransportPool`, `Store::open`, `BackfillRequest` ou `BackfillJobRuntime` n'est ouvert dans cette tranche.
Le niveau de développement est volontairement verbeux pour cette application : `devnet` utilise `supertrace`, et le fallback Logging propre à Backfill Desk utilise `LogFilterLevel::Trace`. Les autres applications Desk ne changent pas de profil Logging.
La découverte du contrat réel de `prepare_packaged_runtime()` a réconcilié le plan : la fonction traverse tout `ConfigFileRegistry::defaults()`. Le registre compte désormais 14 descriptors, de sorte que Config Desk, Wallet Desk, SOL Prices Desk et Backfill Desk embarquent toutes les 14 resources Config/schema. Les documents Wallet/offchain présents dans le bundle Backfill ne sont pas consommés par son runtime et n'élargissent ni ses capabilities ni ses dépendances Rust.
### Gate pre.002 opérateur acquis
- [X] audits Rust et Markdown propres ;
- [X] `cargo check --workspace` propre ;
- [X] `cargo clippy --workspace --all-targets` propre ;
- [X] `cargo test -p ksp-app-backfill-desk` : 12 unitaires + 5 desktop contract + 4 desktop security + 1 public API, aucun échec.
### Gate statique local pre.003
- [X] composite Backfill Desk ajouté au source Config et aux fixtures Config ;
- [X] registre Config porté à 14 descriptors avec exports publics associés ;
- [X] profils `devnet/mainnet/testnet` et références Logging/Transport/Store couplés conformément au plan ;
- [X] les quatre `tauri.conf.json` Desk embarquent le registre Config complet de 14 resources ;
- [X] release packaging Backfill Desk appelle `prepare_packaged_runtime()` avant l'initialisation applicative ;
- [X] bootstrap Backfill valide Logging/Transport/Store puis ne résout que Logging ;
- [X] niveau de développement Backfill Desk verrouillé à `supertrace` via Config et `trace` en fallback ;
- [X] aucune dépendance `ksp-job-backfill-lib`, `ksp-onchain-transport-lib`, `ksp-store-lib` ou backend Store ajoutée au manifeste Backfill Desk ;
- [X] audit Rust workspace propre, zéro candidat d'export ;
- [X] audit Markdown propre : 270 tableaux / 150 fichiers ;
- [X] parsing JSON/TOML, validation JSON Schema et audit structurel Config/package propres ;
- [X] gate opérateur `pre.003` exécuté le 2026-09-02 : **FIX REQUIRED** ; `cargo check --workspace` passe, mais l'audit Rust, Clippy, Config Desk et un canari Backfill Desk isolent quatre défauts locaux détaillés ci-dessous.
## 11. Correctif `pre.003-fix.001`
Le gate opérateur de `pre.003` a isolé quatre défauts qui appartiennent tous au couloir Config/composition de `pre.003` :
- `RUST-FMT-104` dans `src/errors.rs` : `ERROR_CODE_CONFIG_COMPOSITE_INVALID` précédait les constantes `ERROR_CODE_APP_STATE_*` ; le bloc est remis dans l'ordre alphabétique sans changer aucune valeur ;
- Clippy `implicit_return` dans `tests/desktop_contract.rs` : la closure qui lit `bundle.resources` utilise désormais un `return` explicite, conformément aux lints workspace ;
- la fixture `composite.ksp-app-backfill-desk.json` reprenait les profils de production (`supertrace`, `devnet_public`, `mainnet_public`, `publicnode_testnet`) alors que les fixtures réduites Logging/Transport n'exposent que `local_dev` et `secret_test` pour ces besoins ; comme les fixtures Wallet/SOL Prices existantes, la fixture Backfill utilise donc les profils disponibles du corpus de test, sans modifier le composite de production ;
- `tests/desktop_security.rs` attendait littéralement `ksp-config-lib.workspace = true`, alors que les Desk KSP déclarent leurs dépendances internes par chemin local ; le canari vérifie désormais la forme réelle `ksp-config-lib = { path = "../ksp-config-lib" }` et conserve les interdictions des couches Transport/Store/Backfill.
Le correctif ne modifie ni le profil `supertrace` de production, ni les 14 resources packagées, ni le bootstrap runtime, ni les capabilities Tauri, ni les dépendances fonctionnelles de Backfill Desk.
La version Cargo devient `0.3.7-pre.3.fix.1` conformément à `VER-ID-007` et `VER-ID-010`, car le correctif touche des fichiers Rust compilés.
### Gate opérateur ayant déclenché le fix
```text
cargo fmt --all exécuté
python3 scripts/audit_rust_workspace_rules.py FAIL — 1 x RUST-FMT-104
python3 scripts/audit_markdown_tables.py ... deltas/0.3.7 PASS
cargo check --workspace PASS
cargo clippy --workspace --all-targets FAIL — implicit_return dans desktop_contract.rs
cargo test -p ksp-config-lib PASS — 128 tests unitaires + suites associées
cargo test -p ksp-app-config-desk FAIL — fixture Backfill / profil supertrace absent
cargo test -p ksp-app-wallet-desk PASS
cargo test -p ksp-app-solprices-desk PASS
cargo test -p ksp-app-backfill-desk FAIL — canari Cargo.toml obsolète
```
### Gate du fix
- [X] audits statiques Rust/Markdown rejoués dans l'environnement d'assemblage ;
- [X] replay opérateur du 2026-09-02 : audits Rust/Markdown propres, `cargo check --workspace` propre, Clippy propre ;
- [X] `cargo test -p ksp-config-lib` : 128 tests unitaires + suites ownership/public API, aucun échec ;
- [X] `cargo test -p ksp-app-config-desk` : 63 tests unitaires + desktop/security/public API, aucun échec ;
- [X] `cargo test -p ksp-app-wallet-desk` et `cargo test -p ksp-app-solprices-desk` : suites ciblées propres ;
- [X] `cargo test -p ksp-app-backfill-desk` : 13 unitaires + 2 composition + 7 desktop contract + 5 desktop security + 1 public API, aucun échec ;
- [X] arbres `cargo tree` Backfill Desk exécutés sans anomalie rapportée.
## 12. `pre.004` — Transport readiness
Backfill Desk dépend désormais directement de `ksp-onchain-transport-lib` au niveau backend uniquement. `initialize_transport()` résout le profil Transport déjà sélectionné par le composite, construit `HttpTransportPool`, dérive les clusters HTTP activés et déduplique les rôles logiques à partir des snapshots sûrs. Chaque rôle candidat doit réussir `select_for_method()` pour `getSignaturesForAddress` **et** `getTransaction` avant d'être exposé comme compatible.
Le sous-contrat `BackfillDeskOptionsDto` expose uniquement : réseaux configurés, rôles compatibles, readiness Transport et diagnostic applicatif sûr. Il ne contient ni provider, URL, endpoint physique, token, checkpoint, payload RAW ou objet Transport. La commande Tauri `backfill_options` est centralisée dans `tauri.rs`. Les scopes, commitments et bornes restent hors de cette tranche et seront ajoutés en `pre.006`.
Une seule network distincte et au moins un rôle compatible sont requis pour `transport_ready = true`. Une erreur Config/Transport n'empêche pas le shell de démarrer : elle produit une options projection non-ready avec `CommandErrorDto`, tandis que le pool n'est pas conservé. La cohérence avec le réseau Store reste explicitement réservée à `pre.005`.
### Gate statique local `pre.004`
- [X] dépendance `ksp-onchain-transport-lib` ajoutée à Backfill Desk ;
- [X] aucune dépendance `ksp-store-lib`, `ksp-store-api`, `ksp-store-postgres-lib` ou `ksp-job-backfill-lib` ajoutée ;
- [X] `HttpTransportPool` construit uniquement dans `transport_runtime.rs`, pas dans le bootstrap Config/Logging ;
- [X] inventaire des clusters dérivé sans URL/provider ;
- [X] rôles candidats dédupliqués et vérifiés sur les deux RPC requis ;
- [X] le profil standard `devnet_public` possède un unique cluster `devnet` et le rôle wildcard `default` ;
- [X] capabilities Tauri inchangées : `core:default + tracing:default` ;
- [X] tracing de développement Backfill inchangé : Config `supertrace`, fallback `trace` ;
- [X] audit Rust workspace local propre, zéro candidat d'export ;
- [ ] `cargo fmt/check/clippy/test` de `pre.004` à rejouer par l'opérateur ; `cargo`/`rustfmt` restent absents du sandbox.
## 13. `pre.005` — Store readiness et cohérence réseau
### Gate opérateur `pre.004` acquis
- [X] audits Rust/Markdown propres ;
- [X] `cargo check --workspace` propre ;
- [X] `cargo clippy --workspace --all-targets` propre ;
- [X] `cargo test -p ksp-app-backfill-desk` : 17 unitaires + 3 composition + 8 desktop contract + 5 desktop security + 1 public API, aucun échec ;
- [X] arbres `cargo tree` Backfill Desk exécutés sans anomalie rapportée ;
- [X] `cargo tauri dev` démarre le shell sur le profil Logging `supertrace` et le profil Transport `devnet_public` ;
- [X] le runtime réel rapporte un seul réseau, un rôle compatible et `transport_ready = true` ;
- [X] les changements de tabs sont visibles dans le tracing frontend `DEBUG`.
### Gate statique local `pre.005`
- [X] dépendance directe `ksp-store-lib` ajoutée à Backfill Desk ;
- [X] aucune dépendance directe `ksp-store-api`, `ksp-store-postgres-lib`, `ksp-job-backfill-lib`, `reqwest` ou `tokio-postgres` ajoutée ;
- [X] le réseau Store est dérivé des settings Config résolus et comparé au réseau Transport unique avant `Store::open` ;
- [X] une incohérence ou l'absence de réseau Transport cohérent empêche l'ouverture Store ;
- [X] `Store::health()` est exécuté une fois après ouverture et sa projection reste backend-neutre ;
- [X] `BackfillDeskOptionsDto` expose seulement réseau Store, `network_coherent`, `store_ready`, `composition_ready` et diagnostics sûrs en plus du sous-contrat Transport ;
- [X] aucune URI PostgreSQL, URL Transport, identité provider, credential ou objet Store n'est projeté vers l'IPC ;
- [X] le `Store` est détenu côté Rust derrière une fermeture one-shot et `Store::close()` ;
- [X] la fermeture de la fenêtre principale est interceptée pour exécuter le close Store borné avant la sortie applicative ;
- [X] capabilities Tauri inchangées : `core:default + tracing:default` ;
- [X] tracing de développement Backfill inchangé : Config `supertrace`, fallback `trace` ;
- [X] aucun `BackfillRequest`, `BackfillJobRuntime`, Start/Cancel/Resume n'est ouvert ;
- [X] audit Rust workspace local propre, zéro candidat d'export ;
- [ ] `cargo fmt/check/clippy/test` de `pre.005` à rejouer par l'opérateur ; `cargo`/`rustfmt` restent absents du sandbox.
Reference in New Issue View Git Blame Copy Permalink