1113 lines
34 KiB
Markdown
1113 lines
34 KiB
Markdown
<!-- file: prompts/028-V0_3_9_START_PROMPT.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Prompt de démarrage `0.3.9` — `ksp-worker-api` générique + audit RAW Transaction préparatoire
|
|
|
|
## 1. Identité de la release et base exacte requise
|
|
|
|
Ouvrir cette session uniquement après publication et tag validés de :
|
|
|
|
```text
|
|
v0.3.8
|
|
```
|
|
|
|
La base autoritaire est le dépôt stable `v0.3.8` ou, si l'opérateur fournit une archive stable explicitement désignée comme base, cette archive exacte.
|
|
|
|
Vérifier avant tout travail :
|
|
|
|
```text
|
|
workspace.package.version = 0.3.8
|
|
deltas/0.3.8/rel.001.md présent
|
|
ksp-app-store-desk présent et stable
|
|
ksp-job-api / ksp-job-backfill-lib présents et stables
|
|
ksp-onchain-transport-lib / ksp-config-lib / ksp-store-lib présents et stables
|
|
```
|
|
|
|
Release ouverte :
|
|
|
|
```text
|
|
0.3.9
|
|
```
|
|
|
|
Première livraison attendue :
|
|
|
|
```text
|
|
0.3.9-pre.001
|
|
```
|
|
|
|
`pre.001` est un gate d'audit/brainstorming/sizing/planification. Il ne doit pas commencer l'implémentation lourde de `ksp-worker-api` et ne doit surtout pas commencer le worker RAW Transaction.
|
|
|
|
---
|
|
|
|
## 2. Mission et résultat attendu
|
|
|
|
### 2.1 Mission principale
|
|
|
|
Introduire :
|
|
|
|
```text
|
|
crates/ksp-worker-api
|
|
```
|
|
|
|
comme API KSP **générique** pour des services continus pouvant rester actifs indéfiniment.
|
|
|
|
Le contrat doit couvrir uniquement les primitives réellement transversales nécessaires à des workers KSP, par exemple selon l'audit `pre.001` :
|
|
|
|
```text
|
|
identity
|
|
lifecycle/state
|
|
health
|
|
progress/activity sûre
|
|
snapshot latest-value
|
|
notification/resynchronisation
|
|
cancellation/stop borné
|
|
erreur terminale/fault sûre
|
|
handle/supervision si réellement générique
|
|
```
|
|
|
|
Les noms, états exacts et transitions sont des questions de `pre.001`; ils ne sont pas imposés par cette liste.
|
|
|
|
### 2.2 Distinction Worker / Job obligatoire
|
|
|
|
`ksp-worker-api` ne doit pas devenir un alias de `ksp-job-api`.
|
|
|
|
Sémantique cible :
|
|
|
|
```text
|
|
Job = traitement borné/terminable avec outcome et fin normale attendue
|
|
Worker = service continu dont l'état Running peut être durable/indéfini
|
|
```
|
|
|
|
Le pattern latest-value stabilisé dans `ksp-job-api` peut être réutilisé **conceptuellement** lorsque ses propriétés sont génériques, mais :
|
|
|
|
```text
|
|
aucune dépendance ksp-worker-api -> ksp-job-api n'est supposée
|
|
aucune sémantique de checkpoint/backfill n'entre dans Worker API
|
|
aucun JobId/JobKindCode n'est réutilisé par simple commodité
|
|
aucun worker concret ne dicte les états de l'API générique
|
|
```
|
|
|
|
### 2.3 Deuxième résultat obligatoire de `0.3.9`
|
|
|
|
Une fois `ksp-worker-api` **fonctionnellement fermée et hardenée**, la fin de `0.3.9` doit produire un audit fonctionnel exhaustif des sources/méthodes d'acquisition `RawTransaction`.
|
|
|
|
Cet audit est un **handoff architectural pour `0.3.10`**. Il ne constitue pas l'implémentation du worker concret et ne doit pas déformer `ksp-worker-api` pour un besoin Solana-specific.
|
|
|
|
Résultat attendu à la fermeture :
|
|
|
|
```text
|
|
ksp-worker-api stable et générique
|
|
+
|
|
matrice exhaustive RawTransaction documentée
|
|
+
|
|
décisions/gaps préparatoires explicites pour 0.3.10
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Sources de vérité internes obligatoires — ordre de lecture
|
|
|
|
### 3.1 Gouvernance générale
|
|
|
|
Lire d'abord :
|
|
|
|
```text
|
|
RULES.md
|
|
ROADMAP.md
|
|
CHANGELOG.md
|
|
docs/000-README.md
|
|
|
|
docs/rules/RULES_GENERAL.md
|
|
docs/rules/RULES_KSP.md
|
|
docs/rules/RULES_RUST.md
|
|
docs/rules/RULES_DEPENDENCIES.md
|
|
docs/rules/RULES_DOCUMENTATION.md
|
|
docs/rules/FILE_CONTRACTS.md
|
|
docs/rules/VERSION_WORKFLOW.md
|
|
docs/rules/PROMPT_STRUCTURE.md
|
|
```
|
|
|
|
Le prompt complète ces règles ; il ne les remplace pas.
|
|
|
|
Rappels directement bloquants :
|
|
|
|
```text
|
|
Rust 2024
|
|
unsafe / unwrap / expect / panic interdits selon les règles KSP
|
|
? interdit en production
|
|
retours explicites ; clippy::implicit_return deny
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
pas de pub mod
|
|
pub/pub(crate) partagés consommés via crate::Item
|
|
item seulement module-local => private
|
|
unit tests sous unit_tests/
|
|
integration tests sous tests/
|
|
```
|
|
|
|
Après toute modification Rust :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
```
|
|
|
|
Pour tout Markdown touché :
|
|
|
|
```bash
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.9
|
|
```
|
|
|
|
Une commande non exécutée n'est jamais déclarée PASS.
|
|
|
|
### 3.2 Architecture acquisition / workers / jobs
|
|
|
|
Lire intégralement :
|
|
|
|
```text
|
|
docs/architecture/000-README.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
|
|
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
|
```
|
|
|
|
Ces documents possèdent les décisions durables acquises avant l'ouverture de `0.3.9`, notamment :
|
|
|
|
```text
|
|
ksp-worker-api reste générique
|
|
ksp-worker-raw-transaction-ingest-lib est le premier worker concret retenu
|
|
le worker RAW est multi-source dès V1
|
|
l'audit des sources RAW a lieu en fin de 0.3.9 après fermeture Worker API
|
|
0.3.11 appartient à la Desk d'ingestion
|
|
0.3.12 étend le backfill vers les autres sources/stratégies
|
|
```
|
|
|
|
Une divergence entre ces documents et la base réelle déclenche un audit explicite ; ne pas improviser une nouvelle trajectoire.
|
|
|
|
### 3.3 `ksp-job-api` — référence de propriétés, pas parent de Worker
|
|
|
|
Lire :
|
|
|
|
```text
|
|
crates/ksp-job-api/Cargo.toml
|
|
crates/ksp-job-api/README.md
|
|
crates/ksp-job-api/USAGE.md
|
|
crates/ksp-job-api/src/lib.rs
|
|
crates/ksp-job-api/src/
|
|
crates/ksp-job-api/tests/
|
|
|
|
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
|
|
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
|
|
```
|
|
|
|
Inventorier précisément les propriétés déjà prouvées :
|
|
|
|
```text
|
|
identity bornée
|
|
lifecycle explicite
|
|
cancellation partagée/idempotente
|
|
latest-value notification/source
|
|
sequence/resynchronisation
|
|
terminal immuable
|
|
Debug/redaction
|
|
Send/Sync
|
|
API Core-only
|
|
```
|
|
|
|
Puis décider en `pre.001` lesquelles sont réellement génériques à Worker et lesquelles restent Job-specific.
|
|
|
|
Interdiction : copier mécaniquement les types/états Job ou ajouter `ksp-job-api` comme dépendance pour éviter quelques lignes de code.
|
|
|
|
### 3.4 Premier backfill concret — référence de contraste
|
|
|
|
Lire :
|
|
|
|
```text
|
|
crates/ksp-job-backfill-lib/README.md
|
|
crates/ksp-job-backfill-lib/USAGE.md
|
|
crates/ksp-job-backfill-lib/src/
|
|
crates/ksp-job-backfill-lib/tests/
|
|
|
|
crates/ksp-app-backfill-desk/README.md
|
|
crates/ksp-app-backfill-desk/USAGE.md
|
|
|
|
docs/plans/028-V0_3_7_BACKFILL_DESK_PLAN.md
|
|
docs/validation/024-V0_3_7_BACKFILL_DESK.md
|
|
```
|
|
|
|
Objectif de cette lecture :
|
|
|
|
```text
|
|
comprendre la séparation API générique / consumer concret
|
|
identifier ce qui est Job/backfill-specific et ne doit jamais remonter dans Worker API
|
|
constater que le backfill 0.3.6/0.3.7 est une première stratégie HTTP
|
|
ne pas en déduire que tout backfill ou tout ingest doit être HTTP
|
|
```
|
|
|
|
Le scope historique actuel :
|
|
|
|
```text
|
|
getSignaturesForAddress
|
|
-> getTransaction observé
|
|
-> RawTransaction + RawTransactionObservation
|
|
-> ksp-store-lib
|
|
```
|
|
|
|
reste valide mais n'est pas la définition générale de l'acquisition RAW Transaction.
|
|
|
|
### 3.5 Store RAW — convergence multi-source à préserver
|
|
|
|
Lire :
|
|
|
|
```text
|
|
crates/ksp-store-api/README.md
|
|
crates/ksp-store-api/src/lib.rs
|
|
crates/ksp-store-api/src/model/raw_transaction.rs
|
|
crates/ksp-store-api/src/model/raw_primitives.rs
|
|
crates/ksp-store-api/src/model/raw_retention.rs
|
|
crates/ksp-store-api/src/capability/raw_transaction.rs
|
|
|
|
crates/ksp-store-lib/README.md
|
|
crates/ksp-store-lib/USAGE.md
|
|
crates/ksp-store-lib/src/lib.rs
|
|
crates/ksp-store-lib/src/store.rs
|
|
|
|
crates/ksp-store-postgres-lib/README.md
|
|
crates/ksp-store-postgres-lib/tests/
|
|
```
|
|
|
|
Invariants à préserver dans l'audit futur :
|
|
|
|
```text
|
|
identité canonique RawTransaction = réseau + signature
|
|
contenu canonique indépendant du provider/source
|
|
acquisition/provenance séparée dans RawTransactionObservation
|
|
même identité + même contenu => idempotence
|
|
même identité + contenu incompatible => conflit explicite
|
|
jamais d'écrasement silencieux
|
|
Store consommé par les workers uniquement via ksp-store-lib
|
|
```
|
|
|
|
### 3.6 Transport on-chain réel
|
|
|
|
Lire avant l'audit RAW final :
|
|
|
|
```text
|
|
crates/ksp-onchain-transport-lib/README.md
|
|
crates/ksp-onchain-transport-lib/USAGE.md
|
|
crates/ksp-onchain-transport-lib/src/lib.rs
|
|
crates/ksp-onchain-transport-lib/src/rpc_method.rs
|
|
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
|
|
crates/ksp-onchain-transport-lib/src/ws_*.rs
|
|
crates/ksp-onchain-transport-lib/src/grpc_*.rs
|
|
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
```
|
|
|
|
Ne pas se contenter des noms de modules : inventorier les capabilities publiques réellement utilisables, leurs garanties, leurs limites et les metadata de provenance disponibles.
|
|
|
|
### 3.7 Config / secrets / réseaux
|
|
|
|
Lire avant le handoff `0.3.10` :
|
|
|
|
```text
|
|
crates/ksp-config-lib/README.md
|
|
crates/ksp-config-lib/USAGE.md
|
|
crates/ksp-config-lib/src/environment.rs
|
|
crates/ksp-config-lib/src/transport.rs
|
|
crates/ksp-config-lib/tests/
|
|
|
|
config/std.transport.json
|
|
config/schemas/std.transport.schema.json
|
|
.env.example
|
|
```
|
|
|
|
Acquis :
|
|
|
|
```text
|
|
Config est l'unique owner de env/secrets
|
|
KSP_SECRET_HELIUS_API_KEY existe déjà dans le namespace Config KSP
|
|
les URLs/credentials ne doivent jamais être dupliqués dans Worker API
|
|
0.3.9 n'ajoute aucun endpoint/profil Helius pour le worker futur
|
|
```
|
|
|
|
L'audit peut identifier les adaptations nécessaires pour `0.3.10`; il ne les implémente pas dans la phase générique `0.3.9`.
|
|
|
|
---
|
|
|
|
## 4. Référence historique kbot3 — fonctionnelle uniquement
|
|
|
|
Pour la construction de `ksp-worker-api`, kbot3 n'est pas nécessaire comme source d'API.
|
|
|
|
Pour **l'audit RAW Transaction de fin de `0.3.9`**, l'archive kbot3 fournie par l'opérateur doit être réauditée comme référence fonctionnelle historique.
|
|
|
|
Règle absolue :
|
|
|
|
```text
|
|
kbot3 = référence fonctionnelle
|
|
kbot3 != source de code
|
|
kbot3 != source de DTO
|
|
kbot3 != source de Config/URL
|
|
kbot3 != source de dépendances/versions
|
|
kbot3 != contrat KSP
|
|
```
|
|
|
|
Inventorier les fonctions historiques pertinentes :
|
|
|
|
```text
|
|
sources d'acquisition utilisées
|
|
rôles live/history/backfill
|
|
HTTP discovery/hydration
|
|
WS/provider streaming
|
|
sélection provider/source
|
|
reconnect/recovery
|
|
multi-source ou fallback éventuel
|
|
provenance conservée
|
|
limites/quotas connus historiquement
|
|
```
|
|
|
|
Une capability historique n'est jamais déclarée encore disponible sans réaudit de la source primaire actuelle.
|
|
|
|
---
|
|
|
|
## 5. Sources externes normatives à réauditer lorsque la fraîcheur importe
|
|
|
|
L'audit RAW Transaction est freshness-sensitive. Utiliser les sources primaires courantes au moment de la tranche, notamment :
|
|
|
|
```text
|
|
documentation Solana officielle des clusters
|
|
Solana JSON-RPC HTTP officiel
|
|
Solana WebSocket officiel
|
|
Helius documentation/pricing/capability matrix officielle
|
|
Yellowstone gRPC / proto upstream officiel
|
|
provider docs officielles pour replay/from_slot/quota lorsque pertinentes
|
|
```
|
|
|
|
Ne pas figer dans le code une observation historique du prompt.
|
|
|
|
À vérifier explicitement :
|
|
|
|
```text
|
|
terminologie actuelle Mainnet et compatibilité mainnet-beta
|
|
méthodes WS réellement stables/instables et provider support
|
|
Helius HTTP standard Mainnet/Devnet
|
|
Helius WS standard Mainnet/Devnet
|
|
Helius transactionSubscribe et autres extensions : disponibilité/tier courant
|
|
Yellowstone transaction / transaction_status / block / block_meta
|
|
mécanismes replay/from_slot réellement supportés par chaque provider
|
|
quotas, filtre limits, subscription limits, reconnect semantics
|
|
```
|
|
|
|
Les offres provider peuvent évoluer entre le présent prompt et l'exécution de `0.3.9`; toujours réauditer avant décision.
|
|
|
|
---
|
|
|
|
## 6. État validé `v0.3.8` à préserver
|
|
|
|
### 6.1 Frontières fondamentales
|
|
|
|
```text
|
|
ksp-core-lib -> types/erreur/program registry fondamentaux
|
|
ksp-logging-lib -> logging/tracing policy/runtime
|
|
ksp-config-lib -> Config/env/secrets/composites
|
|
ksp-onchain-transport-lib -> HTTP/WS/Yellowstone transport
|
|
ksp-store-api -> contrats persistants backend-neutral
|
|
ksp-store-lib -> façade Store consumer
|
|
ksp-store-postgres-lib -> backend physique privé
|
|
ksp-job-api -> API traitements bornés/terminables
|
|
ksp-job-backfill-lib -> premier job historique concret
|
|
ksp-worker-api -> nouvelle API continue générique, à créer en 0.3.9
|
|
```
|
|
|
|
### 6.2 Store Desk n'est pas rouvert
|
|
|
|
`0.3.8` a stabilisé :
|
|
|
|
```text
|
|
inspection random-access backend-neutral
|
|
RawTransaction / RawAccountState / observations
|
|
DataTables server-side
|
|
pagination machine cursor/keyset conservée
|
|
Store Desk read-only
|
|
```
|
|
|
|
`0.3.9` ne transforme pas Store Desk en écran Worker et ne modifie pas Store API pour préparer artificiellement le worker futur.
|
|
|
|
### 6.3 Interface events
|
|
|
|
`ksp-interface-lib` conserve les événements passifs partagés existants (`SlotLifecycleEvent`, `TransactionExecutionEvent`) sans devenir l'API Worker ou une seconde couche RAW.
|
|
|
|
---
|
|
|
|
## 7. Décisions acquises et questions réellement ouvertes
|
|
|
|
### 7.1 Décisions acquises — non négociables sans contradiction prouvée de la base
|
|
|
|
```text
|
|
ksp-worker-api et ksp-worker-raw-transaction-ingest-lib restent deux crates distinctes
|
|
0.3.9 livre ksp-worker-api
|
|
0.3.10 livre le premier worker RawTransaction concret
|
|
0.3.11 livre la Desk d'ingestion
|
|
0.3.12 étend Backfill aux autres sources/méthodes
|
|
|
|
Worker API reste générique et non Solana
|
|
Worker API est fonctionnellement fermée avant l'audit détaillé RawTransaction
|
|
l'audit RawTransaction est placé en fin de 0.3.9 pour ne pas saturer 0.3.10
|
|
le futur worker est multi-source dès V1
|
|
aucune source HTTP/WS/gRPC unique n'est supposée a priori
|
|
Config reste l'unique owner des secrets
|
|
KSP_SECRET_HELIUS_API_KEY doit être réutilisée dans le futur au lieu de créer un second secret
|
|
aucune URL/endpoints Helius n'est ajoutée pendant 0.3.9
|
|
mainnet/mainnet-beta n'est pas renommé sans audit de compatibilité
|
|
kbot3 reste fonctionnel-only
|
|
```
|
|
|
|
### 7.2 Questions ouvertes pour `ksp-worker-api`
|
|
|
|
`pre.001` doit répondre sans projeter les besoins RawTransaction :
|
|
|
|
```text
|
|
WorkerId propre ou autre identité générique ?
|
|
états lifecycle exacts ?
|
|
Created/Starting/Running/Stopping/Stopped/Faulted nécessaires ?
|
|
health est-il distinct de lifecycle ?
|
|
quel snapshot générique minimal ?
|
|
quelle notion générique de progression/activity existe réellement pour un service continu ?
|
|
latest-value source/sequence doit-elle être directement dans Worker API ?
|
|
stop/cancellation : primitive séparée ou intégrée au handle ?
|
|
restart/restartability appartient-elle à l'API ou au caller ?
|
|
quelle immutabilité après fault/stop ?
|
|
quels contrats Send/Sync/object-safe ?
|
|
external implementation sans runtime KSP possible ?
|
|
Core-only est-il suffisant comme dépendance exacte ?
|
|
```
|
|
|
|
Aucun type spécifique à transaction, slot, provider, endpoint, Store, replay ou backfill ne doit apparaître pour « faciliter » le premier consumer.
|
|
|
|
### 7.3 Questions ouvertes pour l'audit RAW de fin de release
|
|
|
|
L'audit doit déterminer, sans implémenter le worker :
|
|
|
|
```text
|
|
quelles sources sont admissibles en continuous ingest ?
|
|
quelles sources fournissent une transaction complète directement ?
|
|
quelles sources font seulement discovery et nécessitent hydration ?
|
|
quelles sources sont utiles pour gap repair/catch-up ?
|
|
quelles sources peuvent aussi servir au backfill historique ?
|
|
quelles combinaisons multi-source apportent redondance ou complémentarité réelle ?
|
|
quels gaps Transport/Config doivent être comblés en 0.3.10 ?
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Objectifs/livrables `0.3.9`
|
|
|
|
Livrables attendus :
|
|
|
|
```text
|
|
crates/ksp-worker-api/
|
|
Cargo.toml
|
|
src/
|
|
tests/
|
|
README.md
|
|
USAGE.md
|
|
|
|
docs/plans/<nouveau plan 0.3.9>
|
|
docs/validation/<nouvelle validation 0.3.9>
|
|
|
|
document/matrice d'audit RawTransaction de fin de release
|
|
handoff explicite vers 0.3.10
|
|
|
|
deltas/0.3.9/pre.NNN.md / fix / rel.001
|
|
prompt 0.3.10 dans la tranche de publication finale
|
|
```
|
|
|
|
Le document d'audit RAW peut être intégré au plan/architecture/référence la plus appropriée après décision de `pre.001`; ne pas créer un fichier arbitraire si un owner documentaire existe déjà.
|
|
|
|
---
|
|
|
|
## 9. Hors périmètre `0.3.9`
|
|
|
|
Interdit dans cette release sauf correction indispensable d'une contradiction découverte et explicitement rescopée :
|
|
|
|
```text
|
|
ksp-worker-raw-transaction-ingest-lib
|
|
worker RawTransaction fonctionnel
|
|
persistance live RawTransaction depuis un nouveau worker
|
|
ksp-app-raw-transaction-ingest-desk
|
|
modification multi-source de ksp-job-backfill-lib
|
|
modification multi-source de ksp-app-backfill-desk
|
|
nouveaux endpoints/profils Helius runtime
|
|
nouvelles URLs Helius Config
|
|
nouveau secret Helius
|
|
decode Program / STRUCTURAL / DECODED / DOMAIN
|
|
nouveau backend Store
|
|
SQL/schema/migration pour le worker
|
|
scheduler global / control plane / remote worker protocol
|
|
Tauri/IPC Worker
|
|
```
|
|
|
|
`0.3.9` **peut documenter** les adaptations Transport/Config requises par `0.3.10`; elle ne doit pas les implémenter par anticipation pendant l'audit.
|
|
|
|
---
|
|
|
|
## 10. Contraintes sécurité/API/architecture spécifiques
|
|
|
|
### 10.1 Dépendances `ksp-worker-api`
|
|
|
|
Cible initiale à challenger en `pre.001` :
|
|
|
|
```text
|
|
ksp-worker-api -> ksp-core-lib uniquement
|
|
```
|
|
|
|
Ne pas ajouter sans preuve :
|
|
|
|
```text
|
|
ksp-job-api
|
|
ksp-interface-lib
|
|
ksp-config-lib
|
|
ksp-logging-lib
|
|
ksp-onchain-transport-lib
|
|
ksp-store-api
|
|
ksp-store-lib
|
|
tokio
|
|
futures
|
|
serde
|
|
Tauri
|
|
provider SDK
|
|
```
|
|
|
|
Une API passive ne doit pas devenir runtime-owned par commodité.
|
|
|
|
### 10.2 Debug / sécurité
|
|
|
|
Les surfaces génériques doivent :
|
|
|
|
```text
|
|
bornes explicites pour identities/codes
|
|
Debug sûr et borné
|
|
aucun payload/secret arbitraire dans errors/snapshots
|
|
aucun Box<dyn Error> externe conservé dans état public
|
|
codes d'erreur KSP statiques
|
|
aucune queue non bornée
|
|
aucun listener lent autorisé à bloquer le producteur
|
|
```
|
|
|
|
### 10.3 Runtime ownership
|
|
|
|
`ksp-worker-api` décrit des contrats ; elle ne crée pas automatiquement un runtime Tokio, thread, scheduler ou process.
|
|
|
|
Le futur `ksp-worker-raw-transaction-ingest-lib` de `0.3.10` possédera la logique runtime concrète correspondante.
|
|
|
|
---
|
|
|
|
## 11. Première mission `pre.001` — audit, brainstorming, sizing et planification
|
|
|
|
**Ne pas commencer l'implémentation lourde avant la sortie de ce gate.**
|
|
|
|
### 11.1 Vérifier la base
|
|
|
|
- archive/tag stable `v0.3.8` ;
|
|
- `workspace.package.version` ;
|
|
- `rel.001` ;
|
|
- membres workspace ;
|
|
- versions/file headers ;
|
|
- audits Rust/Markdown baseline ;
|
|
- `cargo tree` actuel de `ksp-job-api` et dépendances voisines.
|
|
|
|
### 11.2 Auditer `ksp-job-api`
|
|
|
|
Construire une matrice :
|
|
|
|
```text
|
|
concept Job
|
|
propriété réellement générique ?
|
|
pertinent pour Worker ?
|
|
réutilisation conceptuelle ?
|
|
duplication justifiée ?
|
|
interdit dans Worker ?
|
|
```
|
|
|
|
Ne pas résoudre par héritage nominal ou dépendance de crate avant cette matrice.
|
|
|
|
### 11.3 Brainstorm Worker API
|
|
|
|
Définir :
|
|
|
|
```text
|
|
identity
|
|
state machine
|
|
health model
|
|
snapshot minimal
|
|
notification/latest-value semantics
|
|
stop/cancellation
|
|
fault semantics
|
|
restart ownership
|
|
thread-safety/object-safety
|
|
public API surface
|
|
error codes
|
|
Debug/redaction
|
|
external implementation test
|
|
```
|
|
|
|
Chaque élément doit être justifié par un worker générique, pas uniquement par RAW Transaction.
|
|
|
|
### 11.4 Dependency/threat map
|
|
|
|
Documenter :
|
|
|
|
```text
|
|
allowed dependency graph
|
|
forbidden reverse edges
|
|
runtime ownership
|
|
unbounded queue risks
|
|
slow listener risks
|
|
stale snapshot/race risks
|
|
stop-vs-fault race
|
|
restart/old-handle race
|
|
identity/logging leakage
|
|
```
|
|
|
|
### 11.5 Sizing
|
|
|
|
Recalibrer la release pour rester courte.
|
|
|
|
Objectif : seulement quelques tranches de code Worker API, puis audit RAW et couloirs de fermeture. Si l'API nécessite beaucoup plus de code que prévu, identifier pourquoi avant de l'ouvrir davantage.
|
|
|
|
### 11.6 Sortie obligatoire de `pre.001`
|
|
|
|
Le gate est fermé seulement avec :
|
|
|
|
```text
|
|
architecture Worker API décidée
|
|
state/health/snapshot/stop semantics décidées
|
|
surface publique prévue
|
|
exact dependency map
|
|
questions différées explicitement listées
|
|
threat map
|
|
plan de tests
|
|
prévision souple recalibrée
|
|
audit RAW positionné après freeze fonctionnel de l'API
|
|
aucun code RawTransaction worker commencé
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Prévision souple initiale — release volontairement courte
|
|
|
|
La numérotation est prévisionnelle. Les fixes ou splits nécessaires sont autorisés ; ne jamais forcer la fermeture pour respecter un numéro.
|
|
|
|
### pre.001 — audit / architecture / sizing Worker API
|
|
|
|
Lecture complète, comparaison Job/Worker, state/health/snapshot/cancellation design, dependencies, threat map, tests et sizing. Pas de worker concret.
|
|
|
|
### pre.002 — contrats `ksp-worker-api`
|
|
|
|
Créer la crate et matérialiser le noyau générique décidé : identities/states/health/snapshot/latest-value/stop uniquement selon le plan validé. Tests unit/public/dependency dès la même tranche.
|
|
|
|
#### pre.002-fix.NNN — correctifs éventuels du noyau API
|
|
|
|
Uniquement si le contrat générique de `pre.002` présente un défaut réel.
|
|
|
|
### pre.003 — hardening / external implementation / freeze fonctionnel
|
|
|
|
Fermer lifecycle races, Send/Sync, object-safety si requise, external consumer/implementation, Debug/redaction, exact export/module inventories et dependency firewall.
|
|
|
|
**À la fin de cette tranche, Worker API doit être considérée fonctionnellement fermée avant l'audit RAW Transaction.**
|
|
|
|
### pre.004 — audit fonctionnel exhaustif des sources `RawTransaction` + handoff `0.3.10`
|
|
|
|
Tranche principalement documentaire/research, placée volontairement après la freeze Worker API.
|
|
|
|
Elle ne modifie ni Worker API pour des besoins Solana-specific, ni Transport/Config/endpoints par anticipation.
|
|
|
|
### pre.005 — gate technique final
|
|
|
|
```text
|
|
fmt/audits/check/clippy/tests workspace
|
|
ksp-worker-api ciblé
|
|
graphes Cargo / duplicates pertinents
|
|
```
|
|
|
|
Aucun smoke réseau n'est requis pour Worker API elle-même. Un éventuel probe externe de l'audit source reste diagnostic et ne transforme pas `0.3.9` en implémentation Transport.
|
|
|
|
### pre.006 — réconciliation documentaire finale
|
|
|
|
README/USAGE Worker API, plan/validation, architecture/référence et document d'audit RAW final. `USAGE.md` reste version-neutral.
|
|
|
|
### pre.007 — préparation de publication
|
|
|
|
Uniquement :
|
|
|
|
```text
|
|
prompt 0.3.10
|
|
CHANGELOG.md
|
|
ROADMAP.md
|
|
Cargo.toml mécanique
|
|
delta
|
|
```
|
|
|
|
### rel.001 — publication stable
|
|
|
|
Publication mécanique `v0.3.9`, aucun rattrapage fonctionnel/documentaire.
|
|
|
|
Le nombre de tranches de **code** est volontairement faible. Si `pre.001` conclut que `pre.002` + `pre.003` peuvent être fusionnées sans dépasser les budgets/risques, la prévision peut être raccourcie ; les couloirs audit RAW, gate technique, réconciliation documentaire et publication restent séparés selon leurs responsabilités.
|
|
|
|
---
|
|
|
|
## 13. Audit RAW Transaction obligatoire de fin `0.3.9`
|
|
|
|
### 13.1 Principe
|
|
|
|
Ne jamais commencer par :
|
|
|
|
```text
|
|
"le worker sera HTTP"
|
|
"le worker sera WebSocket"
|
|
"le worker sera gRPC"
|
|
```
|
|
|
|
Commencer par les **capabilities d'acquisition** et les rôles qu'elles remplissent.
|
|
|
|
### 13.2 Familles/méthodes minimales à examiner
|
|
|
|
Au minimum :
|
|
|
|
```text
|
|
HTTP getSignaturesForAddress + getTransaction
|
|
HTTP slots / getBlocks / getBlock
|
|
WS logsSubscribe + éventuelle hydration HTTP
|
|
WS signatureSubscribe + éventuelle hydration
|
|
WS blockSubscribe lorsque réellement disponible
|
|
extensions transactionnelles provider-specific dont Helius transactionSubscribe
|
|
Yellowstone transactions
|
|
Yellowstone transaction_status
|
|
Yellowstone blocks
|
|
Yellowstone block_meta
|
|
replay / from_slot / catch-up lorsque le provider le supporte
|
|
multi-provider / multi-transport
|
|
```
|
|
|
|
Ajouter toute autre voie courante découverte dans les sources primaires.
|
|
|
|
### 13.3 Matrice obligatoire par source/méthode
|
|
|
|
Pour chaque voie :
|
|
|
|
| Dimension | Question obligatoire |
|
|
|---------------------|----------------------------------------------------------------------------|
|
|
| transport/protocole | HTTP, WS, Yellowstone gRPC, provider-specific ? |
|
|
| provider | standard Solana, Helius, PublicNode, OrbitFlare, autre réellement audité ? |
|
|
| réseau | Mainnet, Devnet, Testnet selon disponibilité réelle ? |
|
|
| disponibilité | free, payant, provider/tier-dependent au moment de l'audit ? |
|
|
| temporalité | live, catch-up, gap-repair, historique ? |
|
|
| discovery | comment la transaction est-elle découverte ? |
|
|
| contenu | transaction complète directe, référence, logs, statut, block ? |
|
|
| hydration | `getTransaction` ou autre lecture complémentaire nécessaire ? |
|
|
| filtres | compte/programme/signature/slot/success/failure/vote/etc. ? |
|
|
| ordering | ordre garanti, seulement observé, ou aucun ? |
|
|
| duplication | quelles duplications/replays attendre ? |
|
|
| reconnect | comportement sur coupure et resubscribe ? |
|
|
| replay | slot/checkpoint/from_slot réellement supporté ? profondeur ? |
|
|
| gap repair | comment détecter/réparer une coupure ? |
|
|
| backpressure | comportement si KSP consomme plus lentement ? |
|
|
| commitment/finality | quelles informations et garanties ? |
|
|
| provenance | metadata sûre à conserver dans `RawTransactionObservation` ? |
|
|
| quotas/limits | RPS, subscriptions, account filters, response limits, tier ? |
|
|
| gap Transport KSP | capability déjà présente ou adaptation `0.3.10` ? |
|
|
| gap Config KSP | profil/secret/capability descriptor à ajouter en `0.3.10` ? |
|
|
| applicability | continuous ingest, catch-up/gap repair, historical backfill ? |
|
|
|
|
La table finale doit respecter le formateur/audit Markdown KSP.
|
|
|
|
### 13.4 Relations entre sources
|
|
|
|
Classer explicitement les combinaisons utiles :
|
|
|
|
```text
|
|
alternative = A ou B pour le même rôle
|
|
complémentaire = discovery A + hydration B
|
|
redondante = A + B en parallèle pour résilience/coverage
|
|
spécialisée = source dédiée live, catch-up, gap-repair ou historique
|
|
```
|
|
|
|
Le futur worker peut combiner plusieurs catégories.
|
|
|
|
Éviter un modèle trop pauvre comme :
|
|
|
|
```rust
|
|
// À ne pas adopter comme architecture par défaut.
|
|
enum Source {
|
|
Http,
|
|
WebSocket,
|
|
Grpc,
|
|
}
|
|
```
|
|
|
|
Les rôles/capabilities importent davantage que le protocole nominal.
|
|
|
|
### 13.5 Pipeline de convergence à préparer
|
|
|
|
Le handoff `0.3.10` doit aboutir conceptuellement à :
|
|
|
|
```text
|
|
source(s) / discovery / direct stream / hydration
|
|
|
|
|
v
|
|
normalisation source-independent RawTransaction
|
|
|
|
|
+--> RawTransactionObservation par acquisition
|
|
|
|
|
v
|
|
ksp-store-lib
|
|
```
|
|
|
|
La déduplication ne doit pas effacer les observations de provenance légitimes.
|
|
|
|
### 13.6 Helius
|
|
|
|
L'audit doit :
|
|
|
|
```text
|
|
réauditer la documentation/pricing/capabilities Helius courants
|
|
examiner HTTP standard Mainnet + Devnet
|
|
examiner WS standard Mainnet + Devnet
|
|
examiner séparément les extensions enhanced/advanced telles que transactionSubscribe
|
|
ne jamais supposer qu'un endpoint Helius donne accès à toutes les capabilities
|
|
réutiliser KSP_SECRET_HELIUS_API_KEY via Config dans la future 0.3.10
|
|
ne créer aucun second secret
|
|
ne pas ajouter les URLs/endpoints Helius dans 0.3.9
|
|
```
|
|
|
|
Aucune URL historique kbot3 n'est transférée comme vérité KSP.
|
|
|
|
### 13.7 `mainnet` / `mainnet-beta`
|
|
|
|
Auditer avant toute décision d'implémentation :
|
|
|
|
```text
|
|
RawNetworkId / Store persisté
|
|
Config profiles/targets
|
|
Transport network descriptors
|
|
provider naming
|
|
Backfill scope fingerprints/checkpoints
|
|
CLI/external aliases
|
|
```
|
|
|
|
Objectif :
|
|
|
|
> un même cluster de production ne doit jamais devenir deux identités KSP indépendantes.
|
|
|
|
Ne pas renommer/migrer dans `0.3.9`. Le handoff `0.3.10` doit proposer une stratégie compatible ou conclure explicitement qu'aucun changement n'est nécessaire.
|
|
|
|
### 13.8 Réutilisation future par Backfill
|
|
|
|
La matrice n'est pas seulement « live worker ».
|
|
|
|
Elle doit indiquer pour chaque source :
|
|
|
|
```text
|
|
continuous ingest ?
|
|
gap repair / catch-up ?
|
|
historical backfill ?
|
|
```
|
|
|
|
Cette même matrice devient l'entrée de `0.3.12` pour étendre `ksp-job-backfill-lib` et `ksp-app-backfill-desk` sans refaire l'erreur d'une hypothèse mono-source.
|
|
|
|
---
|
|
|
|
## 14. Règles de versionnement, deltas, commits et tags
|
|
|
|
Conserver le workflow KSP :
|
|
|
|
```text
|
|
0.3.9-pre.1 / pre.2 / ... dans workspace.package.version pour changements code/build/runtime/config
|
|
fix code/test/build => version Cargo fix correspondante
|
|
fix strictement documentaire => pas de bump workspace.package.version
|
|
deltas/0.3.9/pre.NNN.md
|
|
deltas/0.3.9/pre.NNN-fix.MMM.md
|
|
deltas/0.3.9/rel.001.md
|
|
```
|
|
|
|
Le premier delta `pre.001` peut rester doc-only et conserver `workspace.package.version = 0.3.8` si aucun code/build/runtime/config n'est modifié, conformément aux règles de versioning KSP. Le premier changement Rust porte alors le bump technique de prerelease.
|
|
|
|
Archives d'échange minimales selon leur scope :
|
|
|
|
```text
|
|
ksp-doc-<delivery-id>.zip
|
|
ksp-general-<delivery-id>.zip
|
|
```
|
|
|
|
Ne jamais livrer une copie complète du dépôt comme « delta ».
|
|
|
|
Tags :
|
|
|
|
```text
|
|
seul le stable final v0.3.9 est taggé selon le workflow courant
|
|
```
|
|
|
|
---
|
|
|
|
## 15. Validation opérateur
|
|
|
|
### 15.1 Baseline / chaque tranche Rust
|
|
|
|
```bash
|
|
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
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
```
|
|
|
|
Puis tests ciblés :
|
|
|
|
```bash
|
|
cargo test -p ksp-worker-api
|
|
```
|
|
|
|
et, selon les changements :
|
|
|
|
```bash
|
|
cargo test -p ksp-job-api
|
|
cargo test -p ksp-core-lib
|
|
cargo tree -p ksp-worker-api --edges normal
|
|
cargo tree -p ksp-worker-api -e features
|
|
```
|
|
|
|
### 15.2 Gate final
|
|
|
|
Le gate technique final inclut au minimum :
|
|
|
|
```bash
|
|
cargo fmt --all -- --check
|
|
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
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
cargo test --workspace --all-targets --all-features
|
|
cargo tree -p ksp-worker-api --edges normal
|
|
cargo tree -p ksp-worker-api -e features
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
Le shell opérateur peut continuer après une commande rouge ; lire chaque résultat. Une commande ultérieure verte n'annule jamais un échec antérieur.
|
|
|
|
---
|
|
|
|
## 16. Tests attendus pour `ksp-worker-api`
|
|
|
|
Le plan `pre.001` doit au minimum prévoir des preuves sur :
|
|
|
|
```text
|
|
exact lifecycle transition matrix
|
|
invalid transition leaves state unchanged
|
|
stop/cancel idempotence
|
|
stop-vs-fault/terminal races
|
|
snapshot latest-value observable par listeners lents indépendants
|
|
sequence monotone / exhaustion explicite si sequence utilisée
|
|
late listener resync
|
|
Debug/redaction hostile values
|
|
identity exact bounds
|
|
Send/Sync
|
|
external consumer / external implementation
|
|
crate-root public surface
|
|
exact dependency firewall
|
|
exact module/export inventories
|
|
aucun Transport/Store/Config/Tauri/Job-specific type
|
|
```
|
|
|
|
Les tests ne doivent pas inventer un runtime concret si l'API est passive.
|
|
|
|
---
|
|
|
|
## 17. Critères de clôture `0.3.9`
|
|
|
|
La release n'est publiable que lorsque :
|
|
|
|
```text
|
|
ksp-worker-api est stable, documentée et générique
|
|
Worker/Job semantics restent distinctes
|
|
aucun type Solana/Transport/Store/provider n'a contaminé Worker API
|
|
public/dependency/security/race gates sont verts
|
|
README/USAGE version-neutral sont réconciliés
|
|
|
|
audit RawTransaction exhaustif terminé après freeze Worker API
|
|
matrice sources/méthodes couvre live/catch-up/gap-repair/history
|
|
multi-source alternatives/complements/redundancy/specialization documenté
|
|
gaps Transport/Config 0.3.10 explicités
|
|
Helius future use réauditée sans endpoint ajouté en 0.3.9
|
|
mainnet/mainnet-beta strategy auditée sans migration prématurée
|
|
applicability future Backfill 0.3.12 documentée
|
|
|
|
workspace final green
|
|
prompt 0.3.10 cohérent avec l'audit final
|
|
CHANGELOG/ROADMAP finalisés dans le couloir de publication
|
|
rel.001 mécanique uniquement
|
|
```
|
|
|
|
---
|
|
|
|
## 18. Release/session suivante envisagée — `0.3.10`
|
|
|
|
Objectif prévu :
|
|
|
|
```text
|
|
ksp-worker-raw-transaction-ingest-lib
|
|
```
|
|
|
|
Cette release doit **consommer l'audit produit par `0.3.9`**, pas repartir d'une hypothèse de protocole unique.
|
|
|
|
Elle pourra inclure :
|
|
|
|
```text
|
|
adaptations ksp-onchain-transport-lib réellement nécessaires
|
|
adaptations ksp-config-lib réellement nécessaires
|
|
profils Helius HTTP/WS nécessaires Mainnet/Devnet
|
|
réutilisation KSP_SECRET_HELIUS_API_KEY
|
|
multi-source / multi-provider
|
|
discovery + hydration lorsque nécessaire
|
|
direct full-transaction streaming lorsque disponible
|
|
gap repair / reconnect / recovery
|
|
normalisation canonique RawTransaction
|
|
RawTransactionObservation par acquisition
|
|
persistance atomique/idempotente via ksp-store-lib
|
|
supervision via ksp-worker-api
|
|
```
|
|
|
|
Elle ne doit pas :
|
|
|
|
```text
|
|
copier kbot3
|
|
hardcoder une source unique sans justification d'audit
|
|
confondre provider/tier avec capability générique
|
|
renommer mainnet-beta de manière destructive
|
|
ouvrir Decode/STRUCTURAL/DOMAIN
|
|
```
|
|
|
|
`0.3.11` sera la Desk de choix/supervision des sources ; `0.3.12` réutilisera la matrice pour étendre Backfill.
|
|
|
|
---
|
|
|
|
## 19. Instruction d'ouverture
|
|
|
|
Au début de la prochaine session :
|
|
|
|
1. vérifier la base stable exacte `v0.3.8` et `deltas/0.3.8/rel.001.md` ;
|
|
2. lire les règles et architectures obligatoires dans l'ordre du présent prompt ;
|
|
3. auditer `ksp-job-api` comme référence de propriétés génériques **sans supposer une dépendance Worker -> Job** ;
|
|
4. inventorier la surface exacte attendue de `ksp-worker-api`, les risques et les dépendances ;
|
|
5. produire `pre.001` avec brainstorming, sizing, plan/tests/gates et prévision souple recalibrée ;
|
|
6. **ne pas commencer `ksp-worker-raw-transaction-ingest-lib`, ne pas ajouter d'endpoint Helius et ne pas modifier Transport/Config pour l'ingestion avant fermeture du gate Worker API prévu** ;
|
|
7. réserver l'audit exhaustif RawTransaction à la fin de `0.3.9`, après freeze fonctionnel de Worker API, puis utiliser ce document comme handoff autoritaire vers `0.3.10`.
|
|
|
|
Ne pas répondre à une incertitude par une hypothèse : auditer la base, les sources primaires et les règles KSP, puis documenter la décision.
|