ADR-001 : Réconciliation des données primaires

Statut

Accepté — 2026-04-09

Contexte

Le projet MaQI dépend de 4 jeux de données volumineux fournis sur disque externe : GDELT (48 Go), CausalityLink (190 Go), RavenPack (249 Go), Databento (1,4 To).

Ces données transitent par trois niveaux de stockage :

flowchart LR
    vendor["Vendor<br>(GDELT, Databento,<br>RavenPack, CausalityLink)"]
    disk["Disque externe<br>Seagate<br><i>(source primaire)</i>"]
    mac["Copie locale<br><i>(intermédiaire)</i>"]
    s3["Wasabi S3<br><i>(partagé équipe)</i>"]
    compute["Analyses<br>(Colab, notebooks)"]

    vendor -->|download| disk
    disk -->|rsync| mac
    mac -->|rclone sync| s3
    s3 -->|read| compute

    style vendor fill:#eef,stroke:#448
    style disk fill:#fed,stroke:#c60
    style mac fill:#dfd,stroke:#0a0
    style s3 fill:#ddf,stroke:#008
    style compute fill:#fdf,stroke:#808

À chaque étape de transfert, la question se pose : comment garantir que ce qui arrive est bien ce qui est parti ? Et en amont : ce qui est parti est-il intègre ?

Le rapport d'anomalies a révélé que certains jeux de données présentent des anomalies dès la source (fichiers manquants, versions divergentes). Ces anomalies doivent être traitées systématiquement, pas oubliées dans un coin.

Décision

Principe : vérification à chaque frontière

Tout transfert de données franchit une frontière. À chaque frontière, on vérifie l'intégrité du transfert avec les moyens disponibles.

flowchart LR
    A[Vendor] -.->|frontière 1| B[Disque]
    B -.->|frontière 2| C[Local]
    C -.->|frontière 3| D[S3]
    D -.->|frontière 4| E[Compute]

    A -.- v1["checksum vendor<br>ou inventaire"]
    B -.- v2["rsync -c<br>+ checksums"]
    C -.- v3["rclone sync<br>(hash intégré)"]
    D -.- v4["parsing +<br>validation schéma"]

    style v1 fill:#ffe,stroke:#cc0
    style v2 fill:#ffe,stroke:#cc0
    style v3 fill:#ffe,stroke:#cc0
    style v4 fill:#ffe,stroke:#cc0

Frontière	Méthode de vérification
Source (primaire)	Checksum fourni par le vendor si disponible, sinon inventaire de complétude
Disque \(\to\) Local	Comparaison de checksums après `rsync -c` ou scripts de vérification dédiés
Local \(\to\) S3	`rclone sync` avec vérification de taille et hash intégrée
S3 \(\to\) compute	Lecture à la demande, vérification de schéma et parsing

Checksums disponibles par source

Source	Référence fournie	Format	Algorithme
GDELT	Oui (`md5sums`, `filesizes`)	texte plat	MD5 + taille
Databento	Oui (`manifest.json` par lot)	JSON	SHA-256 + taille
RavenPack	Non	—	Comparaison de tailles uniquement
CausalityLink	Non	—	Comparaison `rsync -c` entre source et copie

Suivi des anomalies

Les anomalies détectées sont suivies comme issues GitHub sur le dépôt eserie/MaQI.

Chaque issue suit un cycle de vie simple en 4 étapes :

stateDiagram-v2
    direction LR
    [*] --> identify
    identify --> download : source localisée
    download --> verify : fichier téléchargé
    verify --> upload : checksum OK
    verify --> identify : checksum KO
    upload --> [*] : fichier sur S3

Étape	Description
`identify`	Localiser la source (URL vendor, contact)
`download`	Télécharger le fichier
`verify`	Vérifier l'intégrité (checksum, taille)
`upload`	Pousser sur Wasabi S3

Chaque membre de l'équipe peut consulter l'état des anomalies directement sur GitHub, commenter, s'assigner une issue, ou la fermer quand le fichier est récupéré et uploadé sur S3.

Idempotence et reprise

Tous les outils de transfert sont idempotents :

rsync --partial --append : reprise automatique après interruption
rclone sync : compare hash avant transfert, saute les fichiers inchangés

Une commande peut être relancée en toute sécurité. L'état reste cohérent.

Ce que ce n'est pas

Ce n'est pas un système de reconciliation continue ou de validation applicative. C'est un contrôle d'intégrité des transferts.
Ce n'est pas une validation de schéma ou de qualité sémantique. Un fichier peut être intègre (checksum OK) et contenir des données aberrantes. La validation sémantique est un sujet distinct, à traiter au niveau du code de traitement.

Conséquences

Positives

Les anomalies de données deviennent visibles et traçables via GitHub Issues
Les membres de l'équipe peuvent reprendre une anomalie partiellement traitée grâce au suivi par étapes
Les ré-exécutions sont sûres — on peut relancer un pipeline complet sans crainte de doublons ou corruption

Négatives

RavenPack et CausalityLink ne fournissent pas de checksums, la vérification est plus faible (tailles seulement pour RavenPack, comparaison coûteuse pour CausalityLink)

Action à envisager

Demander à RavenPack et CausalityLink s'ils peuvent fournir un manifest de checksums pour leurs futurs livrables
Générer et archiver nos propres checksums après validation de la copie locale, pour servir de référence future