khadhroony-solana-project/docs/validation/023-V0_3_6_JOB_API_BACKFILL.md

Validation v0.3.6 — Job API et premier backfill RAW

1. Statut de pre.001

• Archive v0.3.5 testée intégralement avant extraction.
• Archive kbot3 testée intégralement et isolée de l'arbre source KSP.
• Noms d'entrées contrôlés contre chemins absolus, traversées et liens symboliques ZIP.
• Règles canoniques, architecture, roadmap, changelog et deltas antérieurs lus.
• Surfaces Core, Transport et Store réelles auditées.
• Documentation officielle Solana des deux appels RPC auditée.
• kbot3 utilisé uniquement comme référence fonctionnelle et corpus de scénarios.
• Matrice reprendre, redessiner, reporter ou rejeter consignée.
• Ownership, limites, notifications, retry, annulation, provenance et checkpoint décidés.
• Plan découpé en tranches atomiques de 15 à 20 minutes.
• Aucun code de crate, manifeste de crate ou test Rust généré en pre.001.
• 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

• scripts/audit_rust_workspace_rules.py : propre avant modification.
• scripts/audit_markdown_tables.py : 240 tables et 150 fichiers propres avant modification.
• Audits Rust workspace post-modification : propres, aucune crate Rust ajoutée.
• Audit Markdown post-modification complet hors deltas historiques antérieurs : 240 tables et 153 fichiers propres.
• Contrats et tailles des trois nouveaux fichiers vérifiés.
• Le journal opérateur fourni rapporte cargo fmt, audits, cargo check, cargo clippy et suites Interface ou Program verts sur v0.3.5.
• L'environnement courant ne fournit pas l'exécutable cargo ; aucune validation Rust locale n'est annoncée comme exécutée.
• Le workspace compte 14 crates et aucune crate Job au point de départ.

4. Autorités et cohérence documentaire

• RULES.md et la hiérarchie documentaire ont été appliqués.
• Les chemins canoniques réels sous docs/rules/ ont été retenus lorsque le prompt utilisait un chemin abrégé.
• Le nom fixé est ksp-job-backfill-lib.
• Les occurrences historiques de ksp-job-backfill sont identifiées pour réconciliation avant fermeture.
• ksp-job-api et ksp-job-backfill-lib sont obligatoires en parallèle dans la release finale.
• 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.
• 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.