chore: finir le retrait execution_mode (audit du commit precedent)

Audit du commit 5e13c0d a revele 13 defauts ; ce commit les corrige.

## Zombies de code production

- adapters/ocr/pero_ocr.py : retire les 2 mentions ProcessPool
qui motivaient le lazy-init du parser. Le pattern reste valable
(eviter de charger PyTorch au constructeur), seul son rationale
fictif disparait.
- adapters/ocr/calamari.py : ajoute la justification GIL/TensorFlow
(asymetrie avec tesseract/pero/kraken corrigee).

## Mensonges documentation actifs

- docs/explanation/architecture.md : runner.py n'est plus decrit
comme "ProcessPool/ThreadPool" mais "ThreadPool unique".
- docs/reference/specification.md : la table "4.2 Moteurs OCR
livres" ne dit plus "CPU (ProcessPool)" / "IO (ThreadPool)"
mais decrit le profil d'execution reel (sous-processus C, PyTorch,
appel HTTP).
- docs/operations/deployment-institutional.md : le sizing institutionnel
ne parle plus de "3 GB RAM par worker ProcessPool" ni de
"ProcessPool 8 workers" mais bien du ThreadPool reel et de
max_in_flight.

## Rechutes soft sur l'option B

- pipeline/runner.py : la docstring retire la phrase "redeviendra
recevable... commit 047ab1b" qui contredisait le choix YAGNI.
- specification.md (section 4.1) : meme nettoyage, la phrase
"un dispatch multi-pool avait ete prototype puis suspendu"
remplacee par une instruction de revue de PR.
- README.md : "all supported adapters release the GIL" recadre en
"today's adapters happen to release the GIL" pour ne pas faire
croire a un invariant du projet.
- CHANGELOG : retire l'enumeration des cas d'usage hypothetiques
(overnorm, voter, MUFI) ; ces fonctionnalites ne sont pas sur
la roadmap publique, les nommer dans un changelog est du wishful
thinking architectural.

## Inconsistances introduites

- test_doc_paths.py : commentaire au-dessus de BROKEN_PATHS_BASELINE
raconte maintenant la transition 6 -> 5 et liste les 5 chemins
restants (etait reste a "6 chemins" apres modification de la
constante).

## Garde-fou trop etroit

