docs(sprint-D): audit complet du retrait de measurements/runner/

Sprint D.0 du plan v2.0 — pré-requis du sprint le plus gros
(8-10 jours d'effort estimé). Ce document détaille
exhaustivement les gaps entre ``measurements.runner.run_benchmark``
(legacy, 1319 LOC sur 7 fichiers) et
``app.services.BenchmarkService`` (rewrite, déjà canonique).

Contenu
-------
1. Surface du retrait : 7 modules legacy, 4 call-sites de
production (cli/_workflows : 2, web/benchmark_utils : 2).
2. API legacy ``run_benchmark`` : 13 paramètres, 12 features
identifiées (parallélisme, timeout, reprise, annulation,
progress, NER, profile, etc.).
3. API rewrite ``BenchmarkService.run`` : 9 paramètres, features
natives (manifest, views, run_id) ; **gaps** identifiés et
chiffrés sub-phase par sub-phase.
4. Plan ordonné D.1 → D.6 :
- D.1 — adapter de compat ``run_benchmark_via_service`` (2-3 j)
- D.2 — combler 6 gaps (3-4 j)
- D.3 — migrer ``web/benchmark_utils.run_benchmark_thread_v2`` (0.5 j)
- D.4 — migrer ou supprimer ``run_benchmark_thread`` legacy (0.3-1 j)
- D.5 — migrer 5 commandes CLI ``cli/_workflows`` (1.5 j)
- D.6 — suppression ``measurements/runner/`` (0.5 j)
5. Risques et mitigations (6 risques chiffrés).
6. Critères d'acceptation (10 checkpoints binaires).
7. Non-objectifs explicites (hors-scope Sprint D).

Découverte
----------
``fixtures.py`` ne consomme PAS ``run_benchmark`` directement —
il fabrique un ``BenchmarkResult`` synthétique en pur Python.
Le plan maître l'avait listé comme caller à migrer ; ce n'est
en fait pas nécessaire. La liste des callers réels passe donc
de 3 (annoncés) à 2 packages (4 sites).

Ce document est la **source de vérité** pour le Sprint D. Toute
déviation du plan doit être documentée en commit message
``docs(sprint-D): ajustement <raison>``.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

docs/migration/sprint-D-audit.md

@@ -0,0 +1,287 @@
+# Sprint D — Audit du retrait de `measurements/runner/`
+
+**Sprint D du plan v2.0** — migration du runner legacy
+(`measurements/runner/`) vers `app/services/BenchmarkService`.
+Préparation à la suppression du sous-package, qui débloque
+ensuite Phase 9 (Web → `interfaces/web/`) et Phase 10 (CLI →
+`interfaces/cli/`).
+
+Ce document est le pré-requis du Sprint D — il identifie
+exhaustivement les **gaps** entre les deux services et le
+**plan ordonné** des sub-phases D.1 à D.6.
+
+## 1. Surface du retrait
+
+### 1.1 — Modules à supprimer (`measurements/runner/`)
+
+| Fichier | LOC | Rôle |
+|---|---:|---|
+| `__init__.py` | 103 | Re-exports |
+| `orchestration.py` | 545 | `run_benchmark()` + boucle principale |
+| `document.py` | 200 | `_compute_document_result()` |
+| `partial.py` | 140 | Reprise sur interruption |
+| `workers.py` | 116 | Pool process/thread |
+| `aggregation.py` | 82 | Agrégation EngineReport |
+| `ner_attach.py` | 133 | Calcul NER (Sprint 40) |
+| **Total** | **1 319** | |
+
+### 1.2 — Callers à migrer
+
+| Caller | Sites | Bloquant |
+|---|---:|---|
+| `cli/_workflows.py` | 2 (run_cmd, compare_cmd) | bloque Phase 10 |
+| `web/benchmark_utils.py` | 2 (run_benchmark_thread + thread_v2) | bloque Phase 9 |
+| `picarones/__init__.py` | 1 (docstring) | cosmétique |
+| `picarones/measurements/__init__.py` | 1 (docstring) | supprimé avec measurements/ |
+| `picarones/adapters/corpus/iiif.py` | 1 (docstring) | cosmétique |
+
+**Total : 4 call-sites de production à migrer.** `fixtures.py` ne
+consomme PAS `run_benchmark()` (il fabrique un `BenchmarkResult`
+synthétique en pur Python).
+
+## 2. API legacy `run_benchmark()`
+
+### 2.1 — Signature
+
+```python
+def run_benchmark(
+    corpus: Corpus,                                    # legacy
+    engines: list[BaseOCREngine],                      # legacy (avec OCRLLMPipeline)
+    output_json: Optional[str | Path] = None,          # I/O
+    show_progress: bool = True,                        # tqdm
+    progress_callback: Optional[callable] = None,      # SSE web
+    char_exclude: Optional[frozenset] = None,          # filtre
+    max_workers: int = 4,                              # parallélisme
+    timeout_seconds: float = 60.0,                     # timeout/doc
+    partial_dir: Optional[str | Path] = None,          # reprise
+    cancel_event: Optional[threading.Event] = None,    # annulation web
+    entity_extractor: Optional[callable] = None,       # NER opt-in
+    profile: str = "standard",                         # profil mesures
+    normalization_profile: Optional[str] = None,       # normalisation
+) -> BenchmarkResult:
+```
+
+### 2.2 — Features fournies
+
+| Feature | Module | Mécanisme |
+|---|---|---|
+| Boucle (engines × corpus) | `orchestration.py` | imbriquée séquentielle |
+| Parallélisme intra-engine | `workers.py` | `Process` ou `ThreadPoolExecutor` selon `engine.execution_mode` |
+| Timeout par document | `workers.py` | Future + `concurrent.futures.wait` |
+| Reprise interruption | `partial.py` | JSON par engine, document-par-document |
+| Annulation propre | `orchestration.py` | `threading.Event` propagé |
+| Progress bar | `orchestration.py` | tqdm + callback |
+| OCR confidences | `document.py` | `EngineResult.token_confidences` |
+| OCR+LLM metadata | `orchestration.py:520` | duck-typing `is_pipeline` (Sprint C.1 ✅) |
+| Over-normalization | `document.py` | `detect_over_normalization(gt, ocr_int, hyp)` |
+| NER calculations | `ner_attach.py` | Optionnel via `entity_extractor` |
+| Profil normalisation | `orchestration.py` | `validate_profile` + `normalization_profile` |
+| Aggregation EngineReport | `aggregation.py` | per-engine corpus stats |
+| Fail-if-CER seuil | callers (CLI) | post-hoc sur `BenchmarkResult` |
+
+## 3. API rewrite `BenchmarkService`
+
+### 3.1 — Signature
+
+```python
+class BenchmarkService:
+    def run(
+        self,
+        *,
+        corpus: CorpusSpec,                            # rewrite
+        pipelines: Iterable[PipelineSpec],             # rewrite (déclaratif)
+        views: Iterable[EvaluationView],
+        ground_truth_factory: GroundTruthFactory,
+        pipeline_inputs_factory: PipelineInputsFactory,
+        context_factory: ContextFactory,
+        run_id: str | None = None,
+        dependencies_lock: dict[str, str] | None = None,
+        adapter_kwargs: dict[str, dict[str, Any]] | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> RunResult:
+```
+
+### 3.2 — Features fournies
+
+| Feature | Disponible ? | Source |
+|---|---|---|
+| Parallélisme intra-pipeline | ✅ | `pipeline.runner.CorpusRunner` (max_in_flight) |
+| Timeout par document | ✅ | `CorpusRunner.timeout_seconds_per_doc` |
+| Annulation propre | ✅ | `threading.Event` (CorpusRunner) |
+| `RunManifest` provenance | ✅ | `RunResult.manifest` |
+| `EvaluationView` (S13+) | ✅ | natif |
+| Run ID stable | ✅ | `run_id` arg |
+
+### 3.3 — Features manquantes
+
+| Feature | Effort | Sub-phase |
+|---|---|---|
+| Progress callback compat web | Faible | D.2.a |
+| tqdm progress bar | Faible | D.2.a |
+| Reprise sur interruption (`partial.py`) | Moyen | D.2.b |
+| `output_json` sérialisation directe | Faible | D.2.c |
+| Conversion `BenchmarkResult` → `RunResult` | Élevé | D.3 |
+| `over_normalization` aggregation | Moyen | D.2.d (déjà migré au volet 1) |
+| NER attach via `entity_extractor` | Moyen | D.2.e |
+| `profile` validation | Faible | D.2.f |
+| `normalization_profile` | Faible | D.2.f |
+| `char_exclude` filter | Faible | D.2.f |
+| `fail_if_cer` (callers) | Faible | côté caller |
+
+## 4. Plan ordonné
+
+### D.0 — Audit (ce document) — fait ✅
+
+### D.1 — Adapter de compat `run_benchmark_via_service`
+
+Fonction qui présente l'API legacy (`Corpus`, `engines`,
+`output_json`, etc.) et construit en interne :
+
+1. `CorpusSpec` à partir du `Corpus` legacy (mapping
+   `Document` → `DocumentRef`).
+2. `PipelineSpec` à partir de chaque `BaseOCREngine` :
+   - OCR seul → spec mono-step via le builder
+     (`adapter_name=engine.name`, params=engine.config).
+   - `OCRLLMPipeline` → utilise déjà `make_ocr_llm_pipeline_spec`
+     en interne via Sprint B.
+3. Adapter resolver (`name → instance`) qui retrouve les engines
+   par leur `name`.
+4. Factories par défaut (ground_truth, pipeline_inputs, context).
+5. Lance `BenchmarkService.run(...)`.
+6. Convertit `RunResult` → `BenchmarkResult` legacy
+   (mapping inverse : `RunDocumentResult` → `DocumentResult`,
+   `pipeline_results` → `EngineReport`).
+
+**Effort** : 2-3 j. **Risque** : la conversion bidirectionnelle
+``Corpus ↔ CorpusSpec`` et ``RunResult ↔ BenchmarkResult`` est la
+partie délicate (les structures sont différentes par design).
+
+### D.2 — Combler les gaps `BenchmarkService`
+
+| Sub-phase | Gap | Effort |
+|---|---|---|
+| D.2.a | progress callback + tqdm | 0.5 j |
+| D.2.b | reprise interruption | 1 j |
+| D.2.c | `output_json` sérialisation | 0.3 j |
+| D.2.d | over_normalization aggregation | 0.5 j |
+| D.2.e | NER attach via entity_extractor | 0.5 j |
+| D.2.f | profile + normalization + char_exclude | 0.5 j |
+
+**Total D.2** : ~3.3 j.
+
+### D.3 — Migrer `web/benchmark_utils.py:run_benchmark_thread_v2`
+
+Le caller le plus simple à migrer (le plus récent, code propre) :
+remplacer `run_benchmark(...)` par `run_benchmark_via_service(...)`.
+Tests `tests/web/test_sprint28_ux_save_compare.py` doivent rester
+verts.
+
+**Effort** : 0.5 j.
+
+### D.4 — Migrer `web/benchmark_utils.py:run_benchmark_thread` (legacy)
+
+Cette fonction est plus ancienne et utilise un format de competitor
+configuration différent. Probablement redondante avec `_v2` —
+candidat à la **suppression pure** plutôt qu'à la migration.
+
+**Effort** : 0.3 j (suppression) ou 1 j (migration si conservé).
+
+### D.5 — Migrer `cli/_workflows.py`
+
+5 commandes : `run`, `diagnose`, `economics`, `edition`, `compare`.
+Toutes appellent `run_benchmark()` directement.  Migration par
+commande, en commençant par la plus simple (`run`).
+
+**Effort** : 1.5 j.
+
+### D.6 — Suppression `measurements/runner/`
+
+Une fois tous les callers migrés :
+
+```bash
+rm -r picarones/measurements/runner/
+```
+
+Plus mise à jour des tests qui importaient depuis `runner` (51
+fichiers) et des baselines architecturaux.
+
+**Effort** : 0.5 j.
+
+## 5. Ordre d'enchaînement et durée
+
+```
+D.0 (audit)        ✅ fait
+  ↓
+D.1 (adapter)      ←─────┐
+  ↓                       │
+D.2 (gaps)         ←──────┤  parallélisable
+  ↓                       │
+D.3 (web v2)              │
+  ↓                       │
+D.4 (web v1, opt.)        │
+  ↓                       │
+D.5 (CLI)                 │
+  ↓                       │
+D.6 (suppression)  ←──────┘
+```
+
+| Sub-phase | Effort |
+|---|---:|
+| D.1 | 2-3 j |
+| D.2 | 3-4 j |
+| D.3 | 0.5 j |
+| D.4 | 0.3-1 j |
+| D.5 | 1.5 j |
+| D.6 | 0.5 j |
+| **Total Sprint D** | **8-10 j** |
+
+## 6. Risques et mitigations
+
+| Risque | Probabilité | Mitigation |
+|---|---|---|
+| Conversion `RunResult ↔ BenchmarkResult` perd des champs | Élevée | tests round-trip détaillés en D.1 |
+| Performance dégradée du runner rewrite | Moyenne | benchmark de comparaison sur fixtures |
+| Reprise sur interruption manque dans rewrite | Élevée | D.2.b prioritaire |
+| Tests Sprint 15 (warnings LLM vide) cassent | Faible | Sprint B a déjà préservé les warnings |
+| Web SSE callback signature incompatible | Moyenne | D.2.a en premier |
+| CLI fail-if-cer logique côté caller | Faible | Reste côté CLI, ne touche pas le runner |
+
+## 7. Critères d'acceptation Sprint D
+
+À l'issue de D.6 :
+
+- [ ] `picarones/measurements/runner/` n'existe plus.
+- [ ] `from picarones.measurements.runner import run_benchmark`
+      → ImportError.
+- [ ] `web/benchmark_utils.py` consomme `BenchmarkService` (ou son
+      adapter).
+- [ ] `cli/_workflows.py` consomme `BenchmarkService` (ou son
+      adapter).
+- [ ] Tests CLI (Sprint 9, 11) verts.
+- [ ] Tests Web (Sprint 6, 28) verts.
+- [ ] Tests metrics (Sprint 3, 15) verts.
+- [ ] Performance : pas de régression > 10 % sur fixtures
+      (corpus de 5 documents, 1 engine Tesseract).
+- [ ] Reprise sur interruption : test `test_partial_resume.py`
+      vert (à créer).
+- [ ] Phase 9 (Web → `interfaces/web/`) débloquée — plus aucun
+      import `measurements.runner` dans `web/`.
+- [ ] Phase 10 (CLI → `interfaces/cli/`) débloquée — plus aucun
+      import `measurements.runner` dans `cli/`.
+
+## 8. Non-objectifs (hors-scope Sprint D)
+
+- ❌ Refactor de `app/services/run_orchestrator.py` (déjà
+  canonique).
+- ❌ Migration des métriques `measurements/*.py` (Sprint E).
+- ❌ Migration des routes web (Sprint F).
+- ❌ Migration des commandes CLI (Sprint G).
+- ❌ Suppression de `OCRLLMPipeline` (Sprint D.6 inclura sa
+  suppression car `pipelines/_executor_runner.py` n'aura plus
+  d'utilité — mais c'est un effet de bord, pas l'objectif).
+
+---
+
+**Document de référence** pour le Sprint D.  Toute déviation du
+plan ci-dessus doit être documentée en commit message
+`docs(sprint-D): ajustement <raison>`.