# Delta `0.3.6-pre.006` — conversion RAW transaction v1 et provenance observée ## Base requise ```text 0.3.6-pre.005-fix.001 appliquée workspace.package.version = 0.3.6-pre.5.fix.1 ``` La base opérateur inclut également la synchronisation manuelle des versions d'en-tête omise dans l'archive initiale du fix : ```text Cargo.toml header 400 -> 401 crates/ksp-job-backfill-lib/src/discovery.rs header 1 -> 2 ``` Le gate opérateur fourni pour cette base confirme : ```text cargo fmt --all PASS python3 scripts/audit_rust_workspace_rules.py PASS / clean python3 scripts/audit_markdown_tables.py ... PASS / clean (264 tables / 148 fichiers) cargo check --workspace PASS cargo clippy --workspace --all-targets PASS cargo test -p ksp-job-backfill-lib PASS unitaires 11 PASS dependency_boundary 2 PASS public_api 2 PASS release_completeness 2 PASS cargo tree -p ksp-job-backfill-lib --edges normal exécuté cargo tree -p ksp-job-backfill-lib -e features exécuté ``` ## Objectif Matérialiser exclusivement la tranche `pre.006` du plan 027 : convertir un candidat Backfill déjà découvert en transaction RAW canonique v1 et en observation d'acquisition sûre à partir du chemin Transport observé `getTransaction`, sans encore persister dans Store ni ouvrir le runtime de Job. L'identité logique reste strictement : ```text RawTransactionReference = (RawNetworkId, RawTransactionSignature) ``` Provider, endpoint, protocole, méthode Transport et `JobId` ne deviennent jamais une identité de transaction. Ils servent uniquement à caractériser l'acquisition et, lorsqu'une transaction existe, l'identité déterministe de son observation. ## Signature canonique `BackfillSignature::to_raw_transaction_signature` ajoute le passage de la forme Base58 bornée de `pre.005` vers `RawTransactionSignature` exactement 64 octets. Le décodeur Base58 est privé, borné et spécialisé pour cette frontière : - alphabet Base58 Solana exact ; - exactement 64 octets décodés requis ; - zéros initiaux `1` conservés ; - dépassement arithmétique rejeté ; - aucune dépendance SDK/protocolaire Solana ; - aucune nouvelle dépendance Base58 externe. La conversion ne modifie pas l'identité réseau du candidat et rejette avant Transport tout candidat dont le réseau diffère de la requête. ## Hydratation Transport observée La voie publique : ```text hydrate_backfill_candidate ``` appelle exclusivement : ```text HttpTransportPool::get_transaction_observed ``` avec : ```text encoding = base64 commitment = engagement explicite du Backfill maxSupportedTransactionVersion = 0 ``` Transport reste propriétaire du routage, retry, pacing, cooldown et endpoint victorieux. Job n'introduit aucun second client ni boucle de retry. Deux outcomes sont distingués : - `Available(BackfillRawAcquisition)` : transaction présente, RAW v1 et observation construits en mémoire ; - `Missing(RawTransactionReference)` : JSON RPC `result: null`, aucune provenance ni observation fabriquée. ## RAW transaction v1 Le format KSP figé par la tranche est : ```text format_id = ksp.solana.raw_transaction format_version = 1 ``` Le payload canonique est du JSON UTF-8 compact déterministe. La forme top-level est construite dans cet ordre : 1. `transaction` ; 2. `meta` si le champ wire n'est pas omitted ; 3. `version` si le champ wire n'est pas omitted ; 4. `transactionIndex` si le champ wire n'est pas omitted. La transaction est conservée sans décodage métier sous la forme : ```json ["","base64"] ``` Les objets JSON imbriqués sont canonisés récursivement par tri lexical des clés ; l'ordre des tableaux reste intact. Les états wire `Omitted`, `Null` et `Value` de `meta`, `version` et `transactionIndex` restent distincts. `slot` et `blockTime` appartiennent aux champs structurés de `RawTransaction` et ne sont pas dupliqués dans le payload. Un `blockTime` négatif ou non représentable dans `RawTimestamp` est une erreur de conversion terminale. SHA-256 et `byte_len` sont calculés sur les octets canoniques exacts avant construction de `RawPayload`. Les réponses transactionnelles non Base64 sont rejetées ; Job ne bascule pas vers une interprétation JSON/jsonParsed ou fournisseur. ## Provenance d'acquisition Une transaction disponible produit `RawAcquisitionProvenance` avec : - provider réellement victorieux ; - protocole sûr `solana.http.json_rpc` ; - méthode `getTransaction` ; - endpoint sûr réellement victorieux ; - engagement demandé ; - `JobId` comme capture session id ; - origine `Backfill` ; - timestamp de réception fourni par l'hôte. Aucun URL, header, secret, body HTTP ou payload fournisseur brut n'est copié dans la provenance. La clé `RawTransactionObservationKey` utilise SHA-256 avec séparation de domaine et couvre : - `JobId` ; - fingerprint du scope ; - signature RAW 64 octets ; - provider ; - endpoint ; - engagement ; - version du contrat d'observation. Même réseau + même signature + endpoint différent représente donc toujours la même transaction logique mais une observation d'acquisition distincte. ## Dépendances La crate conserve ses dépendances KSP de `pre.005` et ajoute uniquement : ```text serde_json.workspace = true ``` `serde_json` est déjà centralisé dans `[workspace.dependencies]`. `sha2` reste la primitive SHA-256 déjà présente. Aucune dépendance `bs58`, SDK Solana, Store API/backend, Config, reqwest ou tonic n'est ajoutée. ## Tests matérialisés La tranche ajoute **8 tests unitaires**, portant le total de `ksp-job-backfill-lib` à **19 unitaires** : - décodage Base58 exact 64 octets, longueur excessive et overflow ; - golden payload canonique, longueur, SHA-256 et provenance ; - distinction omitted/null des champs wire ; - rejet des transactions non Base64 ; - block times négatifs ou non représentables ; - clé d'observation déterministe et sensible à provider/endpoint ; - mismatch réseau rejeté avant Transport ; - outcome Missing limité à la référence réseau + signature. Une canarie publique supplémentaire porte les canaries d'intégration à **7** : - `dependency_boundary` : 2 ; - `public_api` : 3 ; - `release_completeness` : 2. Les canaries verrouillent en outre l'usage du chemin observé, `base64`, `maxSupportedTransactionVersion = 0`, l'absence de persistance et les firewalls de dépendances. ## Fichiers ajoutés ```text crates/ksp-job-backfill-lib/src/conversion.rs crates/ksp-job-backfill-lib/unit_tests/conversion.rs deltas/0.3.6/pre.006.md ``` ## Fichiers modifiés ```text Cargo.toml crates/ksp-job-backfill-lib/Cargo.toml crates/ksp-job-backfill-lib/src/error.rs crates/ksp-job-backfill-lib/src/lib.rs crates/ksp-job-backfill-lib/src/request.rs crates/ksp-job-backfill-lib/tests/dependency_boundary.rs crates/ksp-job-backfill-lib/tests/public_api.rs crates/ksp-job-backfill-lib/tests/release_completeness.rs docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md docs/validation/023-V0_3_6_JOB_API_BACKFILL.md ``` ## Versions d'en-tête Tous les fichiers Rust/TOML modifiés par cette tranche incrémentent leur version d'en-tête par rapport à la base opérateur corrigée : ```text Cargo.toml 401 -> 402 crates/ksp-job-backfill-lib/Cargo.toml 1 -> 2 crates/ksp-job-backfill-lib/src/error.rs 1 -> 2 crates/ksp-job-backfill-lib/src/lib.rs 1 -> 2 crates/ksp-job-backfill-lib/src/request.rs 1 -> 2 crates/ksp-job-backfill-lib/tests/dependency_boundary.rs 1 -> 2 crates/ksp-job-backfill-lib/tests/public_api.rs 1 -> 2 crates/ksp-job-backfill-lib/tests/release_completeness.rs 1 -> 2 ``` Les nouveaux fichiers Rust commencent à `version: 1`. Les documents Markdown modifiés incrémentent eux aussi leur en-tête documentaire : plan 027 et validation 023 passent de `9` à `10`. ## Version workspace La tranche modifie du code Rust et le manifeste runtime de la crate : ```text workspace.package.version = 0.3.6-pre.6 delivery = 0.3.6-pre.006 commit = v0.3.6-pre.006 ``` Aucun tag prerelease. ## Fichiers supprimés Aucun. ## Frontières conservées - aucune persistance Store ; - aucune prélecture Store avant hydratation ; - aucun checkpoint ou frontier contiguë ; - aucune concurrence d'hydratation concrète ; - aucun snapshot Job concret ; - aucune Config/env ; - aucun Worker ou exécutable ; - aucune modification Transport ou Store ; - aucun endpoint/provider/protocole dans l'identité transactionnelle ; - aucun README, USAGE, CHANGELOG ou ROADMAP rouvert ; - aucun code kbot3 copié. ## Validations dans l'environnement d'assemblage L'environnement d'assemblage exécute les audits statiques du dépôt et les contrôles d'archive. Il ne possède ni `cargo`, ni `rustc`, ni `rustfmt`; le gate Rust de `pre.006` doit donc être rejoué par l'opérateur avant clôture. ## Gate opérateur demandé ```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/0.3.6 cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-job-backfill-lib cargo tree -p ksp-job-backfill-lib --edges normal cargo tree -p ksp-job-backfill-lib -e features ``` Résultat attendu : **19 tests unitaires + 7 canaries d'intégration**, sans persistance Store et avec un graphe normal qui conserve `ksp-store-lib` sans backend imposé. ## Questions ouvertes Aucune pour `pre.006`. La persistance atomique Store et ses outcomes restent réservés à `pre.007` après gate vert de cette tranche.