v0.3.7-pre.016

crates/ksp-app-backfill-desk/USAGE.md

@@ -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)
+```