feat(migration): Phase 4-bis — diagnostic + aliases ArtifactType préparatoires

Tentative de migration coordonnée de l'ArtifactType (debloqueur
des 13 mesures legacy + 6 modules core/) — diagnostic posé,
exécution reportée à un sprint dédié.

Stratégie testée
================

Exploiter le mécanisme natif d'aliases d'Enum Python : un membre
avec la même valeur qu'un autre devient un alias. Ajout au
domain.artifacts.ArtifactType :

- TEXT = "raw_text" (alias de RAW_TEXT)
- ALTO = "alto_xml" (alias de ALTO_XML)
- PAGE = "page_xml" (alias de PAGE_XML)

Plus un hook _missing_ qui accepte les valeurs string legacy
(ArtifactType("text") retourne RAW_TEXT, etc.).

Création de domain/module_protocol.py avec BaseModule + ExecutionMode
canoniques (le rewrite a aussi ses Protocols spécialisés
BaseOCRAdapter/BaseLLMAdapter/BaseVLMAdapter dans adapters/ ;
BaseModule reste le contrat générique pour modules tiers).

Tentative reportée
==================

Transformer core/modules.py en shim qui ré-exporte ArtifactType +
BaseModule depuis le canonique a cassé 27 tests legacy (Sprint 63
pipeline runner, Sprint 65 pipeline comparison, Sprint 68 HTML).

Diagnostic
==========

Le legacy core.results.BenchmarkResult.junction_metrics est un
dict[str, dict] indexé par ArtifactType.value. Quand
core.modules.ArtifactType est passé au superset canonique,
ArtifactType.TEXT.value passe silencieusement de "text" à
"raw_text". Les dicts produits par le runner sont alors indexés
par "raw_text", mais les tests cherchent encore la clé "text".

Conséquence : la migration de core.modules.ArtifactType n'est PAS
un simple rename. Elle implique une coordination avec :

