# 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 : ```text 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 : ```text 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 : ```text 0.3.11 ``` Première livraison attendue : ```text 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 : ```text 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` : ```text 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 : ```text 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 : ```text 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 : ```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 bloquants pour toute modification Rust : ```text 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 : ```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 ``` Une commande non exécutée n'est jamais déclarée PASS. ### 3.2 Architecture durable acquisition / Worker / Store Lire intégralement : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text (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 ```text 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 : ```text 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 : ```text 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 : ```text 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` : ```text 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` ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```text 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 : ```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 ``` 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 : ```bash 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 : ```bash 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 : ```text 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 : ```text 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.