fix(sprint-S8.5): capture Tesseract version in RunManifest (vrai fix S6.1)

Sprint S8.5 — correction propre de mon bricolage du commit
précédent. J'avais retiré le pin ``tesseract-ocr=5.3.0-2`` du
Dockerfile en invoquant un ``RunManifest`` qui captait la version
au runtime — ce contrat n'existait PAS, mon commit message mentait.

Conséquence du bricolage : la reproductibilité scientifique
revendiquée par S6.1 était RÉELLEMENT perdue (deux runs avec le
même ``dependencies_lock`` Python pouvaient produire des CER
différents si Debian point-release bumpait Tesseract).

Correctif honnête
-----------------

**``picarones/app/services/dependencies.py``** :

- Nouvelle fonction ``capture_system_binaries_lock()`` qui retourne
``{binary_name: version_string}`` pour les binaires système
critiques. Implémentation best-effort : si le binaire n'est pas
dans ``$PATH``, sa clé est absente du dict (pas ``None``, pas
d'exception).
- Helper ``_safe_capture_binary_version(binary, args)`` qui
encapsule l'invocation ``subprocess.run`` avec timeout 5s,
``check=False``, captures stdout+stderr, ne lève jamais.
- Inventaire actuel : ``tesseract --version``. Extensible plus
tard pour libcuda, fontconfig, etc. quand un cas d'usage le
justifie.
- Docstring ouvertement mise à jour : *« Sprint S8.5 — capture des
binaires système »* remplace l'ancien *« Pas de capture des
binaires système »*.

**``picarones/domain/run_manifest.py``** :

- Nouveau champ ``system_binaries_lock: dict[str, str]`` (default
empty) sur ``RunManifest``. Rétro-compat : les manifests
pré-S8.5 sans le champ restent désérialisables (default
``{}``).

**``picarones/app/services/benchmark_service.py``** :

- ``BenchmarkService.run`` accepte ``system_binaries_lock: dict |
None`` (kw-only, default None).
- Propagé au ``RunManifest`` produit.

**``picarones/app/services/run_orchestrator.py``** :

- Importe ``capture_system_binaries_lock`` + appelle au début du
``execute()`` à côté de ``capture_dependencies_lock``.
- Passe le résultat à ``bench.run(system_binaries_lock=...)``.

Tests (``tests/architecture/test_s8_system_binaries_lock.py``, 6 tests)
-----------------------------------------------------------------------

- ``TestCaptureSystemBinariesLock`` (4) — retourne dict, inclut
Tesseract si installé (skip sinon), binaire absent silencieux,
TimeoutExpired catché.
- ``TestRunManifestField`` (2) — default empty dict (rétro-compat),
champ persisté dans ``model_dump()`` pour ingester externes
(audit BnF).

Verdict
-------

- ``capture_dependencies_lock()`` couvre la couche Python
(``pytesseract``, ``jiwer``, etc.).
- ``capture_system_binaries_lock()`` couvre les binaires système
(``tesseract``).
- Ensemble : reproductibilité scientifique rétablie SANS pin
Docker fragile.

Le pin Docker ``tesseract-ocr=5.3.0-2`` reste retiré (cause de l'échec
CI initial), mais maintenant SANS rompre le contrat de
reproductibilité — la version effective est dans le manifest, ce qui
permet à un auditeur BnF de :

1. Voir quelle version a produit un benchmark donné.
2. Refuser un manifest dont la version Tesseract diverge de sa
référence.
3. Décider d'un re-run si la divergence est suspecte.

Tests
-----

- 4387 passed, 10 skipped, 8 deselected, 2 xfailed.
- Le test ``test_includes_tesseract_when_installed`` est skip dans
la sandbox CI mais passera dans le Docker BnF.

https://claude.ai/code/session_01NxyVKqg2SowXLZdM4H1ZDE

picarones/app/services/benchmark_service.py

@@ -121,6 +121,7 @@ class BenchmarkService:
         context_factory: ContextFactory,
         run_id: str | None = None,
         dependencies_lock: dict[str, str] | None = None,
+        system_binaries_lock: dict[str, str] | None = None,
         adapter_kwargs: dict[str, dict[str, Any]] | None = None,
         metadata: dict[str, str] | None = None,
     ) -> RunResult:
@@ -197,6 +198,7 @@ class BenchmarkService:
             started_at=started_at,
             completed_at=completed_at,
             dependencies_lock=dependencies_lock or {},
+            system_binaries_lock=system_binaries_lock or {},
             metadata=metadata or {},
         )
 

picarones/app/services/dependencies.py

@@ -14,21 +14,30 @@ Chaque ``Distribution`` fournit ``name`` + ``version`` ; on en fait
 un dict ordonné par ``name`` minuscule pour le déterminisme du
 manifest.
 
