khadhroony-solana-project/prompts/030-V0_3_11_START_PROMPT.md

Prompt de démarrage 0.3.11 — fondation runtime du Worker RawTransaction ingest

1. Identité de la release et base exacte requise

Ouvrir uniquement 0.3.11 depuis la release stable/taggée :

v0.3.10

La base de travail fournie par l'opérateur est autoritaire sur les souvenirs de session, snippets, anciennes archives et deltas intermédiaires. Avant toute modification, vérifier au minimum :

workspace.package.version = 0.3.10
deltas/0.3.10/rel.001.md présent
crates/ksp-raw-transaction-lib présent et documenté
crates/ksp-worker-api présent et stable
crates/ksp-job-backfill-lib migré vers ksp-raw-transaction-lib
ksp-worker-raw-transaction-ingest-lib absent sauf divergence explicitement auditée

Release ouverte :

0.3.11

Première livraison attendue :

0.3.11-pre.001

pre.001 est obligatoirement un gate de lecture + audit + brainstorming + sizing + planification. Il ne commence pas l'implémentation lourde du Worker. Si le périmètre ci-dessous ne paraît pas clôturable dans une seule session ou si une tranche dépasse environ 15–20 minutes de travail effectif, la release doit être rescindée avant le développement lourd.

2. Mission et résultat attendu

2.1 Mission de 0.3.11

Introduire :

crates/ksp-worker-raw-transaction-ingest-lib

comme premier Worker concret KSP de la chaîne d'acquisition RawTransaction, mais limiter cette release à sa fondation runtime source-neutral et déterministe.

Résultat cible à réauditer pendant pre.001 :

crate + dependency firewall
settings techniques source-neutral
identité Worker concrète
handle start/stop
lifecycle et terminaison
supervisor privé
channels bornés
pipeline central d'admission
canonicalisation via ksp-raw-transaction-lib
persistence via ksp-store-lib
déduplication/idempotence déterministe
snapshots latest-value sûrs
projection vers ksp-worker-api
hardening shutdown/fault/backpressure de fondation

Aucune source live complexe n'est un critère de sortie de 0.3.11. Les voies Yellowstone, WS standard, Helius et HTTP live sont réparties sur 0.3.12–0.3.14.

2.2 Sémantique Worker à préserver

Le Worker est un service continu :

start
  -> initialise son run live
  -> démarre les tâches privées nécessaires
  -> admet et persiste les acquisitions reçues par ses sources techniques
  -> publie des snapshots latest-value indépendants des lecteurs
stop
  -> arrête les nouvelles admissions
  -> demande l'arrêt coopératif des tâches
  -> draine seulement le travail déjà admis dans une borne explicite
  -> publie un terminal sûr

Le Worker ne reçoit aucune requête métier historique :

pas de signature cible
pas de program_id/adresse métier
pas de before/after
pas de plage historique caller-owned
pas de historical limit
pas de BackfillRequest
pas de BackfillCheckpoint
pas de JobId

ksp-job-backfill-lib et le Worker sont deux producteurs indépendants du même Store. Ils ne s'appellent pas, ne s'attendent pas, ne se supervisent pas et ne partagent aucune orchestration fonctionnelle.

3. Sources de vérité internes obligatoires — ordre de lecture

3.1 Gouvernance générale

Lire intégralement, dans cet ordre :

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 bloquants pour toute modification Rust :

Rust 2024
unsafe interdit
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 reexportés jusqu'à la crate root
accès partagés via crate::Item, y compris intra-crate
item strictement module-local => private
unit tests sous unit_tests/
integration tests sous tests/

Après toute modification Rust :

cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets

Pour tout Markdown touché :

python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas

Une commande non exécutée n'est jamais déclarée PASS.

3.2 Architecture durable acquisition / Worker / Store

Lire intégralement :

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/008-DATA_MATERIALIZATION_AND_STORE.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md

Vocabulaire durable des couches Store :

D1 RAW
D2 STRUCTURAL
D3 DECODED
D4 DOMAIN