- test_no_execution_mode_resurrection.py : scanne maintenant aussi
README.md, CLAUDE.md et docs/*.md (hors docs/archive/) en plus du
code Python. Limite assumee (symbole exact, pas concept renomme)
explicitee dans la docstring. CHANGELOG.md et test_doc_paths.py
whitelistes (mentions historiques legitimes).

## Mensonge oublie dans conftest.py

- tests/conftest.py : le workaround tqdm._monitor invoquait
"ProcessPoolExecutor du runner Picarones" pour justifier la
desactivation. Le runner n'est plus ProcessPool. Commentaire
reecrit pour assumer que la cause racine a pu disparaitre et
qu'il faudra revalider au prochain passage.

## Resultat

- 6058 tests passent (idem, 0 regression).
- ruff check vert.
- +55 LOC nets (essentiellement docstring guardrail elargie + recits
honnetes des choix dans la doc).

https://claude.ai/code/session_01B93huMjNh4CG2rNcexgDeL

CHANGELOG.md

@@ -118,10 +118,7 @@ L'attribut était un mensonge structurel.  L'historique git portait
 une tentative de dispatch multi-pool (``MultiDomainCorpusRunner``,
 commit ``047ab1b``) qui a été suspendue (``cd67184``).  Aucun adapter
 actuel n'est GIL-bound en pratique — chacun délègue à du C qui relâche
-le GIL.  Le jour où un adapter Python-pur GIL-bound deviendra utile
-(détecteur d'over-normalisation, voter d'ensemble, MUFI scorer en
-step de pipeline plutôt qu'en métrique), la décision sera explicite
-plutôt que portée par un attribut décoratif.
+le GIL.  Retirer plutôt que documenter un attribut zombi : YAGNI.
 
 ---
 

README.md

@@ -432,10 +432,12 @@ CONTRIBUTING, SECURITY, ACCESSIBILITY, and the
   `logger.warning("[module] degraded feature: %s", e)`.
 - One canonical home per module — circle dependency direction
   enforced by tests.
-- The `CorpusRunner` is thread-only by design — all supported
-  adapters (OCR via C binary, LLM/VLM via httpx, ML via
-  PyTorch/TensorFlow) release the GIL during their blocking
-  call, so a single thread pool delivers the expected throughput.
+- The `CorpusRunner` is thread-only by design. Today's adapters
+  (OCR via C binary, LLM/VLM via httpx, ML via PyTorch/TensorFlow)
+  happen to release the GIL during their blocking call, which is
+  why a single thread pool works. A future adapter doing pure-Python
+  CPU work would not benefit from parallelism — that's a constraint
+  for adapter authors to verify, not a global invariant.
 - Hardcoded UI strings forbidden — always go through i18n
   (cf. [`docs/developer/extending-i18n.md`](docs/developer/extending-i18n.md)).
 

docs/explanation/architecture.md

@@ -102,7 +102,7 @@ Orchestration mono-document d'une pipeline composée :
 | `executor.py` | `PipelineExecutor` — exécute un `PipelineSpec` step par step, capture `StepResult`, filtre outputs sur `step.output_types` |
 | `planner.py` | `PipelinePlanner` — résout les `inputs_from`, valide la spec, calcule les métriques aux jonctions |
 | `validation.py` | Validation statique d'une `PipelineSpec` (types s'enchaînent, pas de cycle) |
-| `runner.py` | `CorpusRunner` — orchestration corpus-wide avec ProcessPool/ThreadPool, backpressure, timeout, cancellation |
+| `runner.py` | `CorpusRunner` — orchestration corpus-wide (ThreadPool unique), backpressure, timeout, cancellation |
 | `cache.py`, `cache_helpers.py`, `cache_protocol.py` | Reprise par hash via `ArtifactCachePort` |
 | `yaml_io.py` | Sérialisation YAML déterministe d'une `PipelineSpec` |
 | `llm_pipeline_builder.py` | `make_ocr_llm_pipeline_spec` (3 modes : text_only, text_and_image, zero_shot) |

docs/operations/deployment-institutional.md

@@ -17,8 +17,10 @@
 - **Python 3.11 ou 3.12** (3.13 informationnel).
 - **Tesseract OCR ≥ 5.3** (avec packs `fra`, `lat`, `eng` au
   minimum).
-- **3 GB RAM par worker** (le ProcessPool spawne un sous-processus
-  par moteur ; profil mémoire dominé par Pillow + jiwer).
+- **3 GB RAM** pour un worker FastAPI exécutant `max_in_flight=4`
+  documents en parallèle dans le ThreadPool du `CorpusRunner`
+  (profil mémoire dominé par Pillow + jiwer + les modèles OCR locaux
+  chargés une fois par instance).
 - **5 GB de disque** pour l'application + 50 GB recommandés pour
   les uploads et la base SQLite des jobs.
 
@@ -272,7 +274,7 @@ uniquement** (jamais sur le filesystem en clair). Voir [`SECURITY.md`](../../SEC
 | Charge | Configuration |
 |---|---|
 | < 5 jobs/h, < 5 utilisateurs | Mono-instance, SQLite, 2 vCPU / 4 GB RAM |
-| 5–50 jobs/h, < 20 utilisateurs | Mono-instance, SQLite, 4 vCPU / 8 GB RAM, ProcessPool 8 workers |
+| 5–50 jobs/h, < 20 utilisateurs | Mono-instance, SQLite, 4 vCPU / 8 GB RAM, `max_in_flight=8` |
 | > 50 jobs/h | Multi-instance derrière LB, PostgreSQL centralisé, NFS uploads |
 | > 500 jobs/h | Considérer un orchestrateur de tâches dédié (Celery + Redis), hors scope Picarones |
 

docs/reference/specification.md

@@ -308,23 +308,23 @@ ses `input_types` et `output_types` et implémente
 `execute(inputs, params, context, control) -> dict[ArtifactType, Artifact]`.
 
 Le `CorpusRunner` orchestre l'exécution via un `ThreadPoolExecutor`
-unique pour tous les adapters.  Les adapters supportés (OCR via
+unique pour tous les adapters.  Les adapters actuels (OCR via
 binaire C, LLM/VLM via httpx, ML via PyTorch/TensorFlow) relâchent
 le GIL pendant leur travail bloquant, donc un thread pool donne
-les performances attendues.  Un dispatch multi-pool (ThreadPool +
-ProcessPool selon le profil d'exécution) avait été prototypé puis
-suspendu — il pourra être réintroduit si un adapter Python-pur
-GIL-bound apparaît.
+les performances attendues.  Un adapter qui ferait du calcul Python
+pur ne profiterait pas de la parallélisation : c'est à l'auteur de
+l'adapter de vérifier en revue de PR que son `execute()` n'est pas
+GIL-bound avant de prétendre tourner en parallèle.
 
 ### 4.2 Moteurs OCR livrés
 
-| Moteur | Type | Mode d'exécution | Confidence native exposée ? |
+| Moteur | Type | Profil dominant | Confidence native exposée ? |
 |---|---|---|---|
-| **Tesseract 5** | Local CLI | CPU (ProcessPool) | ✅ Sprint 47 (`image_to_data`) |
-| **Pero OCR** | Local Python | CPU (ProcessPool) | ✅ Sprint 48 (`transcription_confidence` ligne) |
-| **Mistral OCR** | Cloud API | IO (ThreadPool) | ✅ Sprint 49 (quand disponible côté API) |
-| **Google Vision** | Cloud API | IO (ThreadPool) | ✅ Sprint 50 (`Word.confidence` en mode `DOCUMENT_TEXT_DETECTION`) |
-| **Azure Doc Intelligence** | Cloud API | IO (ThreadPool) | ✅ Sprint 51 (`Word.confidence`) |
+| **Tesseract 5** | Local CLI | Sous-processus C (GIL relâché) | ✅ Sprint 47 (`image_to_data`) |
+| **Pero OCR** | Local Python | Inférence PyTorch (GIL relâché) | ✅ Sprint 48 (`transcription_confidence` ligne) |
+| **Mistral OCR** | Cloud API | Appel HTTP | ✅ Sprint 49 (quand disponible côté API) |
+| **Google Vision** | Cloud API | Appel HTTP | ✅ Sprint 50 (`Word.confidence` en mode `DOCUMENT_TEXT_DETECTION`) |
+| **Azure Doc Intelligence** | Cloud API | Appel HTTP | ✅ Sprint 51 (`Word.confidence`) |
 
 Quand un moteur expose ses confidences natives, le runner calcule
 automatiquement les métriques de calibration (ECE, MCE, reliability

picarones/adapters/ocr/calamari.py

@@ -9,6 +9,8 @@ Calamari est un OCR open-source basé TensorFlow / Keras, conçu pour
 les imprimés historiques et la transcription ligne par ligne.
 Modèles disponibles via OCR-D, Wikisource, et le hub Calamari.
 Particulièrement performant en ensemble (vote multi-modèles).
+L'inférence passe par TensorFlow (extension C++) qui relâche le GIL,
+donc le ``CorpusRunner`` thread-only suffit.
 
 Configuration
 -------------

picarones/adapters/ocr/pero_ocr.py

@@ -36,9 +36,9 @@ Anti-sur-ingénierie
 -------------------
 - Pas de support GPU explicite (Pero OCR le gère via la config).
 - Pas de retry, pas d'extraction de confidences (à ajouter quand un caller en aura besoin).
-- ``_parser`` lazy-init — si l'instance est sérialisée pour
-  ProcessPool, le parser est re-instancié dans le worker (cohérent
-  avec Pero OCR qui charge ses modèles à l'instanciation).
+- ``_parser`` lazy-init : le modèle PyTorch n'est chargé qu'au
+  premier ``execute()``, pas au constructeur — permet d'instancier
+  l'adapter sans pénalité même si le doc n'est jamais exécuté.
 """
 
 from __future__ import annotations
@@ -96,8 +96,8 @@ class PeroOCRAdapter(BaseOCRAdapter):
         self._name = name
         self._config_path = Path(config_path)
         # Le parser est instancié paresseusement au premier execute()
-        # pour que la sérialisation ProcessPool fonctionne (un parser
-        # contenant des modèles PyTorch n'est pas sérialisable).
+        # — le constructeur reste léger et l'on évite de charger les
+        # modèles PyTorch tant qu'aucun document n'est traité.
         self._parser: Any = None
 
     @property

picarones/pipeline/runner.py

@@ -25,14 +25,14 @@ avec trois propriétés critiques que l'ancien
 
 Limites assumées
 ----------------
-- **Pool d'exécution unique : ThreadPool.**  Tous les adapters
-  supportés (OCR via binaire C, LLM/VLM via httpx, ML via
-  PyTorch/TensorFlow) délèguent leur travail bloquant à du code
-  natif qui relâche le GIL, donc un thread pool unique donne les
-  performances attendues.  Si un futur adapter fait du calcul
-  Python pur GIL-bound, un dispatch vers ``ProcessPoolExecutor``
-  redeviendra recevable — un prototype existe dans l'historique
-  git (commit 047ab1b, depuis suspendu).
+- **Pool d'exécution unique : ThreadPool.**  Choix de conception
+  assumé.  Les adapters actuels (OCR via binaire C, LLM/VLM via
+  httpx, ML via PyTorch/TensorFlow) délèguent leur travail bloquant
+  à du code natif qui relâche le GIL, donc un thread pool unique
+  suffit en pratique.  Un adapter qui ferait du calcul Python pur
+  ne profiterait pas de la parallélisation — c'est sa charge de
+  vérifier que son ``execute()`` n'est pas GIL-bound (cf. revue de
+  PR) avant de prétendre tourner en parallèle.
 - **Cancel coopératif sur les in-flight.**  Quand ``cancel_event``
   est signalé, le runner appelle ``trigger_cancel()`` sur le
   ``RunControl`` de chaque doc en cours : les adapters qui ont

tests/architecture/test_doc_paths.py

@@ -162,11 +162,13 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 #: pré-v2.0 ont été consolidés sous ``docs/archive/``.  Les 35
 #: chemins cassés qu'ils portaient sortent du périmètre actif (cf.
 #: ``EXCLUDED_PATH_PREFIXES`` ci-dessous).
+#: Retrait ``execution_mode`` (mai 2026) : 6 → 5.  La section 4.1 de
+#: ``docs/reference/specification.md`` ne pointe plus vers
+#: ``picarones/adapters/legacy_engines/base.py`` (path supprimé).
 #:
-#: Les 6 chemins restants sont dans la doc active :
+#: Les 5 chemins restants sont dans la doc active :
 #: - CHANGELOG.md (4) : refs Sprint H.4/H.6 dans la section
 #:   migration v2.0 (intouchables sans réécrire l'historique 2.0) ;
-#: - SPECS.md (1) : exemple YAML legacy à corriger en Phase 2 ou v2.1 ;
 #: - docs/explanation/architecture.md (1) : ref historique au shim
 #:   ``picarones/pipeline/spec.py`` supprimé en Sprint S7.
 BROKEN_PATHS_BASELINE = 5

tests/architecture/test_no_execution_mode_resurrection.py

@@ -21,8 +21,25 @@ Ce test bloque sa réintroduction silencieuse.  Si tu le vois échouer :
    profite pas du thread pool), réintroduire l'attribut **avec** le
    dispatch effectif dans le runner — sinon c'est une fausse promesse.
 
-Le test scanne les sources Python du package et de la suite de tests
-pour détecter toute réapparition.
+Portée du scan
+--------------
+Le test couvre :
+
+- ``picarones/`` et ``tests/`` (fichiers ``*.py``) — empêche la
+  réintroduction du symbole dans le code et les tests ;
+- ``README.md``, ``CLAUDE.md``, ``CHANGELOG.md`` et ``docs/``
+  (``*.md``) — empêche la réintroduction de la **promesse** dans
+  la documentation active, là où le drift est historiquement le
+  plus dommageable.
+
+Le ``CHANGELOG.md`` peut légitimement mentionner le symbole pour
+relater le retrait — l'entrée concernée est donc whitelistée.
+
+Limite assumée : on ne détecte que le symbole exact ``execution_mode``
+/ ``ExecutionMode``.  Un attribut renommé (``runtime_mode``,
+``exec_profile``…) passerait ce test ; il appartient au revieweur de
+ne pas réintroduire le concept sous un autre nom sans le dispatch
+effectif.
 """
 
 from __future__ import annotations
@@ -34,20 +51,54 @@ import pytest
 
 _FORBIDDEN_TOKENS = ("execution_mode", "ExecutionMode")
 _REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-_SCAN_ROOTS = (_REPO_ROOT / "picarones", _REPO_ROOT / "tests")
+_PY_ROOTS = (_REPO_ROOT / "picarones", _REPO_ROOT / "tests")
+_DOC_ROOTS = (_REPO_ROOT / "docs",)
+_DOC_FILES = (
+    _REPO_ROOT / "README.md",
+    _REPO_ROOT / "CLAUDE.md",
+)
 _SELF = Path(__file__).resolve()
 
+#: Fichiers qui mentionnent légitimement les symboles retirés pour
+#: documenter leur disparition (CHANGELOG, ratchet doc-paths).
+#: Le whitelister garde le test utile sans bloquer l'historique narratif.
+_WHITELIST: frozenset[Path] = frozenset({
+    (_REPO_ROOT / "CHANGELOG.md").resolve(),
+    (_REPO_ROOT / "tests" / "architecture" / "test_doc_paths.py").resolve(),
+})
 
-@pytest.mark.parametrize("token", _FORBIDDEN_TOKENS)
-def test_no_execution_mode_resurrection(token: str) -> None:
-    offenders: list[str] = []
-    for root in _SCAN_ROOTS:
+#: ``docs/archive/`` capture l'historique pré-0.9.0 (sprints, ADRs
+#: rejetées, plans de migration).  Réécrire ces archives serait une
+#: réécriture d'historique.
+_EXCLUDED_DOC_PREFIXES: tuple[str, ...] = ("docs/archive/",)
+
+
+def _iter_scanned_files():
+    for root in _PY_ROOTS:
         for py in root.rglob("*.py"):
             if py.resolve() == _SELF:
                 continue
-            text = py.read_text(encoding="utf-8")
-            if token in text:
-                offenders.append(str(py.relative_to(_REPO_ROOT)))
+            yield py
+    for root in _DOC_ROOTS:
+        for md in root.rglob("*.md"):
+            rel = md.relative_to(_REPO_ROOT).as_posix()
+            if any(rel.startswith(p) for p in _EXCLUDED_DOC_PREFIXES):
+                continue
+            yield md
+    for path in _DOC_FILES:
+        if path.exists():
+            yield path
+
+
+@pytest.mark.parametrize("token", _FORBIDDEN_TOKENS)
+def test_no_execution_mode_resurrection(token: str) -> None:
+    offenders: list[str] = []
+    for path in _iter_scanned_files():
+        if path.resolve() in _WHITELIST:
+            continue
+        text = path.read_text(encoding="utf-8")
+        if token in text:
+            offenders.append(str(path.relative_to(_REPO_ROOT)))
     assert not offenders, (
         f"{token!r} a été réintroduit dans : "
         + ", ".join(offenders)

tests/conftest.py

@@ -50,20 +50,19 @@ os.environ.setdefault("PICARONES_RATE_LIMIT_PER_HOUR", "0")
 
 
 # (3) Désactivation préventive du thread daemon de tqdm.
-# Sur Python 3.12+ (ubuntu-latest en CI), le combo
-# ``tqdm._monitor`` + ``ProcessPoolExecutor`` (utilisé par
-# ``picarones.measurements.runner.orchestration`` pour les moteurs
-# CPU-bound : Tesseract, Pero OCR) provoque un hang du shutdown de
-# l'interpréteur après ``=== passed ===``.  Le ``_python_exit`` de
-# ``concurrent.futures.process`` essaie de joindre les workers du
-# pool, mais le thread monitor de tqdm bloque la sortie globale —
-# le hang dépasse le timeout GNU configuré dans ci.yml (9 min) et
-# le job échoue avec exit code 124.
+# Workaround historique pour un hang de shutdown observé en CI
+# Python 3.12+ (ubuntu-latest) : ``tqdm._monitor`` reste bloqué et
+# empêche la sortie de l'interpréteur après ``=== passed ===``, ce
+# qui faisait dépasser le timeout GNU de ci.yml (9 min, exit 124).
 #
-# ``monitor_interval=0`` désactive le polling thread de tqdm, qui
-# n'est utile qu'à l'affichage interactif des progress bars (sans
-# valeur ajoutée en CI où stdout est captured).  Fix idiomatique
-# pour ce flake spécifique.
+# Le diagnostic originel pointait une interaction avec
+# ``ProcessPoolExecutor`` du runner historique ; ce runner a été
+# remplacé par un ``ThreadPoolExecutor`` (cf.
+# ``picarones/pipeline/runner.py``), donc la cause racine peut
+# avoir disparu — à revalider la prochaine fois que ce workaround
+# est révisé.  En attendant, ``monitor_interval=0`` désactive le
+# polling thread de tqdm (sans valeur en CI où stdout est captured)
+# et reste inoffensif.
 try:
     from tqdm import tqdm as _tqdm