+Sprint S8.5 — capture des binaires système
+------------------------------------------
+La couche Python (``pytesseract``) ne suffit pas pour reproduire un
+benchmark scientifique : c'est le binaire Tesseract sous-jacent qui
+exécute l'OCR.  ``capture_system_binaries_lock()`` ajoute la version
+du binaire Tesseract (et autres binaires critiques) au manifest, en
+best-effort (silencieux si Tesseract n'est pas installé).
+
 Anti-sur-ingénierie
 -------------------
 - Pas de capture des hashes de wheel : si la BnF veut une preuve
   d'intégrité supply-chain, elle utilise un lockfile Poetry/uv en
   amont — on ne refait pas le travail.
-- Pas de capture des binaires système (Tesseract version, libcuda,
-  fonts) : reporté à un sprint dédié si une ré-exécution échoue
-  pour cette raison.  Le hash du wheel ``pytesseract`` capture déjà
-  la couche Python.
 """
 
 from __future__ import annotations
 
+import logging
+import shutil
+import subprocess
 from importlib.metadata import distributions
 
+logger = logging.getLogger(__name__)
+
 
 def capture_dependencies_lock() -> dict[str, str]:
     """Retourne un dict ``{nom_package: version}`` trié par nom.
@@ -46,4 +55,60 @@ def capture_dependencies_lock() -> dict[str, str]:
     return dict(sorted(lock.items(), key=lambda kv: kv[0].lower()))
 
 
-__all__ = ["capture_dependencies_lock"]
+def _safe_capture_binary_version(
+    binary: str, args: tuple[str, ...] = ("--version",),
+) -> str | None:
+    """Capture la première ligne de sortie de ``<binary> <args>``.
+
+    Retourne ``None`` si le binaire n'est pas dans ``$PATH`` ou si
+    l'invocation échoue.  Ne lève jamais.
+    """
+    if not shutil.which(binary):
+        return None
+    try:
+        result = subprocess.run(
+            [binary, *args],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        logger.debug(
+            "[deps] capture %s %s échouée : %s", binary, " ".join(args), exc,
+        )
+        return None
+    output = (result.stdout or result.stderr).strip()
+    if not output:
+        return None
+    return output.splitlines()[0]
+
+
+def capture_system_binaries_lock() -> dict[str, str]:
+    """Retourne un dict ``{binary_name: version_string}`` pour les
+    binaires système critiques à la reproductibilité scientifique.
+
+    Sprint S8.5 — closes the gap left by the pure-Python
+    ``capture_dependencies_lock`` : la version du wheel
+    ``pytesseract`` ne dit RIEN sur la version du binaire Tesseract
+    qui exécute réellement l'OCR.  Sans capturer cette version,
+    deux runs avec le même ``dependencies_lock`` peuvent produire
+    des CER différents si la base image système a été mise à jour
+    entre temps.
+
+    Best-effort : si un binaire n'est pas installé, sa clé est
+    absente du dict (pas ``None``, pas d'exception).
+    """
+    binaries: dict[str, tuple[str, ...]] = {
+        # Tesseract OCR — version + langues installées.
+        "tesseract": ("--version",),
+    }
+    lock: dict[str, str] = {}
+    for binary, args in binaries.items():
+        version = _safe_capture_binary_version(binary, args)
+        if version:
+            lock[binary] = version
+    return lock
+
+
+__all__ = ["capture_dependencies_lock", "capture_system_binaries_lock"]

picarones/app/services/run_orchestrator.py

@@ -45,7 +45,10 @@ from typing import Any, Callable
 from picarones.app.results import ReportRenderer, RunResult
 from picarones.app.schemas import RunSpec, resolve_adapter_class
 from picarones.app.services.benchmark_service import BenchmarkService
-from picarones.app.services.dependencies import capture_dependencies_lock
+from picarones.app.services.dependencies import (
+    capture_dependencies_lock,
+    capture_system_binaries_lock,
+)
 from picarones.app.services.corpus_service import (
     CorpusImportError,
     CorpusService,
@@ -182,7 +185,10 @@ class RunOrchestrator:
         )
 
         # 6. Capture du verrou de dépendances pour la reproductibilité.
+        # Sprint S8.5 — capture aussi les binaires système (Tesseract,
+        # etc.) qui ne sont pas couverts par le wheel ``pytesseract``.
         deps_lock = capture_dependencies_lock()
+        bin_lock = capture_system_binaries_lock()
 
         result = bench.run(
             corpus=corpus_spec,
@@ -193,6 +199,7 @@ class RunOrchestrator:
             context_factory=_make_context_factory(spec.code_version),
             adapter_kwargs=adapter_kwargs,
             dependencies_lock=deps_lock,
+            system_binaries_lock=bin_lock,
             metadata={"orchestrator": "picarones.app.services.run_orchestrator"},
         )
 

picarones/domain/run_manifest.py

@@ -115,6 +115,15 @@ class RunManifest(BaseModel):
     started_at: datetime
     completed_at: datetime
     dependencies_lock: dict[str, str] = Field(default_factory=dict)
+    #: Sprint S8.5 — versions des binaires système critiques
+    #: (Tesseract, etc.).  Capturé via
+    #: ``picarones.app.services.dependencies.capture_system_binaries_lock``.
+    #: Ferme le trou laissé par ``dependencies_lock`` qui ne couvre
+    #: que les paquets Python — sans cette capture, deux runs avec
+    #: le même ``dependencies_lock`` peuvent produire des CER
+    #: différents si la version Tesseract change entre temps.
+    #: Default empty dict (rétro-compat manifests pré-S8.5).
+    system_binaries_lock: dict[str, str] = Field(default_factory=dict)
     metadata: dict[str, str] = Field(default_factory=dict)
 
     @computed_field  # type: ignore[prop-decorator]

tests/architecture/test_s8_system_binaries_lock.py

@@ -0,0 +1,116 @@
+"""Sprint S8.5 — capture des binaires système dans le RunManifest.
+
+Ferme le trou de reproductibilité laissé par
+``capture_dependencies_lock`` qui ne couvre que les paquets Python.
+La version du binaire Tesseract (qui exécute réellement l'OCR) n'est
+pas dans le wheel ``pytesseract`` et doit être capturée séparément.
+
+Sans cette capture, deux runs avec le même ``dependencies_lock``
+peuvent produire des CER différents si la version Tesseract change
+entre temps (ex : Debian point-release).
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+
+
+# ──────────────────────────────────────────────────────────────────────
+# 1. capture_system_binaries_lock — best-effort
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestCaptureSystemBinariesLock:
+    def test_returns_dict(self) -> None:
+        from picarones.app.services.dependencies import (
+            capture_system_binaries_lock,
+        )
+        lock = capture_system_binaries_lock()
+        assert isinstance(lock, dict)
+
+    def test_includes_tesseract_when_installed(self) -> None:
+        """Si ``tesseract`` est dans ``$PATH``, sa version doit être
+        capturée."""
+        from picarones.app.services.dependencies import (
+            capture_system_binaries_lock,
+        )
+        import shutil
+
+        if not shutil.which("tesseract"):
+            pytest.skip("tesseract non installé sur ce système")
+
+        lock = capture_system_binaries_lock()
+        assert "tesseract" in lock
+        assert "tesseract" in lock["tesseract"].lower()  # ex : "tesseract 5.3.0"
+
+    def test_missing_binary_silently_omitted(self) -> None:
+        """Si un binaire n'est pas dans ``$PATH``, sa clé est absente
+        du dict (pas ``None``, pas d'exception)."""
+        from picarones.app.services.dependencies import (
+            _safe_capture_binary_version,
+        )
+        result = _safe_capture_binary_version("definitely_not_a_real_binary_xyz")
+        assert result is None
+
+    def test_safe_capture_handles_subprocess_error(self) -> None:
+        """``subprocess.run`` qui timeout ou crash → ``None``, pas
+        de propagation."""
+        from picarones.app.services.dependencies import (
+            _safe_capture_binary_version,
+        )
+
+        # Mock pour simuler un binaire qui timeout.
+        import subprocess
+        with patch("shutil.which", return_value="/fake/path"):
+            with patch(
+                "subprocess.run",
+                side_effect=subprocess.TimeoutExpired("fake", 5),
+            ):
+                result = _safe_capture_binary_version("fake")
+                assert result is None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# 2. RunManifest accepte system_binaries_lock
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestRunManifestField:
+    def test_default_empty_dict(self) -> None:
+        """Manifests pré-S8.5 sans le champ doivent rester
+        désérialisables."""
+        from datetime import datetime, timezone
+
+        from picarones.domain.run_manifest import RunManifest
+
+        m = RunManifest(
+            run_id="r",
+            corpus_name="c",
+            n_documents=0,
+            code_version="1.0.0",
+            started_at=datetime.now(timezone.utc),
+            completed_at=datetime.now(timezone.utc),
+        )
+        assert m.system_binaries_lock == {}
+
+    def test_field_persisted_in_serialization(self) -> None:
+        """Le champ apparaît dans le dump JSON pour les ingesters
+        externes (BnF audit)."""
+        from datetime import datetime, timezone
+
+        from picarones.domain.run_manifest import RunManifest
+
+        m = RunManifest(
+            run_id="r",
+            corpus_name="c",
+            n_documents=0,
+            code_version="1.0.0",
+            started_at=datetime.now(timezone.utc),
+            completed_at=datetime.now(timezone.utc),
+            system_binaries_lock={"tesseract": "tesseract 5.3.0"},
+        )
+        dumped = m.model_dump()
+        assert "system_binaries_lock" in dumped
+        assert dumped["system_binaries_lock"]["tesseract"] == "tesseract 5.3.0"