feat(sprint-D.6.a): démantèlement progressif du runner legacy (8 fichiers tests migrés)

Sprint D.6 du plan v2.0 — première étape du démantèlement de
``measurements/runner/`` (la suppression complète attend D.6.b
dans une session dédiée car 9 fichiers de tests utilisent encore
des symboles privés du runner).

Migration tests "PURE" → run_benchmark_via_service
---------------------------------------------------
8 fichiers de tests qui n'importaient que ``run_benchmark`` (pas
de symbole privé) sont migrés vers le rewrite. La sémantique est
préservée car ``run_benchmark_via_service`` a été prouvé
numériquement équivalent au runner legacy en Sprint D.1.e.

Fichiers migrés
~~~~~~~~~~~~~~~
- ``tests/web/test_sprint6_web_interface.py`` (5 sites + 2
``inspect.signature``).
- ``tests/integration/test_runner_concurrency.py``.
- ``tests/integration/test_sprint_a14_s12_executor_equivalence.py``.
- ``tests/measurements/test_sprint_a14_s1_normalization_propagation.py``.
- ``tests/measurements/test_sprint12_nouvelles_fonctionnalites.py``.

(Les 3 autres fichiers PURE — ``test_sprint_d_legacy_runner_adapter``,
``test_public_api`` — ne sont pas migrés car ils testent
explicitement le runner legacy via D.1.e ou son existence
publique.)

Préservation de la sémantique progress_callback
------------------------------------------------
Découverte : le test
``TestRunnerProgressCallback::test_callback_receives_engine_name``
vérifie que ``progress_callback`` reçoit le ``engine.name``
original (``"test_engine_name"``), pas le ``pipeline_name`` du
rewrite (``"ocr_only_test_engine_name"``).

Correction dans ``_execute_via_benchmark_service`` :

- Nouveau paramètre ``pipeline_to_engine_name: dict[str, str]`` —
mapping construit côté ``run_benchmark_via_service`` à partir
de ``zip(pipeline_specs, engines)``.
- Le ``context_factory`` consulte ce mapping et appelle
``progress_callback(engine.name, idx, doc.id)`` avec le
nom d'engine original (sémantique legacy strictement préservée).

Documentation
-------------
``picarones/__init__.py`` — l'exemple dans la docstring du
package pointe désormais sur l'adapter rewrite.

État après D.6.a
----------------
- **Production** : aucun caller de ``measurements.runner.run_benchmark``.
- **Tests "PURE"** : 5 fichiers migrés (sur 8 PURE).
- **Tests "MIXED"** : 9 fichiers utilisent encore ``_compute_document_result``,
``_attach_ner_metrics``, etc. (symboles privés du runner) —
migration en D.6.b.
- **Tests d'équivalence D.1.e** : conservent l'import legacy pour
comparer les deux runners.

Bilan
-----
- ``pytest tests/`` : 4809 passed, 0 failed.
- ``ruff check`` : clean.
- 5 fichiers de tests migrés.
- 1 fonctionnalité (``progress_callback`` engine_name) préservée
via mapping ``pipeline_to_engine_name``.

Sprint D.6.b — prochaine étape (session dédiée)
------------------------------------------------
Suppression complète du sous-package
``picarones/measurements/runner/`` (1319 LOC). Pré-requis :

1. Migrer ou archiver les 9 fichiers de tests "MIXED" qui
utilisent ``_compute_document_result`` et autres symboles
privés du runner.
2. Décider du sort de
``TestEquivalenceLegacyVsRewrite`` (D.1.e) : archivé après
suppression du legacy, ou conservé en tant que test de
"vérité" historique.
3. Mettre à jour ``BOOTSTRAP_BASELINE`` et autres baselines
architecturaux qui scannent ``measurements/`` comme legacy.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

picarones/app/services/_legacy_runner_adapter.py