N1–N4 restent les niveaux architecturaux de composants. CORE n'est plus le nom de la couche D2 ; ne pas renommer pour autant ksp-core-lib ni les vrais usages du domaine Core.

3.3 Handoff autoritaire de 0.3.10

Lire :

docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
crates/ksp-raw-transaction-lib/Cargo.toml
crates/ksp-raw-transaction-lib/README.md
crates/ksp-raw-transaction-lib/USAGE.md
crates/ksp-raw-transaction-lib/src/
crates/ksp-raw-transaction-lib/tests/
crates/ksp-raw-transaction-lib/unit_tests/

Les sections 8, 9, 10, 12, 14, 15, 16 et 17 du plan 031 sont le handoff principal pour 0.3.11. Elles sont des entrées à réauditer sur la base stable réelle, pas une autorisation à tout implémenter d'un bloc.

3.4 Worker API générique

Lire :

crates/ksp-worker-api/Cargo.toml
crates/ksp-worker-api/README.md
crates/ksp-worker-api/USAGE.md
crates/ksp-worker-api/src/
crates/ksp-worker-api/tests/

docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md

Surface générique à préserver :

WorkerId
WorkerKindCode
WorkerState
WorkerHealth
WorkerActivity
WorkerLifecycle
WorkerStopToken
WorkerSnapshotSequence
WorkerSnapshot
WorkerSnapshotFuture
WorkerSnapshotSource

ksp-worker-api dépend uniquement de ksp-core-lib, reste runtime-neutral et ne fournit pas de start()/stop() universel. Le premier Worker concret ne doit pas élargir cette API pour des besoins Solana-specific sauf défaut réellement transversal démontré par l'audit.

3.5 Store et Backfill comme frontières de comportement

Lire au minimum :

crates/ksp-store-api/Cargo.toml
crates/ksp-store-api/src/
crates/ksp-store-api/tests/
crates/ksp-store-lib/README.md
crates/ksp-store-lib/USAGE.md
crates/ksp-store-lib/src/

crates/ksp-job-backfill-lib/Cargo.toml
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/

Le Backfill est une référence fonctionnelle utile pour :

canonicalisation common déjà consommée
persistance atomique/idempotente
content conflict
cancellation
latest-value
bornes de concurrence
redaction

Il n'est pas un parent architectural du Worker et sa sémantique de scope/checkpoint/campagne ne doit pas être copiée.

4. Sources externes et fraîcheur à réauditer

0.3.11 n'ajoute pas de source live complexe par défaut. Il n'est donc pas nécessaire d'ouvrir une nouvelle matrice provider pour coder immédiatement.

En revanche, pre.001 doit vérifier les versions stables réellement courantes de toute dépendance externe que la fondation Worker pourrait ajouter ou activer, notamment si l'audit conclut qu'un runtime Tokio/Futures direct est nécessaire. Utiliser les sources primaires du projet/crate et vérifier les features minimales réellement requises.

Ne pas conserver une version historique simplement parce qu'elle apparaît dans un ancien prompt. Ne pas ajouter de SDK provider.

Les surfaces provider/protocole ne sont réauditées dans 0.3.11 que si une décision de fondation dépend réellement d'elles ; les audits live détaillés appartiennent principalement à 0.3.12–0.3.14.

5. État validé à préserver

5.1 Common RAW

ksp-raw-transaction-lib reste la lower-layer D1 commune :

source-neutral
sans runtime async
sans Transport
sans Config
sans Job/Worker
sans backend Store physique

Le Worker l'utilise ; il ne duplique pas la canonicalisation RAW v1.

5.2 Persistence

Le Worker persiste via :

ksp-store-lib

et non via un backend physique. ksp-store-api reste la couche de contrats/modèles ; les consumers runtime ordinaires ne contournent pas la façade Store pour écrire directement dans PostgreSQL.

Identité de convergence :

(network, signature)

