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.
• Gate opérateur de pre.002 : cargo fmt, audits Rust/Markdown, cargo check --workspace et arbres Cargo normal/features verts.
• Échec de pre.002 constaté dans la preuve opérateur : Clippy --all-targets et les tests compilent unit_tests/lifecycle.rs, où le helper lifecycle() est masqué par une variable homonyme (E0618, puis E0282).
• pre.002-fix.001 renomme uniquement le helper en new_lifecycle() et synchronise ses six appels sans modifier le contrat public ni la matrice de transitions.
• Gate opérateur de pre.002-fix.001 : cargo fmt, audits Rust/Markdown, cargo check, Clippy, dix unitaires + onze canaries ksp-job-api, toutes les suites workspace, cargo test --workspace et arbres Cargo Job API verts.
• L'environnement d'assemblage ne fournit pas l'exécutable cargo ; aucune validation Rust locale de pre.003 ou de son fix n'est annoncée comme exécutée.
• Gate opérateur de pre.003 : cargo fmt, audits Rust/Markdown et cargo check --workspace verts ; Clippy --all-targets et cargo test -p ksp-job-api échouent uniquement sur E0423 dans le helper exhausted_notification_sequence().
• Les arbres Cargo normal/features de ce gate confirment que ksp-job-api dépend toujours uniquement de ksp-core-lib et n'ouvre aucune feature.
• pre.003-fix.001 remplace uniquement la construction via le re-export racine par le constructeur privé directement visible dans le module notification, sans changer l'API publique ni le nombre de tests.
• Gate opérateur de pre.003-fix.001 : cargo fmt, audits Rust/Markdown, cargo check, Clippy, treize unitaires + quatorze canaries ksp-job-api et arbres Cargo normal/features verts.
• pre.004 matérialise une voie observée additive de getTransaction sans modifier le client, les settings, le routage ni la politique de retry Transport ; gate opérateur vert.
• Le workspace comptait 14 crates avant pre.005; ksp-job-backfill-lib devient la 15e crate membre sans créer d'exécutable ni de Worker.
• Gate opérateur de pre.005 : cargo fmt, audits Rust/Markdown et cargo check --workspace verts ; les 11 tests unitaires et 6 canaries ksp-job-backfill-lib sont verts.
• Le même gate révèle un unique échec Clippy clippy::implicit_return dans la closure privée qui dérive le curseur before; les arbres Cargo normal/features sont néanmoins exécutés et cohérents avec le graphe prévu.
• pre.005-fix.001 ajoute uniquement le return explicite exigé dans cette closure et ne modifie ni valeur, ni pagination, ni identité réseau, ni dépendance, ni API publique.
• Gate opérateur de pre.005-fix.001 : cargo fmt, audits Rust/Markdown, cargo check, Clippy, 11 unitaires + 6 canaries ksp-job-backfill-lib et arbres Cargo normal/features verts sur 0.3.6-pre.5.fix.1.
• Versions d'en-tête du Cargo.toml racine et de discovery.rs corrigées dans la base opérateur avant pre.006.

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 documents d'architecture courants sont réconciliés sur ksp-job-backfill-lib; les anciens plans historiques restent historiques et ne sont pas réécrits.
• 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 identité, kind, séquence, état et snapshot complet ; son Debug masque le snapshot et le contrat impose au snapshot concret de rester sûr et borné.
• JobSnapshotSource permet lecture courante et attente abstraite d'une valeur plus récente sans callback producteur ni type Tokio public.
• Aucun type Transport, Store, Logging, Tokio, serde, Worker ou Backfill dans l'API publique de pre.003; le futur abstrait utilise uniquement std.
• Canaries externes de construction, lifecycle, annulation, notifications latest-value, firewalls, complétude et sécurité matérialisées.
• Dix unitaires et onze canaries de pre.002-fix.001 exécutés avec cargo test -p ksp-job-api par l'opérateur.

6. Notifications multi-listeners

pre.003 fige le contrat public et ses canaries de resynchronisation. pre.009 matérialise maintenant le producer concret ksp-job-backfill-lib avec un tokio::sync::watch privé, un handle clonable et des canaries latest-value ; leur gate Rust opérateur reste à rejouer, donc les critères comportementaux ci-dessous restent ouverts jusqu'à exécution.

• 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

pre.005 matérialise les contrats et leurs tests. Le gate du fix confirme les 11 unitaires et 6 canaries avec Clippy vert. L'identité candidate est (RawNetworkId, signature) ; rôle HTTP, provider, endpoint et protocole ne participent ni à cette identité ni au fingerprint sémantique du scope.

