v0.3.5-pre.008
This commit is contained in:
432
prompts/025-V0_3_6_START_PROMPT.md
Normal file
432
prompts/025-V0_3_6_START_PROMPT.md
Normal file
@@ -0,0 +1,432 @@
|
||||
<!-- file: prompts/025-V0_3_6_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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.
|
||||
Reference in New Issue
Block a user