Une entité existante n'autorise pas la suppression d'une observation provenant d'une autre source. Un contenu canonique divergent pour la même identité reste un conflit explicite ; aucun provider gagnant n'est choisi implicitement.

5.3 Réseau

mainnet = identité KSP canonique
mainnet-beta = alias legacy/externe uniquement

Le Worker reçoit un réseau déjà résolu/cohérent ; il ne lit pas l'environnement directement.

5.4 Config et secrets

Frontière obligatoire :

ksp-worker-raw-transaction-ingest-lib -X-> ksp-config-lib

Le Worker reçoit des settings techniques source-neutral et des ressources déjà préparées. Aucun .env, std::env, URL secrète, token, API key ou header sensible n'est lu directement par la crate Worker.

6. Décisions acquises et questions réellement ouvertes

6.1 Décisions acquises

Conserver :

caller fournit un runtime Tokio actif si Tokio est retenu
le Worker ne crée pas son propre runtime
JoinHandle privés
request_stop idempotent
lecteurs de snapshot sans influence sur le lifecycle
queues/channels bornés uniquement
aucun drop silencieux en saturation
start sans paramètre historique métier
snapshot sans transaction/signature/URL/secret/payload distant
Job et Worker indépendants
pas de source live complexe requise pour fermer 0.3.11

6.2 Questions à fermer en pre.001

Auditer avant codage :

surface publique exacte minimale de RawTransactionIngestSettings
shape exacte de RawTransactionSourceId / SourceSettings / capability / role en fondation
quels types sont publics et lesquels restent privés jusqu'aux vraies sources 0.3.12+
forme exacte du start et du handle
forme exacte d'attente terminale sans fuite nominale Tokio inutile
modèle privé de supervisor et tâches
seam déterministe permettant de tester le pipeline sans source live complexe
choix exact channel(s), capacité(s), deadlines et drain bounds
ownership des timestamps/frontiers de fondation
projection exacte WorkerSnapshot commun <-> snapshot concret
comportement de fault sur Store error / conflict / source harness failure
besoin réel d'une dépendance tokio/futures directe et features minimales

Ne pas figer prématurément des champs Yellowstone/WS/Helius dans les types publics de 0.3.11.

7. Objectifs/livrables et hors périmètre

7.1 Livrables attendus de la release

Sous réserve du sizing pre.001 :

crates/ksp-worker-raw-transaction-ingest-lib/
README.md
USAGE.md
surface crate-root minimale
settings/identity/lifecycle/handle/snapshot concrets
runtime privé borné
pipeline déterministe admission -> common RAW -> Store
fixtures/harness déterministes sans réseau obligatoire
unit/integration/public/release/security tests
plan 0.3.11
validation 0.3.11

Le USAGE.md reste version-neutral.

7.2 Hors périmètre de 0.3.11

Yellowstone live complet
from_slot/replay réel et continuité Yellowstone
WS standard live
Helius transactionSubscribe live
HTTP live block polling
multi-provider live convergence complète
gap repair multi-source complet
feed EARLY/shred/deshred
Desk Tauri d'ingestion
Backfill multi-source
D2 STRUCTURAL
nouvelle migration Store sauf nécessité démontrée et explicitement rescindée
nouveau document Config métier Worker imposant un edge Config -> Worker concret

Si une de ces responsabilités devient indispensable à la fondation, le sizing doit expliquer pourquoi et redécouper la trajectoire avant de coder.

8. Contraintes sécurité/API/architecture spécifiques

Le Worker concret doit respecter au minimum :

Debug/Display sûrs et bornés
aucune signature brute dans logs/snapshots publics
aucun payload transaction/meta/log
aucune URL/token/header/credential
aucun remote error text arbitraire
ErrorCode statiques et domain-scoped
source ids/codes bornés et safe
counter arithmetic non-wrapping ou explicitement saturante/checked selon le contrat
channels bornés
shutdown coopératif et borné
aucune tâche orpheline après terminal
aucune queue d'événements pour remplacer latest-value
aucun cache en mémoire utilisé comme vérité de correction à la place du Store