• LatestAddress, BeforeAddress, AfterAddress et ExplicitSignatures couverts.
• Adresse validée par le type Core existant.
• Signature Base58 décodée vers exactement 64 octets, prouvée par le gate pre.006-fix.002.
• 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 ; canarie pre.008-fix.001 exécutée avec succès.
• 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, confirmé par audit de source jusqu'à pre.008.
• Retour observé additif de getTransaction matérialisé et gate opérateur vert.
• Canarie déterministe : un 429 sur le premier endpoint reroute et rapporte le second provider/endpoint victorieux ; gate opérateur vert.
• HttpObservedValue<T> ne contient que valeur typée, endpoint sûr et provider ; URL, headers et body HTTP brut restent privés.
• Aucun retry, pacing ou sélection d'endpoint dans Job, confirmé par audit de source pre.008.
• Aucune détection d'erreur par chaîne dans la composition Backfill pre.008.
• Une erreur Transport finale arrête les admissions avec un code Job sûr ; exécuteur et test pre.008 matérialisés, gate opérateur à rejouer.

10. RAW v1 et provenance

pre.006 matérialise cette surface et ses tests statiques/unitaires. Le gate opérateur confirme les audits, cargo check, les 19 unitaires et les 7 canaries, mais Clippy émet clippy::large_enum_variant sur BackfillHydrationOutcome : Available(BackfillRawAcquisition) contient au moins 560 octets alors que Missing(reference) en contient environ 88. Le résultat fonctionnel est vert, mais la tranche n'est pas considérée warning-free.

pre.006-fix.001 conserve l'API publique de l'enum et introduit une seule indirection privée dans BackfillRawAcquisition. Aucun #[allow] n'est ajouté. Les getters et into_parts conservent leurs signatures, et une canarie vérifie que BackfillRawAcquisition reste de la taille d'un pointeur. Le gate opérateur du fix confirme ensuite les audits, cargo check, les 20 unitaires et les 7 canaries, mais Clippy signale encore deux clippy::explicit_auto_deref dans transaction() et observation().

pre.006-fix.002 remplace uniquement &(*self.inner).transaction et &(*self.inner).observation par les accès auto-deref idiomatiques &self.inner.transaction et &self.inner.observation. La Box privée unique, l'API publique et tous les invariants RAW/provenance restent inchangés. Le gate opérateur de fix.002 est intégralement vert : audits Rust/Markdown, cargo check, Clippy sans warning, 20 unitaires, 7 canaries d'intégration et arbres Cargo passent sur 0.3.6-pre.6.fix.2.

• Identité logique future auditée : transaction/signature scoping par RawNetworkId, jamais par rôle/provider/endpoint/protocole.
• Le Store PostgreSQL actuel est mono-réseau via ksp_store_identity; un futur backend multi-réseaux devra préserver (network, signature) par clé/partition équivalente.
• 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, couverte par le gate pre.006-fix.002.
• Endpoint différent produit une nouvelle observation légitime.

11. Persistance Store

pre.007 matérialise la composition Store normale sans élargir les responsabilités. Le chemin public consomme un BackfillHydrationOutcome, contrôle d'abord le réseau logique du Store, puis utilise exclusivement l'écriture atomique transaction + observation de ksp-store-lib. Missing ne déclenche aucune écriture. Un conflit de contenu Store est converti en outcome Backfill explicite afin que les tranches de frontier/snapshot puissent le compter puis le traiter comme trou/échec, sans le confondre avec l'idempotence. Le gate opérateur pre.007 est intégralement vert : audits, cargo check, Clippy sans warning, 29 unitaires, 8 canaries et arbres Cargo passent.

• Dépendance unique vers ksp-store-lib, jamais vers backend ou API directement, confirmée par audit de manifeste/source.
• Écriture atomique transaction plus observation composée en mode Normal dans l'unique chemin de persistance.
• Aucune prélecture de présence avant hydratation ou persistance.
• Entités insérée, déjà présente et purgée distinguées au gate Rust pre.007.
• Observations insérée, déjà présente et non enregistrée distinguées au gate Rust pre.007.
• getTransaction = null ne produit aucune écriture fabriquée au gate Rust pre.007.
• Conflit Store reste un outcome terminal visible, distinct d'un succès idempotent, au gate Rust pre.007.
• Même JobId et même endpoint donnent une relance idempotente au gate Rust pre.007.
• ForceRehydrate absent du chemin normal pre.007 par audit de source.

12. Concurrence, frontière et checkpoint

pre.008 matérialise un checkpoint opaque caller-owned, sans table Store ni promesse de reprise crash-safe. BackfillRequest::with_checkpoint valide JobId et fingerprint avant usage. L'exécuteur utilise une collection FuturesUnordered strictement bornée par hydration_concurrency, réconcilie les fins hors ordre par index stable et draine les futures déjà admises après la première erreur fatale. Le gate initial révèle uniquement un shadowing de helper dans une canarie ; pre.008-fix.001 le corrige sans changer le contrat. Le gate réduit du fix est intégralement vert : audits, cargo check, Clippy sans warning, 39 unitaires et 9 canaries d'intégration passent sur 0.3.6-pre.8.fix.1.

• Nombre d'hydratations en vol borné par la requête, prouvé par pre.008-fix.001.
• Aucune file de candidats non bornée dans l'exécuteur pre.008; les notifications concrètes restent à valider avec pre.009.
• 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 et Store créent un trou ; la branche annulation est matérialisée dans pre.009 et reste à exécuter.
• 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

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 ; son gate opérateur est désormais intégralement vert : audits, cargo check, Clippy sans warning, 47 unitaires et 10 canaries.

