194 lines
7.6 KiB
Markdown
194 lines
7.6 KiB
Markdown
<!-- file: deltas/0.2.11/pre.002-fix.001.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.11-pre.002-fix.001` — Rustdoc, Logging et taxonomie Off-chain
|
|
|
|
## 1. Base requise
|
|
|
|
Ce correctif s'applique exclusivement après :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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é :
|
|
|
|
```text
|
|
crates/ksp-offchain-transport-lib/src/constants.rs
|
|
```
|
|
|
|
avec le target propriétaire :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```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.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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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.
|