diff --git a/Cargo.toml b/Cargo.toml index e49adee..170138e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 409 +# version: 410 [workspace] resolver = "3" members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"] [workspace.package] -version = "0.3.6-pre.9.fix.1" +version = "0.3.6-pre.9.fix.2" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/crates/ksp-job-backfill-lib/src/request.rs b/crates/ksp-job-backfill-lib/src/request.rs index 06d0d14..73ffaa1 100644 --- a/crates/ksp-job-backfill-lib/src/request.rs +++ b/crates/ksp-job-backfill-lib/src/request.rs @@ -1,5 +1,5 @@ // file: crates/ksp-job-backfill-lib/src/request.rs -// version: 4 +// version: 5 use sha2::Digest; // rust-rules: trait-import @@ -224,6 +224,10 @@ impl std::fmt::Debug for crate::BackfillScope { pub struct BackfillScopeFingerprint([u8; 32]); impl crate::BackfillScopeFingerprint { + const fn from_bytes(bytes: [u8; 32]) -> Self { + return Self(bytes); + } + /// Returns the exact deterministic fingerprint bytes. #[must_use] pub const fn as_bytes(&self) -> &[u8; 32] { @@ -455,7 +459,7 @@ fn fingerprint_scope( std::option::Option::None => hasher.update([0_u8]), } let bytes: [u8; 32] = hasher.finalize().into(); - return crate::BackfillScopeFingerprint(bytes); + return crate::BackfillScopeFingerprint::from_bytes(bytes); } fn hash_bytes(hasher: &mut sha2::Sha256, value: &[u8]) { diff --git a/deltas/0.3.6/pre.009-fix.002.md b/deltas/0.3.6/pre.009-fix.002.md new file mode 100644 index 0000000..6a98579 --- /dev/null +++ b/deltas/0.3.6/pre.009-fix.002.md @@ -0,0 +1,88 @@ + + + +# Delta v0.3.6-pre.009-fix.002 + +## Base requise + +- `0.3.6-pre.9.fix.1` / livraison `pre.009-fix.001`. +- Les audits Rust/Markdown du gate opérateur sont propres. +- `cargo check --workspace` bloque sur `E0423` dans `crates/ksp-job-backfill-lib/src/request.rs` avant que Clippy/tests puissent valider le fix. +- La cause est précise : `BackfillScopeFingerprint` est public et correctement référencé via le crate-root, mais son constructeur de tuple struct n'est pas visible via le réexport parce que son champ `[u8; 32]` reste privé dans `request.rs`. + +## Correctif + +Le fix conserve l'opacité publique du fingerprint et ne réintroduit pas un accès par nom local. + +`impl crate::BackfillScopeFingerprint` reçoit un constructeur associé strictement privé : + +```rust +const fn from_bytes(bytes: [u8; 32]) -> Self { + return Self(bytes); +} +``` + +La fonction de calcul appelle ensuite : + +```rust +return crate::BackfillScopeFingerprint::from_bytes(bytes); +``` + +Ainsi : + +- les consommateurs et le module propriétaire continuent de référencer le type partagé via `crate::BackfillScopeFingerprint` ; +- l'initialisation du champ privé reste confinée dans l'impl situé dans le module propriétaire ; +- le champ ne devient ni `pub` ni `pub(crate)` ; +- aucun chemin `crate::request::BackfillScopeFingerprint` n'est introduit ; +- aucun contrat public, octet de fingerprint, hash, scope, checkpoint, runtime, dépendance ou feature ne change. + +## Cargo et versions de fichiers + +- `workspace.package.version` : `0.3.6-pre.9.fix.1` -> `0.3.6-pre.9.fix.2`. +- `Cargo.toml` : version d'en-tête `409` -> `410`. +- `crates/ksp-job-backfill-lib/src/request.rs` : `4` -> `5`. +- plan 027 : `17` -> `20` (trois révisions réelles pendant la matérialisation du fix). +- validation 023 : `17` -> `20` (trois révisions réelles pendant la matérialisation du fix). + +## Graphe de dépendances + +Aucune dépendance ni feature ne change. Aucun `cargo tree` n'est requis pour ce fix, sauf revalidation volontaire après un `cargo clean` séparé. + +## Payload + +Ajout : + +- `deltas/0.3.6/pre.009-fix.002.md` + +Modifications : + +- `Cargo.toml` +- `crates/ksp-job-backfill-lib/src/request.rs` +- `docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md` +- `docs/validation/023-V0_3_6_JOB_API_BACKFILL.md` + +Aucune suppression. + +## Validations d'assemblage + +À exécuter dans l'environnement d'assemblage : + +```text +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 +``` + +L'environnement d'assemblage ne fournit ni Cargo, ni Rustc, ni Rustfmt ; le gate Rust reste donc opérateur. + +## 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 +``` + +Résultat attendu : 47 unitaires + 10 canaries d'intégration, sans warning Clippy. diff --git a/docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md b/docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md index b291fc0..d4c542e 100644 --- a/docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md +++ b/docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md @@ -1,5 +1,5 @@ - + # Plan v0.3.6 — Job API et premier backfill RAW @@ -498,7 +498,7 @@ Le gate opérateur de `pre.008` confirme `cargo fmt`, les audits Rust/Markdown e ### `pre.009` — Annulation et snapshots concrets -**Statut : matérialisé ; gate fonctionnel vert mais qualité Rust bloquée, corrigée par `pre.009-fix.001`.** +**Statut : matérialisé ; gate fonctionnel vert mais qualité Rust bloquée, corrigée par `pre.009-fix.001` puis `pre.009-fix.002`.** Budget cible : **15-20 min**. Entrée : frontière prouvée et gate `pre.008-fix.001` vert. La tranche matérialise `BackfillJobRuntime`, `BackfillJobHandle`, `BackfillJobSnapshot` et `BackfillSnapshotSource` comme runtime concret du vertical RAW transaction. `ksp-job-api` reste inchangée, passive et runtime-neutral ; Tokio devient uniquement un détail d'implémentation normal de `ksp-job-backfill-lib` (`macros` + `sync`) et aucun type Tokio n'est exposé dans la racine publique. Le canal concret est un `watch` latest-value O(1) : les progressions intermédiaires peuvent être coalescées, chaque listener possède son receiver cloné, et la dernière valeur terminale reste lisible tant que le handle/source existe. @@ -508,9 +508,15 @@ Le snapshot complet reste sûr : phase, catégorie de scope, borne de découvert #### `pre.009-fix.001` — Normalisation crate-root des items partagés et visibilité runtime -**Statut : matérialisé ; gate opérateur du fix à rejouer.** +**Statut : réalisé ; gate opérateur rejoué mais bloqué par `E0423`, corrigé par `pre.009-fix.002`.** -Le fix réconcilie l'intégralité de `ksp-job-backfill-lib` avec les règles de visibilité/import applicables. Tout item public ou crate-wide réexporté au crate-root est désormais référencé via `crate::Item`, y compris depuis son module propriétaire. `BackfillRuntimeControl` et `TerminalClaim`, utilisés uniquement par `runtime.rs` et ses unit tests attachés, redeviennent strictement privés conformément à `RUST-API-007`; les unit tests du module runtime y accèdent via `super::Item`. Les tests discovery/execution ne dépendent plus de cette visibilité artificielle et déclenchent l'annulation avec `JobCancellationToken` + canal `watch` directement. La canarie publique utilise désormais son paramètre générique via `PhantomData`, supprimant `clippy::extra_unused_type_parameters`. Aucun contrat externe, comportement runtime, dépendance ou feature ne change. +Le fix réconcilie l'intégralité de `ksp-job-backfill-lib` avec les règles de visibilité/import applicables. Tout item public ou crate-wide réexporté au crate-root est désormais référencé via `crate::Item`, y compris depuis son module propriétaire. `BackfillRuntimeControl` et `TerminalClaim`, utilisés uniquement par `runtime.rs` et ses unit tests attachés, redeviennent strictement privés conformément à `RUST-API-007`; les unit tests du module runtime y accèdent via `super::Item`. Les tests discovery/execution ne dépendent plus de cette visibilité artificielle et déclenchent l'annulation avec `JobCancellationToken` + canal `watch` directement. La canarie publique utilise désormais son paramètre générique via `PhantomData`, supprimant `clippy::extra_unused_type_parameters`. Le gate de ce fix révèle ensuite `E0423` sur la construction crate-root d'un tuple struct public à champ privé (`BackfillScopeFingerprint`), sans remettre en cause cette normalisation ; `pre.009-fix.002` corrige uniquement cette construction. Aucun contrat externe, comportement runtime, dépendance ou feature ne change. + +#### `pre.009-fix.002` — Construction privée du fingerprint via façade crate-root + +**Statut : matérialisé ; gate opérateur à rejouer.** + +Le gate de `pre.009-fix.001` révèle une erreur `E0423` : le type public `BackfillScopeFingerprint` est correctement référencé via `crate::BackfillScopeFingerprint`, mais son constructeur de tuple struct n'est pas visible à travers le réexport crate-root puisque son champ `[u8; 32]` reste privé. Le correctif conserve le champ privé et la discipline crate-root : l'initialisation des octets est confinée dans un constructeur associé privé `from_bytes` défini dans `impl crate::BackfillScopeFingerprint`, puis le calcul de fingerprint appelle `crate::BackfillScopeFingerprint::from_bytes(bytes)`. Aucun contrat public, fingerprint, hash, dépendance ou feature ne change. ### `pre.010` — Hardening et canaries externes diff --git a/docs/validation/023-V0_3_6_JOB_API_BACKFILL.md b/docs/validation/023-V0_3_6_JOB_API_BACKFILL.md index a09d571..4c938b9 100644 --- a/docs/validation/023-V0_3_6_JOB_API_BACKFILL.md +++ b/docs/validation/023-V0_3_6_JOB_API_BACKFILL.md @@ -1,5 +1,5 @@ - + # Validation v0.3.6 — Job API et premier backfill RAW @@ -189,7 +189,7 @@ Aucune entrée absolue, traversée, avec séparateur inversé ou lien symbolique ## 13. Annulation et résultats terminaux -`pre.009` matérialise le runtime concret, le canal latest-value et les chemins d'annulation/drainage. Le gate opérateur exécute avec succès les 47 unitaires et 10 canaries couvrant l'attente RPC de découverte, une future pré-Store longue, le drainage des candidats déjà admis, les listeners lents/indépendants, la rétention terminale et les arbitrations terminales. La qualité Rust reste néanmoins bloquée jusqu'au gate de `pre.009-fix.001`, qui corrige les chemins crate-root/visibilités et le warning Clippy de la canarie publique. +`pre.009` matérialise le runtime concret, le canal latest-value et les chemins d'annulation/drainage. Le gate opérateur exécute avec succès les 47 unitaires et 10 canaries couvrant l'attente RPC de découverte, une future pré-Store longue, le drainage des candidats déjà admis, les listeners lents/indépendants, la rétention terminale et les arbitrations terminales. La qualité Rust reste néanmoins bloquée : `pre.009-fix.001` corrige les chemins crate-root/visibilités et le warning Clippy de la canarie publique, puis son gate révèle `E0423` sur la construction du fingerprint public opaque ; `pre.009-fix.002` corrige ce dernier point et reste à valider. - [ ] Annulation idempotente et état `Cancelling` observable. - [ ] Admissions arrêtées après observation du token. @@ -209,8 +209,9 @@ Aucune entrée absolue, traversée, avec séparateur inversé ou lien symbolique - [X] Versions/features auditées : aucune nouvelle version externe ; `sha2`, `futures-util` et `tokio` réutilisent les entrées workspace existantes. `futures-util` reste un détail normal privé depuis `pre.008` et `pre.009` promeut Tokio en dépendance normale privée limitée à `macros` + `sync`; aucun type Tokio n'est exposé. - [X] `pre.005` matérialise 11 tests unitaires et 6 canaries d’intégration ; le gate opérateur les exécute tous avec succès. - [X] `pre.006` matérialise 19 tests unitaires et 7 canaries d’intégration ; le gate opérateur les exécute tous avec succès, avec uniquement le warning Clippy corrigé par `pre.006-fix.001`. -- [X] `pre.009` : `cargo check --workspace` vert et 47 unitaires + 10 canaries vertes ; Clippy signale 3 warnings de normalisation/API de test, corrigés par `pre.009-fix.001` mais encore à revalider. +- [X] `pre.009` : `cargo check --workspace` vert et 47 unitaires + 10 canaries vertes ; Clippy signale 3 warnings de normalisation/API de test, corrigés par `pre.009-fix.001`; le gate de ce fix révèle ensuite `E0423`, corrigé par `pre.009-fix.002` et encore à revalider. - [X] Audit manuel `pre.009-fix.001` : les items partagés de `ksp-job-backfill-lib` passent par `crate::Item`; `BackfillRuntimeControl`/`TerminalClaim` restent privés et les unit tests runtime utilisent `super::Item`, conformément à RUST-IMPORT-009/012 et RUST-API-007. +- [ ] `pre.009-fix.002` : `E0423` corrigé en confinant la construction du champ privé dans `BackfillScopeFingerprint::from_bytes`; gate opérateur Rust à rejouer. - [ ] `cargo fmt --all -- --check` vert. - [X] `scripts/audit_rust_workspace_rules.py` vert sur `pre.005` dans l'environnement d'assemblage et dans le gate opérateur. - [X] `scripts/audit_markdown_tables.py` vert sur `pre.005` dans le gate opérateur (264 tables / 147 fichiers, delta inclus). @@ -234,3 +235,4 @@ Aucune entrée absolue, traversée, avec séparateur inversé ou lien symbolique ## 16. Règle de vérité Une case n'est cochée que par une preuve effectivement exécutée ou un audit effectivement réalisé. L'absence de `cargo`, de PostgreSQL configuré ou d'accès live est rapportée comme non exécutée ; elle n'est jamais convertie en succès implicite. +