khadhroony-solana-project/deltas/0.2.11/pre.003-fix.001.md

<!-- file: deltas/0.2.11/pre.003-fix.001.md -->
<!-- version: 1 -->

# Delta `0.2.11-pre.003-fix.001` — conformité crate-root, staging HTTP et burst documenté

## 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
+ 0.2.11-pre.002-fix.001
+ 0.2.11-pre.002-fix.002
+ 0.2.11-pre.002-fix.003
+ 0.2.11-pre.003
```

La version Cargo attendue à l'entrée est :

```text
0.2.11-pre.3
```

La version Cargo de sortie est :

```text
0.2.11-pre.3.fix.1
```

## 2. Motif du correctif

Le gate opérateur de `pre.003` a révélé plusieurs écarts avant poursuite vers `pre.004` :

```text
RUST-FMT-104 : 6 violations dans src/error.rs
cargo check : 6 warnings de réexports pub(crate) HTTP inutilisés
cargo clippy --workspace --all-targets : mêmes warnings de réexports
cargo test -p ksp-offchain-transport-lib : 20 PASS, 1 FAIL
```

Le test en échec était :

```text
http_admission::tests::documented_burst_is_consumed_atomically_before_refill
```

La cause était une validation incorrecte refusant `burst > requests`. Cette contrainte contredit un cas déjà retenu dans le plan : Coinbase documente `10 req/s` avec `burst 15`.

Une relecture de `docs/rules/RULES_RUST.md` confirme également deux règles applicables :

```text
RUST-IMPORT-009 / RUST-API-004
    un item pub/pub(crate) crate-wide est consommé via la façade crate::Item,
    y compris depuis son module de déclaration.

RUST-API-008
    un helper préparatoire sans consumer de production reste sous #[cfg(test)]
    jusqu'à sa première consommation réelle ; #[allow(dead_code)] n'est pas utilisé
    pour conserver artificiellement du code mort.
```

## 3. Correction de façade crate-root

Les items HTTP partagés continuent d'être réexportés au crate-root dans le build de test, et leurs implémentations utilisent désormais leur chemin de façade :

```text
impl crate::HttpAdmissionPolicy
impl crate::HttpAdmissionController
impl crate::HttpJsonDocument
impl crate::HttpGetRequest
impl crate::HttpRestClient
impl crate::HttpClientSettings
```

Les signatures et références crate-wide correspondantes utilisent également `crate::Item` lorsqu'elles traversent un module.

Les types strictement privés, tels que `HttpTokenBucketState`, restent locaux et ne sont pas réexportés.

## 4. Staging `RUST-API-008`

Aucun adapter de production ne consomme encore les primitives `http_*` en `pre.003`.

Les trois modules préparatoires sont donc compilés sous :

```text
#[cfg(test)]
```

jusqu'à `pre.004`, où les premiers adapters de production les consommeront réellement.

Les anciens :

```text
#[allow(dead_code)]
```

sont supprimés.

Le staging concerne :

```text
http_admission
http_client
http_settings
```

Les codes d'erreur HTTP publics restent disponibles dans le build normal ; aucune API HTTP générique n'est rendue publique aux consumers.

## 5. Correction du burst

La policy fixe conserve les invariants suivants :

```text
requests > 0
window > 0
window <= borne défensive
burst > 0 lorsqu'il est explicite
burst absent -> capacité locale conservatrice de 1
```

En revanche :

```text
burst <= requests
```

n'est plus un invariant.

Un burst documenté est une capacité instantanée distincte de la cadence moyenne et peut légitimement lui être supérieur.

Le canari déterministe couvre explicitement :

```text
1 req/s
burst 2
2 admissions immédiates
3e admission différée
```

Cette propriété protège notamment la représentabilité future du cas Coinbase `10 req/s, burst 15`.

## 6. Ordre des constantes

Le bloc `const` de `src/error.rs` est réordonné alphabétiquement conformément à `RUST-FMT-005` / `RUST-FMT-104` sans modifier les valeurs des codes d'erreur.

Aucun code d'erreur n'est ajouté, supprimé ou renommé.

## 7. Test HTTP complémentaire

Un canari supplémentaire construit une requête HTTPS officielle-style sans effectuer de réseau, ajoute query pair et header sensible, puis vérifie que la représentation `Debug` ne contient ni host ni credential.

Ce canari consomme également le constructeur `HttpGetRequest::new_https` pendant le staging `cfg(test)`.

## 8. Fichiers modifiés

```text
Cargo.toml
crates/ksp-offchain-transport-lib/src/error.rs
crates/ksp-offchain-transport-lib/src/http_admission.rs
crates/ksp-offchain-transport-lib/src/http_client.rs
crates/ksp-offchain-transport-lib/src/http_settings.rs
crates/ksp-offchain-transport-lib/src/lib.rs
crates/ksp-offchain-transport-lib/unit_tests/http_admission.rs
crates/ksp-offchain-transport-lib/unit_tests/http_client.rs
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
```

## 9. Fichier ajouté

```text
deltas/0.2.11/pre.003-fix.001.md
```

## 10. Fichiers volontairement inchangés

```text
crates/ksp-offchain-transport-lib/Cargo.toml
crates/ksp-offchain-transport-lib/tests/**
CHANGELOG.md
ROADMAP.md
README.md
.env.example
config/**
crates/ksp-config-lib/**
crates/ksp-onchain-transport-lib/**
prompts/**
```

Le manifeste de la crate hérite toujours de `workspace.package.version`; seul le `Cargo.toml` racine porte le bump technique.

## 11. Validations sandbox

Exécutées après le correctif :

```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
```

Le sandbox ne fournit pas Cargo ; les gates opérateur restent à rejouer sur l'état exact du correctif.

## 12. 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.2.11
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-offchain-transport-lib
cargo test --workspace
```

Le passage à `pre.004` est conditionné à un gate propre sans warning et au retour au vert du test de burst.