Pour le conflit de contenu :

stopper les nouvelles admissions
ne pas réécrire l'entité existante
ne pas choisir une source gagnante
publier un terminal/fault sûr
ne jamais exposer payload/signature/hash divergents dans les diagnostics publics

Le tracing passe par ksp-logging-lib si la crate Worker en dépend ; aucun bypass direct vers une autre façade de logging n'est introduit.

9. Première mission pre.001 — audit/sizing obligatoire

pre.001 doit produire avant toute implémentation lourde :

1. vérification exacte de la base v0.3.10 et des deltas/rel ;
2. lecture complète des sources internes listées ci-dessus ;
3. inventaire de la surface actuelle de ksp-worker-api, ksp-raw-transaction-lib, ksp-store-lib et des patterns Backfill réutilisables conceptuellement ;
4. audit du graphe Cargo cible et des dépendances externes éventuellement nécessaires ;
5. brainstorming des modèles publics/privés, du supervisor, de la cancellation, du drain, des channels, de l'admission/persistence et des snapshots ;
6. définition d'un harness déterministe sans réseau qui prouve le runtime de fondation ;
7. menace/sécurité : payloads, secrets, erreurs distantes, tâches orphelines, deadlocks, saturation, cancellation races, Store conflicts ;
8. sizing réel de chaque tranche sous le budget 15–20 minutes ;
9. décision explicite : 0.3.11 reste clôturable dans une session ou doit être rescindée avant codage ;
10. création/révision du plan et de la validation de release.

Documents attendus pour le gate :

docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md
docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md

Le delta pre.001 doit consigner les questions fermées, questions reportées, dépendances réellement nécessaires, validations futures et forecast recalibré.

Critère de sortie : la première tranche fonctionnelle suivante doit pouvoir être décrite précisément sans avoir à improviser son architecture pendant le codage.

10. Prévision souple initiale des prereleases

Cette prévision est un point de départ à recalibrer par pre.001, pas un engagement de numérotation.

pre.001 — audit / brainstorming / sizing

Lecture, inventaire réel, dépendances, public/private surface, runtime model, threat model, harness déterministe, plan/validation et décision de maintien ou rescission de la release.

pre.002 — crate + dependency firewall + settings foundation

Créer le squelette minimal, les IDs/codes/settings source-neutral réellement nécessaires et verrouiller les edges de dépendances. Ne pas ouvrir de source réseau complexe.

pre.003 — lifecycle / handle / start-stop privé

Matérialiser l'ownership runtime, supervisor privé, stop idempotent et terminal borné avec harness déterministe minimal.

pre.004 — channels bornés + admission pipeline

Introduire le chemin source déterministe -> admission bornée -> canonicalisation common, sans protocole provider concret.

pre.005 — persistence/déduplication Store

Fermer le chemin common RAW -> ksp-store-lib, outcomes new/idempotent/conflict et comportement de fault déterministe.

pre.006 — snapshots / source supervision foundation

Fermer latest-value concret, projection Worker API, compteurs sûrs et health/activity de fondation sans prétendre aux états de continuité live non encore prouvés.

pre.007 — hardening technique de fondation

Races stop/fault, saturation, drain, store failure, slow/no listeners, tâches terminales et inventaires externes. Scinder si cette tranche dépasse le budget.

pre.008 — gate technique final

Workspace complet, Clippy strict, suites ciblées, graphes Cargo et duplicate tree. Aucun nouveau scope fonctionnel.

pre.009 — réconciliation documentaire

README/USAGE, plan, validation, architecture/références réellement concernées. Aucun CHANGELOG/ROADMAP/prompt suivant.

pre.010 — préparation de publication

Prompt 0.3.12, CHANGELOG, ROADMAP et fichiers mécaniques uniquement.

rel.001

Publication stable mécanique sans rattrapage.

Si pre.001 conclut que cette trajectoire n'est pas clôturable dans une seule session, rescinder 0.3.11 avant pre.002 au lieu de laisser une prerelease grossir.

