# Prompt de démarrage `0.3.6` — Job API + premier backfill historique RAW ## 1. Contexte de reprise La base attendue est la release stable : ```text v0.3.5 ``` La surface acquise doit notamment être : ```text ksp-store-api -> RAW backend-agnostic -> RawTransaction + RawAccountState + observations -> 10 capabilities object-safe ksp-store-lib -> façade runtime backend-neutral -> backend postgres activé par feature par défaut ksp-store-postgres-lib -> PostgreSQL 17 validé -> RAW 10/10 physique ksp-interface-lib -> ProgramAccountMeta / ProgramInstruction -> SlotLifecycleEvent / SlotLifecycleStage -> TransactionSignature / TransactionExecutionEvent / TransactionExecutionOutcome -> dépendance normale Core-only ksp-onchain-transport-lib -> HTTP Solana typed complet -> WS standard + Helius -> Yellowstone engine actuel ``` `0.3.5` a confirmé la séparation suivante : ```text DTO riche / provider-specific -> Transport fait passif provider-neutral -> Interface modèle persistant / replayable -> Store API backlog durable -> Store policy / batch-size / progression -> Job/Worker ``` La release à ouvrir est : ```text 0.3.6 — ksp-job-api + premier backfill historique RAW ``` La première tranche est `0.3.6-pre.001` et commence par **audit de la base réelle + brainstorming + sizing + plan**, sans implémentation fonctionnelle lourde. ## 2. Mission Cette release doit introduire : 1. `ksp-job-api`, comme API passive et backend-neutral de lifecycle/progression pour traitements bornés ; 2. un premier job historique RAW concret ; 3. une composition explicite Transport -> conversion RAW -> `ksp-store-lib` ; 4. une ownership claire de la policy, de la pagination réseau, du batch-size, du checkpoint et de la cancellation. Le premier candidat prioritaire est un backfill `RawTransaction` historique **scopé par adresse**, fondé sur les primitives HTTP Solana existantes : ```text getSignaturesForAddress | v signatures ordonnées newest -> oldest | v getTransaction | v conversion vers RawTransaction + observation | v ksp-store-lib ``` Ce candidat n'est pas encore une décision irrévocable : `pre.001` doit vérifier la sémantique officielle actuelle, la surface Transport réelle, les bornes provider/RPC, les lacunes éventuelles et la faisabilité d'une clôture complète de la release dans une session. ## 3. Principes d'architecture non négociables ### 3.1 Store reste une primitive de persistence/navigation Ne pas déplacer dans Store : ```text batch-size métier priorité de job retry policy métier range historique décidé par le job checkpoint métier cadence scheduler progression cancellation ``` Store peut exposer ses primitives de lecture/écriture/cursorisation existantes ; il ne devient pas orchestrateur. ### 3.2 `ksp-job-api` reste passif L'API Job ne doit pas devenir : ```text scheduler global thread pool runtime Tokio propriétaire event bus queue distribuée registry de tous les jobs KSP backend de persistence implicite ``` `pre.001` doit déterminer la surface minimale réellement nécessaire au premier consumer. Les concepts à auditer, sans les figer d'avance, sont notamment : ```text JobId JobState JobDescriptor JobProgress JobOutcome JobCheckpoint cancellation / stop reason ``` Éviter les structs Option-soup et les états dont la sémantique n'est pas observable par le premier job. ### 3.3 Implémentation du backfill séparée de l'API `ksp-job-api` ne doit pas dépendre de Transport ou d'un backend Store physique. Le job concret peut dépendre de : ```text ksp-job-api ksp-onchain-transport-lib ksp-store-lib ksp-core-lib si réellement nécessaire ksp-logging-lib pour le comportement runtime ``` Aucune dépendance directe vers `ksp-store-postgres-lib` n'est autorisée au consumer ordinaire. Le nom et la forme de la crate d'implémentation du premier job doivent être décidés en `pre.001` après audit des conventions workspace. Ne pas créer plusieurs crates auxiliaires spéculatives. ### 3.4 Conversion RAW Le job doit produire les modèles RAW backend-neutral existants et écrire via `ksp-store-lib`. Il ne doit pas : ```text écrire du SQL connaître tokio-postgres/deadpool inventer un RawTransaction concurrent faire du decode Program produire STRUCTURAL/DECODED/DOMAIN persister des DTOs Transport tels quels ``` Auditer si la conversion Transport -> RAW mérite déjà une petite pipeline réutilisable. Par défaut, ne pas introduire `ksp-pipeline-raw-ingestion-lib` tant que la réutilisation job + futur worker ne justifie pas clairement une crate séparée. ## 4. Audit obligatoire de `pre.001` Avant toute implémentation, relire au minimum : ```text RULES.md ROADMAP.md CHANGELOG.md docs/000-README.md docs/PROMPT_STRUCTURE.md docs/VERSION_WORKFLOW.md docs/FILE_CONTRACTS.md docs/architecture/002-LAYERS_AND_DEPENDENCIES.md docs/architecture/003-COMPONENT_CONTRACTS.md docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md crates/ksp-store-api/** crates/ksp-store-lib/** crates/ksp-onchain-transport-lib/** ``` Puis auditer explicitement : ### 4.1 Transport historique Vérifier dans le code KSP et dans la documentation officielle actuelle : ```text getSignaturesForAddress getTransaction ``` Pour `getSignaturesForAddress`, confirmer notamment : ```text ordre newest -> oldest before until limit commitment minContextSlot sémantique de fin de pagination cardinalité/limites réellement supportées ``` Pour `getTransaction`, confirmer notamment : ```text commitment supporté encoding retenu maxSupportedTransactionVersion null / transaction unavailable slot blockTime meta / transaction completeness ``` Ne pas inventer une capacité de scan global de toutes les transactions si le RPC standard ne l'offre pas. ### 4.2 Store Inventorier les capacités `RawTransaction*` réellement disponibles et vérifier comment le job doit : ```text écrire canonical + observation traiter l'idempotence traiter un conflit réel éviter une réhydratation implicite d'un tombstone respecter le RawNetworkId du Store ``` Le job consomme `ksp-store-lib`; il ne bypass pas la façade pour parler à `ksp-store-api` ou au backend PostgreSQL directement sauf preuve architecturale contraire explicite. ### 4.3 Checkpoint et reprise Définir ce qui constitue un checkpoint fiable pour une pagination newest -> oldest par adresse. Le checkpoint doit être distingué de : ```text cursor Store signature candidate courante signature réellement persistée frontière contiguë complétée simple compteur de progression ``` La cancellation et une reprise doivent éviter de sauter silencieusement une transaction non terminée. Ne pas créer une table Job dans Store par réflexe. Si une persistence de checkpoint devient nécessaire, l'ownership et le besoin doivent être démontrés avant toute migration. ### 4.4 Retry et erreurs Séparer : ```text retry Transport déjà possédé par Transport retry métier du job provider rate limit / Retry-After transaction null/indisponible conflit Store cancellation échec terminal ``` Éviter les doubles boucles de retry Transport + Job qui amplifient involontairement les appels réseau. ### 4.5 Logging Le job concret étant comportemental, utiliser `ksp-logging-lib` si logging runtime nécessaire et respecter les conventions KSP de `TRACING_TARGET` / `constants.rs`. Ne jamais logguer : ```text URL/secret provider payload transaction complet credentials SQL bytes sensibles inutiles ``` Les signatures peuvent apparaître uniquement si les règles de logging KSP et le besoin opérationnel l'autorisent explicitement ; ne pas les rendre automatiquement via `Debug`. ## 5. Livrables obligatoires de `pre.001` Créer : ```text docs/plans/027-V0_3_6_JOB_API_RAW_BACKFILL_PLAN.md docs/validation/023-V0_3_6_JOB_API_RAW_BACKFILL.md deltas/0.3.6/pre.001.md ``` Le plan doit contenir au minimum : ```text inventaire des contrats existants matrice ownership API Job / job concret / Transport / Store choix ou rejet du backfill RawTransaction par adresse modèle de pagination/checkpoint/reprise modèle cancellation/progression/outcome risques de double retry et de gaps historiques choix de crate(s) minimal forecast des prereleases critères de clôture ``` `pre.001` peut faire évoluer `Cargo.toml` vers `0.3.6-pre.1`, mais ne doit pas créer de code fonctionnel lourd simplement pour remplir la tranche. ## 6. Direction préférée pour le premier backfill Si l'audit confirme le candidat, viser une verticale minimale : ```text adresse explicite + réseau explicite via Store/Transport configurés + commitment explicite + plage/bornes explicites si supportables sans fausse précision + pagination getSignaturesForAddress + hydratation getTransaction + conversion RAW + write via ksp-store-lib + progression observable + cancellation propre + checkpoint/reprise déterministes ``` Le premier job n'a pas à devenir un crawler global multi-address/provider ou un scheduler de production. ## 7. Tests attendus à terme Prévoir selon l'implémentation : ```text unit tests Job API public API canaries external implementation/consumer pagination newest -> oldest checkpoint contigu / reprise cancellation avant/pendant fetch et avant/pendant persistence idempotence Store conflit Store terminal et sûr null getTransaction rate-limit / retry ownership no secret/payload debug leak manifest/dependency firewall ``` Un smoke Devnet opt-in peut être ajouté seulement s'il apporte une preuve que les fixtures ne peuvent pas apporter. Aucun test live payant n'est requis. ## 8. Hors périmètre `0.3.6` ```text application desktop de backfill/inspection (0.3.7) worker RAW live continu scheduler global queue distribuée cron engine STRUCTURAL/DECODED/DOMAIN Program decoding materialization nouveau backend Store nouvelle persistence RawAccountState réouverture des migrations RAW PostgreSQL sans nécessité démontrée event bus Interface persistence Job ajoutée par réflexe support provider-specific payant requis pour fermer la release ``` ## 9. Archive historique kbot3 L'archive kbot3 **n'est pas requise** pour démarrer ou fermer `0.3.6`. La source de vérité est : ```text base KSP stable v0.3.5 règles/architecture KSP actuelles surfaces Transport/Store réelles contrats RPC officiels actuels ``` Si une comparaison avec un ancien mécanisme de backfill kbot3 devient utile pendant le brainstorming, elle peut être fournie comme référence historique uniquement ; elle ne doit pas être copiée comme architecture normative. ## 10. Cadence provisoire Ne pas figer le nombre exact de prereleases avant le sizing de `pre.001`. Une trajectoire raisonnable à confirmer est : ```text pre.001 audit + brainstorming + sizing + plan pre.002 ksp-job-api minimal pre.003 première verticale backfill RawTransaction pre.004 checkpoint/reprise/cancellation + canaris externes pre.005 hardening + intégration Store/Transport pre.006 gate technique final pre.007 réconciliation documentaire pre.008 préparation de publication rel.001 stable ``` La release doit rester dimensionnée pour **une session maximum**. Si le premier job réel exige nettement plus, réduire le scope plutôt que d'introduire une architecture partielle non fermable. ## 11. Gate opérateur de base Après les tranches Rust significatives : ```text cargo fmt --all python3 scripts/audit_rust_workspace_rules.py python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.6 cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-job-api ``` Ajouter les tests ciblés des crates concrètement modifiées. Le gate technique final doit inclure `cargo test --workspace` et les graphes Cargo pertinents. ## 12. Règle de décision Si le brainstorming de `pre.001` montre que `getSignaturesForAddress + getTransaction` ne permet pas un premier backfill suffisamment exact, reprenable et testable sans élargissement excessif, **ne pas forcer cette verticale**. Documenter le blocage, choisir le plus petit backfill RAW réellement démontrable, et préserver les frontières Job / Transport / Store.