• Annulation idempotente et état Cancelling observable au gate pre.009-fix.002.
• Admissions arrêtées après observation du token au gate pre.009-fix.002.
• Attente de page et hydratation RPC longues abandonnables au gate pre.009-fix.002.
• Persistance déjà soumise drainée jusqu'à un résultat connu au gate pre.009-fix.002.
• Course complétion contre annulation déterministe au gate pre.009-fix.002.
• Course erreur fatale contre annulation déterministe au gate pre.009-fix.002.
• Missing seul donne Completed avec résultat Partial, couvert par le runtime/exécuteur validé pre.009-fix.002.
• Conflit, conversion ou infrastructure donnent Failed, couvert par le runtime/exécuteur validé pre.009-fix.002.
• Checkpoint final cohérent avec le dernier préfixe durable au gate pre.009-fix.002.

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 ; ksp-store-lib est consommée avec default-features = false.
• Aucun retour de dépendance vers Job depuis les couches basses ; canarie externe pre.010 exécutée avec succès.
• 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é.
• pre.005 matérialise 11 tests unitaires et 6 canaries d’intégration ; le gate opérateur les exécute tous avec succès.
• 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.
• pre.009 : après fix.001 puis fix.002, audits, cargo check, Clippy sans warning et 47 unitaires + 10 canaries sont verts sur 0.3.6-pre.9.fix.2.
• 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 intégralement vert.
• cargo fmt --all -- --check vert.
• scripts/audit_rust_workspace_rules.py vert sur pre.005 dans l'environnement d'assemblage et dans le gate opérateur.
• scripts/audit_markdown_tables.py vert sur pre.005 dans le gate opérateur (264 tables / 147 fichiers, delta inclus).
• Contrats de fichiers de FILE_CONTRACTS.md vérifiés sur chaque ajout de pre.001.
• cargo check --workspace vert sur pre.005; le fix ne change qu'une closure privée refusée par Clippy.
• 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.

Hardening externe pre.010

La tranche ajoute 9 canaries externes et une canarie de complétude, portant le total d'intégration à 20 sans modifier les 47 unitaires. Le gate opérateur est intégralement vert : audits Rust/Markdown, cargo check, Clippy sans warning, 47 unitaires et 20 canaries d'intégration passent sur 0.3.6-pre.10.

• Neuf codes d'erreur publics Backfill stables, uniques et dans le domaine job_backfill; canarie externe pre.010 verte.
• Signature Base58 hostile et bornes de requête invalides retournent les codes stables attendus ; canarie externe pre.010 verte.
• Fingerprint sensible au réseau mais indépendant du JobId et du rôle Transport ; canarie externe pre.010 verte.
• Debug des signatures/fingerprint/requête/handle ne révèle ni signature brute ni payload snapshot ; canarie externe pre.010 verte.
• Handle public créé en état Created, annulation acceptée une fois puis idempotemment rejetée ; canarie externe pre.010 verte.
• Surface de dépendances exacte et backend-neutral, avec Store façade default-features = false; canarie externe pre.010 verte.
• Surface source Backfill conforme aux chemins crate-root pour les items partagés et sans crate::module::Item; canarie externe pre.010 verte.
• Aucun retour des couches Core/Logging/Transport/Store vers Job ; canarie externe pre.010 verte.
• Façade publique sans fuite Tokio/Futures/Serde/Store backend/HTTP ; canarie externe pre.010 verte.

15. Gate technique final pre.011

pre.011 n'ajoute aucun code, test fonctionnel, manifeste de crate, dépendance, README/USAGE, CHANGELOG/ROADMAP ni prompt suivant. Il synchronise uniquement workspace.package.version, le plan, la validation et son delta afin de rejouer la preuve technique finale sur la surface pre.010 déjà durcie.

Matrice opérateur attendue :

cargo fmt --all -- --check
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 --all-features -- -D warnings
cargo test --workspace --all-targets --all-features

cargo tree -p ksp-job-api --edges normal
cargo tree -p ksp-job-api -e features
cargo tree -p ksp-job-backfill-lib --edges normal
cargo tree -p ksp-job-backfill-lib -e features
cargo tree --duplicates

Les arbres Cargo sont rejoués ici au titre de la clôture technique finale, même si pre.011 ne modifie aucune dépendance. Un cargo clean préalable reste optionnel et peut être utilisé par l'opérateur pour une reconstruction froide ; il n'est pas un prérequis de cargo tree.

Le smoke PostgreSQL reste conditionnel à une URI dédiée explicitement disponible. En l'absence d'environnement live fourni, il reste non exécuté et non bloquant ; aucune réussite live n'est inventée.

Statut : matérialisé ; gate opérateur final à exécuter.

16. Preuves d'intégration et fermeture

• Fake Transport et fake Store déterministes sans backend direct exécutés avec succès au gate pre.007; fake processor concurrent pre.008-fix.001 exécuté avec succès.
• 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.

17. 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.