11. Versionnement, deltas, commits et tags

Règles obligatoires :

livraison prerelease : 0.3.11-pre.NNN
Cargo               : 0.3.11-pre.N
fix code/runtime     : 0.3.11-pre.N.fix.M
fix doc-only         : ne bump pas Cargo
delta                : deltas/0.3.11/pre.NNN.md ou pre.NNN-fix.NNN.md
commit               : v0.3.11-pre.NNN[-fix.NNN]
tag prerelease       : aucun
tag stable final     : v0.3.11 seulement après rel.001 validée

Toute nouvelle prerelease non-fix synchronise workspace.package.version, même documentaire. Tout fichier modifié incrémente son header de version selon les règles du dépôt.

Les archives d'échange restent des deltas minimaux ; ne jamais livrer une copie complète du repository lorsqu'un delta suffit.

12. Procédure d'application et validation opérateur

Après application d'un delta technique :

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

Puis exécuter les tests ciblés de la tranche et conserver les logs opérateur réels. Ne jamais transformer une commande non lancée en PASS.

Si un gate révèle une erreur, créer un fix appartenant strictement à la responsabilité de la tranche fautive ; ne pas absorber un défaut runtime dans la réconciliation documentaire ou la publication prep.

13. Validations Rust / runtime / graphes pertinentes

À partir de la matérialisation de la crate Worker, le gate cible inclut progressivement :

cargo test -p ksp-worker-raw-transaction-ingest-lib
cargo test -p ksp-raw-transaction-lib
cargo test -p ksp-store-lib
cargo test -p ksp-worker-api

cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal
cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
cargo tree --duplicates

À la fermeture technique :

cargo test --workspace --all-targets --all-features

Aucun smoke provider live n'est obligatoire pour fermer 0.3.11 tant qu'aucune source live complexe n'est dans son scope. Les futures releases ajoutent leurs propres smokes uniquement lorsque leur runtime source est effectivement matérialisé.

14. Critères de clôture de 0.3.11

La release peut se fermer lorsque, sur la base réellement obtenue :

crate Worker concrète présente et documentée
dependency firewall prouvé
start/stop/lifecycle/terminal bornés
aucune tâche privée orpheline après terminal
settings source-neutral bornés
pipeline déterministe sans queue unbounded
canonicalisation exclusivement via ksp-raw-transaction-lib
persistence exclusivement via ksp-store-lib
new/idempotent/conflict prouvés sans payload leak
snapshots concrete + Worker API latest-value prouvés
slow/no listeners sans influence sur lifecycle
hardening cancellation/saturation/store failure/fault vert
gates workspace/clippy/tests/trees verts
README/USAGE/plan/validation réconciliés
prompt 0.3.12 produit dans la dernière prerelease
aucune source live complexe revendiquée comme support de 0.3.11 sans preuve

15. Release suivante envisagée

0.3.12 doit reprendre uniquement après publication stable de 0.3.11 et réauditer la mission :

Yellowstone transaction/block/status
projection productive vers common RAW
hydration HTTP lorsque le matériau est incomplet
source health
from_slot / replay info
run frontier
continuité propre au run
fixtures déterministes + smokes accessibles

Le prompt 0.3.12 sera produit à la fermeture de 0.3.11 depuis la base réellement stabilisée. Il ne doit pas être figé à l'avance au-delà du handoff déjà documenté.

16. Instruction d'ouverture

Au début de la prochaine session :

1. vérifier que la base correspond exactement au tag stable v0.3.10 ;
2. lire les règles, l'architecture, le plan/validation 0.3.10 et les quatre crates de référence avant toute modification ;
3. réauditer le graphe de dépendances et les versions externes éventuellement nécessaires ;
4. produire pre.001 avec brainstorming, sizing, plan 032 et validation 028 ;
5. ne pas créer le runtime Worker lourd ni une source live avant fermeture de ce gate ;
6. rescinder 0.3.11 immédiatement si son périmètre réel n'est pas clôturable dans une seule session.