v0.3.10-pre.004

2026-09-06 17:15:51 +02:00
parent 8309d829cc
commit e19a202565
20 changed files with 949 additions and 56 deletions
--- a/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
+++ b/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->

 # Acquisition et alimentation `RawTransaction`

@@ -539,13 +539,13 @@ KSP possède déjà :
 get_signatures_for_address
 get_transaction / get_transaction_observed
 get_blocks / get_blocks_with_limit
-get_block
+get_block / get_block_observed
 get_slot
 get_first_available_block
 minimum_ledger_slot
 ```

-Gap principal : `getBlock` n'a pas encore d'équivalent `get_block_observed`. Pour un pool multi-endpoint, la provenance provider/endpoint exacte doit être conservée avant de persister une observation.
+`get_block_observed` conserve désormais la provenance sûre provider/endpoint du winner réel d’un pool HTTP, symétriquement à `get_transaction_observed`. La projection d’une transaction full issue d’un bloc vers le matériau RAW commun reste volontairement hors de Transport : l’adapter productif appartient au producer (Worker/Job) afin de ne créer aucun edge `Transport -> ksp-raw-transaction-lib`.

 ### 12.2 Transport WebSocket

@@ -615,7 +615,7 @@ Les prix/tiers d'audit ne doivent pas devenir une politique runtime.

 La canonicalisation RAW v1 actuellement prouvée dans `ksp-job-backfill-lib::conversion` ne doit ni y rester enfermée ni être copiée dans le Worker.

-Le handoff retient une petite crate source-neutral commune, à matérialiser pendant `0.3.10` :
+Le handoff retient la crate source-neutral commune désormais matérialisée :

 ```text
 ksp-raw-transaction-lib
@@ -650,13 +650,16 @@ backend Store physique
 Graphe conceptuel :

 ```text
-ksp-job-backfill-lib --------------------> ksp-raw-transaction-lib ----> Store façade
-ksp-worker-raw-transaction-ingest-lib ---> ksp-raw-transaction-lib ----> Store façade
+ksp-job-backfill-lib --------------------> ksp-raw-transaction-lib ----> ksp-store-api
+ksp-worker-raw-transaction-ingest-lib ---> ksp-raw-transaction-lib ----> ksp-store-api

+ksp-job-backfill-lib --------------------> ksp-store-lib
+ksp-worker-raw-transaction-ingest-lib ---> ksp-store-lib
 ksp-job-backfill-lib --------------------> ksp-onchain-transport-lib
 ksp-worker-raw-transaction-ingest-lib ---> ksp-onchain-transport-lib

 aucun edge Job <-> Worker
+aucun edge Transport <-> ksp-raw-transaction-lib
 ```

 La migration doit préserver exactement les golden bytes/hash RAW v1 déjà prouvés. Aucun RAW v2 n'est justifié.
@@ -709,7 +712,7 @@ sources EARLY via adapter extensible

 | ID     | Adaptation                                                                        | Motif                                                |
 |--------|-----------------------------------------------------------------------------------|------------------------------------------------------|
-| `TR-B` | `get_block_observed` symétrique de `get_transaction_observed`                     | provenance exacte en pool HTTP                       |
+| `TR-B` | fermé : `get_block_observed` symétrique de `get_transaction_observed`             | provenance exacte en pool HTTP                       |
 | `TR-C` | projection source-neutral des transactions full WS/Yellowstone                    | éviter plusieurs canonicalizers filaires             |
 | `TR-D` | métadonnées sûres d'acquisition live au moment de la conversion                   | observation uniforme                                 |
 | `TR-E` | conserver/exploiter `from_slot`, replay info et snapshots de continuité existants | ne pas créer un second moteur Yellowstone            |
--- a/docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
+++ b/docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
@@ -1,5 +1,5 @@
 <!-- file: docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->

 # Plan v0.3.10 — RAW Transaction commune + Worker d’ingestion multi-source

@@ -1050,9 +1050,15 @@ La canonicalisation privée du Backfill est supprimée au profit de `ksp-raw-tra

 Les invariants historiques restent gelés : `ksp.solana.raw_transaction` v1, golden `112` octets, SHA-256 `220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3`, origin `Backfill`, provider/endpoint/commitment/capture-session, observation key de campagne et sémantique `Missing`. Les erreurs common sont remappées sur `ERROR_CODE_BACKFILL_RAW_CONVERSION_INVALID` afin de ne pas modifier le contrat externe du Job.

+Le rejeu opérateur du 2026-09-06 ferme `pre.003` : audits statiques propres, `cargo check --workspace` PASS, Clippy strict PASS, `cargo test -p ksp-raw-transaction-lib` PASS, `cargo test -p ksp-job-backfill-lib` PASS avec 51 tests unitaires et 20 tests d’intégration, et arbres normal/features conformes.
+
 ### `pre.004` — HTTP observed block + block material

-Ajouter `get_block_observed`, fixtures provenance, extraction transaction par transaction et adapters HTTP block vers matériau common. Aucun Worker live complet encore.
+**Statut : réalisé.**
+
+`HttpTransportPool::get_block_observed(...)` complète la provenance HTTP observée sans exposer URL/header/body et conserve le provider/endpoint du winner réel après retry/reroute. La common RAW ajoute l’extraction bornée de la première signature depuis un transaction wire Base64 complet et `RawTransactionMaterial::binary_base64_with_embedded_signature(...)` pour préserver slot, block time, meta, version et transaction index.
+
+Conformément à `TR-C2`, aucun adapter productif Transport DTO -> `RawTransactionMaterial` n’est placé dans Transport : une preuve cross-layer test-only démontre `get_block_observed -> N SolanaBlockTransaction -> RawTransactionMaterial -> RAW v1` sur deux transactions distinctes avec index 0/1, tandis que l’adapter productif reste réservé au futur Worker. Aucun Worker live complet n’est ouvert.

 ### `pre.005` — parité WS/Helius full

--- a/docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
+++ b/docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
@@ -1,5 +1,5 @@
 <!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->

 # Validation v0.3.10 — RAW Transaction commune + Worker d’ingestion

@@ -661,3 +661,109 @@ cargo tree -p ksp-job-backfill-lib --edges normal
 cargo tree -p ksp-job-backfill-lib -e features
 ```

