From 36c683df9eb9171308b64584184d9e9b1d6e4ecd Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Tue, 8 Sep 2026 08:07:06 +0200 Subject: [PATCH] v0.3.10-pre.009 --- CHANGELOG.md | 16 +- Cargo.toml | 4 +- ROADMAP.md | 4 +- deltas/0.3.10/pre.009.md | 188 ++++++++ prompts/030-V0_3_11_START_PROMPT.md | 636 ++++++++++++++++++++++++++++ 5 files changed, 843 insertions(+), 5 deletions(-) create mode 100644 deltas/0.3.10/pre.009.md create mode 100644 prompts/030-V0_3_11_START_PROMPT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 84c323d..323f865 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,22 @@ - + # Changelog KSP +## 0.3.10 — Lower-layer RAW Transaction commune + qualification cross-source — 2026-09-08 + +`0.3.10` introduit `ksp-raw-transaction-lib` comme lower-layer source-neutral commune aux producteurs `RawTransaction`. La canonicalisation RAW v1 auparavant locale à `ksp-job-backfill-lib` est extraite sans modifier les golden bytes/hash existants ; le Backfill consomme désormais cette common crate sans créer de dépendance vers un Worker. La bibliothèque construit les modèles `RawTransaction`/`RawTransactionObservation` de `ksp-store-api`, conserve l'identité canonique `(network, signature)`, borne et redacted les entrées hostiles, et reste volontairement sans Transport, Config, runtime async, Job, Worker ou backend Store physique. + +La common matérialise également un wire Solana source-neutral Legacy/V0/V1 avec sérialisation Base64 et extraction de signature depuis le matériau transactionnel complet. La représentation V1 couvre header, compiled instructions, configuration V1 et signatures terminales ; les gardes structurelles rejettent les états non supportés plutôt que d'inventer une compatibilité. `ksp-onchain-transport-lib` ajoute `get_block_observed`, qui conserve l'identité sûre de la route réellement gagnante tout en réutilisant la validation `getBlock` existante. + +Les preuves cross-source ferment explicitement ce qui est qualifié et ce qui exige encore hydration. Un `blockSubscribe` standard `full/base64` peut produire le même RAW v1 qu'un `getBlock` HTTP sur le sous-ensemble déterministe prouvé. Helius `transactionSubscribe` reste un signal nécessitant hydration HTTP lorsque `blockTime`/version manquent. Yellowstone qualifie le wire Transaction V1 et la conservation du `block_time` dans Block, mais `Transaction` nécessite hydration pour le temps de bloc et le chemin Block complet reste conservateur tant que l'identité byte-for-byte entre meta protobuf et meta JSON HTTP n'est pas prouvée. Aucun RAW-direct Yellowstone complet ni feed EARLY n'est revendiqué sans preuve. + +Le gate technique final `pre.007` passe les audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features`, les suites ciblées common/Transport/Backfill et les graphes Cargo demandés ; les smokes live opt-in restent ignorés conformément à leur contrat. La réconciliation `pre.008` aligne ensuite la terminologie durable des couches Store sur `D1 RAW -> D2 STRUCTURAL -> D3 DECODED -> D4 DOMAIN`, réserve `N1–N4` aux niveaux architecturaux et complète `README.md`/`USAGE.md` de `ksp-raw-transaction-lib`. Son gate opérateur repasse format, audits, `cargo check --workspace` et Clippy strict sur `0.3.10-pre.8`. + +Le runtime concret a été volontairement retiré de `0.3.10` après recalibrage du sizing. La trajectoire devient `0.3.11` fondation runtime/persistence déterministe, `0.3.12` Yellowstone + hydration/continuité, `0.3.13` WS standard/Helius/HTTP live + convergence multi-source, `0.3.14` gap repair/hardening/smokes, `0.3.15` Desk d'ingestion et `0.3.16` extension Backfill multi-source. Le Job historique paramétré et le Worker continu restent des producteurs indépendants du même Store. + +`prompts/030-V0_3_11_START_PROMPT.md` ouvre `0.3.11` uniquement depuis le tag stable `v0.3.10`. Son `pre.001` doit auditer la base réelle, le graphe de dépendances, le runtime/supervision, les bornes de channels, la persistence/déduplication déterministe, les snapshots et le dimensionnement avant toute implémentation lourde ; aucune source live complexe n'est requise pour fermer cette release. + ## 0.3.9 — Worker API générique + audit exhaustif d'acquisition RawTransaction — 2026-09-05 `0.3.9` introduit `ksp-worker-api` comme façade générique, courte et runtime-neutral pour services continus. La surface stable reste Core-only et expose `WorkerId`, `WorkerKindCode`, `WorkerState`, `WorkerHealth`, `WorkerActivity`, `WorkerLifecycle`, `WorkerStopToken`, `WorkerSnapshotSequence`, `WorkerSnapshot`, `WorkerSnapshotFuture` et `WorkerSnapshotSource`. Les identités sont bornées et redacted, le lifecycle possède des transitions explicites avec terminaux immuables, le stop token est partagé/idempotent, la séquence ne wrappe pas et le snapshot source latest-value reste object-safe, `Send + Sync` et implémentable depuis l'extérieur. L'API ne possède aucun runtime `start/stop` universel, aucune sémantique Job/checkpoint, aucun domaine Solana et aucune dépendance Transport/Store/Config/Tauri. diff --git a/Cargo.toml b/Cargo.toml index 2da849f..8f05412 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 503 +# version: 504 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api"] [workspace.package] -version = "0.3.10-pre.8" +version = "0.3.10-pre.9" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 32adcb0..5a154a0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -102,7 +102,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN - [X] `0.3.7` — `ksp-app-backfill-desk` livrée comme Desk Tauri KSP spécialisée : composition Config Mainnet/Devnet/Testnet, quatre scopes HTTP, validation/start single-run, monitoring latest-value `ksp-backfill-status`, Cancel ciblé/idempotent, Resume in-session par checkpoint Rust-only réémis pour un nouveau JobId, autocomplete libre depuis `ksp-core-lib`, hardening IPC/dependency boundaries et build Linux `.deb`/`.rpm`/`.AppImage`. Aucun SQL/backend/provider physique ni checkpoint durable n’est exposé. - [X] `0.3.8` — `ksp-app-store-desk` V1 RAW livrée sur le gabarit KSP courant comme application Tauri read-only backend-neutral. La Desk compose Config + Logging + `ksp-store-lib`, expose health/runtime sûrs, DataTables `serverSide` pour `RawTransaction`, `RawAccountState` et leurs observations, détails bornés, provenance sûre et états de rétention/tombstone, sans SQL/backend physique/Transport dans l'application. La nouvelle inspection random-access `offset + limit + counts exacts` reste distincte de la pagination machine cursor/keyset conservée pour workers/backfills/replays. Le gate final et les builds Linux `.deb`/`.rpm` sont verts. - [X] `0.3.9` — `ksp-worker-api` stable comme API générique et volontairement courte pour services continus : identité/kind bornés, lifecycle explicite, health/activity sûrs, stop token partagé, séquence/snapshot latest-value et `WorkerSnapshotSource` object-safe, avec dépendance Core-only et sans runtime/start-stop universel, Solana, Transport, Store, Config ou Tauri. Après freeze Worker API, l'audit `RawTransaction` a été consolidé dans une synthèse Store-centrique exhaustive séparant possibilités/support/preuve et classant HTTP, WS standard/provider, Yellowstone gRPC, blocs/slots, discovery + hydration, replay de continuité, archives et sources EARLY. Le Job Backfill historique paramétré et le Worker Ingest live start/stop sont deux producteurs indépendants du même Store ; `mainnet` est désormais l'identité KSP canonique et `mainnet-beta` un alias legacy/externe. Le handoff retient `ksp-raw-transaction-lib` comme lower-layer commune de canonicalisation RAW v1 pour `0.3.10`, sans edge Job ↔ Worker. -- [ ] `0.3.10` — Fermer la **lower-layer RAW Transaction commune** et ses preuves cross-source avant ouverture du Worker concret : `ksp-raw-transaction-lib`, migration Backfill sans changement des golden bytes/hash, `get_block_observed`, matériau/wire Legacy/V0/V1 source-neutral et canaris HTTP/WS/Helius/Yellowstone. La release ne construit plus le runtime Worker ; ce redécoupage intervient après `pre.006` afin de respecter le budget de 15–20 minutes par prerelease et la règle d'une release concrète clôturable dans une seule session. +- [X] `0.3.10` — Lower-layer RAW Transaction commune stabilisée : `ksp-raw-transaction-lib` possède la canonicalisation RAW v1 source-neutral partagée, le Backfill est migré sans changement des golden bytes/hash, Transport expose `get_block_observed`, le wire Solana Legacy/V0/V1 est matérialisé et les canaris HTTP/WS standard/Helius/Yellowstone qualifient précisément les voies directes ou nécessitant hydration. La release se ferme sans runtime Worker concret ; celui-ci commence en `0.3.11` selon le redécoupage `0.3.11`–`0.3.14`. - [ ] `0.3.11` — Introduire la **fondation runtime** de `ksp-worker-raw-transaction-ingest-lib` sans source live complexe : crate/dependency firewall, settings source-neutral, handle/start-stop, lifecycle, snapshots, supervisor, bounded channels et pipeline de persistence/déduplication déterministe. Aucun protocole live n'est encore requis pour fermer cette release. - [ ] `0.3.12` — Ajouter au Worker la voie **Yellowstone + hydration HTTP** : transactions/blocks/status, projection vers la common RAW, provenance sûre, `from_slot`, replay info, frontier de run et continuité propre au run, avec fixtures déterministes et smokes accessibles sans prétendre à un RAW-direct lorsque les métadonnées restent incomplètes. - [ ] `0.3.13` — Ajouter les voies **WS standard / Helius / HTTP live** et leur convergence multi-source : `logsSubscribe + getTransaction`, `blockSubscribe`, `transactionSubscribe + hydration`, polling blocs HTTP, observations multiples, content conflict explicite, coalescence et backpressure sans second actor Transport. diff --git a/deltas/0.3.10/pre.009.md b/deltas/0.3.10/pre.009.md new file mode 100644 index 0000000..fa7fae4 --- /dev/null +++ b/deltas/0.3.10/pre.009.md @@ -0,0 +1,188 @@ + + + +# Delta `0.3.10-pre.009` — préparation de publication + +## 1. Base requise + +```text +0.3.10-pre.008 appliquée +0.3.10-pre.008-fix.001 appliqué +workspace.package.version = 0.3.10-pre.8 +``` + +Le gate opérateur de `pre.008` est vert sur format, audits Rust/Markdown, `cargo check --workspace` et Clippy workspace/all-targets/all-features avec `-D warnings`. Le correctif documentaire `pre.008-fix.001` est ensuite validé par les audits Rust/Markdown, tous deux verts. + +## 2. Objet + +Préparer exclusivement la publication stable de `0.3.10` après fermeture technique `pre.007` et réconciliation documentaire `pre.008` + `pre.008-fix.001`. + +Conformément à `PROMPT_STRUCTURE.md` et `VER-LIFECYCLE-003`, cette tranche ne modifie fonctionnellement que : + +```text +prompt de démarrage 0.3.11 +CHANGELOG.md +ROADMAP.md +``` + +avec les fichiers mécaniques obligatoires : + +```text +Cargo.toml +deltas/0.3.10/pre.009.md +``` + +## 3. Version + +```text +workspace.package.version = 0.3.10-pre.9 +delivery = 0.3.10-pre.009 +commit attendu = v0.3.10-pre.009 +aucun tag prerelease +``` + +Le header du `Cargo.toml` racine passe de `503` à `504`. + +## 4. CHANGELOG + +`CHANGELOG.md` reçoit la synthèse stable de `0.3.10` : + +```text +ksp-raw-transaction-lib comme common D1 RAW source-neutral +migration Backfill sans changement des golden bytes/hash +wire Solana Legacy/V0/V1 +get_block_observed +qualification HTTP / WS standard / Helius / Yellowstone +non-claims explicites lorsqu'une hydration reste nécessaire +gate technique final pre.007 +nomenclature D1 RAW -> D2 STRUCTURAL -> D3 DECODED -> D4 DOMAIN +redécoupage Worker 0.3.11 -> 0.3.14 +handoff 0.3.11 +``` + +Aucune nouvelle preuve live n'est inventée par la synthèse. + +## 5. ROADMAP + +`ROADMAP.md` marque `0.3.10` comme réalisé et remplace son texte prospectif par le résultat effectivement livré. Les releases `0.3.11` à `0.3.16` restent prévues et conservent leurs frontières déjà réconciliées. + +Aucune autre réconciliation documentaire n'appartient à cette tranche. + +## 6. Prompt `0.3.11` + +Ajout : + +```text +prompts/030-V0_3_11_START_PROMPT.md +``` + +Le prompt ouvre `0.3.11` uniquement depuis `v0.3.10` et impose un `pre.001` audit/brainstorming/sizing avant codage lourd. + +Mission initiale à réauditer : + +```text +ksp-worker-raw-transaction-ingest-lib +crate/dependency firewall +settings source-neutral +handle/start-stop/lifecycle +supervisor privé +channels bornés +pipeline déterministe common RAW -> Store +persistence/deduplication/content conflict +snapshots latest-value sûrs +hardening runtime de fondation +``` + +Aucune voie Yellowstone/WS/Helius/HTTP live complexe n'est requise pour fermer `0.3.11`. Le prompt impose de rescinder la release avant implémentation si son sizing réel ne tient pas dans une session. + +## 7. Fichiers modifiés + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +``` + +## 8. Fichiers ajoutés + +```text +prompts/030-V0_3_11_START_PROMPT.md +deltas/0.3.10/pre.009.md +``` + +## 9. Fichiers supprimés + +```text +aucun +``` + +## 10. Hors périmètre + +Aucun fichier suivant ne doit être corrigé dans `pre.009` : + +```text +README / USAGE +architecture +plans / validations +code Rust / TypeScript +tests +Config / schemas +migrations +manifest de crate +dépendances/features +runtime/backend +smokes live +``` + +Toute anomalie appartenant à un couloir antérieur renvoie vers une tranche dédiée avant publication. + +## 11. Validations exécutées à l'assemblage + +Résultats réellement obtenus avant empaquetage : + +```text +General Rust rule audit: clean +Rust export completeness audit: 0 candidate(s) +KSP workspace Rust rule audit: clean +Markdown table audit: clean (340 table(s), 771 file(s)) +contrôle du scope: exactement cinq fichiers ajoutés/modifiés +unzip -t: PASS +reconstruction overlay: 1713 fichiers, 0 différence byte +``` + +Cargo/rustc/rustfmt ne sont pas disponibles dans l'environnement d'assemblage ; aucun gate Rust local n'est déclaré PASS. + +## 12. Validation opérateur attendue + +```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 +``` + +Comme la tranche ne change aucun code ni dépendance, ce gate de publication reste volontairement minimal. Un échec ouvre `pre.009-fix.NNN` seulement s'il relève du CHANGELOG, ROADMAP, prompt ou de la mécanique de publication ; une anomalie de code/documentation durable antérieure retourne dans son couloir propre. + +## 13. Décisions prises + +```text +0.3.10 est fermé fonctionnellement autour de la common RAW et de ses preuves cross-source +le Worker concret commence en 0.3.11 +0.3.11 n'exige aucune source live complexe pour sa clôture +pre.001 de 0.3.11 doit re-sizer la release avant codage lourd +D1/D2/D3/D4 et STRUCTURAL restent la terminologie durable des couches Store +``` + +## 14. Questions ouvertes + +Aucune question de `0.3.10` ne doit être résolue dans `pre.009`. Les choix exacts de runtime/settings/supervisor/harness du Worker sont transférés au gate `0.3.11-pre.001`. + +## 15. Suite + +Si le gate opérateur de cette tranche est vert : + +```text +0.3.10-rel.001 +``` + +doit rester une publication stable mécanique : version Cargo finale `0.3.10`, delta `rel.001`, commit de release puis tag stable `v0.3.10`, sans rattrapage fonctionnel ou documentaire. diff --git a/prompts/030-V0_3_11_START_PROMPT.md b/prompts/030-V0_3_11_START_PROMPT.md new file mode 100644 index 0000000..bea7c3d --- /dev/null +++ b/prompts/030-V0_3_11_START_PROMPT.md @@ -0,0 +1,636 @@ + + + +# 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.