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 et de son fix

• 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.
• Sizing converti en sous-sections ### pre.NNN et #### pre.NNN-fix.MMM.
• Faux négatif du validateur Markdown reproduit avec une ligne séparatrice espacée.
• Reconnaissance des séparateurs plausibles corrigée avant validation d'alignement.
• Alignements gauche, droit et centré reliés aux marqueurs de la ligne séparatrice.
• Cinq tests de régression positifs et négatifs ajoutés au validateur.
• Treize documents durables révélés par le validateur corrigé réalignés mécaniquement.
• Audit général corrigé : 264 tables et 141 fichiers propres.
• Anciens deltas publiés laissés byte-inchangés.
• Version workspace du correctif d'outillage synchronisée en 0.3.6-pre.1.fix.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.
• Le résultat historique 240 tables / 150 fichiers est identifié comme incomplet : les séparateurs espacés n'étaient pas reconnus.
• Audits Rust workspace post-modification : propres, aucune crate Rust ajoutée.
• Le résultat historique 240 tables / 153 fichiers de pre.001 est identifié comme faux positif pour les nouveaux tableaux non alignés.
• 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.
• Gate opérateur de pre.001-fix.001 : 5 tests Python, audit Markdown 264/141, audit Rust et cargo check --workspace verts.
• 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é à 128 octets, validé, opaque et redacted en Debug.
• JobKindCode stable, borné et limité à l'alphabet sûr KSP.
• JobCompletion distingue Complete et Partial sans texte libre.
• Transitions Created, Running, Cancelling, Completed, Cancelled et Failed contrôlées.
• États terminaux immuables et lifecycle producteur non cloneable.
• JobCancellationToken cloneable, idempotent, Send + Sync 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, serde, Worker ou Backfill dans l'API publique de pre.002.
• Canaries externes de construction, lifecycle, annulation, firewalls, complétude et sécurité matérialisées.
• Dix unitaires et onze canaries Rust exécutés avec cargo test -p ksp-job-api par l'opérateur.

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 dépend exactement de Core et n'a aucune feature, dev-dependency ou build-dependency.
• 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 sur pre.002 dans l'environnement d'assemblage.
• scripts/audit_markdown_tables.py vert sur pre.002 dans l'environnement d'assemblage.
• 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.