12 KiB
Prompt de démarrage 0.3.6 — Job API + premier backfill historique RAW
1. Contexte de reprise
La base attendue est la release stable :
v0.3.5
La surface acquise doit notamment être :
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 :
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 :
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 :
ksp-job-api, comme API passive et backend-neutral de lifecycle/progression pour traitements bornés ;- un premier job historique RAW concret ;
- une composition explicite Transport -> conversion RAW ->
ksp-store-lib; - 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 :
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 :
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 :
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 :
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 :
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 :
é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 :
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 :
getSignaturesForAddress
getTransaction
Pour getSignaturesForAddress, confirmer notamment :
ordre newest -> oldest
before
until
limit
commitment
minContextSlot
sémantique de fin de pagination
cardinalité/limites réellement supportées
Pour getTransaction, confirmer notamment :
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 :
é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 :
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 :
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 :
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 :
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 :
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 :
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 :
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
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 :
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 :
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 :
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.