+## 13. Fermeture opérateur `pre.003` et gate `pre.004` — HTTP observed block
+
+### 13.1 Fermeture opérateur de `pre.003`
+
+Le rejeu communiqué le 2026-09-06 ferme la migration Backfill :
+
+```text
+cargo fmt --all : exécuté
+General Rust rule audit: clean
+Rust export completeness audit: 0 candidate(s)
+KSP workspace Rust rule audit: clean
+Markdown table audit: clean (339 table(s), 756 file(s))
+cargo check --workspace : PASS
+cargo clippy --workspace --all-targets --all-features -- -D warnings : PASS
+cargo test -p ksp-raw-transaction-lib : PASS, 9 unit + 8 intégration
+cargo test -p ksp-job-backfill-lib : PASS, 51 unit + 20 intégration
+cargo tree -p ksp-job-backfill-lib --edges normal : edge common présent, graphe attendu
+cargo tree -p ksp-job-backfill-lib -e features : aucune feature KSP inattendue
+```
+
+`pre.004` peut donc être ouverte sur une base entièrement validée.
+
+### 13.2 Surface Transport `pre.004`
+
+`HttpTransportPool::get_block_observed(...)` :
+
+```text
+réutilise exactement la validation/config moderne de get_block
+utilise le même routing/admission/retry standard
+retourne Option<SolanaConfirmedBlock>
+conserve endpoint_name + provider du winner réel
+préserve result = null comme None
+n’expose ni URL, ni headers, ni raw HTTP body
+Debug de HttpObservedValue ne rend pas le block payload
+```
+
+Les fixtures déterministes couvrent le retry/reroute depuis un premier endpoint `429` vers un second winner et vérifient que la provenance retournée appartient au second endpoint.
+
+### 13.3 Matériau common depuis un bloc Base64
+
+`ksp-raw-transaction-lib` ajoute :
+
+```text
+extract_raw_transaction_signature_from_binary_base64(...)
+RawTransactionMaterial::binary_base64_with_embedded_signature(...)
+```
+
+L’extracteur :
+
+```text
+borne l’entrée avant décodage
+exige un Base64 STANDARD canonique
+lit le short_vec Solana de signatures sans dépendance Solana transaction runtime
+refuse count = 0
+refuse short_vec tronqué/non canonique
+refuse tableau de signatures tronqué
+exige des bytes message après le tableau déclaré
+copie uniquement la première signature exacte de 64 octets
+ne copie jamais le transaction wire dans erreur/Debug
+```
+
+Les fixtures de référence utilisent deux transactions minimales de `66` octets : prefix `1`, signatures respectives `[0; 64]` et `[1; 64]`, puis un byte de message. Les signatures extraites sont donc exactement distinctes et restent associées aux index 0 et 1 du bloc.
+
+### 13.4 Preuve cross-layer sans mauvais edge
+
+Le canari d’intégration `ksp-job-backfill-lib/tests/http_block_material.rs` utilise les deux dépendances déjà autorisées de cette crate pour prouver :
+
+```text
+get_block_observed
+    -> SolanaConfirmedBlock
+    -> 2 SolanaBlockTransaction distinctes
+    -> full Base64 transaction + meta + version + index 0/1
+    -> RawTransactionMaterial::binary_base64_with_embedded_signature
+    -> canonicalize_raw_transaction
+    -> signatures [0;64] / [1;64] préservées
+```
+
+Cette preuve est volontairement test-only. `TR-C2` reste inchangé : l’adapter productif Transport DTO -> common sera Worker-owned. Il n’existe toujours aucun edge de production `ksp-onchain-transport-lib -> ksp-raw-transaction-lib` ni l’inverse.
+
+### 13.5 Audits d’assemblage
+
+Exécuté dans l’environnement d’assemblage après fermeture du delta :
+
+```text
+python3 scripts/audit_rust_workspace_rules.py
+General Rust rule audit: clean
+Rust export completeness audit: 0 candidate(s)
+KSP workspace Rust rule audit: clean
+
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
+Markdown table audit: clean (339 table(s), 757 file(s))
+```
+
+Les gates Cargo restent à rejouer côté opérateur dans l’environnement Rust complet :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test -p ksp-raw-transaction-lib
+cargo test -p ksp-onchain-transport-lib
+cargo test -p ksp-job-backfill-lib --test http_block_material
+cargo tree -p ksp-raw-transaction-lib --edges normal
+cargo tree -p ksp-onchain-transport-lib --edges normal
+```
+