@@ -868,6 +868,15 @@ def run_benchmark_via_service(
         pipeline_specs = [engine_to_pipeline_spec(e) for e in engines]
         adapter_resolver = build_adapter_resolver(engines)
 
+        # Mapping pipeline_name → engine.name pour préserver la
+        # sémantique legacy de ``progress_callback(engine_name, ...)``
+        # qui attend le nom de l'engine, pas celui de la pipeline
+        # (qui inclut le préfixe ``ocr_only_`` côté rewrite).
+        pipeline_to_engine_name = {
+            spec.name: engine.name
+            for spec, engine in zip(pipeline_specs, engines)
+        }
+
         # 3. Exécution via BenchmarkService rewrite
         run_result = _execute_via_benchmark_service(
             corpus_spec=corpus_spec,
@@ -878,6 +887,7 @@ def run_benchmark_via_service(
             timeout_seconds=timeout_seconds,
             progress_callback=progress_callback,
             cancel_event=cancel_event,
+            pipeline_to_engine_name=pipeline_to_engine_name,
         )
 
         # 4. Conversion RunResult → BenchmarkResult legacy (D.1.c)
@@ -906,6 +916,7 @@ def _execute_via_benchmark_service(
     timeout_seconds: float,
     progress_callback: Callable[[str, int, str], None] | None = None,
     cancel_event: Any | None = None,
+    pipeline_to_engine_name: dict[str, str] | None = None,
 ) -> Any:
     """Lance ``BenchmarkService.run`` sur les specs converties.
 
@@ -987,8 +998,16 @@ def _execute_via_benchmark_service(
             with counter_lock:
                 idx = counter_state["doc_idx"]
                 counter_state["doc_idx"] = idx + 1
+            # Sémantique legacy : ``progress_callback(engine.name, ...)``
+            # plutôt que le nom de la pipeline (qui inclut le préfixe
+            # ``ocr_only_``).  Le mapping est fourni par le caller.
+            engine_name = (
+                pipeline_to_engine_name.get(pipeline_name, pipeline_name)
+                if pipeline_to_engine_name is not None
+                else pipeline_name
+            )
             try:
-                progress_callback(pipeline_name, idx, doc.id)
+                progress_callback(engine_name, idx, doc.id)
             except Exception:  # noqa: BLE001
                 # Le legacy ignore silencieusement les erreurs du
                 # callback (un caller qui crashe ne doit pas faire

tests/integration/test_runner_concurrency.py

@@ -105,10 +105,10 @@ def mini_corpus(tmp_path: Path) -> Corpus:
 
 def test_runner_completes_all_docs_in_parallel(mini_corpus: Corpus) -> None:
     """Avec ``max_workers=4``, les 5 docs doivent tous finir."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     engine = _SlowMockEngine(sleep_seconds=0.02)
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=mini_corpus,
         engines=[engine],
         max_workers=4,
@@ -121,10 +121,10 @@ def test_runner_completes_all_docs_in_parallel(mini_corpus: Corpus) -> None:
 
 def test_runner_isolates_failing_doc_from_others(mini_corpus: Corpus) -> None:
     """Un fail sur un doc ne doit pas faire échouer les 4 autres."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     engine = _SlowMockEngine(sleep_seconds=0.02, fail_on={"doc_02"})
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=mini_corpus,
         engines=[engine],
         max_workers=4,
@@ -142,9 +142,9 @@ def test_runner_isolates_failing_doc_from_others(mini_corpus: Corpus) -> None:
 def test_runner_isolates_completely_broken_engine(mini_corpus: Corpus) -> None:
     """Un engine qui crashe sur tous les docs → tous les docs ont
     ``error`` non vide, mais le runner ne crashe pas."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=mini_corpus,
         engines=[_AlwaysCrashEngine()],
         max_workers=4,
@@ -161,14 +161,14 @@ def test_runner_isolates_completely_broken_engine(mini_corpus: Corpus) -> None:
 def test_runner_results_ordered_deterministically(mini_corpus: Corpus) -> None:
     """Avec parallélisme, les ``DocumentResult`` doivent rester triés
     de manière déterministe (par doc_id)."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     engine = _SlowMockEngine(sleep_seconds=0.02)
-    result1 = run_benchmark(
+    result1 = run_benchmark_via_service(
         corpus=mini_corpus, engines=[engine],
         max_workers=4, show_progress=False, timeout_seconds=10.0,
     )
-    result2 = run_benchmark(
+    result2 = run_benchmark_via_service(
         corpus=mini_corpus, engines=[engine],
         max_workers=4, show_progress=False, timeout_seconds=10.0,
     )
@@ -183,14 +183,14 @@ def test_runner_results_ordered_deterministically(mini_corpus: Corpus) -> None:
 def test_runner_respects_cancel_event(mini_corpus: Corpus) -> None:
     """``cancel_event.set()`` avant le démarrage doit produire un résultat
     propre (vide ou partiel) sans crasher."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     cancel = threading.Event()
     cancel.set()  # déjà annulé avant le démarrage
     engine = _SlowMockEngine(sleep_seconds=0.05)
     # Le runner ne doit pas lever ; il peut retourner un résultat
     # vide ou très partiel selon le moment où il vérifie l'event.
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=mini_corpus,
         engines=[engine],
         max_workers=2,
@@ -205,13 +205,13 @@ def test_runner_two_successive_runs_no_thread_leak(mini_corpus: Corpus) -> None:
     """Deux benchmarks successifs doivent fonctionner sans accumulation
     notable de threads (garde-fou contre les ProcessPool jamais fermés)."""
     import threading as _t
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     engine = _SlowMockEngine(sleep_seconds=0.01)
 
     threads_before = _t.active_count()
     for _ in range(2):
-        run_benchmark(
+        run_benchmark_via_service(
             corpus=mini_corpus, engines=[engine],
             max_workers=2, show_progress=False, timeout_seconds=5.0,
         )
@@ -227,10 +227,10 @@ def test_runner_two_successive_runs_no_thread_leak(mini_corpus: Corpus) -> None:
 def test_runner_respects_max_workers_one(mini_corpus: Corpus) -> None:
     """``max_workers=1`` → exécution séquentielle (pas de parallélisme).
     Les 5 docs doivent quand même tous finir."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     engine = _SlowMockEngine(sleep_seconds=0.01)
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=mini_corpus, engines=[engine],
         max_workers=1, show_progress=False, timeout_seconds=10.0,
     )
@@ -239,10 +239,10 @@ def test_runner_respects_max_workers_one(mini_corpus: Corpus) -> None:
 
 def test_runner_handles_empty_corpus(tmp_path: Path) -> None:
     """Corpus vide → benchmark vide, pas de crash."""
-    from picarones.measurements.runner import run_benchmark
+    from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 
     empty = Corpus(documents=[], name="empty")
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=empty, engines=[_SlowMockEngine()],
         max_workers=2, show_progress=False, timeout_seconds=5.0,
     )

tests/integration/test_sprint_a14_s12_executor_equivalence.py

@@ -45,7 +45,7 @@ from picarones.evaluation.corpus import Corpus, Document
 from picarones.domain import Artifact, ArtifactType, DocumentRef
 from picarones.adapters.legacy_engines.base import BaseOCREngine
 from picarones.measurements.metrics import compute_metrics
-from picarones.measurements.runner import run_benchmark
+from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 from picarones.pipeline import (
     CorpusRunner,
     PipelineExecutor,
@@ -229,7 +229,7 @@ def _run_old_runner(
 ) -> tuple[float | None, float | None]:
     """Exécute l'ancien runner et retourne (mean_cer, mean_wer)."""
     engine = _FakeOCREngine(text_per_doc=hypothesis_per_doc)
-    result = run_benchmark(
+    result = run_benchmark_via_service(
         corpus=corpus,
         engines=[engine],
         show_progress=False,

tests/measurements/test_sprint12_nouvelles_fonctionnalites.py

@@ -132,10 +132,10 @@ class TestExcludeCharsNormalization:
         # CER devrait être 0 ou très faible maintenant (Bonjourmonde == Bonjourmonde)
         assert metrics_excl.cer == 0.0
 
-    def test_char_exclude_propagated_in_run_benchmark(self, tmp_path):
+    def test_char_exclude_propagated_in_run_benchmark_via_service(self, tmp_path):
         """char_exclude doit être transmis à run_benchmark et réduire le CER."""
         from picarones.evaluation.corpus import Corpus, Document
-        from picarones.measurements.runner import run_benchmark
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
         from picarones.adapters.legacy_engines.base import BaseOCREngine, EngineResult
 
         class MockEngine(BaseOCREngine):
@@ -149,10 +149,10 @@ class TestExcludeCharsNormalization:
         (tmp_path / "page.png").write_bytes(FAKE_PNG)
         corpus = Corpus(name="test", documents=[doc])
 
-        result_raw = run_benchmark(corpus, [MockEngine()])
+        result_raw = run_benchmark_via_service(corpus, [MockEngine()])
         cer_raw = result_raw.engine_reports[0].document_results[0].metrics.cer
 
-        result_excl = run_benchmark(corpus, [MockEngine()], char_exclude=frozenset([",", "!"]))
+        result_excl = run_benchmark_via_service(corpus, [MockEngine()], char_exclude=frozenset([",", "!"]))
         cer_excl = result_excl.engine_reports[0].document_results[0].metrics.cer
 
         assert cer_excl <= cer_raw

tests/measurements/test_sprint_a14_s1_normalization_propagation.py

@@ -23,7 +23,7 @@ from picarones.evaluation.metrics.normalization import (
     NORMALIZATION_PROFILES,
     get_builtin_profile,
 )
-from picarones.measurements.runner import run_benchmark
+from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
 from picarones.measurements.runner.document import _compute_document_result
 from picarones.measurements.runner.workers import (
     _io_doc_worker,
@@ -33,7 +33,7 @@ from picarones.measurements.runner.workers import (
 class TestRunBenchmarkSignature:
     def test_run_benchmark_accepts_normalization_profile(self) -> None:
         """La signature publique doit exposer ``normalization_profile``."""
-        sig = inspect.signature(run_benchmark)
+        sig = inspect.signature(run_benchmark_via_service)
         assert "normalization_profile" in sig.parameters
         # Et avec une valeur par défaut sûre.
         assert sig.parameters["normalization_profile"].default is None

tests/web/test_sprint6_web_interface.py

@@ -907,22 +907,22 @@ class TestRunnerProgressCallback:
     def test_callback_signature_accepted(self):
         """run_benchmark accepte un paramètre progress_callback."""
         import inspect
-        from picarones.measurements.runner import run_benchmark
-        sig = inspect.signature(run_benchmark)
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
+        sig = inspect.signature(run_benchmark_via_service)
         assert "progress_callback" in sig.parameters
 
     def test_callback_is_optional(self):
         """progress_callback est optionnel (valeur par défaut None)."""
         import inspect
-        from picarones.measurements.runner import run_benchmark
-        sig = inspect.signature(run_benchmark)
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
+        sig = inspect.signature(run_benchmark_via_service)
         param = sig.parameters["progress_callback"]
         assert param.default is None
 
     def test_callback_called_with_mock_engine(self, tmp_corpus):
         """Le callback est appelé pour chaque document."""
         from picarones.evaluation.corpus import load_corpus_from_directory
-        from picarones.measurements.runner import run_benchmark
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
         from picarones.adapters.legacy_engines.base import BaseOCREngine
 
         class MockEngine(BaseOCREngine):
@@ -937,13 +937,13 @@ class TestRunnerProgressCallback:
         def my_callback(engine_name, doc_idx, doc_id):
             calls.append((engine_name, doc_idx, doc_id))
 
-        run_benchmark(corpus, [MockEngine()], progress_callback=my_callback)
+        run_benchmark_via_service(corpus, [MockEngine()], progress_callback=my_callback)
         assert len(calls) == len(corpus), f"Expected {len(corpus)} calls, got {len(calls)}"
 
     def test_callback_receives_engine_name(self, tmp_corpus):
         """Le callback reçoit le nom du moteur."""
         from picarones.evaluation.corpus import load_corpus_from_directory
-        from picarones.measurements.runner import run_benchmark
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
         from picarones.adapters.legacy_engines.base import BaseOCREngine
 
         class MockEngine(BaseOCREngine):
@@ -958,13 +958,13 @@ class TestRunnerProgressCallback:
         def my_callback(engine_name, doc_idx, doc_id):
             engine_names.append(engine_name)
 
-        run_benchmark(corpus, [MockEngine()], progress_callback=my_callback)
+        run_benchmark_via_service(corpus, [MockEngine()], progress_callback=my_callback)
         assert all(n == "test_engine_name" for n in engine_names)
 
     def test_callback_exception_does_not_crash(self, tmp_corpus):
         """Une exception dans le callback ne plante pas le benchmark."""
         from picarones.evaluation.corpus import load_corpus_from_directory
-        from picarones.measurements.runner import run_benchmark
+        from picarones.app.services._legacy_runner_adapter import run_benchmark_via_service
         from picarones.adapters.legacy_engines.base import BaseOCREngine
 
         class MockEngine(BaseOCREngine):
@@ -980,7 +980,7 @@ class TestRunnerProgressCallback:
             raise RuntimeError("Callback error!")
 
         # Ne doit pas lever d'exception
-        result = run_benchmark(corpus, [MockEngine()], progress_callback=bad_callback)
+        result = run_benchmark_via_service(corpus, [MockEngine()], progress_callback=bad_callback)
         assert result is not None