v0.3.7-pre.016
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 441
|
||||
# version: 442
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-app-backfill-desk", "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.7-pre.15"
|
||||
version = "0.3.7-pre.16"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: README.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Khadhroony Solana Project
|
||||
|
||||
@@ -51,6 +51,8 @@ Les besoins du trading constituent une priorité produit à court terme mais ne
|
||||
|
||||
La couche RAW dispose d'une façade Store backend-neutral et d'un premier job historique concret. `ksp-job-api` porte les contrats passifs communs des jobs bornés ; `ksp-job-backfill-lib` compose Transport observé et Store pour découvrir, hydrater et persister des transactions historiques RAW avec concurrence bornée, checkpoint contigu caller-owned, annulation coopérative et snapshots latest-value.
|
||||
|
||||
`ksp-app-backfill-desk` fournit la surface desktop spécialisée de composition de ce runtime : sélection d'un scope historique et d'un rôle HTTP logique, validation backend des bornes, Start single-run, monitoring latest-value, Cancel ciblé et Resume in-session sur checkpoint Rust-only. L'application ouvre Transport et Store via leurs façades KSP, ne dépend d'aucun backend Store concret et n'expose ni URL/credential, ni payload RAW, ni checkpoint opaque au frontend.
|
||||
|
||||
Ces contrats restent distincts des futurs workers continus : un job borné n'est ni un service worker ni un pipeline générique imposé aux autres couches.
|
||||
|
||||
## Points d'entrée
|
||||
|
||||
105
crates/ksp-app-backfill-desk/README.md
Normal file
105
crates/ksp-app-backfill-desk/README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
<!-- file: crates/ksp-app-backfill-desk/README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# `ksp-app-backfill-desk`
|
||||
|
||||
`ksp-app-backfill-desk` est l'application desktop spécialisée de contrôle d'un backfill historique `RawTransaction` KSP.
|
||||
|
||||
Elle reste une couche de composition Tauri : Config sélectionne les profils, Transport possède les endpoints/rôles/retry/rate-limit, Store possède la persistence et le backend, et `ksp-job-backfill-lib` possède découverte, hydratation, frontier/checkpoint et lifecycle du job.
|
||||
|
||||
## Package
|
||||
|
||||
```text
|
||||
package : ksp-app-backfill-desk
|
||||
lib : ksp_app_backfill_desk_lib
|
||||
bin : ksp-app-backfill-desk
|
||||
```
|
||||
|
||||
Le binaire est un launcher mince. La bibliothèque applicative possède le bootstrap, l'état Rust single-run, les DTOs Tauri, les commands et le bridge latest-value vers le frontend.
|
||||
|
||||
## Composition
|
||||
|
||||
```text
|
||||
ksp-config-lib -> composite, profils, secrets et runtime packagé
|
||||
ksp-core-lib -> erreurs, Pubkey et registre Program IDs
|
||||
ksp-onchain-transport-lib -> HTTP pool, rôles, admission, retry/rate-limit
|
||||
ksp-store-lib -> façade Store backend-neutral
|
||||
ksp-job-api -> lifecycle Job commun
|
||||
ksp-job-backfill-lib -> request/runtime/checkpoint/snapshots Backfill
|
||||
ksp-logging-lib -> logging/tracing applicatif
|
||||
ksp-app-backfill-desk -> orchestration Tauri + projections sûres
|
||||
```
|
||||
|
||||
L'application ne dépend pas directement de `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic` ou `yellowstone-grpc-proto`.
|
||||
|
||||
## Capacités
|
||||
|
||||
La surface utilisateur comprend :
|
||||
|
||||
- quatre scopes : latest address, before address, after address et explicit signatures ;
|
||||
- engagements `finalized` et `confirmed` ;
|
||||
- sélection d'un rôle HTTP logique compatible avec `getSignaturesForAddress` et `getTransaction` ;
|
||||
- bornes page/candidats/concurrence validées côté Rust par le contrat Backfill ;
|
||||
- validation de la requête avant Start ;
|
||||
- un seul run actif ;
|
||||
- monitoring latest-value par événement `ksp-backfill-status` avec resynchronisation explicite ;
|
||||
- Cancel ciblé par JobId backend et idempotent ;
|
||||
- Resume in-session lorsqu'un checkpoint terminal est disponible ;
|
||||
- autocomplete libre des Program IDs provenant du registre canonique `ksp-core-lib`.
|
||||
|
||||
L'autocomplete n'est jamais une allow-list : une adresse Solana valide non enregistrée reste saisissable.
|
||||
|
||||
## Checkpoint et Resume
|
||||
|
||||
Le checkpoint concret ne traverse jamais IPC. Le backend conserve uniquement en mémoire Rust le dernier terminal compatible et la requête nécessaire à une reprise dans la même session.
|
||||
|
||||
Un Resume crée un nouveau JobId backend. `ksp-job-backfill-lib` valide le checkpoint contre la requête d'origine puis le réémet pour ce nouveau Job sans modifier le scope fingerprint ni la frontier. Il n'existe pas de checkpoint durable de Backfill Desk après redémarrage de l'application.
|
||||
|
||||
## Config et réseaux
|
||||
|
||||
Le composite dédié est :
|
||||
|
||||
```text
|
||||
cfg.composite.ksp-app-backfill-desk
|
||||
```
|
||||
|
||||
Les profils committed couvrent `mainnet`, `devnet` et `testnet`. Mainnet est le profil par défaut. Transport et Store doivent sélectionner exactement le même réseau avant que la composition soit déclarée ready.
|
||||
|
||||
Les profils Store committed utilisent actuellement TLS PostgreSQL `disabled`; cette politique de profil n'enlève pas le support `verify_full` du Store/schema.
|
||||
|
||||
Le frontend ne reçoit jamais URI Store, URL RPC, credential provider, secret Config ou backend physique.
|
||||
|
||||
## Monitoring et sécurité
|
||||
|
||||
Le monitoring expose des compteurs et codes sûrs : lifecycle, phase, boundary, candidats, entités/observations, missing/conflicts/holes, concurrence maximale, frontier contiguë, présence de checkpoint et éventuel domain/code d'échec.
|
||||
|
||||
Il n'expose pas :
|
||||
|
||||
- payload RAW ;
|
||||
- adresse ou signatures de campagne ;
|
||||
- checkpoint/cursor concret ;
|
||||
- endpoint URL ou credential ;
|
||||
- contexte d'erreur arbitraire.
|
||||
|
||||
Le frontend ne possède ni accès direct filesystem/réseau, ni persistence navigateur de données Backfill. Les capabilities Tauri guest restent `core:default` et `tracing:default`.
|
||||
|
||||
## Ports et développement
|
||||
|
||||
```text
|
||||
Vite HTTP : 1436
|
||||
Vite WS : 1437
|
||||
```
|
||||
|
||||
Lancement :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri dev)
|
||||
```
|
||||
|
||||
Build production :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri build)
|
||||
```
|
||||
|
||||
Voir également [`USAGE.md`](USAGE.md), [`../ksp-job-backfill-lib/README.md`](../ksp-job-backfill-lib/README.md), [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) et [`../../docs/validation/024-V0_3_7_BACKFILL_DESK.md`](../../docs/validation/024-V0_3_7_BACKFILL_DESK.md).
|
||||
145
crates/ksp-app-backfill-desk/USAGE.md
Normal file
145
crates/ksp-app-backfill-desk/USAGE.md
Normal file
@@ -0,0 +1,145 @@
|
||||
<!-- file: crates/ksp-app-backfill-desk/USAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Utilisation de `ksp-app-backfill-desk`
|
||||
|
||||
## 1. Lancement
|
||||
|
||||
Depuis la racine du workspace :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri dev)
|
||||
```
|
||||
|
||||
Le runtime charge le composite Backfill Desk via `ksp-config-lib`, construit le pool HTTP, ouvre Store puis vérifie que les deux surfaces utilisent le même réseau avant d'autoriser une campagne.
|
||||
|
||||
## 2. Choix du profil et readiness
|
||||
|
||||
Le composite `cfg.composite.ksp-app-backfill-desk` utilise Mainnet par défaut. Devnet et Testnet restent disponibles via la sélection Config du profil composite.
|
||||
|
||||
Avant Start, l'écran indique séparément :
|
||||
|
||||
```text
|
||||
Transport ready
|
||||
Store ready
|
||||
Network coherent
|
||||
Composition ready
|
||||
```
|
||||
|
||||
Une composition non ready doit être corrigée côté Config/runtime ; le frontend ne peut pas fournir une URL RPC, une URI Store ou un secret pour contourner ces contrôles.
|
||||
|
||||
## 3. Adresse et autocomplete Program IDs
|
||||
|
||||
Le champ adresse accepte toute Pubkey Solana valide. Le `datalist` propose en complément les Program IDs du registre canonique `ksp-core-lib` avec leurs metadata publiques.
|
||||
|
||||
Choisir une proposition remplit simplement le champ ; une adresse absente du dataset reste autorisée. Le dataset n'est pas une allow-list.
|
||||
|
||||
## 4. Scopes
|
||||
|
||||
Les scopes disponibles sont :
|
||||
|
||||
```text
|
||||
latest_address
|
||||
before_address
|
||||
after_address
|
||||
explicit_signatures
|
||||
```
|
||||
|
||||
`latest_address` recherche l'historique récent d'une adresse. `before_address` et `after_address` ajoutent une signature d'ancrage selon la sémantique Backfill. `explicit_signatures` traite une liste explicite de signatures et n'accepte pas `min_context_slot`.
|
||||
|
||||
Les signatures et adresses sont revalidées côté Rust ; leur présence dans le formulaire ne les rend pas persistantes dans le frontend.
|
||||
|
||||
## 5. Engagement, route HTTP et bornes
|
||||
|
||||
Les engagements disponibles sont `finalized` et `confirmed`.
|
||||
|
||||
Le sélecteur HTTP expose uniquement des rôles logiques que le backend a vérifiés compatibles avec les deux méthodes nécessaires au Backfill. Le rôle pool permet au Transport de choisir/rerouter entre endpoints selon ses propres règles ; les rôles ciblés permettent de sélectionner une route logique spécifique sans exposer l'URL physique.
|
||||
|
||||
Les bornes de campagne comprennent notamment :
|
||||
|
||||
```text
|
||||
page size
|
||||
max pages
|
||||
max candidates
|
||||
hydration concurrency
|
||||
min context slot
|
||||
```
|
||||
|
||||
Les limites maximales proviennent de `ksp-job-backfill-lib` et sont revalidées lors de la conversion vers `BackfillRequest`.
|
||||
|
||||
## 6. Valider puis démarrer
|
||||
|
||||
**Valider la requête** projette un résumé sûr de la campagne sans démarrer le job.
|
||||
|
||||
**Démarrer** crée ensuite un JobId backend et installe le handle de contrôle avant le spawn asynchrone. Un second Start est refusé tant qu'un run est actif, y compris pendant `cancelling`.
|
||||
|
||||
## 7. Monitoring latest-value
|
||||
|
||||
La carte de monitoring est alimentée par les snapshots latest-value du runtime. Le backend émet `ksp-backfill-status`; **Resynchroniser** appelle également `backfill_status` afin de récupérer explicitement le dernier état complet.
|
||||
|
||||
Les informations utiles incluent :
|
||||
|
||||
- lifecycle et phase ;
|
||||
- scope et discovery boundary ;
|
||||
- candidats selected/admitted/finished ;
|
||||
- entités et observations inserted/existing ;
|
||||
- purged/missing/conflicts/holes/cancelled candidates ;
|
||||
- maximum in flight ;
|
||||
- contiguous completed ;
|
||||
- présence d'un checkpoint ;
|
||||
- domain/code stable d'échec éventuel.
|
||||
|
||||
Le monitoring ne doit pas être interprété depuis les logs texte.
|
||||
|
||||
## 8. Annuler
|
||||
|
||||
**Annuler** envoie le JobId actuellement affiché. Cette cible protège un nouveau run contre une requête Cancel retardée destinée au run précédent.
|
||||
|
||||
Le premier Cancel pré-terminal demande une annulation coopérative. Une répétition est idempotente. Le lifecycle peut passer par `cancelling`; les opérations déjà admises vers la persistence ne sont pas présentées comme brutalement interrompues.
|
||||
|
||||
## 9. Reprendre
|
||||
|
||||
**Reprendre** est disponible uniquement lorsqu'un snapshot terminal retenu contient un checkpoint. La commande n'accepte aucun checkpoint ou payload de campagne depuis le frontend.
|
||||
|
||||
Le backend :
|
||||
|
||||
1. exige qu'aucun run ne soit actif ;
|
||||
2. récupère la requête terminale Rust-only ;
|
||||
3. revalide le réseau Store et le rôle HTTP courant ;
|
||||
4. génère un nouveau JobId ;
|
||||
5. demande à `ksp-job-backfill-lib` de réémettre le checkpoint pour ce JobId ;
|
||||
6. relance le même runtime/monitoring.
|
||||
|
||||
La reprise est limitée à la session courante. Fermer l'application supprime ce checkpoint applicatif en mémoire.
|
||||
|
||||
## 10. Fermeture de l'application
|
||||
|
||||
La fermeture de la fenêtre principale bloque d'abord tout nouveau Start, tente une annulation coopérative du run actif puis ferme Store avant l'exit.
|
||||
|
||||
Le shutdown applicatif n'est pas un mécanisme de checkpoint durable ou de reprise après crash.
|
||||
|
||||
## 11. Données qui ne traversent pas le frontend
|
||||
|
||||
Backfill Desk ne projette jamais :
|
||||
|
||||
```text
|
||||
URI Store
|
||||
URL RPC
|
||||
credentials/secrets
|
||||
payload RAW
|
||||
checkpoint/cursor concret
|
||||
handles Store/Transport/Job
|
||||
contexte d'erreur arbitraire
|
||||
```
|
||||
|
||||
Les actions utilisateur et transitions sont instrumentées via Logging KSP sans journaliser adresse, signature ou payload métier.
|
||||
|
||||
## 12. Runtime packagé
|
||||
|
||||
Le build Tauri embarque les documents Config/schemas enregistrés. `ksp-config-lib` prépare ensuite la racine KSP user-writable et conserve les Config utilisateur existantes ; `.env` n'est jamais embarqué.
|
||||
|
||||
Le build production est :
|
||||
|
||||
```bash
|
||||
(cd crates/ksp-app-backfill-desk && cargo tauri build)
|
||||
```
|
||||
63
deltas/0.3.7/pre.016.md
Normal file
63
deltas/0.3.7/pre.016.md
Normal file
@@ -0,0 +1,63 @@
|
||||
<!-- file: deltas/0.3.7/pre.016.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.7-pre.016` — réconciliation documentaire finale Backfill Desk
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.3.7-pre.015
|
||||
```
|
||||
|
||||
Le gate technique final est entièrement vert : format check, audits, check, Clippy `-D warnings`, workspace all-targets/all-features, graphes Cargo, duplicates et build Tauri Linux.
|
||||
|
||||
## 2. Objectif
|
||||
|
||||
Réconcilier exclusivement la documentation durable avec la surface réellement livrée de Backfill Desk. Aucun runtime, test, frontend, Config ou manifest de crate n'est rouvert.
|
||||
|
||||
## 3. Version
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.7-pre.16
|
||||
```
|
||||
|
||||
## 4. Réconciliation
|
||||
|
||||
- README/USAGE durables de `ksp-app-backfill-desk` ;
|
||||
- README racine et index docs/validation ;
|
||||
- plan réaligné sur les six commandes Backfill réelles et `ksp-backfill-status` ;
|
||||
- validation finale avec preuve du gate `pre.015` ;
|
||||
- architecture Layers/Contracts/Inventory/Dependency Graph/Apps & Services mise à jour ;
|
||||
- inventaire Backfill Desk fixé sur `ksp-app-backfill-desk`, statut Implémenté.
|
||||
|
||||
`USAGE.md` reste strictement version-neutral : aucun journal de gate/prerelease n'y est ajouté.
|
||||
|
||||
## 5. Gate technique enregistré
|
||||
|
||||
La preuve opérateur `pre.015` établit :
|
||||
|
||||
```text
|
||||
1 494 tests passés
|
||||
0 échec
|
||||
15 tests ignorés opt-in/operator-only
|
||||
Clippy -D warnings propre
|
||||
3 bundles Tauri Linux : deb, rpm, AppImage
|
||||
```
|
||||
|
||||
## 6. Hors scope
|
||||
|
||||
```text
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
prompt suivant
|
||||
code/test/frontend/config
|
||||
```
|
||||
|
||||
Ces surfaces restent réservées à `pre.017`.
|
||||
|
||||
## 7. Suite
|
||||
|
||||
```text
|
||||
0.3.7-pre.017 — préparation publication minimale + prompt suivant
|
||||
0.3.7-rel.001 — publication stable
|
||||
```
|
||||
File diff suppressed because one or more lines are too long
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 9 -->
|
||||
<!-- version: 10 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
@@ -134,7 +134,7 @@ Les applications Tauri restent minces :
|
||||
- instrumentation frontend ;
|
||||
- aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.
|
||||
|
||||
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, backfill/RAW tooling, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites.
|
||||
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, Store/RAW tooling, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only.
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
@@ -203,14 +203,17 @@ KSP privilégie des applications spécialisées servant à valider/exploiter une
|
||||
```text
|
||||
ksp-app-config-desk
|
||||
ksp-app-wallet-desk
|
||||
price desk
|
||||
backfill/raw tooling
|
||||
ksp-app-solprices-desk
|
||||
ksp-app-backfill-desk
|
||||
ksp-app-store-desk
|
||||
CORE tooling
|
||||
ksp-app-market-desk
|
||||
```
|
||||
|
||||
Une application globale reste future.
|
||||
|
||||
`ksp-app-backfill-desk` est l'interface spécialisée du premier job historique. Elle dépend des façades KSP nécessaires à la composition (`ksp-config-lib`, `ksp-job-api`, `ksp-job-backfill-lib`, `ksp-onchain-transport-lib`, `ksp-store-lib`, Core et Logging), garde Store/Transport/checkpoint côté Rust et expose uniquement les options, demandes opérateur bornées, états latest-value et acquittements de contrôle sûrs.
|
||||
|
||||
## Progression verticale Program
|
||||
|
||||
À partir de DECODE :
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 31 -->
|
||||
<!-- version: 32 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
@@ -42,7 +42,7 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
|
||||
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4` | backend référence : fondation, RawTransaction et RawAccountState |
|
||||
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
|
||||
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6` | backfill `RawTransaction` borné via Transport observé + Store, checkpoint et runtime |
|
||||
| Backfill Desk | nom à fixer | app | Retenu | `0.3.7` | contrôle/inspection du backfill RAW |
|
||||
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7` | Start/monitoring/Cancel/Resume in-session du backfill RAW via façades KSP |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | Retenu | fin couche RAW | lifecycle des services continus |
|
||||
| RAW worker | `ksp-worker-raw-retriever` ou nom révisé | worker | Retenu | fin couche RAW | acquisition live vers RAW |
|
||||
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 20 -->
|
||||
<!-- version: 21 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -425,16 +425,21 @@ ksp-app-solprices-desk
|
||||
|
||||
L'application est une HID pure. Elle ne dépend d'aucun SDK provider, ne construit aucune requête HTTP provider et ne connaît ni endpoint, ni credential, ni limite provider. Les rows et actions de refresh sont alimentées par les descriptors/états/opérations génériques de `ksp-offchain-transport-lib`.
|
||||
|
||||
### Backfill app
|
||||
### Backfill Desk
|
||||
|
||||
```text
|
||||
backfill app
|
||||
-> ksp-job-api
|
||||
-> concrete backfill job
|
||||
ksp-app-backfill-desk
|
||||
-> ksp-core-lib
|
||||
-> ksp-config-lib
|
||||
-> ksp-job-api
|
||||
-> ksp-job-backfill-lib
|
||||
-> ksp-logging-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
La Desk compose les ressources et contrôles du job sans traverser la façade Store : aucune dépendance directe à `ksp-store-api`, `ksp-store-postgres-lib`, `tokio-postgres`, `reqwest`, `tonic` ou `yellowstone-grpc-proto`. Le frontend ne connaît que des rôles HTTP logiques et des DTOs sûrs ; endpoints, credentials, backend Store, RAW et checkpoint concret restent sous les composants Rust propriétaires.
|
||||
|
||||
### Market Desk
|
||||
|
||||
```text
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -90,6 +90,8 @@ Le job :
|
||||
- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
|
||||
- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
|
||||
|
||||
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
|
||||
|
||||
### Worker RAW live
|
||||
|
||||
Le worker live futur :
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Applications, services, scenarios et control plane
|
||||
|
||||
@@ -77,6 +77,7 @@ Exemples de familles spécialisées :
|
||||
ksp-app-config-desk
|
||||
ksp-app-wallet-desk
|
||||
ksp-app-solprices-desk
|
||||
ksp-app-backfill-desk
|
||||
ksp-app-store-desk
|
||||
ksp-app-worker-<role>-desk
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
@@ -106,12 +107,23 @@ ksp-app-solprices-desk
|
||||
-> ksp-config-lib
|
||||
-> ksp-offchain-transport-lib
|
||||
|
||||
ksp-app-backfill-desk
|
||||
-> ksp-core-lib
|
||||
-> ksp-config-lib
|
||||
-> ksp-job-api
|
||||
-> ksp-job-backfill-lib
|
||||
-> ksp-logging-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib
|
||||
|
||||
ksp-app-store-desk
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
`ksp-store-lib` réexporte la surface Store commune nécessaire aux applications ; une app ne dépend pas directement de `ksp-store-api` uniquement pour atteindre les modèles/capabilities, et ne dépend jamais d'une crate backend concrète.
|
||||
|
||||
Backfill Desk suit exactement cette règle : elle ouvre Store via `ksp-store-lib`, construit le pool HTTP via `ksp-onchain-transport-lib`, puis remet ces ressources à `ksp-job-backfill-lib`. Start/Cancel/Resume restent des opérations applicatives de composition ; le checkpoint de reprise et les ressources physiques ne deviennent jamais des DTOs Tauri.
|
||||
|
||||
Les couches N1–N4 expriment des responsabilités et une direction de dépendances ; elles n'imposent pas de traverser toutes les couches intermédiaires.
|
||||
|
||||
## Tauri
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md -->
|
||||
<!-- version: 15 -->
|
||||
<!-- version: 16 -->
|
||||
|
||||
# Plan v0.3.7 — Backfill Desk
|
||||
|
||||
@@ -108,27 +108,31 @@ main
|
||||
|
||||
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 |
|
||||
| Élément | Direction | Contenu | Validation / source de vérité | Sensibilité |
|
||||
|----------------------------------|------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------|--------------|
|
||||
| `BackfillDeskOptionsDto` | Rust -> UI | réseau, rôles, commitments, scopes, bornes, readiness, Program IDs autocomplete | Config + Transport + Core + Backfill | sûre |
|
||||
| `BackfillRequestLimitsDto` | Rust -> UI | defaults + maxima de campagne | constantes publiques Backfill | sûre |
|
||||
| `BackfillStartRequestDto` | UI -> Rust | scope inputs, commitment, rôle, bornes, optional min context slot | conversion stricte vers types KSP | métier borné |
|
||||
| `BackfillRequestPreviewDto` | Rust -> UI | request validée sans valeur d'adresse/signature | mapping applicatif + `BackfillRequest` | sûre |
|
||||
| `BackfillStartResponseDto` | Rust -> UI | JobId backend + état initial | slot single-run | sûre |
|
||||
| `BackfillRunStatusDto` | Rust -> UI | job state, phase, compteurs, boundary, checkpoint_present, contiguous_completed, failure code | `BackfillSnapshotSource` | sûre |
|
||||
| `BackfillCancelResponseDto` | Rust -> UI | accepted + JobId ciblé + état | `BackfillJobHandle` | sûre |
|
||||
| `BackfillResumeResponseDto` | Rust -> UI | accepted + nouveau JobId + état | checkpoint Rust détenu par `BackfillRunState` | sûre |
|
||||
| `ProgramIdAutocompleteOptionDto` | Rust -> UI | program_id + metadata publiques de taxonomie | `ksp_core_lib::entries()` | publique |
|
||||
| `CommandErrorDto` | Rust -> UI | domain/code + message app maîtrisé | mapping applicatif | sûre |
|
||||
|
||||
Commandes prévues :
|
||||
Commandes finales :
|
||||
|
||||
```text
|
||||
backfill_options() -> BackfillDeskOptionsDto
|
||||
backfill_status() -> BackfillRunStatusDto
|
||||
backfill_start(request) -> BackfillRunStatusDto
|
||||
backfill_status() -> Option<BackfillRunStatusDto>
|
||||
backfill_validate_request(request) -> BackfillRequestPreviewDto
|
||||
backfill_start(request) -> BackfillStartResponseDto
|
||||
backfill_cancel(job_id) -> 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.
|
||||
Le monitoring continu ne dépend pas du parsing de logs. Le backend possède un bridge latest-value depuis `BackfillSnapshotSource`, projette le snapshot et émet l'événement Tauri stable `ksp-backfill-status`. `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.
|
||||
|
||||
@@ -314,7 +318,9 @@ La tranche `pre.015` n'ajoute aucune capacité ni aucun test. Elle matérialise
|
||||
|
||||
### pre.016 — réconciliation documentaire
|
||||
|
||||
README/USAGE/plan/validation et architecture seulement si la surface finale l'exige. Aucun nouveau runtime.
|
||||
Le gate technique final `pre.015` est intégralement vert : `cargo fmt --check`, audits, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features`, arbres Cargo ciblés, `cargo tree --duplicates` et build Tauri Linux passent. Le run workspace agrège 1 494 tests passés, 0 échec et 15 tests ignorés explicitement opt-in/operator-only ; le build produit les bundles `.deb`, `.rpm` et `.AppImage`.
|
||||
|
||||
La tranche réconcilie exclusivement les documents durables : README/USAGE de Backfill Desk, index documentaires, plan/validation et architecture courante. Aucun runtime, test, frontend ou Config n'est rouvert.
|
||||
|
||||
### pre.017 — préparation publication
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/000-README.md -->
|
||||
<!-- version: 35 -->
|
||||
<!-- version: 36 -->
|
||||
|
||||
# Validations KSP
|
||||
|
||||
@@ -32,3 +32,4 @@ Documents :
|
||||
- [`021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — matrice finale de `0.3.4 — RawAccountState + complétude RAW` : quatre capabilities account supplémentaires, V002, pagination/idempotence et conformance Store 10/10.
|
||||
- [`022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md`](022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md) — matrice finale de `0.3.5 — Interface acquisition events` : événements passifs slot/transaction, façade crate-root, bornes/debug et firewall Interface.
|
||||
- [`023-V0_3_6_JOB_API_BACKFILL.md`](023-V0_3_6_JOB_API_BACKFILL.md) — matrice candidate de `0.3.6 — Job API + RAW transaction backfill` : lifecycle/notifications runtime-neutral, scopes, provenance, RAW v1, Store/idempotence, concurrence/checkpoint, annulation/snapshots, hardening externe et gate workspace final.
|
||||
- [`024-V0_3_7_BACKFILL_DESK.md`](024-V0_3_7_BACKFILL_DESK.md) — matrice candidate de `0.3.7 — Backfill Desk` : composition Config/Transport/Store/Job, scopes et rôles HTTP, single-run, monitoring latest-value, Cancel, Resume in-session Rust-only, autocomplete Program IDs, hardening et gate workspace/Tauri final.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/024-V0_3_7_BACKFILL_DESK.md -->
|
||||
<!-- version: 25 -->
|
||||
<!-- version: 26 -->
|
||||
|
||||
# Validation v0.3.7 — Backfill Desk
|
||||
|
||||
@@ -99,15 +99,15 @@ Le journal opérateur fourni rapporte `cargo clean`, `cargo fmt`, audits Rust/Ma
|
||||
- [X] Transport readiness et role inventory sûrs.
|
||||
- [X] Store readiness et cohérence réseau.
|
||||
- [X] 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.
|
||||
- [X] Single active run + Start.
|
||||
- [X] Snapshot latest-value bridge.
|
||||
- [X] Cancel + races terminales.
|
||||
- [X] Checkpoint/frontier projection + Resume in-session.
|
||||
- [X] Frontend/security/composition tests verts.
|
||||
- [X] `cargo test --workspace --all-targets --all-features` final vert.
|
||||
- [X] `(cd crates/ksp-app-backfill-desk && cargo tauri build)` final vert.
|
||||
- [X] Smokes Mainnet opérateur antérieurs suffisants ; aucun nouveau smoke final requis.
|
||||
- [X] Réconciliation README/USAGE/plan/validation/architecture dans `pre.016`.
|
||||
- [ ] Prompt 0.3.8 + CHANGELOG + ROADMAP uniquement dans la lane de publication.
|
||||
|
||||
## 9. pre.002 — scaffold desktop
|
||||
@@ -651,4 +651,34 @@ Un `cargo clean` préalable est optionnel : il peut être utilisé pour une reco
|
||||
- [X] gate final borné au workspace, arbres Cargo et build Tauri ;
|
||||
- [ ] gate opérateur final à exécuter ;
|
||||
- [ ] `pre.016` interdit tant que ce gate n'est pas intégralement vert.
|
||||
## 32. `pre.015` — gate technique final
|
||||
|
||||
Le gate opérateur final est intégralement vert sur `0.3.7-pre.15` :
|
||||
|
||||
- [X] `cargo fmt --all -- --check` ;
|
||||
- [X] audits Rust/exports/workspace et Markdown ;
|
||||
- [X] `cargo check --workspace` ;
|
||||
- [X] `cargo clippy --workspace --all-targets --all-features -- -D warnings` sans warning ;
|
||||
- [X] `cargo test --workspace --all-targets --all-features` : 1 494 tests passés, 0 échec, 15 tests ignorés explicitement opt-in/operator-only ;
|
||||
- [X] arbres normal/features de `ksp-app-backfill-desk` et `ksp-job-backfill-lib` produits ;
|
||||
- [X] `cargo tree --duplicates` exécuté et revu ;
|
||||
- [X] `cargo tauri build` final réussi ;
|
||||
- [X] bundles Linux `.deb`, `.rpm` et `.AppImage` produits ;
|
||||
- [X] aucun smoke live supplémentaire requis, les smokes Mainnet précédents ayant déjà prouvé Start, monitoring, Cancel et Resume réels.
|
||||
|
||||
Aucun défaut technique n'est reporté vers la réconciliation documentaire.
|
||||
|
||||
## 33. `pre.016` — réconciliation documentaire finale
|
||||
|
||||
La surface candidate est réconciliée sans rouvrir le runtime :
|
||||
|
||||
- [X] `crates/ksp-app-backfill-desk/README.md` décrit responsabilités, composition, frontières et build de manière durable ;
|
||||
- [X] `crates/ksp-app-backfill-desk/USAGE.md` décrit l'utilisation sans journal de prerelease ni preuve de gate ;
|
||||
- [X] le plan est réaligné sur les commandes réellement livrées et l'événement `ksp-backfill-status` ;
|
||||
- [X] les index `docs/000-README.md` et `docs/validation/000-README.md` référencent `0.3.7` ;
|
||||
- [X] l'inventaire d'architecture fixe `ksp-app-backfill-desk` comme composant implémenté ;
|
||||
- [X] Layers/Contracts/Dependency Graph/Apps & Services décrivent la composition finale et les firewalls ;
|
||||
- [X] README racine mentionne la surface desktop Backfill sans faire de la documentation durable un changelog ;
|
||||
- [X] CHANGELOG et ROADMAP restent réservés à `pre.017` ;
|
||||
- [X] aucun code, test, frontend, Config ou manifest de crate n'est modifié.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user