- core/results.py (BenchmarkResult — 30 champs agrégés indexés)
- core/pipeline.py (junction_metrics)
- measurements/runner/* (orchestrateur legacy)
- measurements/pipeline_benchmark.py + pipeline_comparison.py

Ces modules indexent des dicts par valeur string ArtifactType, un
couplage implicite invisible à l'audit initial.

Conservé en place
=================

- domain/artifacts.py : aliases TEXT/ALTO/PAGE + _missing_.
Inoffensif — aucun caller legacy ne les voit. Préparation pour
la session future qui complétera Phase 4-bis.
- domain/module_protocol.py : BaseModule canonique défini. Pas
encore consommé par les sous-classes legacy (qui continuent à
hériter de core.modules.BaseModule original).

Tracker mis à jour
==================

docs/migration/legacy-retirement-plan.md documente :
- la tentative et son revert,
- le diagnostic du couplage dicts-string,
- le plan rectifié pour Phase 4-bis (25-30 j vs 18-22 estimés —
le couplage n'avait pas été vu à l'audit).

Validation
==========

- pytest tests/ : 5019 passed (état pré-tentative restauré).
- pytest -m regression : 16 passed.
- Test architectural test_no_legacy_imports_in_rewrite : 3 passed.
- ruff check : clean.

Phase 5 (22 renderers HTML) reste possible en parallèle, indépendante
de Phase 4-bis. Ou poursuivre les phases plus petites
(Phase 6/7/8).

docs/migration/legacy-retirement-plan.md

@@ -278,6 +278,59 @@ legacy reste vert.  Les 13 modules réels + 6 modules `core/`
 restants sont documentés comme dépendant d'une migration
 ArtifactType.
 
+#### Tentative Phase 4-bis (avortée — diagnostic posé)
+
+Une tentative de migration coordonnée de l'``ArtifactType`` a été
+explorée puis revertée :
+
+**Stratégie testée** : exploiter le mécanisme natif d'aliases
+d'``Enum`` Python (un membre avec la même valeur qu'un autre devient
+un alias).  Ajout de ``TEXT = "raw_text"``, ``ALTO = "alto_xml"``,
+``PAGE = "page_xml"`` à ``domain.artifacts.ArtifactType`` + hook
+``_missing_`` pour accepter les valeurs string legacy.  Puis
+transformation de ``core/modules.py`` en shim qui ré-exporte
+``ArtifactType`` et ``BaseModule`` depuis le canonique.
+
+**Conservé en place** : les aliases + ``_missing_`` dans
+``domain.artifacts.ArtifactType``.  Inoffensif — aucun code legacy
+ne les voit puisqu'aucun module legacy n'importe encore depuis le
+canonique.
+
+**Reverté** : le shim ``core/modules.py``.  Cause : passer le
+``core.modules.ArtifactType`` du legacy enum 6 valeurs au superset
+canonique change silencieusement ``ArtifactType.TEXT.value`` de
+``"text"`` à ``"raw_text"``.  Or 27 tests legacy
+(``test_sprint63_pipeline_runner``, ``test_sprint65_pipeline_comparison``,
+``test_sprint68_pipeline_comparison_html`` etc.) reposent sur le
+fait que les clés des dicts ``junction_metrics`` produites par le
+runner legacy sont les valeurs string legacy.  Quand le runner
+utilise ``at.value`` pour stocker, il stocke maintenant ``"raw_text"``,
+et les tests qui cherchaient ``junction_metrics["text"]`` cassent.
+
+Le diagnostic est plus profond qu'un simple rename : le legacy
+``BenchmarkResult.junction_metrics`` est un ``dict[str, dict]``
+indexé par valeur string ; sa stabilité de format est implicitement
+testée.  Migrer ``core.modules.ArtifactType`` exige un travail
+**par module** d'identification des dicts indexés par valeur
+string, et soit (a) double-clé pour rétrocompat, (b) migration
+ordonnée tests-en-même-temps.
+
+**Plan rectifié pour Phase 4-bis** :
+
+1. Lister exhaustivement les dicts indexés par ``ArtifactType.value``
+   dans le legacy (``core/results.py``, ``core/pipeline.py``,
+   ``measurements/runner/``, ``measurements/pipeline_*``).
+2. Décider la stratégie par module : double-clé pendant la
+   migration vs migration coordonnée tests + code.
+3. Migrer un cluster à la fois en validant la suite après chaque.
+
+**Effort rectifié** : 25-30 jours (vs 18-22 estimés initialement —
+le couplage implicite des dicts indexés par valeur string n'avait
+pas été vu à l'audit).
+
+**Statut Phase 4-bis** : analyse posée, exécution reportée à un
+sprint dédié de plusieurs sessions.
+
 ### Phase 5 — Reports HTML (`report/`)
 
 **Modules** :
@@ -465,7 +518,13 @@ mais le CER a glissé de 0,002 par doc »*.
 | 2 | ✅ Terminée (8/8 modules statistics migrés) |
 | 3 | ✅ Terminée (11 modules narrative + 2 templates + 18 détecteurs migrés) |
 | 4 | ✅ Partielle (9 modules autonomes/cascade ; 13 modules + 6 modules `core/` + 1 sous-package → Phase 4-bis) |
-| 4-bis | ⚪ À démarrer (migration ArtifactType + débloqueur des bloqués) |
+| 4-bis | 🟡 Diagnostic posé, exécution reportée (couplage dicts-string plus complexe que prévu — voir détail Phase 4) |
 | 5-11 | ⚪ À démarrer |
 
-**Dernière mise à jour** : 2026-05 (Phase 4 partielle livrée).
+**Dernière mise à jour** : 2026-05 (Phase 4-bis tentative + revert + diagnostic).
+
+**Reste en place suite à la tentative Phase 4-bis** : aliases
+``TEXT``/``ALTO``/``PAGE`` dans ``domain.artifacts.ArtifactType``
+(inoffensif) + hook ``_missing_`` pour accepter les valeurs string
+legacy.  Préparation pour la session future qui complétera Phase
+4-bis.

picarones/domain/artifacts.py

@@ -103,6 +103,36 @@ class ArtifactType(str, Enum):
     #: reliability diagram).
     CONFIDENCES = "confidences"
 
+    #: Aliases legacy pour rétrocompat avec ``picarones.core.modules``
+    #: (Phase 4-bis du retrait du legacy).  Le mécanisme natif d'Enum
+    #: Python rend ces noms équivalents aux canoniques :
+    #:
+    #: >>> ArtifactType.TEXT is ArtifactType.RAW_TEXT
+    #: True
+    #:
+    #: Le mapping sémantique TEXT → RAW_TEXT est documenté dans
+    #: ``docs/migration/regression-tolerances.md``.  À supprimer en 2.0
+    #: une fois tous les callers legacy retirés.
+    TEXT = "raw_text"
+    ALTO = "alto_xml"
+    PAGE = "page_xml"
+
+    @classmethod
+    def _missing_(cls, value):
+        """Accepte les valeurs string legacy (``"text"``, ``"alto"``,
+        ``"page"``) en plus des valeurs canoniques.
+
+        Ce hook est invoqué par ``ArtifactType("text")`` (lecture YAML
+        legacy par exemple) — sans lui, ``ValueError``.  À supprimer
+        en 2.0 avec les aliases legacy ci-dessus.
+        """
+        legacy_map = {
+            "text": cls.RAW_TEXT,
+            "alto": cls.ALTO_XML,
+            "page": cls.PAGE_XML,
+        }
+        return legacy_map.get(value)
+
 
 def compute_content_hash(payload: bytes) -> str:
     """SHA-256 hex (64 chars) d'un payload binaire.

picarones/domain/module_protocol.py

@@ -0,0 +1,139 @@
+"""``BaseModule`` — interface générique d'un module exécutable.
+
+Un module est une **fonction typée** d'artefacts vers artefacts.  Il
+déclare ce qu'il consomme (``input_types``) et ce qu'il produit
+(``output_types``), et expose une méthode ``process`` qui prend un
+dictionnaire d'entrées et retourne un dictionnaire de sorties.
+
+Usage minimal ::
+
+    class UpperCaseModule(BaseModule):
+        input_types = (ArtifactType.RAW_TEXT,)
+        output_types = (ArtifactType.RAW_TEXT,)
+        execution_mode = "cpu"
+
+        @property
+        def name(self) -> str:
+            return "uppercase"
+
+        def process(self, inputs):
+            txt = inputs[ArtifactType.RAW_TEXT]
+            return {ArtifactType.RAW_TEXT: txt.upper()}
+
+Ce module canonique (Phase 4-bis du retrait du legacy) est le
+remplacement de ``picarones.core.modules.BaseModule``.  Le shim
+legacy ``core/modules.py`` le ré-exporte pour la rétrocompat des
+~25 callers (engines, measurements, modules officiels, cli, web,
+report) qui le consomment.
+
+Le rewrite a aussi des protocols spécialisés
+(``BaseOCRAdapter``, ``BaseLLMAdapter``, ``BaseVLMAdapter`` dans
+``picarones.adapters``) qui sont des cas particuliers de
+``BaseModule`` typés pour leur domaine.  ``BaseModule`` reste le
+contrat **générique** pour les modules contribués par des tiers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Literal
+
+from picarones.domain.artifacts import ArtifactType
+
+ExecutionMode = Literal["io", "cpu"]
+
+
+class BaseModule(ABC):
+    """Interface générique pour tout module exécutable par le runner.
+
+    Un module est une fonction typée d'artefacts vers artefacts.  Il
+    déclare ce qu'il consomme et ce qu'il produit, et expose une
+    méthode ``process`` qui prend un dictionnaire d'entrées et
+    retourne un dictionnaire de sorties.
+
+    Attributs de classe (à surcharger en sous-classe)
+    -------------------------------------------------
+    input_types : tuple[ArtifactType, ...]
+        Types d'artefacts consommés par ``process``.  L'ordre n'a
+        pas de signification ; le runner passe un dictionnaire.
+    output_types : tuple[ArtifactType, ...]
+        Types d'artefacts produits par ``process``.  Tous les types
+        listés doivent être présents dans le dict retourné par
+        ``process`` (le runner valide).
+    execution_mode : ``"io"`` ou ``"cpu"``
+        Indique au runner quel exécuteur utiliser :
+        ``ThreadPoolExecutor`` pour les modules I/O-bound (API,
+        réseau), ``ProcessPoolExecutor`` pour les CPU-bound
+        (Tesseract, Pero).
+    """
+
+    input_types: tuple[ArtifactType, ...] = ()
+    output_types: tuple[ArtifactType, ...] = ()
+    execution_mode: ExecutionMode = "io"
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant unique et stable du module."""
+
+    @abstractmethod
+    def process(
+        self,
+        inputs: dict[ArtifactType, Any],
+    ) -> dict[ArtifactType, Any]:
+        """Exécute le module sur les artefacts d'entrée.
+
+        Parameters
+        ----------
+        inputs:
+            Dictionnaire ``{ArtifactType: payload}``.  Tous les types
+            déclarés dans ``input_types`` doivent être présents
+            (``validate_inputs`` peut être utilisé pour valider).
+
+        Returns
+        -------
+        dict[ArtifactType, Any]
+            Dictionnaire des sorties produites.  Tous les types
+            déclarés dans ``output_types`` doivent être présents.
+        """
+
+    def metadata(self) -> dict:
+        """Métadonnées libres exposées par le module.
+
+        Sous-classes peuvent surcharger pour exposer la version, la
+        license, la citation académique, etc.  Le runner inclut ce
+        dict dans le résultat afin que le rapport puisse l'afficher.
+        """
+        return {}
+
+    # ──────────────────────────────────────────────────────────────────
+    # Helpers de validation utilisés par le runner et les tests
+    # ──────────────────────────────────────────────────────────────────
+
+    def validate_inputs(self, inputs: dict[ArtifactType, Any]) -> None:
+        """Lève ``ValueError`` si un type d'entrée déclaré est manquant."""
+        missing = [t for t in self.input_types if t not in inputs]
+        if missing:
+            raise ValueError(
+                f"Module {self.name!r} : entrées manquantes "
+                f"{[t.value for t in missing]} (attendues : "
+                f"{[t.value for t in self.input_types]})",
+            )
+
+    def validate_outputs(self, outputs: dict[ArtifactType, Any]) -> None:
+        """Lève ``ValueError`` si un type de sortie déclaré est manquant."""
+        missing = [t for t in self.output_types if t not in outputs]
+        if missing:
+            raise ValueError(
+                f"Module {self.name!r} : sorties manquantes "
+                f"{[t.value for t in missing]} (déclarées : "
+                f"{[t.value for t in self.output_types]})",
+            )
+
+    def __repr__(self) -> str:
+        ins = ",".join(t.value for t in self.input_types) or "·"
+        outs = ",".join(t.value for t in self.output_types) or "·"
+        return f"{self.__class__.__name__}(name={self.name!r}, {ins}→{outs})"
+
+
+__all__ = ["ArtifactType", "BaseModule", "ExecutionMode"]