Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.7-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-02 08:47:42 +02:00
parent dd48ed9140
commit dd85ac5e77
4 changed files with 483 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md Normal file
View File

@@ -0,0 +1,294 @@
<!-- file: docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md -->
<!-- version: 1 -->
# 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<BackfillJobSnapshot>` | 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.