khadhroony-solana-project/prompts/025-V0_3_6_START_PROMPT.md

<!-- 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.