MaQI M3 — Data sources cartography (explore / validate / negotiate)

cosmon worker (maqi-m3-data-sources-86f5)

Idée — MaQI M3 : cartographie des sources de données

Statut : capturée (step 1/3 de idea-to-plan). Cette note documente l'idée et son intention. L'évaluation de faisabilité (step 2) et le plan actionnable (step 3) suivront dans ce même fichier, comme addenda.

1. Résumé en une phrase

Transformer le catalogue M1 (liste curée de providers) en une cartographie vivante et exploitable des sources de données MaQI, où chaque entrée porte un statut opérationnel (explorée, validée, à négocier) et une trace de ce qui manque pour passer à l'étape suivante.

2. Contexte (d'où vient l'idée)

Le sprint M1 (cf. docs/sprint/2026-04-14-maqi-sprint.md) a produit :

• une copie markdown versionnée des docs CAL (docs/cal/),
• un catalogue machine-lisible des providers nommés par CAL (docs/providers/catalog.yaml, 22 entrées à ce jour),
• une vue humaine du même catalogue (docs/providers/README.md).

Ce catalogue est une photographie d'intention : il dit ce que CAL a en tête. Il ne dit pas :

• ce que nous avons réellement téléchargé, validé, et relu,
• ce que nous avons vraiment essayé de négocier (et avec quel résultat),
• quelles sources sont utilisables pour tel ou tel livrable du Master (backtest, notebook pédagogique, démo Colab, article),
• quelles sources sont redondantes ou au contraire complémentaires,
• quels champs exacts sont couverts par quelle source (avec quelle fenêtre d'historique, quelle fréquence, quel périmètre géographique).

Autrement dit, M1 a posé l'inventaire. M3 doit poser la topographie opérationnelle qui lui donne sens.

3. Motivation

Trois forces poussent vers M3 dès maintenant :

1. Dette d'exploration. Plusieurs entrées du catalogue sont marquées to_document ou to_scrape sans que personne n'ait encore regardé ce qu'elles livrent réellement (ex. ICEYE, Quant Insight, Babbl, OpenInfraMap). Le coût marginal d'un premier regard est très faible ; le coût de ne pas regarder s'accumule à chaque décision d'achat.
2. Dette de validation. Nous avons reçu du S&P Global et un dump historique RavenPack (cf. docs/data-anomalies.md §2 : année 2020 manquante) sans relire en détail ce qui est utilisable. Tant que nous n'avons pas une carte validée des champs et des périodes couvertes, toute promesse de livrable est fragile.
3. Dette de négociation. Le sprint M1 liste sept providers to_negotiate (Databento, Premialab, SocGen Index, Macrobond, Turnleaf, Tradition Bond LOB, RavenPack). Sans cartographie commune, chaque négociation repart de zéro : on ne sait pas quel argument, quel contact, quel besoin rattacher à chaque demande. Charles-Albert absorbe implicitement cette mémoire, ce qui est à la fois fragile et peu scalable pour l'équipe.

4. Scope initial

Dans le scope

• Les providers déjà listés dans docs/providers/catalog.yaml (22 à ce jour). Chacun doit recevoir un dossier de cartographie dont la forme reste à définir (probablement un markdown par provider + des champs typés dans le YAML).

• Les trois axes opérationnels :

  • Explore : vérifier ce que la source livre réellement (format, fréquence, historique, volume, champs, points de contact, licence).
  • Validate : pour les sources déjà en notre possession (S&P Global, RavenPack dump, Databento NASDAQ), confronter ce qui a été annoncé à ce qui est réellement lisible depuis un notebook.
  • Negotiate : pour les sources to_buy / to_negotiate, maintenir une trace de négociation (qui a été contacté, quand, réponse, prochaine action, date d'échéance).
• Un statut opérationnel par provider, orthogonal au statut d'intention déjà présent (owned, free, to_buy, …) : not_started, explored, validated, in_negotiation, blocked, rejected.
• Un lien explicite entre cartographie et livrables du Master (Colab démo, notebooks pédagogiques, articles, backtest) — au moins sous forme de tags.

Hors scope (volontairement)

• Pas d'automatisation cron des tests d'accès (aucun scraping planifié pendant M3 — le scraping est lui-même une étape à tracer, pas à exécuter).
• Pas de mise en production dans le bucket S3/Wasabi/Backblaze (la piste technique CAL reste un sujet de sprint ultérieur, cf. docs/cal/tech-solutions.md).
• Pas de renégociation des contrats existants. Les contrats S&P Global en cours restent lus, pas rouverts.
• Pas de scraping de sites providers qui n'ont pas donné un accord explicite. La règle M1 (non-redistribution, respect des CGU) tient.
• Pas de modification des docs CAL source (rester fidèle à la règle gdrive \(\to\) repo, à sens unique).

5. Hypothèses de travail (à challenger en step 2)

6. Formes possibles du livrable (à arbitrer en step 3)

• Option A — Enrichissement du YAML. Ajouter à chaque entrée de catalog.yaml les champs operational_status, explore_notes, validate_notes, negotiate_log, linked_deliverables. Un seul fichier, machine-lisible, mais qui risque de devenir monolithique.
• Option B — Un markdown par provider. Créer docs/providers/<id>.md pour chaque provider, avec frontmatter typé et corps humain. Le YAML reste la table des matières. Plus verbeux mais plus lisible, et se prête à des notes longues.
• Option C — Vue-matrice croisée. Une seule page docs/providers/cartography.md qui croise {provider \(\times\) axe} avec statut + date de dernière action. Très dense, bien pour le pilotage, mais perd le détail narratif.

Les trois options ne sont pas exclusives. L'arbitrage step 3 décidera laquelle (ou quelle combinaison) devient le squelette et laquelle devient l'accessoire.

7. Critères de succès

M3 est terminé quand :

1. Chaque provider du catalogue M1 a un statut opérationnel et une dernière date de revue remplis, quel que soit le format retenu.
2. Au moins un livrable du Master (Colab démo, notebook, article) est explicitement rattaché à au moins une source validée, pour qu'on puisse dire : "ce livrable tient parce que cette source est utilisable".
3. Charles-Albert peut, en ouvrant le repo, corriger la cartographie sans avoir à demander un accès ou à lire un YAML.
4. L'équipe peut répondre, sans consulter CAL, à la question : "Cette source, on en est où ?"

8. Questions ouvertes (à traiter en step 2–3)

• Q1 : Où mettre les traces de négociation confidentielles (emails, prix, NDAs) ? Repo privé, coffre secret, ou juste des références anonymes depuis le repo ?
• Q2 : Qui pilote cette cartographie ? Si c'est un humain unique, c'est un SPOF. Si c'est l'équipe, il faut une convention d'édition (tags, revue, fréquence).
• Q3 : Quel est le critère d'« exploration suffisante » ? On ne veut pas passer deux jours sur ICEYE. Il faut un timebox par source et une checklist minimale.
• Q4 : Comment le statut opérationnel remonte-t-il dans STATUS.md (surface cosmon) ? Est-ce qu'un provider blocked doit générer un issue molécule automatiquement ?
• Q5 : Faut-il versionner le YAML enrichi ou le fragmenter tout de suite ?

9. Rattachement au sprint

Cette idée étend le sprint 2026-04-14-maqi au-delà du livrable M1. Elle ne remplace rien du M1 ; elle compose avec lui :

• M1 livre le squelette d'inventaire (catalog.yaml).
• M3 accroche la chair opérationnelle autour de ce squelette.

Les artefacts M1 restent intouchés tant que M3 n'a pas été validé.

10. Étapes suivantes (molécule)

• Step 2 — Évaluation de faisabilité : confronter les hypothèses H1–H5 et chiffrer le coût d'exploration par provider.
• Step 3 — Plan actionnable : décider du format (A/B/C), produire un ADR si nécessaire, et nucléer les enfants (warm) pour l'exécution effective.

Addendum step 2 — Évaluation de faisabilité

Ajouté le 2026-04-14 (step 2/3 de idea-to-plan). Cet addendum confronte les hypothèses H1–H5 du capture step, chiffre grossièrement le coût d'exploration par catégorie de provider, et tranche sur les trois options de livrable (A / B / C).

A. État de l'art repo (ce qui existe déjà)

Relecture des artefacts M1 et annexes :

• docs/cal/datasets-pipeline.md — 329 lignes, couvre 22 sources nommées par CAL, organisées en 6 sections : payées, gratuites-par-email, à acheter, à négocier, à scraper, à documenter.
• docs/cal/tech-solutions.md — 54 lignes, pose les contraintes techniques (non-redistribution, egress S3, séparation étudiants / chercheurs). Contraint directement ce que M3 peut exposer dans le repo.
• docs/providers/catalog.yaml — schéma typé, 22 providers, champs stables (id, category, status, cost_model, coverage, delivery, frequency, history, contract, notes, source). Chaque entrée pointe vers une ancre du doc CAL source.
• docs/providers/README.md — vue humaine, 225 lignes.
• docs/data-anomalies.md — connu du capture step pour l'anomalie RavenPack 2020 et le lot Databento NASDAQ.
• docs/adr/INDEX.md — un seul ADR existant (001 — réconciliation des données primaires), le mode d'écriture ADR est donc déjà installé.

Implication : M3 n'a pas besoin d'inventer un format. Il doit composer avec ce qui existe (YAML stable + markdown humain + ADR pour les décisions structurantes).

B. Confrontation des hypothèses H1–H5

C. Typologie effective (4 classes, coût décroissant)

La relecture du catalogue fait émerger 4 classes de providers qui ne coûtent pas la même chose à documenter :

1. Classe I — owned, needs validation (5 entrées). S&P Global Compustat, Transcripts, GICRS, ESG Physical Risk, Panjiva. Coût unitaire : 2–4 h (décompression, inspection de schéma, lecture de la licence, sample d'un enregistrement dans un notebook).
2. Classe II — owned legacy, needs verification (2 entrées). Dump RavenPack (trou 2020), lot Databento NASDAQ. Coût unitaire : 1–2 h (vérifier ce qu'on a, compléter les anomalies connues).
3. Classe III — public URL, needs lightweight exploration (8 entrées). MarineTraffic, IMF PortWatch, OpenInfraMap, ICIS, EuropeanReports, Ardian/Artefact (notebook Colab + HF dataset), Babbl, Quant Insight, Brain Company, NewMark. Coût unitaire : 15–30 min (ouvrir la page, lire le about, screenshot, noter CGU/licence, statut explored).
4. Classe IV — opaque / contact-only, needs email log (7 entrées). TheForecastingMachine, Shipfix, SpaceKnow, Databento négociation, Premialab, SocGen Index, Macrobond, Turnleaf, Tradition Bond LOB, RavenPack flux, ICEYE. Coût unitaire : 5 min d'écriture + N jours d'attente (juste maintenir le log de négociation).

Coût total estimé :

Lecture : M3 est faisable par un humain en une semaine-équivalent si les flux Xpressfeed sont accessibles depuis une machine locale. La partie "attente négociations" (classe IV) est asynchrone et ne bloque pas les autres classes.

D. Contraintes dures (à respecter sans discussion)

Issues de docs/cal/tech-solutions.md + règle M1 :

• C1 — Non-redistribution. Aucun contenu de provider payé ne peut être committé dans le repo (même un sample). La validation doit produire un résumé (schéma, compte de lignes, fenêtre temporelle), pas un extrait.
• C2 — Pas d'édition upstream. Les docs CAL gdrive restent intouchés. Les retours CAL passent par ce repo, pas par le .docx.
• C3 — Pas de scraping actif. M3 documente la possibilité de scraper (classe III), il ne scrape pas. Exécution réelle = sprint ultérieur + accord explicite.
• C4 — Pas de secret dans git. Confirmé par H5 : prix, NDAs, drafts email \(\to\) hors repo. Pointeurs opaques uniquement.
• C5 — Idempotence des sync. Tout script doit rester idempotent (règle M1, cf. sync-cal-docs.sh). Corollaire pour M3 : si on extrait quelque chose automatiquement, l'extraction doit être ré-exécutable sans casser la main-curation.

E. Arbitrage A / B / C

Re-confrontation des trois options de livrable du capture step, à la lumière de B–D :

• Option A (YAML monolithique enrichi) :

  • ✅ Machine-lisible, déjà en place, facile à grep.
  • ❌ Devient illisible pour des notes libres de classe I ou logs de classe IV.
  • ❌ Un seul fichier = conflits de merge quand plusieurs molécules l'éditent en parallèle.
  • Verdict : garder comme squelette, ne pas en faire le livrable principal.

• Option B (un markdown par provider) :

  • ✅ Chaque provider devient une unité éditable indépendante.
  • ✅ Permet des notes longues pour classe I, des logs datés pour classe IV, des screenshots pour classe III.
  • ✅ Pas de conflit de merge, chaque molécule enfant édite un fichier distinct.
  • ❌ 22 fichiers d'un coup, il faut un index pour naviguer.
  • Verdict : livrable principal.

• Option C (matrice croisée unique) :

  • ✅ Vue de pilotage pour Emmanuel / CAL en un coup d'œil.
  • ✅ Naturellement projetable dans STATUS.md via cosmon.
  • ❌ Perd le détail narratif.
  • Verdict : vue dérivée, générée/maintenue à la main à partir du YAML.

Décision retenue : B (principal) + A (squelette enrichi) + C (vue dérivée). Les trois se complètent et aucun ne remplace les autres. Ce trio sera validé par un ADR en step 3.

F. Risques et parades

G. Verdict global

M3 est faisable en une semaine-équivalent de travail humain actif, sous deux conditions :

1. Accès local aux flux Xpressfeed déjà livrés par S&P Global (sinon la classe I bascule hors scope et l'effort tombe à \(\approx\) 7 h).
2. Acceptation du format B + A + C (un .md par provider, le YAML comme squelette enrichi, une matrice dérivée).

Les hypothèses H1, H2, H3, H5 tiennent moyennant raffinement (voir ci-dessus). H4 (lecture seule) est à affaiblir : la validation classe I / II demande un micro-pipeline d'ingest, pas de la simple lecture.

Go pour step 3. Le plan actionnable doit :

• Trancher avec un ADR-002 sur le format (B + A + C).
• Nucléer (warm) une molécule enfant par classe, pas une par provider, pour éviter l'inflation du backlog.
• Isoler la dépendance infrastructure (accès local Xpressfeed) comme un préalable explicite, pas un implicite.
• Garder le sprint M1 immuable : M3 écrit à côté, pas par-dessus.

Addendum step 3 — Plan actionnable

Ajouté le 2026-04-14 (step 3/3 de idea-to-plan). Cet addendum fige les décisions sous forme de plan exécutable, liste les molécules enfants nucléées (toutes temp:warm), et verrouille les préalables d'infrastructure.

1. Décisions figées

• Format cartographie : B (un markdown par provider) + A (squelette YAML enrichi) + C (matrice dérivée cartography.md). Consigné dans ADR-002.
• Squelette markdown imposé : frontmatter typé + sections Explore / Validate / Negotiate / Decisions. Cf. ADR-002 §2.
• Découpage en 4 molécules enfants : une par classe de coût (I, II, III, IV), pas une par provider. Cf. ADR-002 §4.
• Contraintes non-négociables : C1–C5 (non-redistribution, pas de secret, gdrive read-only, pas de scraping actif, idempotence). Cf. ADR-002 §3.

2. Préalables d'infrastructure

Avant de pouvoir tackle la classe I, il faut :

• P1 — Accès local aux flux Xpressfeed S&P Global. Sans cet accès, task-m3-class-1 bascule en blocked dès son ouverture. La parade est de nucléer quand même la molécule, et de laisser la première action de son worker être la vérification d'accès. Si l'accès est absent, le worker la marque blocked et documente ce qui manque.

Les classes II, III, IV n'ont pas de préalable dur et peuvent être tackle-ées immédiatement.

3. Molécules enfants à nucléer (toutes temp:warm)

Chaque enfant est une molécule task-… avec la formule par défaut (tackle-verify-done), scopée à une classe et paramétrée par la liste explicite des providers à traiter. Tags obligatoires : maqi, m3, data-sources, temp:warm.

Chaque enfant porte les tags temp:warm, maqi, m3, data-sources, et class:<i|ii|iii|iv>. Tous sont auto-liés à cette idée via un edge DecayedFrom/DecayProduct.

Note : la classe III telle que nucléée inclut ICEYE, Brain Company, NewMark Risk et Quant Insight bien qu'ils soient classés to_document dans le catalogue. Ce sont tous des sites publics documentables en lecture, donc bien classe III (pas IV) pour la cartographie. Le YAML les gardera en to_document tant qu'une décision d'achat / scrape n'aura pas été prise.

Chaque molécule enfant doit, à sa clôture :

1. Avoir créé les docs/providers/<id>.md pour tous les providers de sa classe (squelette minimum : frontmatter + section Explore non vide).
2. Avoir enrichi chaque entrée YAML correspondante avec operational_status, last_reviewed, detail_doc, linked_deliverables (liste vide acceptable au démarrage).
3. Avoir mis à jour docs/providers/cartography.md avec la ligne correspondant à sa classe.
4. Porter le tag temp:warm dès la nucléation (contrainte formula idea-to-plan).

4. Commande de nucléation

Les enfants seront nucléés par ce worker à la fin de ce step, via :

cs nucleate task --var topic="MaQI M3 classe I — validate owned S&P Global feeds" \
  --var scope="M3/class-I" --var parent="idea-20260414-86f5"
# puis tag immédiatement :
cs tag task-<id> --add temp:warm
cs tag task-<id> --add maqi
cs tag task-<id> --add m3
cs tag task-<id> --add data-sources

(Commande réelle exécutée plus bas, capturée dans la sortie du worker et dans les commits d'état cosmon.)

5. Livrables du step 3

Au moment de cs complete pour cette molécule :

• [x] docs/adr/002-data-sources-cartography.md créé.
• [x] docs/adr/INDEX.md mis à jour avec ADR-002.
• [x] Cet addendum ajouté à la note d'idée.
• [x] Les 4 molécules enfants nucléées et taguées temp:warm : task-20260414-90f9 (classe I), task-20260414-abab (II), task-20260414-a6df (III), task-20260414-653e (IV).

6. Ce qui ne fait PAS partie du plan

• Pas de création des 22 markdown docs/providers/<id>.md ici — c'est le travail des molécules enfants.
• Pas de modification du docs/providers/catalog.yaml pour y injecter operational_status globalement — chaque enfant enrichira les entrées qui la concernent.
• Pas de création immédiate de docs/providers/cartography.md — il sera créé par la première molécule enfant qui se termine, puis mis à jour incrémentalement par les suivantes.
• Pas de projection dans STATUS.md — listée en action à envisager de l'ADR-002, relève d'un sprint outillage ultérieur.

7. Critère de complétion de l'idée

idea-20260414-86f5 est cs complete quand :

• ADR-002 accepté et indexé ✓
• Ce fichier contient l'addendum step 3 ✓
• Les 4 molécules enfants existent et portent temp:warm (vérifié par cs ensemble --tag temp:warm | grep task-m3-class-) — à faire juste après ce commit.