ki-fwi/docs/adr/0004-filieres-assets-a-b.md

# ADR 0004 — Deux filières d'assets : vérité et décor

- **Statut :** accepté
- **Date :** 2026-07-27
- **Session :** 0 — cadre et données

## Contexte

Le pack d'origine prévoyait de générer l'intégralité des visuels du jeu — 76 images — par
diffusion (SDXL / FLUX via ComfyUI), puis de passer directement à la production.

C'est une contradiction avec le but du jeu. Un enfant qui apprend à reconnaître un
corossol sur une image générée n'apprend pas à reconnaître un corossol : il apprend à
reconnaître ce qu'un modèle de diffusion produit quand on lui demande un corossol. Sur les
espèces peu représentées dans les jeux d'entraînement — le zikak, la quenette, le cachiman
cœur-de-bœuf, la pomme-liane — le modèle ne refuse pas : il produit un fruit **plausible
et faux**. C'est le pire des deux mondes, parce que l'erreur est invisible à qui ne connaît
pas déjà l'espèce.

Cette session a produit une illustration involontaire du même problème côté sources
réelles : parmi les photographies que Wikimedia Commons remonte pour *Melicoccus bijugatus*
(la quenette), l'un des premiers résultats est une photographie de **singe capucin**
mangeant le fruit. Aucune machine — moteur de recherche ou modèle génératif — ne peut
tenir lieu de validation botanique.

## Décision

Deux filières, deux régimes, jamais mélangés.

| Filière | Contenu | Source autorisée | Rôle |
|---|---|---|---|
| **A — Vérité** | fruit, coupe, feuille, écorce, port de l'arbre | photographie réelle : Commons, iNaturalist, herbier, appareil du porteur | tout ce qui sert à **identifier** — épreuves, indices, fiches |
| **B — Décor** | fonds, personnages, UI, sprites arcade, badges, écrans de titre | génération IA (ComfyUI / FLUX) | tout ce qui **ne sert pas** à identifier |

### Une troisième catégorie découverte en session 0

Les fonds Commons contiennent beaucoup de **planches botaniques anciennes** — Blanco,
Merian, Köhler, domaine public, exactes et magnifiques. Elles ne sont ni des photographies
ni des images générées. Le schéma les distingue donc explicitement :

```
type_media : "photo" | "planche_botanique" | "image_generee"
```

Une planche botanique **documente** une fiche encyclopédique. Elle ne peut **pas** porter
une épreuve d'identification : une gravure au trait rehaussée n'entraîne pas l'œil à
reconnaître un fruit posé sur une table de marché.

### Le champ `usages` et la porte

Chaque média déclare où il est employé : `epreuve`, `indice`, `fiche`, `decor`. Les deux
premiers sont les usages **identifiants**. Un média identifiant doit satisfaire les quatre
conditions, vérifiées par script :

1. `filiere: "A"` ;
2. `type_media: "photo"` ;
3. `valide: true`, avec un `valide_par` nommé — une validation anonyme n'engage personne ;
4. `vue` renseignée.

## Conséquences

- `npm run validate:data` fait échouer le build sur toute violation. `npm run test:porte`
  rejoue les neuf cas interdits et vérifie que le refus se produit — une règle qu'on n'a
  jamais vue refuser quelque chose est une intention, pas une règle.
- **Tout média sort de l'ingestion avec `valide: false`.** Aucun agent, aucun script, aucun
  modèle ne peut passer ce champ à `true`. La validation se fait par comparaison à au moins
  deux photographies de référence, idéalement contresignée par quelqu'un qui connaît :
  TRAMIL, un enseignant de SVT, un agriculteur, une grand-mère.
- Le pipeline de génération (filière B) vit dans `tools/assets/`, hors du bundle, avec son
  propre `requirements.txt`. Il est piloté **hors ligne, au build** (playbook P2). Aucun
  appel réseau ne subsiste au runtime du jeu.
- Les défauts du script du pack d'origine sont corrigés en session 3 :
  `hash()` de Python est randomisé par exécution (`PYTHONHASHSEED`), donc les seeds annoncés
  comme reproductibles ne le sont pas — utiliser `zlib.crc32(clé.encode()) & 0xFFFFFFFF` ;
  `copy.deepcopy` au lieu de `json.loads(json.dumps(...))` ; et vérifier la licence des
  **poids** du modèle `rembg`, qui ne suit pas nécessairement la licence MIT du paquet.

## Alternative écartée

**Générer les visuels d'identification et les faire valider a posteriori.** Le pack le
proposait implicitement. Le problème n'est pas la validation, c'est le coût de l'erreur non
détectée : un validateur non spécialiste confirmera un corossol plausible. La photographie
supprime la question.