refactor(audit): Phase 7 — unifier doublons (PipelineMode + path helpers + engine list)

Trois factorisations identifiées par l'audit code-quality.

**7.1 — ``PipelineMode`` Literal unifié**

Avant : 3 définitions identiques mais indépendantes :

- ``picarones.pipeline.llm_pipeline_config.OCRLLMMode``
- ``picarones.pipeline.llm_pipeline_builder.OCRLLMPipelineMode``
- ``picarones.interfaces.web.models.PipelineMode``

Risque : si l'une ajoute un mode (par exemple ``"hybrid"``), les
deux autres divergent silencieusement et un payload Pydantic
``PipelineConfig.pipeline_mode = "hybrid"`` passe l'API web mais
plante côté pipeline.

Refactor :

- Nouvelle source de vérité unique :
``picarones.domain.pipeline_spec.PipelineMode`` (couche 1).
- Les 3 sites historiques deviennent des **alias importés** —
préserve les imports existants sans casser l'API publique.

Test ajouté : ``tests/domain/test_pipeline_mode_single_source.py``
(4 tests) — vérifie la définition canonique, l'égalité des alias,
**et** scan AST pour interdire toute future redéfinition d'un
``Literal["text_only", "text_and_image", "zero_shot"]`` hors du
module canonique.

**7.2 — Validation de chemin utilisateur centralisée**

Pattern dupliqué dans 3 routers web :

.. code-block:: python

try:
resolved = validated_path(
user_path,
allowed_roots=compute_workspace_roots(UPLOADS_DIR),
must_exist=False,
)
except PathValidationError as exc:
raise HTTPException(status_code=400, detail=str(exc)) from exc

Factorisé en deux helpers dans
``picarones/interfaces/web/_path_helpers.py`` :

- ``validated_user_path(user_path, *, must_exist, must_be_dir) -> Path``
- ``validated_user_output_dir(user_path) -> str`` (alias sémantique
avec ``must_exist=False`` pour les ``output_dir``).

Sites migrés :

- ``routers/importers.py`` (helper local ``_validated_output_dir``
devient un alias vers ``validated_user_output_dir``).
- ``routers/history.py`` (validation inline → ``validated_user_path``).
- ``routers/benchmark.py`` conservé tel quel : il groupe 3
validations distinctes dans un seul try/except (corpus_path +
output_dir + prompt_file), la factorisation gagne peu.

Bénéfice : 4 imports d'utilitaires bas-niveau retirés
(``PathValidationError``, ``validated_path``, ``compute_workspace_roots``,
``UPLOADS_DIR``) dans ``importers.py`` et ``history.py``.

**7.3 — Liste engines : garde-fou d'alignement**

Le router ``/api/engines`` énumère manuellement les engines OCR
(``check_engine("tesseract", ...)`` + ``cloud_ocr_specs``). La
factory ``picarones.adapters.ocr.factory._SUPPORTED`` est la source
de vérité canonique. Risque de drift : un nouvel engine ajouté
côté factory sans MAJ du router → endpoint manque l'info ; ou
l'inverse → frontend affiche un engine non instanciable.

Refonte forcée non viable (le router consomme des métadonnées —
label humain, env var — que la factory ne fournit pas). À la
place, garde-fou actif :

Test ajouté : ``tests/web/test_engines_router_alignment.py``
(2 tests) — scan AST du router, extrait les ``engine_id`` cités
dans ``check_engine(...)`` et ``cloud_ocr_specs``, vérifie qu'ils
sont tous dans ``_SUPPORTED``. Vérifie aussi le contenu minimal
de ``_SUPPORTED`` (8 engines canoniques).

**Bilan**

Suite : 4 800 passed, 16 skipped, 8 deselected, 2 xfailed.
+6 tests (4 PipelineMode + 2 engine alignment). Ruff propre,
sync-counters CI vert.

