v0.3.6-pre.001

docs/validation/023-V0_3_6_JOB_API_BACKFILL.md

@@ -0,0 +1,188 @@
+<!-- file: docs/validation/023-V0_3_6_JOB_API_BACKFILL.md -->
+<!-- version: 1 -->
+
+# Validation v0.3.6 — Job API et premier backfill RAW
+
+## 1. Statut de `pre.001`
+
+- [X] Archive v0.3.5 testée intégralement avant extraction.
+- [X] Archive kbot3 testée intégralement et isolée de l'arbre source KSP.
+- [X] Noms d'entrées contrôlés contre chemins absolus, traversées et liens symboliques ZIP.
+- [X] Règles canoniques, architecture, roadmap, changelog et deltas antérieurs lus.
+- [X] Surfaces Core, Transport et Store réelles auditées.
+- [X] Documentation officielle Solana des deux appels RPC auditée.
+- [X] kbot3 utilisé uniquement comme référence fonctionnelle et corpus de scénarios.
+- [X] Matrice reprendre, redessiner, reporter ou rejeter consignée.
+- [X] Ownership, limites, notifications, retry, annulation, provenance et checkpoint décidés.
+- [X] Plan découpé en tranches atomiques de 15 à 20 minutes.
+- [X] Aucun code de crate, manifeste de crate ou test Rust généré en `pre.001`.
+- [X] Version workspace ouverte en `0.3.6-pre.1`.
+
+## 2. Preuve des archives d'entrée
+
+| Archive | SHA-256 | Résultat ZIP | Usage |
+| --- | --- | --- | --- |
+| `khadhroony-solana-project-v0.3.5-thelatest1.zip` | `c395efb6a09c786069aa5063a7a414b55f8ae24e2b9d6eaa414b2f312cd62588` | 1 515 entrées, test intégral propre | Source exclusive de code |
+| `khadhroony-bot3_v0.5.3-pre.005-fix010-thelatest1.zip` | `ee47643b9f8b582ee8db97b2381ec107e45aef8c009fee44757531514615d318` | 2 501 entrées, test intégral propre | Référence fonctionnelle isolée |
+| `Texte collé.txt` | `0b86c7107349bcbf0a80319ba8cf9aabdd2809f27af9459592667f3e425e8d58` | Sans objet | Journal opérateur v0.3.5 |
+
+Aucune entrée absolue, traversée, avec séparateur inversé ou lien symbolique ZIP n'a été trouvée dans les deux archives.
+
+## 3. Baseline v0.3.5 observée
+
+- [X] `scripts/audit_rust_workspace_rules.py` : propre avant modification.
+- [X] `scripts/audit_markdown_tables.py` : 240 tables et 150 fichiers propres avant modification.
+- [X] Audits Rust workspace post-modification : propres, aucune crate Rust ajoutée.
+- [X] Audit Markdown post-modification complet hors deltas historiques antérieurs : 240 tables et 153 fichiers propres.
+- [X] Contrats et tailles des trois nouveaux fichiers vérifiés.
+- [X] Le journal opérateur fourni rapporte `cargo fmt`, audits, `cargo check`, `cargo clippy` et suites Interface ou Program verts sur v0.3.5.
+- [X] L'environnement courant ne fournit pas l'exécutable `cargo` ; aucune validation Rust locale n'est annoncée comme exécutée.
+- [X] Le workspace compte 14 crates et aucune crate Job au point de départ.
+
+## 4. Autorités et cohérence documentaire
+
+- [X] `RULES.md` et la hiérarchie documentaire ont été appliqués.
+- [X] Les chemins canoniques réels sous `docs/rules/` ont été retenus lorsque le prompt utilisait un chemin abrégé.
+- [X] Le nom fixé est `ksp-job-backfill-lib`.
+- [X] Les occurrences historiques de `ksp-job-backfill` sont identifiées pour réconciliation avant fermeture.
+- [X] `ksp-job-api` et `ksp-job-backfill-lib` sont obligatoires en parallèle dans la release finale.
+- [X] Worker API, application et pipeline RAW partagé sont explicitement hors v0.3.6.
+- [ ] Architecture, README, roadmap et contrats finaux réconciliés avant publication.
+
+## 5. Contrat `ksp-job-api`
+
+- [ ] `JobId` borné, validé et opaque.
+- [ ] `JobKindCode` stable et sans texte humain libre.
+- [ ] Transitions `Created`, `Running`, `Cancelling`, `Completed`, `Cancelled` et `Failed` contrôlées.
+- [ ] États terminaux immuables et résultat complet ou partiel explicite.
+- [ ] `JobCancellationToken` cloneable, idempotent et sans Tokio public.
+- [ ] `JobNotificationSequence` strictement monotone avec overflow traité sans panic.
+- [ ] `JobNotification<S>` contient un snapshot complet, sûr et borné.
+- [ ] `JobSnapshotSource` permet lecture courante et attente de changement sans callback producteur.
+- [ ] Aucun type Transport, Store, Logging, Tokio ou serde dans l'API publique.
+- [ ] Canaries externes de construction, observation et annulation vertes.
+
+## 6. Notifications multi-listeners
+
+- [ ] Stockage O(1) de la dernière valeur, sans historique non borné.
+- [ ] Un listener lent ne bloque jamais le producteur.
+- [ ] Plusieurs listeners progressent indépendamment.
+- [ ] Une séquence manquée se résout par resynchronisation du snapshot courant.
+- [ ] L'abandon ou l'échec d'un listener n'affecte pas le Job.
+- [ ] Le snapshot terminal reste disponible tant que le handle existe.
+- [ ] Aucun secret, URL, body RPC, liste massive ou message fournisseur n'est exposé.
+
+## 7. Admission et portées
+
+- [ ] `LatestAddress`, `BeforeAddress`, `AfterAddress` et `ExplicitSignatures` couverts.
+- [ ] Adresse validée par le type Core existant.
+- [ ] Signature Base58 décodée vers exactement 64 octets.
+- [ ] Engagement limité à `Confirmed` ou `Finalized`.
+- [ ] Taille de page entre 1 et 1 000.
+- [ ] Nombre de pages entre 1 et 10 000.
+- [ ] Nombre de candidats entre 1 et 10 000.
+- [ ] Concurrence d'hydratation entre 1 et 64.
+- [ ] `min_context_slot` transmis sans en changer le sens.
+- [ ] Checkpoint rejeté si son JobId ou son fingerprint de scope diffère.
+- [ ] Aucun défaut d'application silencieux dans la bibliothèque.
+
+## 8. Pagination, ordre et déduplication
+
+- [ ] Latest respecte l'ordre officiel du plus récent au plus ancien.
+- [ ] Before utilise une ancre exclusive et avance vers l'historique plus ancien.
+- [ ] After atteint l'ancre, garde les plus proches candidats plus récents et produit un ordre déterministe.
+- [ ] Ancre before absente acceptée comme curseur.
+- [ ] Ancre after non atteinte bornée et signalée comme résultat partiel.
+- [ ] Doublons inter-pages retirés à première occurrence.
+- [ ] Doublons explicites retirés sans réordonner la liste.
+- [ ] Limites de pages et candidats respectées sur tous les chemins.
+
+## 9. Acquisition Transport et retry
+
+- [ ] Les wrappers typés officiels restent l'unique chemin RPC.
+- [ ] Retour observé additif de `getTransaction` couvert.
+- [ ] Fournisseur et endpoint rapportés correspondent au succès réel après reroutage.
+- [ ] URL, headers et body brut restent privés.
+- [ ] Aucun retry, pacing ou sélection d'endpoint dans Job.
+- [ ] Aucune détection d'erreur par chaîne.
+- [ ] Une erreur Transport finale arrête les admissions avec un code Job sûr.
+
+## 10. RAW v1 et provenance
+
+- [ ] Format `ksp.solana.raw_transaction`, version `1`, figé.
+- [ ] `getTransaction` demandé en `base64` avec version maximale `0`.
+- [ ] Bytes JSON compacts déterministes et golden tests stables.
+- [ ] Transaction binaire conservée sans décodage métier.
+- [ ] `meta`, `version` et `transactionIndex` distinguent absent, `null` et valeur.
+- [ ] Slot et block time non dupliqués dans le payload.
+- [ ] Block time négatif rejeté explicitement.
+- [ ] Hash SHA-256 et taille calculés sur les bytes exacts.
+- [ ] Provenance contient fournisseur, protocole, méthode, endpoint sûr, engagement et réception.
+- [ ] Clé d'observation domain-separated et déterministe.
+- [ ] Endpoint différent produit une nouvelle observation légitime.
+
+## 11. Persistance Store
+
+- [ ] Dépendance unique vers `ksp-store-lib`, jamais vers backend ou API directement.
+- [ ] Écriture atomique transaction plus observation en mode `Normal`.
+- [ ] Aucune prélecture de présence avant hydratation.
+- [ ] Entités insérée, déjà présente et purgée distinguées.
+- [ ] Observations insérée, déjà présente et non enregistrée distinguées.
+- [ ] `getTransaction = null` ne produit aucune écriture fabriquée.
+- [ ] Conflit Store reste une erreur terminale visible.
+- [ ] Même JobId et même endpoint donnent une relance idempotente.
+- [ ] `ForceRehydrate` inaccessible depuis le chemin normal.
+
+## 12. Concurrence, frontière et checkpoint
+
+- [ ] Nombre d'hydratations en vol borné par la requête.
+- [ ] Aucune file de candidats ou notifications non bornée.
+- [ ] Résultats hors ordre réconciliés par index stable.
+- [ ] Frontière avance sur insert, already present et purged skip durables.
+- [ ] Missing, conflit, conversion, Transport, Store et annulation créent un trou.
+- [ ] Frontière ne saute jamais un trou même si des résultats ultérieurs terminent.
+- [ ] Latest rejoue la vue courante de façon idempotente.
+- [ ] Before reprend au curseur contigu.
+- [ ] After et explicite rejouent le scope borné avec préfixe validé.
+
+## 13. Annulation et résultats terminaux
+
+- [ ] Annulation idempotente et état `Cancelling` observable.
+- [ ] Admissions arrêtées après observation du token.
+- [ ] Attente de page et hydratation RPC longues abandonnables.
+- [ ] Persistance déjà soumise drainée jusqu'à un résultat connu.
+- [ ] Course complétion contre annulation déterministe.
+- [ ] Course erreur fatale contre annulation déterministe.
+- [ ] Missing seul donne `Completed` avec résultat `Partial`.
+- [ ] Conflit, conversion ou infrastructure donnent `Failed`.
+- [ ] Checkpoint final cohérent avec le dernier préfixe durable.
+
+## 14. Firewalls et qualité Rust
+
+- [ ] `ksp-job-api` ne dépend au plus que de Core.
+- [ ] `ksp-job-backfill-lib` ne dépend pas de Config, App, Wallet, Program, Interface ou backend Store.
+- [ ] Aucun retour de dépendance vers Job depuis les couches basses.
+- [ ] Versions et features des nouvelles dépendances auditées avant ajout.
+- [ ] `cargo fmt --all -- --check` vert.
+- [ ] `scripts/audit_rust_workspace_rules.py` vert.
+- [ ] `scripts/audit_markdown_tables.py` vert.
+- [X] Contrats de fichiers de `FILE_CONTRACTS.md` vérifiés sur chaque ajout de `pre.001`.
+- [ ] `cargo check --workspace` vert.
+- [ ] `cargo clippy --workspace --all-targets --all-features -- -D warnings` vert.
+- [ ] `cargo test --workspace --all-targets --all-features` vert.
+- [ ] `cargo tree -d` examiné et doublons justifiés.
+
+## 15. Preuves d'intégration et fermeture
+
+- [ ] Fake Transport et fake Store déterministes sans backend direct.
+- [ ] Vertical découverte, hydratation, conversion, persistance et observation couvert.
+- [ ] Smoke Devnet plus PostgreSQL configuré exécuté si l'environnement explicite est disponible.
+- [ ] Aucun endpoint payant, credential ou donnée sensible requis par les tests normaux.
+- [ ] Gates technique, documentaire et de publication séparés.
+- [ ] CHANGELOG et ROADMAP alignés seulement après preuve technique.
+- [ ] Archives de release minimales et vérifiées.
+- [ ] Version stable publiée uniquement après tous les critères obligatoires.
+
+## 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.