khadhroony-solana-project/deltas/0.3.6/pre.004.md

Delta 0.3.6-pre.004 — provenance Transport observée pour getTransaction

Base requise

0.3.6-pre.003-fix.001 appliquée
workspace.package.version = 0.3.6-pre.3.fix.1

Le gate opérateur fourni pour cette base confirme :

cargo fmt --all                                      PASS
python3 scripts/audit_rust_workspace_rules.py        PASS / clean
python3 scripts/audit_markdown_tables.py ...         PASS / clean (264 tables / 145 fichiers)
cargo check --workspace                              PASS
cargo clippy --workspace --all-targets               PASS
cargo test -p ksp-job-api                            PASS / 13 unitaires + 14 canaries
cargo tree -p ksp-job-api --edges normal             Core-only confirmé
cargo tree -p ksp-job-api -e features                aucune feature Job API

Objectif

Matérialiser exclusivement la tranche pre.004 du plan 027 : permettre au futur backfill de connaître le provider et l'endpoint HTTP qui ont réellement produit le succès de getTransaction, y compris après retry/reroutage, sans dupliquer le client RPC ni déplacer la politique Transport vers Job.

Conception

La nouvelle enveloppe générique HttpObservedValue<T> contient uniquement :

• la valeur typée T ;
• le nom configuré et validé de l'endpoint victorieux ;
• le descripteur provider de cet endpoint.

Elle ne contient jamais :

• URL d'endpoint ;
• headers HTTP ;
• body HTTP brut ;
• credentials ou autre détail de connexion.

Son Debug conserve l'identité sûre de routage mais remplace systématiquement la valeur typée par <available> afin qu'un diagnostic générique ne rende pas accidentellement un payload transactionnel volumineux.

Le moteur HTTP commun n'est pas dupliqué. execute_standard_rpc_with possède toujours l'unique boucle de support, request-id, admission, deadline, retry, cooldown, HTTP, parsing JSON-RPC et accounting. Une projection de succès interne décide seulement de la forme de retour :

• execute_standard_rpc retourne la valeur historique sans allouer de provenance ;
• la voie interne observée capture endpoint/provider uniquement après le succès final ;
• get_transaction_observed réutilise cette voie et retourne HttpObservedValue<Option<SolanaConfirmedTransaction>>.

Les validations de paramètres getTransaction sont factorisées dans un helper commun. get_transaction et get_transaction_observed rejettent donc exactement les mêmes entrées et utilisent le même décodage typé. L'API historique reste source-compatible.

Tests ajoutés

Deux tests unitaires Transport :

• typed_get_transaction_observed_reports_actual_winner_after_retry_reroute : deux endpoints de même priorité, premier résultat HTTP 429, retry sur le second ; la valeur observée doit rapporter winner-endpoint / winner-provider, pas le candidat initial ;
• typed_get_transaction_observed_preserves_null_and_redacts_typed_value_debug : result: null reste None, endpoint/provider restent disponibles et le Debug ne rend pas la valeur typée.

Une canarie publique :

• public_v0_3_6_pre_004_observed_get_transaction_surface_is_available_from_crate_root : méthode et enveloppe observée sont consommables depuis le crate-root.

Aucun fixture wire nouveau n'est nécessaire : les fixtures get_transaction.base64.json et get_transaction.null.json existantes sont réutilisées.

Fichiers ajoutés

deltas/0.3.6/pre.004.md

Fichiers modifiés

Cargo.toml
crates/ksp-onchain-transport-lib/src/http_executor.rs
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/unit_tests/rpc_transactions.rs
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md

Mécanique Cargo :

header version: 398 -> 399
workspace.package.version: 0.3.6-pre.3.fix.1 -> 0.3.6-pre.4
workspace members: inchangés
workspace dependencies: inchangées

Fichiers supprimés

Aucun.

Frontières conservées

• aucune crate Job ou Store n'entre dans Transport ;
• aucune dépendance ou feature n'est ajoutée ;
• aucune sélection d'endpoint, pause ou boucle de retry n'est ajoutée dans Job ;
• aucune nouvelle lecture Config/env n'est introduite ;
• aucun code, DTO, client, retry loop ou provenance kbot3 n'est copié ; la matrice fonctionnelle pre.001 reste seulement une référence de besoin ;
• le legacy get_transaction_legacy reste inchangé et non observé ; le backfill v0.3.6 utilisera le formulaire moderne objet ;
• README/USAGE restent fermés jusqu'à la tranche de réconciliation documentaire prévue par le plan.

Validations exécutées dans l'environnement d'assemblage

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/0.3.6
-> Markdown table audit: clean

python3 -m unittest scripts/tests/test_audit_markdown_tables.py
-> 5 tests / OK

Le premier passage de l'auditeur Rust a détecté deux rustdocs manquantes sur les helpers pub(crate) de HttpObservedValue; elles ont été ajoutées avant assemblage et le second passage est intégralement propre.

L'environnement d'assemblage ne fournit ni cargo, ni rustfmt, ni rustc. Aucune compilation ou suite Rust de pre.004 n'est donc annoncée comme exécutée localement.

Gate opérateur demandé

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-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --edges normal
cargo tree -p ksp-onchain-transport-lib -e features

Le gate doit notamment confirmer le retry/reroutage déterministe du nouveau test observé et l'absence de nouvelle dépendance/feature Transport.

Questions ouvertes

Aucune question ne bloque pre.005 après un gate opérateur vert de pre.004.