Couvre 3 des findings « duplications » majeurs identifiés par
l'audit. Restent en Phase 7 : ``BaseOCRAdapter`` template-method
(8 adapters OCR qui se recopient ~250 LOC chacun) et ``BaseRenderer``
pour les 28 renderers HTML — chantiers plus ambitieux à traiter
dans des PRs dédiés.

CLAUDE.md

@@ -116,7 +116,7 @@ picarones/
 
 ## État des tests et bugs historiques
 
-`pytest tests/` → **4750 passed, 16 skipped, 8 deselected, 2 xfailed, 0 failed**
+`pytest tests/` → **4800 passed, 16 skipped, 8 deselected, 2 xfailed, 0 failed**
 (post-audit code-quality, mai 2026).  Les deselected sont les markers
 `live` (5 tests d'intégration contre vraie API/binaire) + `network`
 (3 tests qui hit le réseau réel), opt-in en local via `pytest -m live`

README.md

@@ -401,7 +401,7 @@ python -m mypy picarones/domain/    # strict mode (Layer 1)
 python -m mypy picarones/           # lax mode (full tree)
 ```
 
-**Test suite**: ~4750 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4800 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when

picarones/app/services/benchmark_runner.py

@@ -1189,7 +1189,7 @@ def run_benchmark_via_service(
 # et ``_aggregate_ner_metrics`` restent ici comme alias pour ne pas
 # casser les appels internes (les autres fonctions du runner s'y
 # réfèrent) et les tests qui patchent ces symboles via monkeypatch.
-from picarones.app.services._benchmark_ner import (
+from picarones.app.services._benchmark_ner import (  # noqa: F401
     aggregate_ner_metrics as _aggregate_ner_metrics,
     attach_ner_metrics_to_benchmark as _attach_ner_metrics_to_benchmark,
 )

picarones/domain/pipeline_spec.py

@@ -54,6 +54,7 @@ Anti-sur-ingénierie
 from __future__ import annotations
 
 import re
+from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -64,6 +65,23 @@ from picarones.domain.artifacts import ArtifactType
 #: lisible par un humain dans les logs et le rapport.
 _STEP_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 
+#: Modes canoniques d'un pipeline OCR+LLM.  Source de vérité unique
+#: depuis la Phase 7.1 audit code-quality (2026-05) — auparavant
+#: dupliqué trois fois (``pipeline/llm_pipeline_config.py:25``,
+#: ``pipeline/llm_pipeline_builder.py:61``,
+#: ``interfaces/web/models.py:71``), avec un risque concret de
+#: divergence si l'un des trois ajoutait un nouveau mode.
+#:
+#: Sémantique :
+#:
+#: - ``text_only`` — l'OCR amont produit un texte brut, le LLM le
+#:   corrige sans voir l'image (post-correction texte pur).
+#: - ``text_and_image`` — l'OCR amont produit un texte ; le VLM le
+#:   corrige en s'appuyant sur l'image (post-correction multimodale).
+#: - ``zero_shot`` — pas d'OCR amont ; un VLM transcrit l'image
+#:   directement.
+PipelineMode = Literal["text_only", "text_and_image", "zero_shot"]
+
 #: Sentinel pour ``inputs_from`` qui désigne les artefacts initiaux
 #: fournis au runner (typiquement ``IMAGE``).
 INITIAL_STEP_ID = "__initial__"
@@ -178,4 +196,4 @@ class PipelineSpec(BaseModel):
         return None
 
 
-__all__ = ["PipelineStep", "PipelineSpec", "INITIAL_STEP_ID"]
+__all__ = ["PipelineMode", "PipelineSpec", "PipelineStep", "INITIAL_STEP_ID"]

picarones/interfaces/web/_path_helpers.py

@@ -0,0 +1,101 @@
+"""Helpers de validation de chemin partagés par les routers FastAPI.
+
+Phase 7.2 audit code-quality (2026-05) — le pattern :
+
+.. code-block:: python
+
+    try:
+        resolved = validated_path(
+            user_path,
+            allowed_roots=compute_workspace_roots(UPLOADS_DIR),
+            must_exist=False,
+        )
+    except PathValidationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+était dupliqué dans :
+
+- ``routers/importers.py:45`` (``_validated_output_dir``)
+- ``routers/history.py:53-60`` (inline)
+- ``routers/benchmark.py:104-115`` (2 appels successifs)
+
+Factorisé ici en deux fonctions :
+
+- :func:`validated_user_path` — un chemin, retourne ``str``.
+- :func:`validated_user_output_dir` — alias sémantique avec
+  ``must_exist=False`` par défaut (le ``output_dir`` peut être créé
+  ultérieurement par le worker).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import HTTPException
+
+from picarones.app.services.path_security import (
+    PathValidationError,
+    validated_path,
+)
+from picarones.interfaces.web.security import compute_workspace_roots
+from picarones.interfaces.web.state import UPLOADS_DIR
+
+
+def validated_user_path(
+    user_path: str,
+    *,
+    must_exist: bool = False,
+    must_be_dir: bool = False,
+) -> Path:
+    """Valide un chemin utilisateur contre les racines workspace.
+
+    Wrapper FastAPI autour de :func:`validated_path` : convertit
+    ``PathValidationError`` en ``HTTPException(400)`` pour que le
+    client reçoive un 400 lisible plutôt qu'un 500 stacktrace.
+
+    Parameters
+    ----------
+    user_path:
+        Chaîne fournie par le client (corps JSON, query param,
+        form field, etc.).
+    must_exist:
+        Si ``True``, refuse un chemin qui n'existe pas.  Utile pour
+        les inputs ; mettre à ``False`` pour les outputs (le worker
+        créera le répertoire).
+    must_be_dir:
+        Si ``True``, refuse un fichier (n'accepte que les dossiers).
+
+    Returns
+    -------
+    Path
+        Chemin canonique résolu (relatif à une racine workspace).
+
+    Raises
+    ------
+    HTTPException(400)
+        Si le chemin n'est pas dans une racine autorisée, contient
+        ``..`` ou un symlink hors workspace, etc.
+    """
+    try:
+        return validated_path(
+            user_path,
+            allowed_roots=compute_workspace_roots(UPLOADS_DIR),
+            must_exist=must_exist,
+            must_be_dir=must_be_dir,
+        )
+    except PathValidationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+def validated_user_output_dir(user_path: str) -> str:
+    """Variante sémantique pour les ``output_dir`` des importers.
+
+    Équivalente à ``str(validated_user_path(user_path, must_exist=False))``.
+    Préserve la signature historique de ``_validated_output_dir``
+    qui retournait une ``str`` (les backends consommateurs n'attendent
+    pas un ``Path``).
+    """
+    return str(validated_user_path(user_path, must_exist=False))
+
+
+__all__ = ["validated_user_path", "validated_user_output_dir"]

picarones/interfaces/web/models.py

@@ -68,23 +68,11 @@ Liste alignée sur ``measurements.normalization.NORMALIZATION_PROFILES``
 répercutée ici sous peine de rejet Pydantic au niveau API web.
 Sprint A14-S1 — alignement README ↔ web models ↔ runtime."""
 
-PipelineMode = Literal["text_only", "text_and_image", "zero_shot"]
-"""Modes de pipeline OCR+LLM acceptés par ``PipelineConfig``.
-
-Aligné sur :class:`picarones.pipeline.llm_pipeline_config.OCRLLMMode` —
-toute valeur hors de ces 3 littéraux est rejetée 422 par Pydantic.
-
-Sémantique :
-
-- ``text_only`` — l'OCR amont produit un texte brut, le LLM le corrige
-  sans voir l'image (post-correction texte).
-- ``text_and_image`` — l'OCR amont produit un texte ; le VLM le corrige
-  en s'appuyant sur l'image (post-correction multimodale).
-- ``zero_shot`` — pas d'OCR amont ; un VLM transcrit l'image directement.
-
-Phase 2 du chantier post-rewrite : suppression du fallback silencieux
-``mode_map.get(comp.pipeline_mode, 'text_only')`` qui acceptait toute
-chaîne arbitraire et la mappait sur ``text_only``."""
+# Phase 7.1 audit code-quality (2026-05) : ``PipelineMode`` est désormais
+# importé depuis :data:`picarones.domain.pipeline_spec.PipelineMode`
+# (source de vérité unique).  L'alias local préserve l'API publique
+# de ce module pour les callers historiques.
+from picarones.domain.pipeline_spec import PipelineMode  # noqa: E402
 
 
 # ``BenchmarkRequest`` (mode legacy à liste de moteurs plats) a été

picarones/interfaces/web/routers/history.py

@@ -23,13 +23,6 @@ from typing import Any, Optional
 
 from fastapi import APIRouter, HTTPException, Query
 
-from picarones.interfaces.web.security import (
-    PathValidationError,
-    compute_workspace_roots,
-    validated_path,
-)
-from picarones.interfaces.web.state import UPLOADS_DIR
-
 router = APIRouter()
 _logger = logging.getLogger(__name__)
 
@@ -50,15 +43,13 @@ async def api_history_regressions(
     from picarones.evaluation.metrics.history import BenchmarkHistory
 
     if db_path:
-        try:
-            resolved = validated_path(
-                db_path,
-                allowed_roots=compute_workspace_roots(UPLOADS_DIR),
-                must_exist=False,
-            )
-        except PathValidationError as exc:
-            raise HTTPException(status_code=400, detail=str(exc)) from exc
-        effective_db_path: Optional[str] = str(resolved)
+        # Phase 7.2 audit code-quality : helper centralisé pour la
+        # validation chemin → HTTPException 400.
+        from picarones.interfaces.web._path_helpers import validated_user_path
+
+        effective_db_path: Optional[str] = str(
+            validated_user_path(db_path, must_exist=False),
+        )
     else:
         env_db = os.environ.get("PICARONES_HISTORY_DB", "").strip()
         effective_db_path = env_db or None

picarones/interfaces/web/routers/importers.py

@@ -7,12 +7,6 @@ import os
 from fastapi import APIRouter, HTTPException, Query
 
 from picarones.interfaces.web.models import HTRUnitedImportRequest, HuggingFaceImportRequest
-from picarones.interfaces.web.security import (
-    PathValidationError,
-    compute_workspace_roots,
-    validated_path,
-)
-from picarones.interfaces.web.state import UPLOADS_DIR
 
 router = APIRouter()
 
@@ -42,23 +36,14 @@ def _htr_united_catalogue():
     return HTRUnitedCatalogue.from_remote(timeout=5)
 
 
-def _validated_output_dir(user_path: str) -> str:
-    """Valide ``output_dir`` reçu d'un importer contre les racines workspace.
-
-    Les endpoints d'import écrivent un corpus distant sur le filesystem
-    du serveur — un ``output_dir`` libre permet d'écrire arbitrairement
-    (path traversal). On valide ici contre :func:`compute_workspace_roots`
-    avant de passer la chaîne au backend.
-    """
-    try:
-        resolved = validated_path(
-            user_path,
-            allowed_roots=compute_workspace_roots(UPLOADS_DIR),
-            must_exist=False,
-        )
-    except PathValidationError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    return str(resolved)
+# Phase 7.2 audit code-quality (2026-05) : la fonction
+# ``_validated_output_dir`` (helper local historique) est désormais
+# importée depuis ``interfaces/web/_path_helpers.py`` sous le nom
+# ``validated_user_output_dir`` (factorisation de 3 sites web).  Alias
+# conservé pour ne pas casser les usages locaux.
+from picarones.interfaces.web._path_helpers import (
+    validated_user_output_dir as _validated_output_dir,
+)
 
 
 # ──────────────────────────────────────────────────────────────────────────

picarones/pipeline/llm_pipeline_builder.py

@@ -46,19 +46,19 @@ Le runtime résout les ``adapter_name`` en instances via le
 
 from __future__ import annotations
 
-from typing import Literal
-
 from picarones.domain.artifacts import ArtifactType
 from picarones.domain.errors import PicaronesError
 from picarones.domain.pipeline_spec import (
     INITIAL_STEP_ID,
+    PipelineMode as OCRLLMPipelineMode,
     PipelineSpec,
     PipelineStep,
 )
 
 
-#: Modes supportés — alignés sur ``picarones.pipelines.base.PipelineMode``.
-OCRLLMPipelineMode = Literal["text_only", "text_and_image", "zero_shot"]
+# Phase 7.1 audit code-quality (2026-05) : ``OCRLLMPipelineMode`` est
+# désormais un alias de ``picarones.domain.pipeline_spec.PipelineMode``
+# importé en tête de fichier — plus de définition locale.
 
 
 def make_ocr_llm_pipeline_spec(

picarones/pipeline/llm_pipeline_config.py

@@ -20,9 +20,12 @@ Attributs exposés
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Literal
+from typing import Any
 
-OCRLLMMode = Literal["text_only", "text_and_image", "zero_shot"]
+# Phase 7.1 audit code-quality (2026-05) : alias historique conservé
+# pour les callers existants ; la source de vérité unique vit
+# désormais dans :data:`picarones.domain.pipeline_spec.PipelineMode`.
+from picarones.domain.pipeline_spec import PipelineMode as OCRLLMMode
 
 
 @dataclass(frozen=True)

tests/domain/test_pipeline_mode_single_source.py

@@ -0,0 +1,127 @@
+"""Phase 7.1 audit code-quality (2026-05) — ``PipelineMode`` doit
+avoir **une seule** définition canonique : :data:`picarones.domain.pipeline_spec.PipelineMode`.
+
+Avant la Phase 7.1 :
+
+- ``picarones.pipeline.llm_pipeline_config.OCRLLMMode`` :
+  ``Literal["text_only", "text_and_image", "zero_shot"]``
+- ``picarones.pipeline.llm_pipeline_builder.OCRLLMPipelineMode`` :
+  idem (redéfini)
+- ``picarones.interfaces.web.models.PipelineMode`` : idem (redéfini)
+
+Trois définitions identiques mais indépendantes — risque concret de
+divergence si l'une ajoute un mode (par exemple ``"hybrid"``) sans
+mettre à jour les deux autres.
+
+Refactor : ``domain/pipeline_spec.py`` (couche 1) accueille la
+définition canonique ; les trois alias historiques (OCRLLMMode,
+OCRLLMPipelineMode, PipelineMode) deviennent des re-exports pour
+préserver les imports existants.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import get_args
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SOURCE = REPO_ROOT / "picarones"
+
+
+def test_pipeline_mode_canonical_definition_exists() -> None:
+    """La définition canonique vit dans ``domain/pipeline_spec.py``."""
+    from picarones.domain.pipeline_spec import PipelineMode
+
+    args = set(get_args(PipelineMode))
+    assert args == {"text_only", "text_and_image", "zero_shot"}, (
+        f"PipelineMode canonique doit valoir exactement les 3 littéraux "
+        f"canoniques.  Reçu : {args}"
+    )
+
+
+def test_pipeline_mode_aliases_are_identical() -> None:
+    """Chaque alias historique pointe vers la même valeur Literal."""
+    from picarones.domain.pipeline_spec import PipelineMode as canonical
+    from picarones.interfaces.web.models import PipelineMode as web_alias
+    from picarones.pipeline.llm_pipeline_builder import OCRLLMPipelineMode as builder_alias
+    from picarones.pipeline.llm_pipeline_config import OCRLLMMode as config_alias
+
+    canonical_args = set(get_args(canonical))
+    for alias_name, alias in [
+        ("interfaces.web.models.PipelineMode", web_alias),
+        ("pipeline.llm_pipeline_builder.OCRLLMPipelineMode", builder_alias),
+        ("pipeline.llm_pipeline_config.OCRLLMMode", config_alias),
+    ]:
+        alias_args = set(get_args(alias))
+        assert alias_args == canonical_args, (
+            f"Alias {alias_name} diverge du canonique : "
+            f"{alias_args} != {canonical_args}.  Vérifier que l'alias "
+            f"importe bien ``PipelineMode`` depuis ``domain/pipeline_spec``."
+        )
+
+
+def test_no_independent_literal_definition_in_codebase() -> None:
+    """Aucun fichier du code source (hors ``domain/pipeline_spec``)
+    ne doit redéfinir ``Literal["text_only", "text_and_image", "zero_shot"]``.
+
+    Scan AST.  Refuse toute occurrence d'une annotation de type
+    ``Literal[...]`` qui contient ces 3 chaînes — sauf dans le module
+    canonique.
+    """
+    canonical_strings = frozenset({"text_only", "text_and_image", "zero_shot"})
+    canonical_file = SOURCE / "domain" / "pipeline_spec.py"
+
+    offenders: list[tuple[str, int]] = []
+    for path in SOURCE.rglob("*.py"):
+        if path == canonical_file or "__pycache__" in path.parts:
+            continue
+        text = path.read_text(encoding="utf-8")
+        try:
+            tree = ast.parse(text)
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            # Cherche ``X = Literal["a", "b", ...]`` ou
+            # ``foo: Literal["a", "b", ...]`` partout.
+            if not isinstance(node, ast.Subscript):
+                continue
+            val = node.value
+            if not (
+                (isinstance(val, ast.Name) and val.id == "Literal")
+                or (isinstance(val, ast.Attribute) and val.attr == "Literal")
+            ):
+                continue
+            # Extraire les chaînes des arguments.
+            slice_node = node.slice
+            if isinstance(slice_node, ast.Tuple):
+                elts = slice_node.elts
+            else:
+                elts = [slice_node]
+            strings = {
+                e.value for e in elts
+                if isinstance(e, ast.Constant) and isinstance(e.value, str)
+            }
+            if canonical_strings.issubset(strings) and len(strings) == 3:
+                rel = path.relative_to(REPO_ROOT).as_posix()
+                offenders.append((rel, node.lineno))
+
+    if offenders:
+        sample = "\n".join(f"  {p}:{ln}" for p, ln in offenders)
+        raise AssertionError(
+            "Définition indépendante de ``PipelineMode`` "
+            "(``Literal[\"text_only\", \"text_and_image\", \"zero_shot\"]``) "
+            "détectée hors du module canonique :\n"
+            + sample
+            + "\n\nLa Phase 7.1 audit code-quality impose une source de vérité "
+            "unique dans ``picarones/domain/pipeline_spec.py``.  Remplacer "
+            "la définition locale par ``from picarones.domain.pipeline_spec "
+            "import PipelineMode``."
+        )
+
+
+def test_pipeline_mode_in_domain_all() -> None:
+    """``PipelineMode`` est exporté par ``picarones.domain.pipeline_spec``."""
+    from picarones.domain import pipeline_spec
+
+    assert "PipelineMode" in pipeline_spec.__all__

tests/web/test_engines_router_alignment.py

@@ -0,0 +1,105 @@
+"""Phase 7.3 audit code-quality (2026-05) — le router
+``/api/engines`` doit lister uniquement des engines connus de la
+factory ``picarones.adapters.ocr.factory``.
+
+L'audit avait identifié un risque de drift :
+
+- ``picarones.adapters.ocr.factory._SUPPORTED`` (source de vérité)
+- ``picarones.interfaces.web.routers.engines._collect_engines_sync``
+  énumère manuellement ``tesseract``, ``pero_ocr``, ``kraken``,
+  ``calamari``, puis ``cloud_ocr_specs = (mistral_ocr, google_vision,
+  azure_doc_intel)``.
+
+Si quelqu'un ajoute un nouvel adapter OCR à la factory sans
+mettre à jour le router, ``/api/engines`` mentirait au frontend.
+Si l'inverse, le frontend afficherait un engine non instanciable.
+
+Plutôt qu'une refonte (le router a besoin de métadonnées
+supplémentaires — label humain, nom de variable d'env, type
+``local``/``cloud`` — que la factory ne fournit pas), ce test
+verrouille l'invariant minimal : tout engine ID listé par le
+router doit exister dans ``_SUPPORTED`` de la factory.
+"""
+
+from __future__ import annotations
+
+
+def test_router_engines_subset_of_factory_supported() -> None:
+    """Chaque engine listé par le router est dans la factory."""
+    from picarones.adapters.ocr.factory import _SUPPORTED
+
+    # Inspection AST du router pour extraire les engine_ids cités.
+    import ast
+    from pathlib import Path
+
+    router_path = (
+        Path(__file__).resolve().parents[2]
+        / "picarones" / "interfaces" / "web" / "routers" / "engines.py"
+    )
+    tree = ast.parse(router_path.read_text(encoding="utf-8"))
+
+    # Stratégie : extraire toutes les chaînes littérales qui
+    # ressemblent à un engine_id (snake_case court).  Les chaînes
+    # d'engine candidates sont les premiers args de
+    # ``check_engine(name, ...)`` et le 1er tuple de
+    # ``cloud_ocr_specs = ((engine_id, ...), ...)``.
+    cited: set[str] = set()
+    for node in ast.walk(tree):
+        # ``check_engine("name", ...)``
+        if isinstance(node, ast.Call):
+            func = node.func
+            is_check = (
+                (isinstance(func, ast.Name) and func.id == "check_engine")
+                or (
+                    isinstance(func, ast.Attribute)
+                    and func.attr == "check_engine"
+                )
+            )
+            if is_check and node.args:
+                first = node.args[0]
+                if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                    cited.add(first.value)
+        # ``cloud_ocr_specs = (("id", "label", "ENV"), ...)``
+        if (
+            isinstance(node, ast.Assign)
+            and len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and node.targets[0].id == "cloud_ocr_specs"
+            and isinstance(node.value, ast.Tuple)
+        ):
+            for tup in node.value.elts:
+                if isinstance(tup, ast.Tuple) and tup.elts:
+                    first = tup.elts[0]
+                    if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                        cited.add(first.value)
+
+    supported = set(_SUPPORTED)
+    unknown = cited - supported
+    assert not unknown, (
+        f"Le router ``/api/engines`` mentionne des engines qui "
+        f"n'existent pas dans la factory : {sorted(unknown)}.\n"
+        f"Factory supportée : {sorted(supported)}.\n"
+        f"Soit ajouter ces engines à la factory, soit les retirer du router."
+    )
+
+
+def test_factory_supported_at_least_canonical() -> None:
+    """``_SUPPORTED`` contient les engines historiquement annoncés."""
+    from picarones.adapters.ocr.factory import _SUPPORTED
+
+    minimal = {
+        "tesseract",
+        "pero_ocr",
+        "kraken",
+        "calamari",
+        "mistral_ocr",
+        "google_vision",
+        "azure_doc_intel",
+        "precomputed",
+    }
+    actual = set(_SUPPORTED)
+    missing = minimal - actual
+    assert not missing, (
+        f"Engines canoniques absents de _SUPPORTED : {sorted(missing)}. "
+        f"Régression de la factory."
+    )