7.6 KiB
Delta 0.2.11-pre.002-fix.001 — Rustdoc, Logging et taxonomie Off-chain
1. Base requise
Ce correctif s'applique exclusivement après :
v0.2.10
+ 0.2.11-pre.001
+ 0.2.11-pre.001-fix.001
+ 0.2.11-pre.002
Conformément à VER-ID-007 et VER-ID-010, la version Cargo devient 0.2.11-pre.2.fix.1 car ce correctif modifie du code Rust et un manifeste de crate.
2. Motifs du correctif
La validation opérateur de pre.002 a montré que cargo check et les tests passaient, mais que cargo clippy --workspace --all-targets émettait deux warnings missing_docs sur les crates d'intégration :
crates/ksp-offchain-transport-lib/tests/dependency_boundary.rs
crates/ksp-offchain-transport-lib/tests/public_api.rs
Le gate n'était donc pas propre malgré le succès fonctionnel. Les résultats opérateur complets de pre.002 restent l'autorité sur cette constatation.
Une relecture des règles a également confirmé les contrats suivants :
RUST-DOC-001/003 rustdocs utiles sur les surfaces concernées
DEP-LOG-004 runtime KSP instrumenté via ksp-logging-lib
DEP-LOG-010 target explicite dans src/constants.rs
DEP-LOG-011 pas de target dérivé implicitement de Cargo
FILE_CONTRACTS modules séparés selon responsabilités/invariants
Enfin, la fondation initiale utilisait des noms internes trop génériques (decimal.rs, observation.rs, provider.rs, settings.rs) alors que ksp-offchain-transport-lib est destinée à porter plusieurs familles off-chain hétérogènes.
3. Corrections Rustdoc
Les deux tests d'intégration possèdent désormais une rustdoc de crate explicite, ce qui supprime les warnings missing_docs attendus sous #![warn(missing_docs)].
Aucun lint n'est désactivé ou abaissé.
4. Logging KSP
ksp-offchain-transport-lib dépend désormais réellement de ksp-logging-lib.
Le fichier suivant est ajouté :
crates/ksp-offchain-transport-lib/src/constants.rs
avec le target propriétaire :
ksp-offchain-transport-lib
Les validations/constructions comportementales de la fondation émettent uniquement via les macros ksp-logging-lib et crate::TRACING_TARGET. Aucune dépendance directe à tracing, tracing-subscriber ou tracing-appender n'est ajoutée.
Les logs de validation ne recopient ni identifiant rejeté, ni display name rejeté, ni futur credential.
5. Taxonomie de modules
La crate est explicitement traitée comme un transport off-chain hétérogène et non comme une crate dédiée exclusivement aux prix.
Les modules V1 de prix sont renommés :
decimal.rs -> market_price_decimal.rs
observation.rs -> market_price_observation.rs
provider.rs -> market_price_provider.rs
settings.rs -> market_price_settings.rs
Les tests unitaires en miroir suivent la même convention.
La façade publique reste au crate-root ; aucun pub mod n'est introduit. Les noms publics Price* restent ceux du contrat V1, tandis que le classement physique privé rend explicite leur appartenance à la famille market_price.
La taxonomie durable prévue est :
constants.rs / error.rs partagé crate-wide
http_* mécanique HTTP partageable lorsqu'elle existe réellement
market_price_* prix de marché / spot
swap_quote_* futures quotes montant/route
autres familles ajoutées seulement avec un scope réel
Cette organisation suit le précédent KSP des familles http_*, ws_*, grpc_* et rpc_* de On-chain Transport.
6. Lecture/écriture
market_price V1 reste strictement read-only. La crate n'est pas déclarée définitivement read-only pour toute évolution future : la sémantique métier décide de l'ownership, pas le simple verbe HTTP.
Une future quote Jupiter appartient à une famille distincte swap_quote; une soumission ou signature de transaction Solana reste hors de cette crate. Toute vraie mutation d'un service distant demandera un contrat explicite avant implémentation.
7. Tests et canaries modifiés
dependency_boundary.rs vérifie désormais au minimum :
ksp-logging-lib présent
aucune dépendance tracing directe
constants.rs et TRACING_TARGET explicites
modules V1 préfixés market_price_*
anciens modules internes génériques absents
Config, reqwest et SDK providers toujours absents de pre.002
public_api.rs conserve les canaries de façade de pre.002 avec sa rustdoc de crate.
8. Validations demandées après application
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.2.11
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-offchain-transport-lib
cargo test --workspace
Le résultat attendu de Clippy est sans warning rustdoc pour ksp-offchain-transport-lib.
9. Scope inchangé
Le correctif n'ajoute aucun client HTTP, limiter actif, adapter provider, credential Config, quote Jupiter ou nouvelle paire. pre.003 reste propriétaire du premier runtime HTTP commun.
10. Validation opérateur de pre.002 ayant déclenché le fix
La validation fournie par l'opérateur avant ce correctif donne :
cargo fmt --all exécuté
python3 scripts/audit_rust_workspace_rules.py clean
python3 scripts/audit_markdown_tables.py clean, 115 tables / 102 files
cargo check --workspace PASS
cargo clippy --workspace --all-targets PASS fonctionnel avec 2 warnings missing_docs
cargo test -p ksp-offchain-transport-lib PASS, 10 unit + 1 boundary + 2 public API
cargo test --workspace PASS, ignored opt-in/diagnostic inchangés
Les deux warnings Clippy sont précisément la raison rustdoc du présent fix ; ils ne sont pas requalifiés en PASS propre.
11. Fichiers ajoutés
crates/ksp-offchain-transport-lib/src/constants.rs
crates/ksp-offchain-transport-lib/src/market_price_decimal.rs
crates/ksp-offchain-transport-lib/src/market_price_observation.rs
crates/ksp-offchain-transport-lib/src/market_price_provider.rs
crates/ksp-offchain-transport-lib/src/market_price_settings.rs
crates/ksp-offchain-transport-lib/unit_tests/market_price_decimal.rs
crates/ksp-offchain-transport-lib/unit_tests/market_price_observation.rs
crates/ksp-offchain-transport-lib/unit_tests/market_price_provider.rs
crates/ksp-offchain-transport-lib/unit_tests/market_price_settings.rs
deltas/0.2.11/pre.002-fix.001.md
12. Fichiers modifiés
Cargo.toml
crates/ksp-offchain-transport-lib/Cargo.toml
crates/ksp-offchain-transport-lib/src/error.rs
crates/ksp-offchain-transport-lib/src/lib.rs
crates/ksp-offchain-transport-lib/tests/dependency_boundary.rs
crates/ksp-offchain-transport-lib/tests/public_api.rs
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
13. Fichiers supprimés par renommage
crates/ksp-offchain-transport-lib/src/decimal.rs
crates/ksp-offchain-transport-lib/src/observation.rs
crates/ksp-offchain-transport-lib/src/provider.rs
crates/ksp-offchain-transport-lib/src/settings.rs
crates/ksp-offchain-transport-lib/unit_tests/decimal.rs
crates/ksp-offchain-transport-lib/unit_tests/observation.rs
crates/ksp-offchain-transport-lib/unit_tests/provider.rs
crates/ksp-offchain-transport-lib/unit_tests/settings.rs
Ces suppressions font partie du correctif : les anciens fichiers génériques ne doivent pas coexister avec les fichiers market_price_* après application.