From dd85ac5e7779c679f4d28da69615c32b5d4fd33c Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Wed, 2 Sep 2026 08:47:42 +0200 Subject: [PATCH] v0.3.7-pre.001 --- Cargo.toml | 4 +- deltas/0.3.7/pre.001.md | 76 +++++ docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md | 294 ++++++++++++++++++++ docs/validation/024-V0_3_7_BACKFILL_DESK.md | 111 ++++++++ 4 files changed, 483 insertions(+), 2 deletions(-) create mode 100644 deltas/0.3.7/pre.001.md create mode 100644 docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md create mode 100644 docs/validation/024-V0_3_7_BACKFILL_DESK.md diff --git a/Cargo.toml b/Cargo.toml index 691f705..a93bc86 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 415 +# version: 416 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.6" +version = "0.3.7-pre.1" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.3.7/pre.001.md b/deltas/0.3.7/pre.001.md new file mode 100644 index 0000000..ce2ef5c --- /dev/null +++ b/deltas/0.3.7/pre.001.md @@ -0,0 +1,76 @@ + + + +# Delta v0.3.7-pre.1 — audit et planification Backfill Desk + +## Base requise + +```text +v0.3.6 +workspace.package.version = 0.3.6 +``` + +La source de code est exclusivement l'archive stable KSP v0.3.6 fournie. L'archive kbot3 a été extraite séparément et utilisée uniquement comme référence fonctionnelle/UX. + +## Résumé + +Cette tranche ouvre v0.3.7 sans scaffold Tauri lourd. Elle audite les règles, les surfaces Job/Backfill/Config/Transport/Store, les Desks KSP actuels, la référence historique kbot3 et les sources Tauri/TS-RS courantes, puis fixe le screen map, les DTO/commands, la composition Config, le graphe de dépendances, le threat model et le découpage de la release. + +Décisions principales : + +- application single-active-run ; +- quatre scopes KSP uniquement ; +- rôle HTTP logique dérivé de Transport et compatible avec les deux RPC requis ; +- réseau Store/Transport cohérent avant Start ; +- checkpoint conservé uniquement en Rust et reprise in-session ; +- monitoring via snapshots latest-value, sans parsing de logs ; +- aucun provider/endpoint/retry/SQL/RAW payload exposé au frontend ; +- composite prévu avec profils devnet/mainnet/testnet ; +- gate final Tauri obligatoire, smoke live seulement opt-in. + +## Vérification des archives + +- KSP v0.3.6 : SHA-256 `90eceb9fd28d87e580e3881cdd3eda935784532caac07d0ba3fb845be664c845`, 1 594 entrées, ZIP intégral propre ; +- kbot3 : SHA-256 `ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318`, 2 501 entrées, ZIP intégral propre ; +- aucune entrée absolue, traversal, séparateur inversé ou lien symbolique ZIP ; +- journal opérateur v0.3.6 : SHA-256 `f70930be652d2532e2403f01227af9870fd31ec0603e64ddadca4a44d910d8cc`. + +## Fichiers ajoutés + +- `docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md` ; +- `docs/validation/024-V0_3_7_BACKFILL_DESK.md` ; +- `deltas/0.3.7/pre.001.md`. + +## Fichier modifié + +- `Cargo.toml` : header `415` vers `416`, version workspace `0.3.6` vers `0.3.7-pre.1` conformément à `VER-ID-009`. + +## Validations exécutées localement + +Avant modification : + +- audit Rust workspace : propre, zéro candidat d'export ; +- audit Markdown : 295 tables / 652 fichiers propres. + +Après modification : + +- audit Rust workspace : propre, zéro candidat d'export ; +- audit Markdown : 301 tables / 655 fichiers propres. + +## Validations non exécutées localement + +L'exécutable `cargo` est absent de l'environnement d'assemblage. `cargo fmt`, `cargo check`, Clippy et tests ne sont donc pas annoncés comme PASS localement. Le journal opérateur fourni rapporte en revanche un gate stable v0.3.6 complet et propre ; il reste une preuve externe de la base, pas une exécution de ce delta. + +## Non inclus + +- aucune nouvelle crate ; +- aucun Rust/TypeScript/HTML ; +- aucun `package.json`, `tauri.conf.json` ou capability ; +- aucun composite runtime créé ; +- aucune reprise de code kbot3 ; +- aucune modification CHANGELOG/ROADMAP ; +- aucune publication stable. + +## Suite prévue + +`pre.002` crée uniquement le scaffold desktop minimal `ksp-app-backfill-desk` avec lib/bin, shell/splash/tracing/capability, frontend minimal et ports stricts 1436/1437. Config/Transport/Store restent aux tranches suivantes. diff --git a/docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md b/docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md new file mode 100644 index 0000000..5c9e278 --- /dev/null +++ b/docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md @@ -0,0 +1,294 @@ + + + +# Plan v0.3.7 — Backfill Desk + +## 1. But de la version + +La v0.3.7 crée `ksp-app-backfill-desk`, application Tauri spécialisée qui compose Config, Transport, Store et `ksp-job-backfill-lib` afin de lancer, observer, annuler et reprendre un backfill historique borné. + +L'application reste une couche de composition et d'interface. Elle ne possède ni découverte RPC, ni retry/rate-limit, ni persistance, ni frontier/checkpoint, ni navigation Store générale. + +Chaîne cible : + +```text +Config composite/profile + -> Logging + -> Transport HTTP + -> Store + -> AppState Rust + -> BackfillRequest + -> BackfillJobRuntime + -> BackfillJobHandle + -> BackfillSnapshotSource + -> DTO Tauri sûrs + -> UI latest-value +``` + +## 2. Base et audits de pre.001 + +Base autoritaire : archive stable `v0.3.6`, `workspace.package.version = 0.3.6`, avec `deltas/0.3.6/rel.001.md`, `ksp-job-api`, `ksp-job-backfill-lib` et les trois Desks existants. + +Les deux archives ont été testées intégralement avant utilisation et extraites dans des arbres séparés. kbot3 reste une référence fonctionnelle/UX ; aucun code, DTO, commande Tauri ou algorithme n'en est repris. + +Sources internes relues : règles racine et `docs/rules/`, architectures Layers/Dependencies/Components/Jobs/Apps, clôture complète de v0.3.6, surfaces Rust Job/Backfill/Config/Transport/Store et gabarits des Desks Config, Wallet et SOL Prices. + +L'audit externe du 2026-09-02 confirme que le socle Tauri v2, son modèle capabilities/runtime authority et les versions courantes restent compatibles avec les contraintes existantes. Le workspace résout déjà `tauri 2.11.5`, `tauri-build 2.6.3`, `tauri-plugin-tracing 0.3.4` et `ts-rs 12.0.1`; les manifests frontend utilisent `@tauri-apps/api ^2.11`, `@tauri-apps/cli ^2.11`, TypeScript `^7.0` et Vite `^8.2`. Une version plus récente de Vite existe, mais aucun besoin fonctionnel ne justifie une mise à niveau en v0.3.7. + +## 3. Surface Backfill réellement disponible + +`ksp-job-backfill-lib` expose déjà les quatre scopes `LatestAddress`, `BeforeAddress`, `AfterAddress` et `ExplicitSignatures`, les commitments `Confirmed`/`Finalized`, les bornes publiques, `BackfillRequest`, `BackfillCheckpoint`, `BackfillJobRuntime`, `BackfillJobHandle` et `BackfillSnapshotSource`. + +Le snapshot sûr expose phase, scope kind, boundary, candidats selected/admitted/finished, entities inserted/existing/purged, missing, conflicts, observations inserted/existing, cancelled candidates, holes, maximum in-flight, contiguous completed, présence d'un checkpoint et failure code. L'UI ne fabrique aucun pourcentage global lorsque le dénominateur n'est pas connu. + +Bornes backend-owned : + +| Paramètre | Borne publique | +|-----------------------|---------------------------------------------:| +| page size | 1..=1000 | +| max pages | 1..=10000 | +| max candidates | 1..=10000 | +| hydration concurrency | 1..=64 | +| signature Base58 | 64..=88 octets texte, validation Rust exacte | + +`min_context_slot` est admis pour les scopes adresse et rejeté pour `ExplicitSignatures` par `BackfillRequest`. + +## 4. Matrice kbot3 + +| Capacité historique | Preuve fonctionnelle kbot3 | Équivalent KSP v0.3.6 | Décision | +|---------------------------------------------------------|----------------------------------------|---------------------------------------|-----------------------------| +| Formulaire de campagne | `demo_backfill.html` + request TS/Rust | `BackfillRequest` explicite et borné | REPRENDRE FONCTIONNELLEMENT | +| Signatures explicites | textarea + mode `explicit_signatures` | `BackfillScope::explicit_signatures` | REPRENDRE FONCTIONNELLEMENT | +| Adresse + direction | address, anchor, before/after | Latest/Before/After address distincts | REDESSINER POUR KSP | +| Commitment | sélecteur confirmed/finalized | `BackfillCommitment` | REPRENDRE FONCTIONNELLEMENT | +| Rôle logique | rôle HTTP sélectionnable | `HttpRoleName` + Transport | REDESSINER POUR KSP | +| Provider/endpoint affichés | options et summary | Transport possède routage physique | REJETER | +| Retry opérateur | `maxRetries` UI | Transport possède retry/pacing | REJETER | +| Page size/max pages/limit | inputs bornés | constantes Backfill publiques | REPRENDRE FONCTIONNELLEMENT | +| Concurrency | input opérateur | `hydration_concurrency` | REPRENDRE FONCTIONNELLEMENT | +| Program/token/pool modes | accordéons dédiés | scopes génériques adresse/signatures | REJETER comme types KSP | +| Progression live | événements textuels + log | snapshots latest-value structurés | REDESSINER POUR KSP | +| Annulation | bool atomique + commande | `BackfillJobHandle::cancel()` | REDESSINER POUR KSP | +| Résumé terminal | payload summary | notification/snapshot terminal | REPRENDRE FONCTIONNELLEMENT | +| Compteurs inserted/existing/missing/failed/observations | summary | compteurs `BackfillJobSnapshot` | REDESSINER POUR KSP | +| Cursor older-history | `resume_before_signature` | `BackfillCheckpoint` opaque | REDESSINER POUR KSP | +| Reprise durable | cursor texte retourné | aucun checkpoint sérialisable public | REPORTER | +| Single-run UI | flag `running` | runtime single-run + handle | REPRENDRE FONCTIONNELLEMENT | +| Store browsing | demo desktop monolithique | futur Store Desk v0.3.8 | REJETER | + +## 5. Screen map + +Un seul écran principal responsive suffit en V1, en plus du splash commun. + +```text +main +├─ header : Backfill Desk + statut runtime/config +├─ readiness : profil composite, réseau, rôle(s) compatibles, Store/Transport ready +├─ campaign form +│ ├─ scope kind +│ ├─ address / anchor / signatures selon scope +│ ├─ commitment + rôle logique +│ └─ page size / max pages / max candidates / concurrency / min_context_slot +├─ active job +│ ├─ lifecycle + phase +│ ├─ boundary/frontier +│ ├─ compteurs structurés +│ ├─ checkpoint présent + contiguous completed +│ └─ Start / Cancel selon état +├─ terminal summary +│ ├─ outcome/lifecycle +│ ├─ failure code sûr +│ └─ Resume / New campaign selon checkpoint et scope +└─ diagnostics sûrs : codes, jamais secrets/URL/RAW +``` + +États UI explicites : `booting`, `ready`, `starting`, `running`, `cancelling`, `completed`, `cancelled`, `failed`, `resume-ready`. `cancelling` ne prétend jamais que la persistance déjà soumise est interrompue. + +## 6. DTO et command map + +Les DTOs sont possédés par l'application et dérivés TS-RS uniquement à cette frontière. + +| Élément | Direction | Contenu | Validation / source de vérité | Sensibilité | +|-----------------------------|------------|-----------------------------------------------------------------------------------------------|------------------------------------------|--------------| +| `BackfillDeskOptionsDto` | Rust -> UI | réseau, rôles compatibles, commitments, scopes, bornes, readiness | Config + Transport + constantes Backfill | sûre | +| `BackfillStartRequestDto` | UI -> Rust | scope inputs, commitment, rôle, bornes, optional min context slot | conversion stricte vers types KSP | métier borné | +| `BackfillRunStatusDto` | Rust -> UI | job state, phase, compteurs, boundary, checkpoint_present, contiguous_completed, failure code | `JobNotification` | sûre | +| `BackfillCancelResponseDto` | Rust -> UI | accepted + état courant | `BackfillJobHandle` | sûre | +| `BackfillResumeResponseDto` | Rust -> UI | accepted/new job status | checkpoint Rust détenu par AppState | sûre | +| `SafeAppErrorDto` | Rust -> UI | domain/code + message app maîtrisé | mapping applicatif | sûre | + +Commandes prévues : + +```text +backfill_options() -> BackfillDeskOptionsDto +backfill_status() -> BackfillRunStatusDto +backfill_start(request) -> BackfillRunStatusDto +backfill_cancel() -> BackfillCancelResponseDto +backfill_resume() -> BackfillResumeResponseDto +backfill_reset() -> BackfillRunStatusDto +``` + +Le monitoring continu ne dépend pas du parsing de logs. Le backend possède un bridge latest-value qui attend `JobSnapshotSource::wait_for_change`, projette le snapshot et émet un événement Tauri borné, par exemple `backfill-status-changed`. `backfill_status` reste le chemin de resynchronisation initiale/explicite. + +Aucun `BackfillCheckpoint`, `Store`, `HttpTransportPool`, sender/receiver Tokio ni payload RAW n'est sérialisé vers le frontend. + +## 7. Config et composition + +Le composite cible est `config/composite.ksp-app-backfill-desk.json` avec trois profils cohérents : + +| Profil composite | Logging | Transport | Store | Réseau | +|------------------|----------------|----------------------|-----------|----------------| +| `devnet` | `supertrace` | `devnet_public` | `devnet` | `devnet` | +| `mainnet` | `console_info` | `mainnet_public` | `mainnet` | `mainnet-beta` | +| `testnet` | `console_info` | `publicnode_testnet` | `testnet` | `testnet` | + +Le default V1 est `devnet`, afin de ne pas lancer implicitement une campagne mainnet. Aucun `std.job_backfill.json` n'est créé : les paramètres de campagne restent opérationnels et backend-validés. + +Au bootstrap, l'application charge le composite, résout Logging/Transport/Store via `ksp-config-lib`, construit `HttpTransportPool` et ouvre `ksp_store_lib::Store`. Elle compare le réseau Store au(x) cluster(s) HTTP activés et refuse le readiness si une composition mélange des réseaux. + +Les rôles présentés à l'UI sont dérivés des snapshots/settings Transport, dédupliqués, puis validés côté Rust comme capables de sélectionner à la fois `getSignaturesForAddress` et `getTransaction`. Le rôle `default` est actuellement le seul rôle des profils standard, mais il n'est pas codé en dur comme contrat du Desk. + +Les resources bundle minimales sont le composite Backfill Desk, `std.logging.json`, `std.transport.json`, `std.store.json` et leurs schemas, plus `composite.schema.json`. Les documents Wallet/offchain ne sont pas embarqués sans besoin démontré. + +## 8. Dependency map + +Dépendances Rust normales envisagées : + +```text +ksp-app-backfill-desk +├─ ksp-core-lib # erreurs, Pubkey/app DTO si requis +├─ ksp-logging-lib # façade logging +├─ ksp-config-lib # composition et packaging Config +├─ ksp-job-api # JobState/JobSnapshotSource consommés directement +├─ ksp-job-backfill-lib # request/runtime/handle/snapshot +├─ ksp-onchain-transport-lib # construction HttpTransportPool + role/method readiness +├─ ksp-store-lib # Store::open et ressource runtime +├─ serde # DTO IPC +├─ tauri +├─ tauri-plugin-tracing +├─ tokio # spawn/synchronisation app si gabarit Tauri l'exige +└─ ts-rs # bindings DTO applicatifs +``` + +`ksp-job-backfill-lib` dépend déjà de Store avec `default-features = false`. Le Desk devra cependant ouvrir le Store concret ; la feature backend de `ksp-store-lib` doit donc être explicitement auditée au scaffold. Le pattern cible est une dépendance sur `ksp-store-lib` uniquement, avec le backend compilé par la feature de façade adéquate, jamais une dépendance directe sur `ksp-store-postgres-lib`. + +Dépendances interdites : `ksp-store-api` direct, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic`, `yellowstone-grpc-proto`, SDK provider. + +## 9. Single-run lifecycle et races + +AppState conserve au plus : ressources runtime stables, un slot de run actif, le dernier snapshot terminal et le dernier checkpoint sûr associé à la requête/backend state nécessaires à une reprise en session. + +Règles : + +- start atomique : refus si un run est `starting/running/cancelling` ; +- le handle est installé avant spawn afin que Cancel ne perde pas la course au démarrage ; +- Cancel répété est idempotent au niveau UX, mais le retour expose si la demande a été acceptée ; +- un terminal publié gagne sur un Cancel tardif ; +- la source latest-value est conservée jusqu'à projection du terminal ; +- reset/new campaign n'est autorisé qu'en absence de run actif ; +- fermeture de l'application déclenche une demande d'annulation coopérative best-effort puis laisse la destruction du process terminer les ressources ; aucune promesse de drain crash-safe n'est faite ; +- aucun registry multi-job générique n'est introduit. + +## 10. Reprise et checkpoint + +V1 conserve le dernier `BackfillCheckpoint` uniquement dans Rust. L'UI voit `checkpoint_present` et `contiguous_completed`, jamais les octets/identité internes du checkpoint. + +`Resume` reconstruit une requête sémantiquement identique avec un nouveau lifecycle contrôlé et réattache le checkpoint via `BackfillRequest::with_checkpoint`. Le backend doit préserver les éléments participant au scope fingerprint ; toute modification de scope/commitment/bornes sémantiques force une nouvelle campagne et invalide Resume. + +Aucun JSON, fichier ou table checkpoint n'est inventé. La reprise après crash/redémarrage est reportée à une évolution explicite du contrat Backfill si un besoin durable est démontré. + +## 11. Threat model + +| Menace | Surface | Contrôle v0.3.7 | +|------------------------------|------------------|----------------------------------------------------------------------------------------------| +| fuite URI Store | Config/backend | jamais projetée en DTO/log frontend | +| fuite URL/token provider | Transport/Config | uniquement rôle/cluster/readiness sûrs ; aucune URL | +| fuite RAW transaction | snapshots/IPC | snapshot existant ne contient aucun payload ; aucun Store read général | +| fuite liste signatures | request/logging | input transmis au command, non journalisé ; DTO retour n'en contient pas | +| fuite adresse | instrumentation | ne pas journaliser la valeur ; seulement scope kind/action code | +| frontend falsifie bornes | IPC | validation Rust + `BackfillRequest` autoritaire | +| rôle incompatible | Config/Transport | inventory + `select_for_method` pour les deux RPC avant Start | +| réseau incohérent | Config | rejet bootstrap/readiness avant création de request | +| double Start | AppState | admission atomique single-run | +| Cancel/terminal race | AppState/runtime | handle installé avant spawn, terminal autoritaire | +| checkpoint forgé | frontend | checkpoint jamais traverse IPC | +| permissions Tauri excessives | capabilities | `core:default` + `tracing:default`, aucune permission fs/dialog/network frontend sans besoin | +| browser storage de secrets | frontend | interdit ; aucun secret ne doit atteindre JS | + +Tauri capabilities restent le mécanisme de frontière IPC. La capability par défaut doit cibler seulement `splash` et `main` et ne pas ajouter de plugin filesystem/dialog/network sans besoin réel. + +## 12. Gate fonctionnel/live + +Obligatoire pendant la release : tests déterministes Rust/desktop/security/composition, gates workspace et `cargo tauri build` final lancé depuis `crates/ksp-app-backfill-desk`. + +Un smoke `Config -> Transport -> Store -> Backfill` peut exister comme test ignoré/opt-in uniquement si l'opérateur dispose d'un PostgreSQL de test et d'un endpoint public sûr. Aucun compte payant, secret fournisseur ou ressource non reproductible n'est requis pour clôturer la release. + +## 13. Prévision recalibrée + +### pre.001 — audit et planification + +Archives/règles/surfaces, matrice kbot3, screen map, DTO/commands, Config/composition, dépendances, threat model, lifecycle single-run, role/network/resume et sizing. Aucun scaffold lourd. + +### pre.002 — scaffold desktop minimal + +Créer package lib+bin, shell/splash/tracing/capability, frontend minimal, ports Vite/HMR 1436/1437 stricts et tests desktop de structure. + +### pre.003 — Config composite et packaging + +Ajouter composite Backfill Desk, resources minimales, bootstrap Config/Logging et canaries packaging/composition sans encore ouvrir réseau/Store réel. + +### pre.004 — Transport readiness + +Construire `HttpTransportPool`, dériver réseau/role inventory sûr, vérifier support des deux RPC et produire options DTO sans provider/URL. + +### pre.005 — Store readiness + +Ouvrir `ksp-store-lib::Store`, vérifier réseau Store/Transport avant run, lifecycle de fermeture et erreurs sûres. Scinder ici plutôt que mélanger Transport + Store dans une seule tranche large. + +### pre.006 — DTO/request mapping + +DTO TS-RS app-owned, quatre scopes, commitments, min context slot, bornes backend-owned, signatures hostiles et validation de rôle/réseau. + +### pre.007 — runtime + Start + +Single-active-run state, construction `BackfillJobRuntime`, spawn non bloquant, handle installé avant exécution et snapshot initial/terminal. + +### pre.008 — monitoring latest-value + +Bridge de snapshots, status DTO, événements coalescés, compteurs complets, resynchronisation et absence de log parsing. + +### pre.009 — Cancel et races terminales + +Cancel, état cancelling, idempotence UX, concurrence Start/Cancel/terminal, sémantique de drain Store et fermeture app. + +### pre.010 — checkpoint/frontier et Resume + +Projection sûre, conservation Rust-only du checkpoint, reprise in-session et invariants par scope. + +### pre.011 — frontend fonctionnel et polish + +Formulaire complet, états responsive, instrumentation sûre, summary terminal, erreurs, boutons contextuels, aucun secret/browser storage. + +### pre.012 — hardening et complétude + +Tests desktop/security/dependency/composition/release completeness, canaries DTO et scan des dépendances/interdictions. + +### pre.013 — gate technique final + +`cargo fmt`, audits, check/clippy/tests workspace, arbres Cargo utiles, `cargo tauri build`, smoke opt-in si environnement sûr disponible. + +### pre.014 — réconciliation documentaire + +README/USAGE/plan/validation et architecture seulement si la surface finale l'exige. Aucun nouveau runtime. + +### pre.015 — préparation publication + +Prompt 0.3.8, CHANGELOG et ROADMAP uniquement avec le bump prerelease/delta requis. + +### rel.001 — publication stable + +Mécanique de publication `v0.3.7`, sans rattrapage. + +## 14. Hors périmètre + +Store Desk/navigation RAW, Worker API/service daemon, scheduler/registry générique Job, checkpoint durable, retry Job, sélection provider physique, nouveau protocole Transport, migration Store, decoding/materialization, application globale/control desk. diff --git a/docs/validation/024-V0_3_7_BACKFILL_DESK.md b/docs/validation/024-V0_3_7_BACKFILL_DESK.md new file mode 100644 index 0000000..6395e6f --- /dev/null +++ b/docs/validation/024-V0_3_7_BACKFILL_DESK.md @@ -0,0 +1,111 @@ + + + +# 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 + +- [ ] Package Rust lib + bin conforme. +- [ ] Ports Vite/HMR 1436/1437 stricts. +- [ ] Splash/main + tracing conformes. +- [ ] Composite Backfill Desk packagé et valide. +- [ ] 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.