Déploiement de la vitrine Cinoc

.gitattributes

@@ -0,0 +1,8 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+*.woff filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,90 @@
+# Image **moteur** Cinoc pour un Hugging Face Space (SDK: docker).
+#
+# ≠ la vitrine lecture seule (deploy/Dockerfile{,.space}) : celle-ci **bake un vrai
+# moteur OCR gratuit** (Tesseract 5 + langues fra/lat/eng) pour qu'un visiteur du
+# Space public lance un run Tesseract **sans clé ni installation**. Les moteurs
+# cloud et les plugins tiers restent *gated* (mode public, fail-closed côté appli).
+#
+# Contexte de build « racine plate » (Dockerfile / requirements.txt / pyproject.toml
+# / cinoc / reports TOUS à la racine) — assemblé par .github/workflows/deploy-space.yml,
+# comme Dockerfile.space.
+FROM python:3.11-slim
+
+# ── Dépendances système : Tesseract 5 + langues + libs image (Pillow) ──────────
+# Les langues sont baquées (pas téléchargées au runtime) : un Space free-tier n'a
+# pas d'accès réseau garanti au démarrage, et le déterminisme exige une version de
+# binaire figée. ``fra`` est le besoin patrimonial central ; ``lat`` (latin) et
+# ``eng`` complètent. Pas de pin de version exacte (Debian point-release rebump
+# fréquemment ``5.3.0-2`` → ``+deb12u1`` → casse le build) : la repro repose sur la
+# capture de ``tesseract --version`` dans ``RunManifest.system_binaries_lock``.
+RUN apt-get update -o Acquire::Retries=3 \
+    && apt-get install -y --no-install-recommends -o Acquire::Retries=3 \
+        tesseract-ocr \
+        tesseract-ocr-fra \
+        tesseract-ocr-lat \
+        tesseract-ocr-eng \
+        libtiff6 \
+        libjpeg62-turbo \
+        libpng16-16 \
+        libwebp7 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Variables d'exécution ──────────────────────────────────────────────────────
+# TESSDATA_PREFIX : emplacement Debian bookworm des modèles Tesseract 5.
+ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
+# OMP_THREAD_LIMIT=1 : OBLIGATOIRE sur free-tier 2 vCPU. Tesseract LSTM (oem 3)
+# parallélise via OpenMP ; non borné sur un CPU partagé il **deadlock** (incident
+# documenté côté Picarones, 2026-05-16) — l'OCR gèle et chaque document timeoute.
+# Mono-thread par appel = plus rapide ET déterministe ici.
+ENV OMP_THREAD_LIMIT=1
+# Mode public (verrou *fail-closed*) **non forcé** : par défaut l'instance exécute
+# ses moteurs (cloud compris) avec la clé de l'opérateur — pas de 403. Qui expose
+# un Space **public** et veut protéger sa clé d'un visiteur pose lui-même
+# CINOC_PUBLIC_MODE=true (alors seul le socle gratuit tesseract s'exécute).
+ENV PYTHONUNBUFFERED=1
+
+# ── Smoke-test du binaire au BUILD (fail-fast) ─────────────────────────────────
+# Un Tesseract cassé OU figé doit casser le BUILD (le Space garde l'image
+# précédente fonctionnelle), pas déployer une image qui gèle en silence :
+#   (a) le binaire charge ses libs et expose la langue ``fra`` (sinon build refusé) ;
+#   (b) une reconnaissance réelle sur une image générée se TERMINE sous 30 s — un
+#       timeout (rc 124) = deadlock OpenMP / libs incohérentes → build refusé.
+RUN set -eu; \
+    timeout 30 tesseract --version; \
+    timeout 30 tesseract --list-langs 2>&1 | grep -qx fra; \
+    printf 'P1\n16 16\n' > /tmp/smoke.pbm; \
+    i=0; while [ "$i" -lt 16 ]; do \
+        printf '1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0\n' >> /tmp/smoke.pbm; \
+        i=$((i + 1)); \
+    done; \
+    rc=0; \
+    timeout 30 tesseract /tmp/smoke.pbm - -l fra --psm 6 >/dev/null 2>&1 || rc=$?; \
+    rm -f /tmp/smoke.pbm; \
+    if [ "$rc" = 124 ]; then \
+        echo "FATAL: tesseract a gelé (timeout) — build refusé, libs incohérentes." >&2; \
+        exit 1; \
+    fi
+
+# ── Utilisateur non-root (sécurité d'un service exposé) ────────────────────────
+RUN useradd --create-home --uid 1000 cinoc
+WORKDIR /home/cinoc/app
+
+# ── Dépendances Python d'abord (cache de couche) ───────────────────────────────
+# requirements.txt fige le cœur + l'extra [serve] + pytesseract (wrapper du binaire).
+COPY requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ── Code + paquet (sans deps : tout est déjà figé ci-dessus) ───────────────────
+COPY pyproject.toml README.md ./
+COPY cinoc ./cinoc
+RUN pip install --no-cache-dir --no-deps .
+
+# ── Rapports bakés (lecture seule) — dossier toujours présent ──────────────────
+COPY reports ./reports
+ENV CINOC_REPORTS_DIR=/home/cinoc/app/reports
+
+USER cinoc
+EXPOSE 7860
+# 0.0.0.0 attendu en conteneur (le réseau est géré par la plateforme).
+CMD ["cinoc", "serve", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,52 @@
+---
+title: Cinoc — banc d'essai OCR/HTR/VLM
+emoji: 📜
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# Cinoc — banc d'essai OCR/HTR/VLM
+
+Banc d'essai **déterministe** de pipelines de transcription (OCR / HTR / VLM).
+Ce Space **exécute un vrai OCR Tesseract gratuitement** — **sans clé ni
+installation** : déposez un corpus, lancez Tesseract, obtenez un rapport CER/WER/MER
+réel. Il sert aussi des rapports `RunResult` pré-calculés, rendus en HTML autonome.
+
+- `/` — liste des rapports disponibles
+- `/library` — préparer un corpus (upload ZIP)
+- `/benchmark` — lancer un run **Tesseract** (gratuit, local) sur un corpus
+- `/reports/<nom>` — un rapport rendu en HTML
+- `/health` — sonde de vivacité
+
+**Par défaut, l'instance exécute ses moteurs avec la clé de son opérateur** —
+aucun blocage. Sans clé posée, seul le **socle gratuit** tourne (Tesseract, aucun
+secret, aucun appel facturé) ; dès qu'une clé est présente (`MISTRAL_API_KEY`,
+`OPENAI_API_KEY`…), les moteurs **cloud** (OCR→LLM, VLM) s'exécutent normalement.
+
+## Utiliser un moteur cloud (Mistral, OpenAI…)
+
+1. **Secret** : `MISTRAL_API_KEY` = votre clé (Settings → Variables and secrets).
+   Le SDK `mistralai` est déjà dans `requirements.txt`. Redéployez.
+2. C'est tout : le menu déroulant « Modèle » du Banc d'essai se remplit directement
+   depuis l'API Mistral (`models.list`) et les prompts sont éditables par concurrent.
+
+> 🔴 **Sécurité** : sur un Space **public**, la clé que vous posez est dépensable par
+> n'importe quel visiteur. Rendez le Space **Private** (Settings → Visibility →
+> Private) si vous y posez une clé facturée, **ou** activez le verrou ci-dessous.
+
+## Verrou « mode public » — opt-in, pour protéger une clé sur un Space public
+
+Si vous tenez à exposer un Space **public** *tout en* gardant une clé posée sans
+qu'un visiteur puisse la dépenser, activez le verrou **fail-closed** : variable
+`CINOC_PUBLIC_MODE` = `true` (Settings → Variables and secrets). Alors seul le
+**socle gratuit** (Tesseract) s'exécute ; les moteurs **cloud**, les **imports
+distants** (IIIF/Gallica/…) et les **plugins tiers** sont **refusés** (`403`). Le
+verrou est **désactivé par défaut** : ne le posez que si ce scénario est le vôtre.
+
+> Ce fichier est l'en-tête de configuration du Space Hugging Face (`sdk: docker`).
+> Au déploiement, il devient le `README.md` racine du dépôt du Space ; le
+> `Dockerfile` et `requirements.txt` vivent dans `deploy/`.

cinoc/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1.dev1+g7ca8e2eab'
+__version_tuple__ = version_tuple = (0, 1, 1, 'dev1', 'g7ca8e2eab')
+
+__commit_id__ = commit_id = 'g7ca8e2eab'

cinoc/adapters/ANALYSE_COUCHE_5.md

@@ -0,0 +1,271 @@
+# ANALYSE_COUCHE_5.md — `adapters/` (Picarones → Cinoc)
+
+> **Type** : session d'ANALYSE (ne code rien). Guide de portage **durable**.
+> **Couche** : 5 = `adapters` (cf. `CLAUDE.md` §3 : `domain(1) ← formats(2) ← evaluation(3) ← pipeline(4) ← adapters(5) ← app(6) ← reports(7) ← interfaces(8)`).
+> **Source gelée** : `../Picarones/picarones/adapters/` — **41 fichiers, 9 682 LOC** (mesuré).
+> **Cible** : `cinoc/adapters/`.
+> **Couches amont mergées dont on dépend** : `domain` (mergée), `formats` (mergée), `evaluation` (plan acté `MIGRATION_COUCHE_3.md`), `pipeline` (à venir — porte le **contrat de module**).
+> **Partie 1 = durable** (source figée). **Partie 2 = périssable** (« à confirmer à la tranche »).
+
+---
+
+## 0. Drapeaux à lever AVANT toute construction (lire en premier)
+
+| # | Drapeau | Statut | Action |
+|---|---|---|---|
+| **F-0** | La consigne d'analyse disait « Couche4 », le titre/ livrable disent « couche 5 ». | Coquille. `CLAUDE.md` §3 + `PROMPT_ANALYSE_COUCHE.md` confirment **couche 5 = `adapters`**. | Aucun conflit. Analysé = `adapters`. |
+| **F-1** | `CLAUDE.md` D1 décrit le legacy comme « double contrat **`BaseOCRAdapter`→`BaseModule`** ». **Le code gelé ne contient PAS cet héritage.** | `base.py:58` = `class BaseOCRAdapter(ABC)` ; `llm/base.py:202` = `class BaseLLMAdapter(ABC)` ; **aucun n'hérite de `BaseModule`**. Le vrai contrat runtime est **`StepExecutor`** (`pipeline/protocols.py:42`, `execute(...)`). `BaseModule` (`domain/module_protocol.py`, `process(...)`) est **vestigial** : sa docstring `:24-27` *prétend* (à tort) que les adapters en sont des cas particuliers ; ses seuls usages sont un ré-export dans `__init__` + `evaluation/metrics/module_policy.py` (lui-même classé « mort » par `MIGRATION_COUCHE_3.md` §11). | **Ne PAS s'arrêter** : la *décision* D1 (un seul `Protocol` en couche 4, `BaseModule` supprimé) reste **correcte et même renforcée** — Picarones a déjà ce `Protocol` unique (`StepExecutor`). Seule la *caractérisation factuelle* de la source est à corriger : il s'agit d'un contrat **vestigial parallèle** (`BaseModule.process`), pas d'un emballage. Documenté §1.2. |
+| **F-2** | `CLAUDE.md` §8.8 dit « 8+8+8 adapters LLM/VLM ». | Réalité : **8 OCR + 4 LLM + 4 VLM**. | Direction (« → minimal/starter ») valide ; chiffres rectifiés §1.1. |
+| **F-3** | `_fallback_log.py` n'a qu'un consommateur final : le **détecteur narratif** `IMPORTER_FALLBACK_TRIGGERED`. | Or le **moteur narratif est SUPPRIMÉ** (`CLAUDE.md` §6, D2). | ⇒ « pas de consommateur = supprimé ». Verdict **SUPPRIMER** (remplacé par `logger.warning`). §1.3-corpus. |
+
+Aucun de ces points ne contredit une couche **mergée** ni une décision actée → analyse poursuivie.
+
+---
+
+# PARTIE 1 — ANALYSE DE LA SOURCE PICARONES (durable)
+
+## 1.1 Inventaire exact (41 fichiers / 9 682 LOC)
+
+| Sous-paquet | Fichiers | LOC | Rôle vérifié |
+|---|---|---|---|
+| **`/` (utils racine)** | 6 | **866** | I/O atomique, retry, http(x), downscale image, résolution de chemins. Mutualisés OCR+LLM. |
+| **`ocr/`** | 12 | **3 206** | Contrat `BaseOCRAdapter` + factory + 8 moteurs + sidecar confidences. |
+| **`corpus/`** | 8 | **3 045** | Importeurs de corpus patrimoniaux (IIIF, Gallica, eScriptorium, HTR-United, HuggingFace) + http urllib anti-SSRF + journal fallback. |
+| **`llm/`** | 6 | **1 208** | Post-correction texte (`RAW_TEXT → CORRECTED_TEXT`). Base + 4 providers. |
+| **`storage/`** | 3 | **964** | `ArtifactStore` (cache fichier) + `JobStore` (SQLite jobs web). |
+| **`vlm/`** | 6 | **393** | Transcription `IMAGE → RAW_TEXT` zéro-OCR. Base + 4 manifestes de composition. |
+
+Libs externes (toutes confinées à `adapters/`, conforme `CLAUDE.md` §3) : `pytesseract`+`PIL` (tesseract), `kraken`, `calamari-ocr`+TF, `pero-ocr`+torch, `google-cloud-vision`, `azure-ai-documentintelligence`, `mistralai`, `openai`, `anthropic`, `httpx` (ollama — **dép. cœur**, pas un extra), `datasets` (hf), `yaml`/`tqdm` (corpus). Le **noyau de contrat** (`ocr/base.py`, `factory.py`, `confidences.py`, `llm/base.py`, `vlm/base.py`, utils racine) n'importe **aucune** lib tierce sauf `httpx`/`PIL`.
+
+## 1.2 Le contrat réel (la couture décisive `domain↔pipeline↔adapters`)
+
+**Trois contrats coexistent ; un seul est vivant côté runtime.**
+
+| Contrat | Lieu | Forme | Statut réel |
+|---|---|---|---|
+| `BaseModule` | `domain/module_protocol.py:39` | `process(inputs)→outputs`, types `tuple`, **aucun** concern d'exécution | **Vestigial.** Aucun adapter ne l'hérite ni ne l'implémente. Consommateurs : ré-export `__init__` + `module_policy.py` (mort). |
+| **`StepExecutor`** | `pipeline/protocols.py:42` | `name`,`input_types`/`output_types` (`frozenset`), **`execute(inputs, params, context: RunContext, control: RunControl) → dict[ArtifactType, Artifact]`** | **Contrat vivant.** Porte deadline (`context.deadline`) + annulation (`control`). Satisfait par **duck-typing** (jamais hérité). |
+| `BaseOCRAdapter` / `BaseLLMAdapter` / `BaseVLMAdapter` | `adapters/{ocr,llm,vlm}/base.py` | ABC d'**implémentation** (défauts `input_types`/`output_types`, helpers, `name`/`execute` abstraits) | Ce sont des **mixins d'implémentation**, **pas** un second contrat. `BaseVLMAdapter(BaseLLMAdapter)` ; les deux autres `(ABC)`. |
+
+**Résolution `adapter_name → executor`** : pas de registre. `build_adapter_resolver(engines)` (`app/services/_benchmark_adapter_resolver.py:215`) construit un `dict[str, StepExecutor]` à partir d'**instances** d'engines fabriquées en amont, et lève `PicaronesError` sur collision de `name` à configs distinctes. La factory `ocr_adapter_from_name` (`ocr/factory.py:64`) est une **cascade `if/elif` codée en dur** (anti-OCP). **Aucune découverte de plugins entry-points** (`registry_service.py:39` le dit explicitement). Seule extensibilité « tierce » : `adapter_class: dotted.path` dans le YAML `run_spec` (`app/schemas/run_spec.py:32-62`), classe importable dans le venv.
+
+> ⚠️ **Conséquence pour Cinoc** : le `Protocol` de module que `CLAUDE.md` D1 veut construire en **couche 4** ≈ **`StepExecutor` déjà existant**. Les adapters l'implémentent **directement**. `BaseModule` est **supprimé sans perte**. *(`version` manque dans `StepExecutor`/`BaseOCRAdapter` → à **ajouter** pour la repro `RunManifest`, cf. §2.1.)*
+
+## 1.3 Verdicts fichier par fichier — **PROVISOIRE — à confirmer au build**
+
+Légende verdict : **G**=garder · **M**=modifier · **C**=changer de couche · **S**=supprimer · **I**=incrémental (porter à la tranche qui le consomme, pas avant).
+
+### Utils racine (`adapters/*.py`)
+
+| Fichier | LOC | Rôle vérifié | Consommateurs réels (hors tests) | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 28 | Docstring de paquet, `__all__=[]`. | 0 (imports par chemin complet). | — | **G** (mince) |
+| `_atomic_io.py` | 151 | `atomic_write_text` (tmp+`fsync`+`os.replace`). | `atomic_write_text` : **11 adapters**. | `atomic_write_bytes` = **0 conso** (mort). Corps dupliqué text/bytes. | **M** : garder `atomic_write_text`, **S** `atomic_write_bytes`. **`storage/` doit l'utiliser** (cf. infra). |
+| `_httpx_helpers.py` | 213 | Client httpx deadline-aware + cancel cross-thread (`make_httpx_client`, `translate_or_reraise`). | **1** (`llm/ollama_adapter`). | Détection « close » par **heuristique de message** (`:179-190`) fragile. Couple `adapters→pipeline.run_control`. | **G+M** (revoir l'heuristique ; unifier la trad. d'erreur). |
+| `_image.py` | 87 | Downscale image base64 (`PIL` lazy, dégradable). | **3** (ollama/openai/mistral LLM). | Bloc d'appel `if max_edge>0: downscale` **copié 3×** chez les callers. | **G** (factoriser l'appel dans la base LLM). |
+| `_retry.py` | 274 | Retry exponentiel + `Retry-After` + jitter, deadline-aware (`call_with_retry`, `is_retryable`, `compute_retry_wait`). | `call_with_retry` : **3 OCR cloud** ; primitives : `llm/base.py`. | **Bug** : jitter `×[1.0,1.5)` appliqué **après** le plafond → `DEFAULT_MAX_WAIT` (120 s) dépassé jusqu'à **180 s** (`:138-139`). `retry_after_seconds`/`DEFAULT_MAX_WAIT` exportés sans conso externe. **Boucle ré-implémentée** dans `llm/base.py:384-429` ET `corpus/_http.download_url`. | **M** : corriger le jitter ; **unifier les 3 implémentations** ; resserrer l'API publique. |
+| `output_paths.py` | 113 | `resolve_output_path` (segment par pipeline anti-collision). | **9 adapters**. | `context: Any` (duck-typing `RunContext`) → dégrade en silence si attribut absent. | **G**. |
+
+### `ocr/`
+
+| Fichier | LOC | Rôle / sortie | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 48 | Façade ; ré-exporte les 8 adapters + base + factory. | traversé par `llm_pipeline_config`. | **Import eager** des 8 classes (sûr car les modules n'importent pas la lib lourde au top-level) mais court-circuite la robustesse lazy de la factory. | **M** (mince ; aligner sur le registre). |
+| `base.py` | 189 | `BaseOCRAdapter(ABC)` + `OCRAdapterError`. **`effective_output_types`** = sous-ensemble **garanti** (vs maximal). | 8 adapters + resolver + factory + cli + robustness. | **Pas d'attribut `version`** (repro). `control` jamais honoré (cf. dette §1.4). | **M** : = mixin d'impl ; **ajouter `version`** ; garder `effective_output_types`. Contrat = `Protocol` couche 4. |
+| `factory.py` | 194 | `ocr_adapter_from_name(name) → BaseOCRAdapter`. | cli + web + `__init__`. | **Cascade `if/elif`** (anti-OCP) ; alias incohérents (`calamari_ocr`→`calamari`, pas de court `kraken`) ; `_SUPPORTED`/`_ALIASES` divergent à la main ; message Azure cite `azure-ai-formrecognizer` ≠ SDK réel. | **C→app** : remplacer par **registre + entry-points** (`CLAUDE.md` §3 : registre = app/adapters, découverte = app). |
+| `confidences.py` | 164 | Sidecar JSON de confidences. `ConfidenceToken`=TypedDict `{text, confidence∈[0,1]}`, **niveau mot**, normalisation Tesseract 0-100→0-1. | **1** (tesseract). Artefact `CONFIDENCES` lu par `evaluation/calibration`. | `model_version:null` toujours sérialisé ; entrée `list[dict]` non typée. | **G+M** : logique en adapters ; **promouvoir `ConfidenceToken`→`domain`** quand la calibration est consommée (backlog domain `CLAUDE.md`). |
+| `precomputed.py` | 221 | **Starter.** Lit `<stem>.<label>.txt`. `IMAGE→RAW_TEXT`. 0 dép externe. | factory + builders. | Nommage `name` = `precomputed_<label>` (`_`) ≠ doc factory (`:`). `control` inutilisé ; double I/O policy `empty`. | **G** (starter) ; corriger nommage. |
+| `tesseract.py` | 548 | **Starter.** `pytesseract` (binaire). `RAW_TEXT` (+`CONFIDENCES`/`ALTO_XML` **opt-in** via `effective_output_types`). | factory + cli + web. | >400 LOC. `control` inutilisé (timeout subprocess compense). | **G** (starter) ; **trim/split <400**. |
+| `kraken.py` | 237 | HTR ML local (torch). `RAW_TEXT`. Extra `[kraken]`. | factory + web. | Deadline **ignorée** (inférence non interruptible) ; API Kraken 4.x fragile vs 5.x. | **G+I** (incrémental). |
+| `calamari.py` | 253 | OCR ligne (TF). `RAW_TEXT`. Extra `[calamari]`. | factory + web. | Parsing résultat fragile (`getattr(...,"sentence","")`) ; deadline ignorée. | **G+I**. |
+| `pero_ocr.py` | 226 | HTR ML local (torch, PAGE aplati). `RAW_TEXT`. | factory + web. | Docstring tronquée (`:1-3`) ; deadline ignorée ; ordre `page_size=(h,w)` à vérifier. | **G+I**. |
+| `google_vision.py` | 330 | Cloud (SDK **ou** REST/urllib). `RAW_TEXT`. | factory + web. | SDK path ignore la deadline ; motif HTTP dupliqué (cf. azure/mistral). | **G+I**. |
+| `azure_doc_intel.py` | 425 | Cloud async + polling (SDK ou REST). `RAW_TEXT`. | factory + web. | >400. **Meilleure gestion deadline** (REST) ; SDK path l'ignore. Backoff maison. | **G+I** ; trim<400. |
+| `mistral_ocr.py` | 371 | `/v1/ocr` (urllib) **ou** chat/vision (SDK). `RAW_TEXT`. | factory + web. | SDK chat ignore deadline. **Importe `adapters.llm.base.normalize_llm_content`** (couplage cross-famille). | **G+I** ; sortir `normalize_*` en helper partagé. |
+
+### `llm/` + `vlm/`
+
+| Fichier | LOC | Rôle / contrat | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `llm/__init__.py` | 16 | Docstring cadrage. | 0. | — | **G**. |
+| `llm/base.py` | 582 | **Cœur.** `BaseLLMAdapter(ABC)`. **Double API** : `complete(prompt, image_b64, *, deadline, control)→LLMResult` (appel + retry) **et** `execute(...)` (orchestration fichier→complete→fichier). `RAW_TEXT→CORRECTED_TEXT`. | pipeline (llm_config/builder) + VLM + `mistral_ocr` (helper). | >400. `LLMResult.tokens_used` **jamais peuplé** (`:194` vs `:396`) → coût non remonté. `except Exception`(`:401`) intentionnel+tracé. | **M** : **split <400** (helpers / `LLMResult` / base / orchestration) ; **peupler ou supprimer `tokens_used`**. |
+| `llm/openai_adapter.py` | 123 | **Starter.** SDK `openai`, extra `[llm]`, `temperature=0`. | web factory. | `del control` (SDK non câblé, documenté). | **G** (starter). |
+| `llm/ollama_adapter.py` | 160 | **Starter.** httpx brut (**dép. cœur**), **seul à câbler `control`** (cancel cross-thread). | web factory. | `except (TimeoutException, HTTPError): pass` (`:131-132`) — re-raise délégué, à mieux commenter. | **G** (starter). |
+| `llm/anthropic_adapter.py` | 129 | Idem motif, extra `[llm]`. | web factory. | `del control`. | **G+I**. |
+| `llm/mistral_adapter.py` | 198 | Idem + table `_TEXT_ONLY_MODELS` (dégradé multimodal). | web factory. | Logs verbeux ; instance client par appel. | **G+I**. |
+| `vlm/__init__.py` | 42 | Façade ré-export. | 0 (hors tests). | — | **G+I**. |
+| `vlm/base.py` | 245 | `BaseVLMAdapter(BaseLLMAdapter)` : `IMAGE→RAW_TEXT`, override `execute` + prompts ; **garde-fou MRO** (`__init_subclass__`). | 0 instanciateur (2 docs). | — | **G+I** (porter à la tranche `zero_shot`). Conserver le garde MRO. |
+| `vlm/openai_vlm.py` | 22 | `(BaseVLMAdapter, OpenAIAdapter)` + `name`. | **0**. | — | **I/S** : ~90 % hérité, **0 conso** → ne **pas** porter spéculativement (porter à la tranche zero_shot). |
+| `vlm/anthropic_vlm.py` | 32 | idem. | **0**. | — | **I/S** idem. |
+| `vlm/mistral_vlm.py` | 26 | idem + `default_model=pixtral`. | **0**. | — | **I/S** idem. |
+| `vlm/ollama_vlm.py` | 26 | idem + `default_model=llava`. | **0**. | — | **I/S** idem. |
+
+### `corpus/`
+
+| Fichier | LOC | Source / sortie | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 24 | Docstring « nommer/localiser (image, GT) » ; `__all__=[]`. | 0. | — | **G** (mince). |
+| `_http.py` | 270 | urllib + **anti-SSRF** (`validate_http_url`, blocage IP réservées, revalidation redirects) + retry deadline-aware. | iiif, gallica, escriptorium. | `install_opener` = **effet de bord global au process** (`:159`). Boucle retry ≈ `_retry`. | **G+M** : brique sécurité réutilisable (invariant `CLAUDE.md`) ; retirer l'`install_opener` global ; unifier le retry. |
+| `_fallback_log.py` | 98 | Journal mémoire des dégradations d'importeur. | `consume`←app `_benchmark_converter` → **détecteur narratif**. `record`←htr_united/hf. | Seul débouché = narratif. | **S** (narratif supprimé `CLAUDE.md` §6 → plus de consommateur ; remplacer par `logger.warning`). |
+| `iiif.py` | 567 | Manifeste IIIF v2/v3 → **`Corpus`**. | CLI (`import iiif`) + web + gallica. | >400. **Fuite de fichiers temp** si `output_dir=None` (`NamedTemporaryFile(delete=False)`, `:465`). `tqdm` lazy. | **G+I+M** : trim<400 ; corriger la fuite temp. Référence du contrat « → Corpus ». |
+| `gallica.py` | 563 | SRU+IIIF+OCR brut BnF → **`Corpus`** (délègue à `IIIFImporter`). | web seulement. | >400. **Bug latent** `selected_indices[i]+1` (additionne `IIIFCanvas`+int, `:415`). `_fetch_url` force `retries=1`. Beaucoup de surface morte (`search_gallica`, `get_metadata`…). | **M+I** : corriger le bug ; **S** des fonctions sans conso ; trim<400. |
+| `escriptorium.py` | 571 | API REST eScriptorium → **`Corpus`** + écriture distante (export couche OCR). | web (`import_document` seul). | >400. **BUG dur** `Corpus(source=...)` (champ = `source_path`, `:450`) → `TypeError` au 1ᵉʳ appel réel, **masqué par les mocks**. `image_path:str` ≠ domain `Path`. ~40 % surface API morte. | **M+I** : corriger le bug ; **S** `export_benchmark_as_layer`/`list_*`/`connect_*` (0 conso) ; trim<400. |
+| `htr_united.py` | 488 | Catalogue HTR-United (GitHub) → **dict-manifeste** (pas `Corpus`) + GT extraits (sans images). | web. | >400. **Pas de `_http`** (ni anti-SSRF ni retry). `except (URLError, Exception)`. ZIP **chargé entier en RAM**. `_DEMO_CATALOGUE`=**113 LOC de données fabriquées** dans le code. | **M+I** : sortie unifiée `Corpus` ; **données démo → `data/` (S du code)** ; passer par `_http` ; borner le download. |
+| `huggingface.py` | 464 | HF Hub (lib `datasets`) → **dict-manifeste** + paires `.jpg`/`.gt.txt`. | web. | >400. **Monkey-patch au load** (`_patch_dataset_replace_source`, `:456`). `except (ImportError, Exception): return 0` **muet** (lib absente indistinguable de dataset cassé). GT orphelin si `image.save` échoue. `_REFERENCE_DATASETS`=**109 LOC** en dur. Docstring annonce des fonctions inexistantes. | **M+I** : sortie unifiée `Corpus` ; extra `[hf]` + message clair ; supprimer le monkey-patch ; données → `data/`. |
+
+### `storage/`
+
+| Fichier | LOC | Backend / type | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 58 | Façade ré-export. Docstring annonce 2 cibles **non livrées** (migration `web/jobs`, rapatriement history SQLite). | — | — | **G**. |
+| `artifact_store.py` | 417 | **Filesystem** (`index.jsonl` + `artifacts/<key>.json` + `payloads/<key>.bin`) indexé par `ArtifactKey.hash_hex()`. Expose `StoredArtifact{key, artifact, payload}`. | **0 direct** : consommé via le **Protocol `ArtifactCachePort`** (`pipeline/cache_protocol.py`) injecté dans l'executor (inversion de dépendance). | >400. **`put` non atomique** (3 écritures sous simple `Lock`) ; **pas de `fsync`** (réimplémente un écriture inférieure au lieu d'utiliser `_atomic_io`) ; **path-traversal non gardé** (`f"{key}.json"`) ; index non borné ; pas de concurrence multi-process. | **G+M** : **utiliser `_atomic_io`** ; **valider la clé / `validated_path`** (invariant `CLAUDE.md`) ; implémente un **port défini en couche 4**. Tranche *cache*. |
+| `job_store.py` | 489 | **SQLite** (table `jobs`, WAL, `schema_version`). `JobRecord`, `JobStore`. États `pending→running→{complete\|error\|cancelled\|interrupted}`. | **1** : `app/services/job_runner.py`. | >400. **Doublon** : un **2ᵉ `JobStore` legacy** vit en `interfaces/web/jobs.py:103` et c'est **lui** que l'app web tournante câble (`state.py:138`). `LIMIT` interpolé (neutralisé par `int()`). Pas de validation des transitions. | **G+M** : **UN seul** job store (celui-ci) ; **S** le doublon legacy (couche 8, hors périmètre mais à acter) — ⚠️ mais le canonical **n'a ni `job_events` ni reprise SSE `Last-Event-ID`** (assumé `job_store.py:48-54`), capacités que porte le legacy `web/jobs.py` **et dont dépend le stream SSE du web** (cf. `ANALYSE_COUCHE_8` §0/§1.3 D-γ) → **réabsorber l'événementiel AVANT** de supprimer le legacy ; valider les transitions. Tranche *web/async*. |
+
+`StoredArtifact` : **non-candidat domain confirmé** (`domain/artifact_key.py:22-24` : « infrastructures, pas des types purs » ; le pipeline le touche via Protocol, pas en direct). Reste en `adapters/storage`.
+
+## 1.4 Dette transverse vérifiée (durable)
+
+| # | Dette | Preuve | Portée |
+|---|---|---|---|
+| **D-A** | **`control: RunControl` jamais honoré** : tous les `execute()` OCR + LLM/VLM cloud le reçoivent mais **n'appellent jamais** `register_cancel_handle`. **Seul `ollama_adapter` câble l'annulation** (via `_httpx_helpers`). | `base.py:82-86` documente le contrat ; aucun adapter ne l'honore sauf ollama. | Gap d'annulation cross-thread généralisé. |
+| **D-B** | **Deadline asymétrique** : Tesseract (timeout subprocess) + Azure-REST (polling clampé) la respectent ; **tous les paths SDK** (Azure SDK, Google SDK, Mistral chat) l'ignorent (limite SDK) ; kraken/calamari/pero l'ignorent totalement. | `azure_doc_intel.py:366-379` (bon) vs `:261` (SDK ignore) ; `mistral_ocr.py:310-316`. | Un run ML local/SDK peut dépasser le budget en silence. |
+| **D-C** | **Retry implémenté 3×** : `_retry.call_with_retry`, `llm/base.py:384-429` (inline), `corpus/_http.download_url`. | grep. | Triple maintenance du même algorithme. |
+| **D-D** | **Deux piles HTTP** dans la même couche : `httpx` (`_httpx_helpers`+`_retry`, pour OCR/LLM cloud) vs `urllib` (`corpus/_http`, anti-SSRF, pour importeurs). Aucune ne réutilise l'autre. | grep : `corpus/*` n'importe jamais `_retry`/`_httpx_helpers`. | Scission lib/menace **assumée** mais coûteuse. |
+| **D-E** | **`__init__` à effet de bord** : `corpus/_http.py:159` fait `install_opener` **global** au process à l'import. | `:153-161`. | Viole l'esprit « `__init__` minces, aucun effet de bord » (`CLAUDE.md` §7). |
+| **D-F** | **Fracture du contrat de sortie corpus** : iiif/gallica/escriptorium → `Corpus` ; **htr_united/huggingface → `dict`-manifeste** + effets disque. 3/5 écrivent des fichiers. | tableaux §1.3-corpus. | Pas de contrat unique d'ingestion. |
+| **D-G** | **Code mort / surface non câblée** : `atomic_write_bytes` ; exports `_retry` sans conso ; ~40 % d'`escriptorium.py` ; commodités `gallica`/`hf` ; `JobRecord.is_terminal/is_live` ; `_MIGRATIONS` vide. | greps agents. | « pas de consommateur = supprimé ». |
+| **D-H** | **Données fabriquées dans le code** : `_DEMO_CATALOGUE` (113 LOC) + `_REFERENCE_DATASETS` (109 LOC) = ~220 LOC de fausses données servies en repli. | `htr_united.py:44`, `huggingface.py`. | Risque d'afficher du faux contenu ; doit être de la **donnée** (`data/`) ou supprimé. |
+| **D-I** | **Bugs latents masqués par les mocks** : `escriptorium Corpus(source=...)` (`:450`) ; `gallica selected_indices[i]+1` (`:415`). | lecture code + tests mockés. | Régression garantie au 1ᵉʳ appel réel → à corriger au portage. |
+| **D-J** | **`execution_mode` : déjà retiré** (« mensonge structurel », commit `5e13c0d`, mai 2026 — attribut décoratif jamais lu par le runner thread-only). 0 occurrence prod ; garde-fou de test anti-résurrection. | git show. | **Leçon** : ne **jamais** réintroduire d'attribut « au cas où » non câblé. |
+
+---
+
+# PARTIE 2 — RÉORGANISATION CIBLE Cinoc (périssable — « à confirmer à la tranche »)
+
+> Conforme `CLAUDE.md` : **deux axes**, **tranches verticales** (jamais « finir la couche de haut en bas »), **budgets <400 LOC**, **rupture nette zéro shim**, **narrative supprimé**, **« pas de consommateur = supprimé »**. La couche 5 se **remplit par tranches** (chaque adapter naît avec le pipeline qui le consomme), pas en bloc.
+
+## 2.1 Enveloppe (axe 1 — dimensionnée plein-scope, mais **définie en couche 4**)
+
+Le **contrat de module exécutable** n'est **pas** un livrable de la couche 5 : il vit en **couche 4** (`pipeline`, cf. `CLAUDE.md` D1). La couche 5 ne fait que **l'implémenter**. À acter quand on conçoit la couche 4 (rappelé ici car il façonne tous les adapters) :
+
+- **`Protocol` unique** ≈ `StepExecutor` de Picarones : `name`, **`version`** (➕ vs Picarones, repro `RunManifest`), `input_types`/`output_types` (`frozenset[ArtifactType]`), `execute(inputs, params, context, control) → dict`.
+- **`BaseModule` supprimé** (vestigial). Les ABC `Base*Adapter` deviennent de **simples mixins d'implémentation** (défauts + helpers + `_write_text_artifact()`), **pas** un contrat.
+- **`effective_output_types`** (garanti ⊂ maximal) **conservé** — sinon `missing_output` casse les steps quand un extra opt-in (Tesseract `CONFIDENCES`/`ALTO_XML`) n'est pas produit.
+- **Trancher la dette d'annulation `control`** (D-A/D-B) : soit honorer `control` partout où l'opération est annulable, soit assumer explicitement « best-effort deadline » (documenté, testé). Ne pas traîner un paramètre non câblé.
+
+**Registre + découverte (couche `app`, cf. `CLAUDE.md` §3)** : remplacer la cascade `if/elif` + les factories CLI/web dispersées par **un registre type-driven `adapter_name → factory`** + **découverte entry-points `cinoc.modules`** + `register()` local. **Seul point d'extension tiers = les briques de pipeline** (OCR/HTR/VLM/post-correction/segmentation/ordre de lecture/NER). **Corpus, métriques, sections, stores = first-party, non pluggables.**
+
+## 2.2 Surface (axe 2 — incrémentale, par tranches)
+
+**Starter pack** (le strict nécessaire au squelette ambulant) :
+
+| Brique | Fichiers source | Extra | Tranche |
+|---|---|---|---|
+| `precomputed` (OCR 0 dép) | `ocr/precomputed.py` | — | **squelette texte** (corpus pré-calculé → CER) |
+| `tesseract` (OCR binaire) | `ocr/tesseract.py` + `confidences.py` | binaire système | tôt (1ᵉʳ vrai moteur) |
+| `openai` + `ollama` (LLM) | `llm/base.py` + `openai_adapter.py` + `ollama_adapter.py` | `[llm]` (openai) ; `httpx`=cœur (ollama) | tranche OCR+LLM `text_only` |
+| utils racine | `_atomic_io`(text), `_retry`(corrigé+unifié), `output_paths`, `_image`, `_httpx_helpers` | — | portés **en bloc** avec le starter |
+
+**Incrémental (porter à la tranche qui le consomme)** : anthropic/mistral (LLM) ; kraken/calamari/pero/google/azure/mistral_ocr (OCR — extras dédiés) ; **VLM** (tranche `zero_shot` — ~90 % gratuit une fois le LLM porté, **0 conso aujourd'hui → ne pas porter avant**) ; importeurs corpus (un par un) ; `artifact_store` (tranche *cache*) ; `job_store` (tranche *web/async*) ; **store longitudinal *tidy*** (tranche *longitudinal*, **rapatrié** de `evaluation/metrics/history.py` → `adapters/storage`, cf. `MIGRATION_COUCHE_3.md` §8).
+
+## 2.3 Arborescence cible proposée (à confirmer)
+
+```
+cinoc/adapters/
+├── _atomic_io.py        atomic_write_text (+fsync)         [G, -atomic_write_bytes]
+├── _retry.py            retry unifié, jitter corrigé       [M, unifie les 3]
+├── _http.py             transport + anti-SSRF + retry      [fusion _httpx_helpers + corpus/_http ?]
+├── _image.py            downscale (PIL lazy)               [G]
+├── output_paths.py      resolve_output_path                [G]
+├── ocr/                 base(mixin)+precomputed+tesseract  [starter] ; reste incrémental
+│   └── confidences.py   (ConfidenceToken→domain à terme)
+├── llm/                 base+openai+ollama [starter] ; anthropic/mistral incrémental
+├── vlm/                 base+manifestes — tranche zero_shot uniquement
+├── corpus/              importeurs first-party, sortie UNIQUE = Corpus, 1 par tranche
+│                        [_fallback_log SUPPRIMÉ ; données démo → data/]
+└── storage/             artifact_store + job_store (UNIQUE) + history tidy (rapatrié)
+```
+*Note* : la **factory/registre** ne vit **pas** ici mais en `app/` (résolution `adapter_name`) ; la couche 5 ne fait qu'exposer des classes implémentant le `Protocol` couche 4.
+
+## 2.4 Application des 5 garde-fous
+
+- **Rupture nette / zéro shim** : un seul `JobStore` (S le legacy `web/jobs.py`) ; un seul contrat de sortie corpus (`Corpus`, S les dict-manifestes) ; pas de `BaseModule` ; une seule pile HTTP si possible (D-D).
+- **Budgets <400** : `llm/base.py`(582), `escriptorium`(571), `iiif`(567), `gallica`(563), `tesseract`(548), `job_store`(489), `htr_united`(488), `huggingface`(464), `azure`(425), `artifact_store`(417) **dépassent**. La plupart **rétrécissent** après retrait du code mort (D-G), des données démo (D-H) et dédup du boilerplate (`_write_text_artifact`, retry, HTTP). Sinon split ou entrée justifiée `test_file_budgets`.
+- **Pas de consommateur = supprimé** : `atomic_write_bytes`, `_fallback_log`, surface morte d'escriptorium/gallica/hf, exports `_retry` inutiles, VLM concrets tant que `zero_shot` n'existe pas.
+- **Tests d'archi jour 1** : whitelist `adapters/` = `domain` + `pipeline` + `formats` (+ `evaluation` pour le type `Corpus` chargé, **à expliciter** — Picarones le tolérait par wildcard) ; `no-side-effect-import` (tue le `install_opener` global D-E) ; `no-broad-except` (htr/hf `except Exception`) ; `file-budgets`.
+- **Feature entière + élaguée** : chaque adapter porté **avec** sa correction de bug (D-I), son extra optionnel, son message clair d'absence de dép, sans annotation de sprint.
+
+## 2.5 Libs cibles & arbitrages (périssable — « à confirmer à la tranche »)
+
+> Rappel : la minceur de la couche vient surtout de l'**élagage** (code mort, données démo, dédup), **pas** de l'ajout de libs. Une lib ne paie que si elle **retire plus de code que le wrapper qu'elle impose**. Contreparties transverses à toute dép : **supply-chain** (cf. `fastapi==0.136.3` / `MAL-2026-4750` exclue dans le `pyproject` Picarones ; `pip-audit` à tenir), **reproductibilité** (`dependencies_lock` du `RunManifest` → **épingler serré**), **code tiers in-process** (entry-points).
+
+| Lib / appel | Verdict | Raison / condition |
+|---|---|---|
+| `httpx` (transport REST unique) | ✅ **conditionnel** | Pour le REST à **auth simple** (ollama, mistral `/v1/ocr`, HF, eScriptorium, htr_united, openai-compatible). Unifie les 2 piles HTTP (D-D), corrige la deadline (D-B). **Garder le SDK** pour Google/Azure (auth JWT service-account / AD lourde). Anti-SSRF toujours à coder (transport dédié, **sans `install_opener` global** — D-E). |
+| Drop dual SDK/REST cloud | ✅ **conditionnel** | Seulement où le SDK n'offre ni timeout-par-appel ni annulation **et** l'auth est simple. Pas systématique. |
+| `huggingface_hub` | ✅ **extra `[hf]`** | Remplace le REST urllib maison de `huggingface.py` (pagination tronquée, `except` muet, monkey-patch — D-G). Lib lourde/mouvante → confinée à l'extra, épinglée. |
+| `importlib.metadata.entry_points` (stdlib) | ✅ **gaté** | Outil du point d'extension `cinoc.modules`. **Désactiver la découverte en mode public** (in-process = sécurité, `CLAUDE.md` §3) ; capter la **version** du plugin pour le `RunManifest`. |
+| `pydantic` v2 | ✅ **configs** / ❌ **par-token** | OK pour les **configs d'adapter** (petites, 1×, aligne le repo). **Pas** pour `ConfidenceToken` (milliers/page → coût de validation, cf. `MIGRATION_COUCHE_2.md` G-D) : `TypedDict`/`dataclass(slots=True)`, valider une fois à la frontière. |
+| `tenacity` (retry) | ❌ **garder maison** | Le retry doit être deadline/cancel-aware (`clamp_to_remaining`, `RunControl`), honorer `Retry-After`, et **testable déterministe** (horloge injectable). Tenacity impose un wrapper custom qui annule le gain. `_retry.py` maison (bug jitter corrigé) reste plus aligné. |
+| anti-SSRF · parseur IIIF · subprocess Tesseract | ❌ **garder maison** | Pas de lib mainstream fiable (SSRF, IIIF) ; le subprocess `pytesseract` est **ce qui honore la deadline** pour Tesseract — un binding C-API (`tesserocr`) la perdrait. |
+| ORM (SQLAlchemy) · async (`anyio`) | ❌ | `sqlite3` brut suffit (2 tables) ; runner **thread-only** acté (retrait `execution_mode`, D-J) → async = rupture injustifiée. |
+
+**Cible LOC** (rappel, périssable) : enveloppe + starter pack utile ≈ **3 700 LOC** ; parité complète nettoyée ≈ **6 500–7 000 LOC** (vs **9 682** Picarones, ≈ **−30 %**). La couche se remplit par tranches — elle n'a jamais besoin de revoir les 9,7k. *(Détail des leviers de coupe : §1.4 + §2.4.)*
+
+---
+
+# PARTIE 3 — RISQUES DE TRANSFERT & DETTES (avec détection)
+
+| Risque | Détail | Comment détecter / désamorcer |
+|---|---|---|
+| **R-1 Contrat couche 4 manquant** | La couche 5 ne peut être portée **qu'après** le `Protocol` de module (couche 4) + `RunContext`/`RunControl`/`Deadline`. | Construire d'abord la tranche pipeline minimale ; un adapter starter (`precomputed`) sert de **premier client** du `Protocol`. |
+| **R-2 `version` absent** | Picarones n'a pas d'attribut `version` sur les adapters → repro `RunManifest` incomplète. | Test : `RunManifest` doit capter `name+version` de chaque step ; refuser un module sans `version`. |
+| **R-3 Annulation/deadline (D-A/D-B)** | `control` non câblé partout sauf ollama ; deadline ignorée par SDK/ML local. | Test d'annulation : lancer un step long, déclencher `control.cancel()`, vérifier l'arrêt < N s. Décider par adapter : annulable ou « best-effort » documenté. |
+| **R-4 `ConfidenceToken`** | TypedDict local mot-niveau, échelle [0,1], normalisation Tesseract. À promouvoir en `domain` **quand** la métrique calibration le consomme. | Ne pas figer la forme avant le consommateur (backlog domain). Test de normalisation 0-100→0-1 + rejet <0/>100. |
+| **R-5 Sortie corpus non uniforme (D-F)** | Choisir **`Corpus`** comme sortie unique ; pousser l'**orchestration disque** (download→write→manifest) en **service `app`**, garder en couche 5 le **transport + parsing schéma**. | Test : tout importeur retourne un `Corpus` valide (pas de `dict`). Séparer « localiser » (adapter) de « matérialiser » (app). |
+| **R-6 Sécurité (anti-SSRF + chemins)** | `corpus/_http` porte l'anti-SSRF ; `artifact_store`/eScriptorium ne valident pas les chemins/URL. Invariant `CLAUDE.md` : `validated_path()` + URL contrôlée. | Test : URL loopback/IP réservée rejetée ; clé d'artefact `../` rejetée ; pas d'`install_opener` global (no-side-effect-import). |
+| **R-7 Bugs latents (D-I)** | ✅ **entièrement clos**. `Corpus(source=)` eScriptorium (sortie `CorpusSpec`, `source` ∈ `metadata` → `TypeError` impossible). `selected_indices[i]+1` Gallica : mapping vue↔`f{n}` direct (position 1-based = numéro de vue), **aucune indirection** portée. Les deux prouvés non-mockés (`test_escriptorium_local_server.py`, `test_gallica_local_server.py`). | **Test d'intégration non-mocké** : loopback réel (`http.server`) par source — préféré au `live` quand la source exige auth/instance privée. |
+| **R-8 Dérive de budget** | Fichiers riches >400. | `test_file_budgets` actif dès le 1ᵉʳ commit d'adapters ; budgets honnêtes, pas de gonflement silencieux. |
+| **R-9 Couplage cross-famille** | `mistral_ocr` importe `llm.base.normalize_llm_content`. | Extraire la normalisation de contenu LLM en helper neutre partagé ; test d'archi sur les imports inter-sous-paquets. |
+| **R-10 Deux JobStores** | Le legacy `interfaces/web/jobs.py` est celui réellement câblé. | Au portage : un seul store (`adapters/storage`), l'app web le consomme ; supprimer le legacy ; test qu'aucun `JobStore` ne vit hors `adapters/storage`. **⚠️ Le canonical doit d'abord réabsorber la table d'événements + la reprise `Last-Event-ID`** (absentes aujourd'hui), sinon le **stream SSE régresse** (cf. `ANALYSE_COUCHE_8` §0). |
+| **R-11 Données démo en dur (D-H)** | ~220 LOC de faux catalogues. | Les sortir en `data/*.yaml` **ou** supprimer ; un repli démo ne doit jamais se faire passer pour de la vraie donnée (champ `is_demo` explicite). |
+| **R-12 Numérique non rétro-compatible** | Comme la couche 2 (`MIGRATION_COUCHE_2.md` MIG-2) : Cinoc change normalisation/contrats → **toute « validation » par égalité de chiffres avec Picarones est invalide**. | Goldens **refaits**, pas hérités. |
+
+---
+
+## Résumé pour la session de CONSTRUCTION (3-5 points)
+
+1. **Le « double contrat » à tuer n'est pas un héritage** : Picarones a déjà **un** contrat runtime unique = `StepExecutor` (`pipeline/protocols.py`, `execute(inputs, params, context, control)`), que les adapters implémentent par duck-typing. `BaseModule` est **vestigial** (à supprimer sans perte). ⇒ Le `Protocol` couche 4 de Cinoc ≈ `StepExecutor` **+ un attribut `version`** ; les `Base*Adapter` deviennent de simples **mixins d'implémentation**.
+2. **Construire par tranches, starter pack d'abord** : `precomputed` + `tesseract`(+`confidences`) + `openai`+`ollama`, avec les utils racine (`_atomic_io`/`_retry` corrigé/`output_paths`/`_image`/`_httpx_helpers`) portés **en bloc**. Tout le reste (kraken/calamari/pero/cloud OCR, anthropic/mistral, **VLM**, importeurs, stores) est **incrémental — porté à la tranche qui le consomme**, jamais d'avance. **VLM = 0 consommateur aujourd'hui → ne pas porter avant la tranche `zero_shot`.**
+3. **Dettes à corriger AU portage (pas après)** : annulation `control` non câblée (D-A) + deadline asymétrique (D-B) à trancher ; **3 implémentations de retry à unifier** + bug jitter>plafond ; **bugs latents** `Corpus(source=)`/Gallica masqués par les mocks ; `artifact_store` doit utiliser `_atomic_io`+`fsync` et **valider les chemins** ; **un seul `JobStore`**.
+4. **Élagage discipliné** : **SUPPRIMER** `_fallback_log` (son seul débouché, le narratif, est supprimé), `atomic_write_bytes`, la surface morte (escriptorium/gallica/hf), `execution_mode` (déjà parti) ; **sortir** les ~220 LOC de données démo en `data/` ; **sortie corpus unique = `Corpus`** (fin des dict-manifestes). Registre/découverte = **couche `app`** (entry-points `cinoc.modules`), **seul point d'extension tiers = les briques de pipeline**.
+5. **Placement & dépendances** : les importeurs de corpus restent **first-party en couche 5** (transport + parsing → `Corpus`), l'**orchestration disque** remonte en service `app` ; le **store SQLite longitudinal/tidy** est **rapatrié** de `evaluation/` vers `adapters/storage` (cf. `MIGRATION_COUCHE_3.md`). Whitelist d'archi `adapters/` à **expliciter** (inclut `evaluation` pour le type `Corpus` chargé).
+
+## DoD vivante (couche 5) — **autorité de détail** ; le `MIGRATION_PLAN.md` indexe
+
+> **T8 (D-066)** : tous les modules du socle renvoient `StepOutput` ; les adapters LLM/VLM remontent `tokens_in/out` (OpenAI/Mistral `usage.prompt/completion_tokens`, Anthropic `usage.input/output_tokens`, Ollama `prompt_eval_count`/`eval_count`) via `LLMCompletion` — un seul point de logique (`_base.run_llm_step`).
+
+> **T12 (D-070)** : tesseract publie l'artefact `CONFIDENCES` (sidecar JSON de `ConfidenceToken`, `image_to_data` conf÷100, best-effort → sidecar vide + warning). Preuves : `tests/adapters/test_tesseract.py`.
+
+> **T14 (D-072)** : `+ ocr/kraken.py` (HTR, extra `[kraken]`, `model` requis, RAW_TEXT+CONFIDENCES) `+ ocr/mistral_ocr.py` (cloud à la page, kind `mistral_ocr`). Preuves : `tests/adapters/test_kraken.py` · `test_mistral_ocr.py`.
+
+> Tri-état : `[x]` fait **+ preuve** · `[ ]` à faire · `[~]` différé/réserve + raison.
+> Maj dans le **même commit** que le code. **Statut : ✅ T3 complet** — `precomputed` + `tesseract` + **`openai`** + **`ollama`** (LLM post-correction) verts, annulation câblée (D-A clos) **+ `mistral`** (post-correction cloud, extra `[mistral]`, secret `MISTRAL_API_KEY`) ; stores/VLM **par tranches**. **+ T5 `layout/`** : `precomputed` (source LAYOUT + recognizer région), `assembler` (`AltoAssembler`), **`crop`** (`crop_region` PIL — découpe réelle des blocs du pipeline hybride seg→OCR ; `PIL` ajouté à la whitelist archi `adapters`). — *preuves : `tests/adapters/layout/test_crop.py`, `…/test_alto_assembler.py`, `tests/pipeline/test_hybrid_real_bnl.py` (live)*. **+ T7 `corpus/`** : 1ᵉʳ importeur **IIIF** — `_http` (transport `httpx` durci anti-SSRF : http(s) seul, rejet userinfo + IP non publiques, redirections re-validées, taille plafonnée, **aucun `install_opener` global** ; **anti-DNS-rebinding fermé** D-051 : résolution unique → IP validées **épinglées** via `network_backend` `httpcore` custom (`_PinnedBackend`), URL/`Host`/SNI/cert TLS inchangés, ré-épinglage par redirection — `httpcore` whitelisté en archi adapters + extras ; **`download` en flux disque** D-052 : `.part` au fil de l'eau + `os.replace` atomique + cap `IMAGE_MAX_BYTES`, aucun fichier partiel ; `download` accepte `headers` — média eScriptorium **même-hôte** seul porte le jeton) + `iiif` (parser manifeste v2/v3 → `IIIFImage`, **images seules**, pur) ; matérialisation disque → **`CorpusSpec`** en `app/corpus_import.py` (R-5 : localiser ≠ matérialiser). Sortie **unique `CorpusSpec`** (fin des dict-manifestes). — *preuves : `tests/adapters/corpus/{test_iiif_parse,test_http_ssrf,test_iiif_local_server}.py` (transport réel loopback), `…/test_iiif_live.py` (distant, opt-in), `tests/app/test_corpus_import.py`*. **+ eScriptorium** (porteur de **GT** → corpus **scorable**) : `escriptorium.py` (auth token, pagination `next`, `extract_gt_text` couche transcription, pur ; `_http.fetch_json` gagne `headers`) + `import_escriptorium_corpus` (image + `.gt.txt` → `GroundTruthRef` RAW_TEXT). **R-7/D-I fermé** : pas de `Corpus(source=)` (la sortie est `CorpusSpec`, `source` ∈ `metadata`) — prouvé **non-mocké** (test loopback : auth header + pagination 2 pages + GT lignes/`content`). — *preuves : `tests/adapters/corpus/{test_escriptorium_parse,test_escriptorium_local_server}.py`, `tests/app/test_corpus_import_escriptorium.py`*. **+ Gallica** : `gallica.py` (`normalize_ark` + `manifest_url` **IIIF `/iiif/`** + `fetch_ocr_text` via **ALTO** `RequestDigitalElement` + `alto_to_text` ; `_http.fetch_bytes` ajouté pour parser l'ALTO en octets) — **images réutilisent `IIIFImporter`**, OCR = **référence étiquetée** : type domaine `REFERENCE_TEXT` (D-053, ≠ GT manuelle) + `gt_source=gallica_ocr` — non scoré par défaut, vue référence dédiée (opt-in). **2 bugs prod corrigés (D-058, révélés par la capture réelle)** : URL manifeste `/iiif/` manquant (→ 403, masqué par les mocks) ; `texteBrut` ALTCHA-gated → bascule ALTO (rupture nette, `texteBrut`/`_looks_like_html` supprimés). **R-7 clos** : mapping vue *i* ↔ `f{i}` lu dans l'URL d'image (`/f{n}/`), **sans indirection**, prouvé non-mocké sur **vraies pages Gallica** (`tests/fixtures/gallica_alto/`, *Pourceaugnac*). — *preuves : `tests/adapters/corpus/{test_gallica_parse,test_gallica_alto,test_gallica_local_server}.py`, `tests/app/test_corpus_import_gallica.py`*. **+ HTR-United & HuggingFace** (**découverte**, pas matérialisation) : `htr_united.py` (`fetch_catalogue` YAML via `_http.fetch_text` + `parse_catalogue` pur + recherche + **repli démo `is_demo`** ; `yaml` ajouté à la whitelist adapters) ; `huggingface.py` (`search_reference` socle intégré + `HuggingFaceCatalogue.search` API publique **best-effort** via `_http.fetch_json`, `source` ∈ {reference, api}). **+ import HF matérialisant** (D-054, Lot D) : `stream_pages` (convention Cinoc `image`+`ground_truth`, lib `datasets` en extra `[huggingface]`, `streaming=True`, `Image(decode=False)` → octets sans PIL, `loader` injectable) → `app.import_hf_corpus` (GT `RAW_TEXT` réelle) + endpoint `/api/corpus/import/huggingface` (CSRF, gate public 403, non-conforme 422, extra absent 409). **Importeurs cœur complets.** — *preuves : `tests/adapters/corpus/{test_htr_united,test_htr_united_local_server,test_huggingface,test_huggingface_local_server}.py`*. **+ T7 `storage/history_store.py`** : `HistoryStore` SQLite **longitudinal** — `add(HistoryRecord…)` (idempotent, PK `(run_id,pipeline,view,metric)`), `history(pipeline,view,metric)` (chronologique), `regressions(view,metric, threshold, higher_is_better)` (2 derniers runs, direction-aware). Persistance **pure de lignes primitives** (n'importe pas `RunResult`) ; 1 connexion/opération (thread-safe). — *preuves : `tests/adapters/storage/test_history_store.py` (vrai SQLite : round-trip, idempotence, persistance inter-instances, régression/seuil/sens)*
+
+**Enveloppe :**
+- [x] `precomputed` implémente le `Module` Protocol (couche 4) **directement**, avec `name`/`version`. — *preuve : `tests/adapters/test_precomputed.py` (`isinstance(.., Module)` ; lecture `<stem>.<label>.txt` → `RAW_TEXT` + `content_hash` ; UTF-8 strict ; annulation)*
+- [x] **1ᵉʳ vrai moteur : `tesseract`** (implémente `Module` directement ; `lang` anti-injection, timeout borné par la deadline, écrit dans le **workspace** ; pytesseract = **extra**, invocation **mockable** → CI sans binaire). — *preuve : `test_tesseract` (mock + validations + workspace + annulation) ; `test_live` opt-in*
+- [x] **2ᵉ famille de module : LLM post-correction** (`openai`, mode `text_only`) — `RAW_TEXT → CORRECTED_TEXT` ; SDK extra, invocation **mockable** (CI sans clé) ; **pipeline multi-étapes OCR→LLM** prouvé (`CORRECTED_TEXT` **non vide**, bug historique). — *preuve : `test_openai` + `test_llm_pipeline`*
+- [x] **2ᵉ LLM (généralisation prouvée) : `ollama`** — *même* contrat que `openai`, sortie `CORRECTED_TEXT`, **aucun cas particulier** ; transport `httpx` = **extra**, `_invoke_ollama` **mockable** (CI sans serveur). **Référence d'annulation câblée** : `_invoke_ollama` enregistre `client.close` via `RunControl.register_cancel_handle` → `trigger_cancel` ferme la connexion en vol ; « annulation vs panne » tranchée en sondant `is_cancelled` (`_fail_or_cancel`, **fiable** — remplace l'heuristique de message fragile, **D-A clos**). — *preuve : `test_ollama` (conformité Module + mock + workspace + annulation + `_fail_or_cancel` cancel/panne) ; mécanisme `register_cancel_handle` : `test_run_control` (fire-on-cancel · immédiat-si-déjà-annulé · once · ordre)*
+- [~] VLM/`zero_shot` (0 conso) · `Base*Adapter` mixins · confidences/ALTO · `unregister`/déduplication des handles (accumulation bénigne, runs bornés) : **différés**.
+
+**Garde-fous :**
+- [x] `layer_dependencies` (whitelist `adapters` explicitée : domain+pipeline+formats) · `no_side_effect_imports` · `no_broad_except` · `file_budgets`. — *preuve : `test_adapters_imports_are_allowed` + suite archi verte.* `[~]` `install_opener` global (D-E) : tué à la tranche HTTP.
+
+**Validation par tranche :** `MIGRATION_PLAN.md` §3 — starter pack via `Module` (T1-T3) · **1 seul `JobStore` avec SSE/`job_events` réabsorbés** (T4, cf. §0/D-γ) · bugs latents `Corpus(source=)`/`selected_indices+1` corrigés + test `live` (T7).
+
+- [~] **Différé** : kraken/calamari/pero/cloud OCR, anthropic/mistral, **VLM (0 conso → pas avant `zero_shot`)**, importeurs (1/tranche, sortie unique `Corpus`), stores. **Supprimer** `_fallback_log` + données démo en dur (→`data/`).
+
+---
+
+*Tous les verdicts de la Partie 1 sont marqués **PROVISOIRE — à confirmer au build** : le contact du code corrige souvent l'analyse.*

cinoc/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Couche 5 — ``adapters`` : modules concrets (starter pack).
+
+Chaque adapter implémente directement le ``Module`` Protocol (couche 4). Les
+dépendances lourdes (SDK LLM, moteurs OCR) sont des extras optionnels, importés
+dans le module qui les utilise — jamais ici. ``__init__`` mince, sans effet de
+bord.
+"""
+
+from __future__ import annotations

cinoc/adapters/_resilience.py

@@ -0,0 +1,170 @@
+"""Résilience des appels réseau (couche 5, adapters) : cap de concurrence + retry.
+
+Deux mécanismes, **par défaut, sans configuration**, pour qu'un run depuis l'UI
+web (n'importe qui) ne sature pas une API instable :
+
+- **Cap de concurrence par fournisseur** (``network_slot``) : un sémaphore borné
+  *par fournisseur* (Mistral, OpenAI… chacun le sien) → au plus N appels réseau
+  simultanés, quel que soit le nombre de threads du runner. C'est le fix
+  structurel du pool global partagé (Pero local + LLM réseau dans un même run).
+- **Retry borné** (``call_resilient``) : sur 429/5xx, attend ``Retry-After`` si le
+  serveur l'indique, sinon un backoff exponentiel borné + gigue, puis recommence.
+
+Stdlib pure (aucune dépendance). **Déterminisme (invariant §12)** : ces mécanismes
+ne changent que le *timing*, jamais la valeur renvoyée → le ``RunResult`` reste
+byte-identique. ``N`` = ``CINOC_NETWORK_CONCURRENCY`` (défaut 3, plancher 1).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+import threading
+import time
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+#: Plafond par défaut d'appels réseau concurrents **par fournisseur** (anti-429).
+_DEFAULT_LIMIT = 3
+_LIMIT_ENV = "CINOC_NETWORK_CONCURRENCY"
+#: Politique de retry : tentatives + backoff exponentiel borné (secondes).
+_DEFAULT_ATTEMPTS = 5
+_BASE_BACKOFF = 1.0
+_MAX_BACKOFF = 30.0
+#: Statuts HTTP retentés : 429 (rate limit) + 5xx transitoires (instabilité).
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+#: Registre process-global des sémaphores, créés paresseusement (aucun effet de
+#: bord à l'import). Protégé par un verrou : ``network_slot`` est thread-safe.
+_SEMAPHORES: dict[str, threading.BoundedSemaphore] = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def _network_limit() -> int:
+    """Plafond effectif depuis l'environnement (défaut ``_DEFAULT_LIMIT``)."""
+    raw = os.environ.get(_LIMIT_ENV)
+    if raw is None:
+        return _DEFAULT_LIMIT
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning(
+            "[resilience] %s=%r invalide (entier attendu) — défaut %d.",
+            _LIMIT_ENV,
+            raw,
+            _DEFAULT_LIMIT,
+        )
+        return _DEFAULT_LIMIT
+    return max(1, value)
+
+
+def network_slot(provider: str) -> AbstractContextManager[bool]:
+    """Sémaphore borné **du fournisseur** : ``with network_slot("mistral"): …``.
+
+    Au plus ``_network_limit()`` détenteurs simultanés par fournisseur. Chaque
+    fournisseur a son quota propre (un run OpenAI + Mistral ne les fait pas se
+    partager le budget). Le plafond est figé à la première création du fournisseur
+    (lecture d'environnement unique, déterministe pour la durée du process)."""
+    with _REGISTRY_LOCK:
+        sem = _SEMAPHORES.get(provider)
+        if sem is None:
+            sem = threading.BoundedSemaphore(_network_limit())
+            _SEMAPHORES[provider] = sem
+    return sem
+
+
+def _default_jitter() -> float:
+    return random.uniform(0.0, 1.0)
+
+
+def _backoff(attempt: int, jitter: Callable[[], float]) -> float:
+    """Backoff exponentiel borné + gigue (désynchronise les threads concurrents)."""
+    return min(_MAX_BACKOFF, _BASE_BACKOFF * (2.0**attempt)) + jitter()
+
+
+def http_is_retryable(exc: BaseException) -> bool:
+    """Vrai si l'exception SDK porte un statut HTTP transitoire (429/5xx).
+
+    Duck-typing assumé : les SDK httpx (mistralai/openai/anthropic) exposent
+    ``status_code``. Une erreur sans statut (réseau coupé, bug local) n'est **pas**
+    retentée — on ne masque pas un vrai défaut."""
+    return getattr(exc, "status_code", None) in _RETRYABLE_STATUS
+
+
+def http_retry_after(exc: BaseException) -> float | None:
+    """Délai ``Retry-After`` (secondes, borné) si le serveur l'indique, sinon ``None``.
+
+    Sonde l'en-tête sur ``exc.response.headers`` puis ``exc.headers`` ; tolère
+    toute absence/forme invalide (→ ``None`` → l'appelant calcule un backoff)."""
+    for holder in (getattr(exc, "response", None), exc):
+        headers = getattr(holder, "headers", None)
+        if headers is None or not hasattr(headers, "get"):
+            continue
+        raw = headers.get("retry-after")
+        if raw is None:
+            continue
+        try:
+            seconds = float(raw)
+        except (TypeError, ValueError):
+            continue
+        if seconds >= 0:
+            return min(_MAX_BACKOFF, seconds)
+    return None
+
+
+def call_resilient(
+    provider: str,
+    fn: Callable[[], T],
+    *,
+    is_retryable: Callable[[BaseException], bool] = http_is_retryable,
+    retry_after: Callable[[BaseException], float | None] = http_retry_after,
+    attempts: int = _DEFAULT_ATTEMPTS,
+    sleep: Callable[[float], None] = time.sleep,
+    jitter: Callable[[], float] = _default_jitter,
+) -> T:
+    """Exécute ``fn`` sous le quota du fournisseur, avec retry borné sur 429/5xx.
+
+    Acquiert ``network_slot(provider)`` **par tentative** (relâché pendant
+    l'attente → on ne gèle pas un quota en dormant). Sur erreur retentable et tant
+    qu'il reste des tentatives : attend ``Retry-After`` si fourni, sinon un backoff
+    exponentiel borné + gigue, puis recommence. Sinon l'exception remonte
+    (l'appelant la traduit en ``AdapterStepError`` → unité isolée par le runner).
+    ``sleep``/``jitter`` injectables (tests déterministes). **Ne change que le
+    *timing*, jamais la valeur renvoyée.**"""
+    for attempt in range(attempts):
+        delay = 0.0
+        with network_slot(provider):
+            try:
+                return fn()
+            except Exception as exc:
+                if not is_retryable(exc) or attempt == attempts - 1:
+                    raise
+                after = retry_after(exc)
+                delay = after if after is not None else _backoff(attempt, jitter)
+                logger.warning(
+                    "[resilience] %s : tentative %d/%d échouée (%s) — "
+                    "nouvelle tentative dans %.1f s.",
+                    provider,
+                    attempt + 1,
+                    attempts,
+                    type(exc).__name__,
+                    delay,
+                )
+        sleep(delay)  # hors du créneau : on ne retient pas le quota en dormant
+    raise AssertionError(  # pragma: no cover — la boucle retourne ou relance avant
+        "call_resilient : boucle épuisée sans issue"
+    )
+
+
+__all__ = [
+    "call_resilient",
+    "http_is_retryable",
+    "http_retry_after",
+    "network_slot",
+]

cinoc/adapters/_workspace.py

@@ -0,0 +1,31 @@
+"""Chemins de sortie dans le workspace (couche 5, partagé par les écrivains).
+
+Les adapters qui **produisent** un artefact (OCR, post-correction LLM) y déposent
+un fichier. Le ``stem`` dérivé du ``document_id`` est **injectif** et sans
+séparateur de chemin : encodage type URL (``quote``), **réversible** donc
+injectif, qui neutralise ``/`` (→ ``%2F``) et l'octet nul (→ ``%00``). Deux ids
+distincts ne peuvent jamais produire le même nom de fichier (et donc s'écraser) —
+y compris les cas limites ``a/_b`` vs ``a_/b`` qu'un simple échappement maison
+collisionnerait. Les ids courants (alphanumériques) restent lisibles.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+
+def safe_document_stem(document_id: str) -> str:
+    """``document_id`` → composant de nom de fichier **injectif** et sans ``/``."""
+    return quote(document_id, safe="")
+
+
+def workspace_artifact_path(
+    workspace_uri: str, document_id: str, label: str, suffix: str
+) -> Path:
+    """Chemin ``<workspace>/<stem>.<label>.<suffix>`` (``stem`` injectif)."""
+    stem = safe_document_stem(document_id)
+    return Path(workspace_uri) / f"{stem}.{label}.{suffix}"
+
+
+__all__ = ["safe_document_stem", "workspace_artifact_path"]

cinoc/adapters/corpus/__init__.py

@@ -0,0 +1,39 @@
+"""Importeurs de corpus first-party (couche 5).
+
+Chaque importeur **localise** des ressources (transport + parsing de schéma) et
+retourne un type neutre ; la **matérialisation disque → ``CorpusSpec``** vit en
+couche ``app``. Module mince, aucun effet de bord à l'import.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.corpus.escriptorium import (
+    EScriptoriumImporter,
+    EScriptoriumPage,
+)
+from cinoc.adapters.corpus.gallica import GallicaImporter, normalize_ark
+from cinoc.adapters.corpus.htr_united import (
+    HTRUnitedCatalogue,
+    HTRUnitedEntry,
+    fetch_catalogue,
+)
+from cinoc.adapters.corpus.huggingface import (
+    HuggingFaceCatalogue,
+    HuggingFaceDataset,
+)
+from cinoc.adapters.corpus.iiif import IIIFImage, IIIFImporter, parse_manifest
+
+__all__ = [
+    "EScriptoriumImporter",
+    "EScriptoriumPage",
+    "GallicaImporter",
+    "HTRUnitedCatalogue",
+    "HTRUnitedEntry",
+    "HuggingFaceCatalogue",
+    "HuggingFaceDataset",
+    "IIIFImage",
+    "IIIFImporter",
+    "fetch_catalogue",
+    "normalize_ark",
+    "parse_manifest",
+]

cinoc/adapters/corpus/_http.py

@@ -0,0 +1,360 @@
+"""Transport HTTP **durci anti-SSRF** pour les importeurs de corpus (couche 5).
+
+Un importeur va chercher des ressources à une URL **fournie par l'utilisateur** :
+le risque est qu'on serve de proxy vers le réseau interne (SSRF) ou qu'on télécharge
+sans borne (DoS mémoire/disque). Défenses, toutes testées :
+
+- **schéma** ``http``/``https`` seuls (pas de ``file://``, ``gopher://``…) ;
+- **pas de userinfo** dans l'URL ;
+- **résolution DNS validée** : *toutes* les IP résolues doivent être **publiques**
+  (rejet loopback / privé / link-local / réservé / multicast / non-spécifié) ;
+- **redirections re-validées** à chaque saut (une 30x ne peut pas pointer vers
+  l'interne) ; nombre de sauts borné ;
+- **taille plafonnée** au fil de l'eau (on ne fait pas confiance à
+  ``Content-Length``).
+
+**DNS-rebinding fermé — épinglage d'IP.** ``assert_public_url`` résout l'hôte
+**une seule fois**, valide **toutes** les IP, et **retourne** ces IP. La
+connexion vise alors directement l'IP **épinglée** (transport ``httpx`` à
+``network_backend`` custom, cf. :class:`_PinnedBackend`) : il n'y a **pas de
+seconde résolution** que pourrait détourner un DNS hostile. Le nom d'hôte de
+l'URL reste inchangé, donc le ``Host`` envoyé, le **SNI** et la vérification du
+certificat TLS portent toujours sur le vrai hôte (aucun override fragile) —
+seule la cible TCP est figée. L'épinglage est ré-appliqué **à chaque saut** de
+redirection. Le **gate « mode public » (403)** côté interface reste la première
+barrière (les imports distants y sont refusés) ; l'épinglage est la défense en
+profondeur, désormais étanche.
+
+Auth & redirections : les en-têtes (jeton) ne suivent **pas** un changement
+d'hôte (cf. ``_stream_validated``). Une seule pile HTTP (``httpx`` + son moteur
+``httpcore``) ; **aucun état global** (pas d'``install_opener``).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import json
+import os
+import socket
+import typing
+from collections.abc import Iterator
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpcore
+import httpx
+
+from cinoc.domain.errors import CinocError
+
+#: Plafonds (généreux mais bornés — un Space gratuit n'est pas un entrepôt).
+MANIFEST_MAX_BYTES = 16 * 1024 * 1024
+IMAGE_MAX_BYTES = 50 * 1024 * 1024
+DEFAULT_TIMEOUT = 30.0
+_MAX_REDIRECTS = 5
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+class CorpusHttpError(CinocError):
+    """Échec de transport d'un importeur de corpus."""
+
+
+class SsrfError(CorpusHttpError):
+    """L'URL cible une ressource interdite (schéma, userinfo ou IP non publique)."""
+
+
+class HttpFetchError(CorpusHttpError):
+    """La requête a échoué (statut, redirection cassée, dépassement de taille)."""
+
+
+def _is_public(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    return not (
+        ip.is_private
+        or ip.is_loopback
+        or ip.is_link_local
+        or ip.is_reserved
+        or ip.is_multicast
+        or ip.is_unspecified
+    )
+
+
+def assert_public_url(url: str) -> tuple[str, ...]:
+    """Valide ``url`` et **retourne les IP publiques** vers lesquelles épingler.
+
+    Résout l'hôte **une seule fois** et exige que **toutes** les IP retournées
+    soient publiques : un nom qui résout (même partiellement) vers l'interne est
+    rejeté (``SsrfError``). Les IP validées sont retournées pour que l'appelant
+    **épingle** la connexion dessus (anti-DNS-rebinding) — pas de seconde
+    résolution. Pour une IP littérale, retourne cette IP (aucun DNS réel).
+    """
+    parts = urlsplit(url)
+    if parts.scheme not in _ALLOWED_SCHEMES:
+        raise SsrfError(f"schéma non autorisé : {parts.scheme!r} (http/https seuls).")
+    if parts.username or parts.password:
+        raise SsrfError("userinfo interdit dans l'URL.")
+    host = parts.hostname
+    if not host:
+        raise SsrfError("URL sans hôte.")
+    port = parts.port or (443 if parts.scheme == "https" else 80)
+    try:
+        infos = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+    except OSError as exc:
+        raise SsrfError(f"résolution DNS impossible pour {host!r} : {exc}.") from exc
+    pins: list[str] = []
+    for info in infos:
+        addr = str(info[4][0])  # sockaddr[0] = adresse textuelle (IPv4/IPv6)
+        if not _is_public(ipaddress.ip_address(addr)):
+            raise SsrfError(
+                f"hôte {host!r} résout vers une IP non publique ({addr})."
+            )
+        if addr not in pins:
+            pins.append(addr)
+    return tuple(pins)
+
+
+class _PinnedBackend(httpcore.SyncBackend):
+    """Épingle la cible TCP sur des IP **pré-validées** (anti-DNS-rebinding).
+
+    ``httpcore`` appelle ``connect_tcp(host, port)`` avec le **nom d'hôte** de
+    l'origine ; on substitue les IP déjà résolues+validées, sans repasser par le
+    DNS. Le nom d'hôte de l'URL restant inchangé, le SNI et la vérification du
+    certificat TLS (pilotés par ``httpcore`` depuis l'origin) portent toujours
+    sur le **vrai hôte** — donc aucun override fragile. On essaie les IP dans
+    l'ordre (comme ``socket.create_connection`` le ferait), préservant le
+    repli multi-adresses.
+    """
+
+    def __init__(self, ips: tuple[str, ...]) -> None:
+        super().__init__()
+        self._ips = ips
+
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: typing.Any = None,
+    ) -> httpcore.NetworkStream:
+        last_exc: httpcore.ConnectError | None = None
+        for ip in self._ips:
+            try:
+                return super().connect_tcp(
+                    ip,
+                    port,
+                    timeout=timeout,
+                    local_address=local_address,
+                    socket_options=socket_options,
+                )
+            except httpcore.ConnectError as exc:
+                last_exc = exc
+        assert last_exc is not None  # _ips est non vide (cf. _make_client)
+        raise last_exc
+
+
+def _pinned_transport(ips: tuple[str, ...]) -> httpx.HTTPTransport:
+    """Transport ``httpx`` dont le backend réseau épingle ``ips``.
+
+    ``httpx`` n'expose pas ``network_backend`` ; on le pose sur le pool interne
+    (seul point d'injection). Le ``isinstance`` fait échouer **bruyamment** si
+    une future version de ``httpx`` change la forme du pool, plutôt que de
+    contourner silencieusement l'épinglage.
+    """
+    transport = httpx.HTTPTransport()
+    pool = transport._pool
+    if not isinstance(pool, httpcore.ConnectionPool):  # pragma: no cover
+        transport.close()
+        raise CorpusHttpError("épinglage IP indisponible : transport httpx inattendu.")
+    pool._network_backend = _PinnedBackend(ips)
+    return transport
+
+
+def _make_client(pins: tuple[str, ...] | None, timeout: float) -> httpx.Client:
+    """Client mono-saut. ``pins`` vide/None → résolution httpx normale.
+
+    Le cas ``None`` n'arrive qu'en test (``assert_public_url`` neutralisé en
+    no-op pour viser le loopback) ; en production il est toujours non vide.
+    """
+    if not pins:
+        return httpx.Client(timeout=timeout, follow_redirects=False)
+    return httpx.Client(
+        transport=_pinned_transport(pins), timeout=timeout, follow_redirects=False
+    )
+
+
+@contextlib.contextmanager
+def _stream_validated(
+    url: str, *, timeout: float, headers: dict[str, str] | None = None
+) -> Iterator[httpx.Response]:
+    """GET en streaming, **épinglé à l'IP validée** et re-validé à chaque saut.
+
+    Chaque saut (origine + redirections, bornées) : résout+valide une fois via
+    ``assert_public_url``, épingle la connexion sur l'IP retournée, puis envoie.
+    Les en-têtes fournis (ex. ``Authorization: Token …``) ne sont **jamais**
+    propagés vers un **hôte différent** de l'origine (fuite de credentials sur
+    redirection). Un client ``httpx`` distinct est créé par saut (épinglage
+    propre à l'IP du saut) ; tous sont fermés à la sortie du contexte.
+    """
+    origin_host = urlsplit(url).hostname
+    current = url
+    with contextlib.ExitStack() as stack:
+        for _ in range(_MAX_REDIRECTS + 1):
+            pins = assert_public_url(current)
+            # Auth conservée seulement tant qu'on reste sur l'hôte d'origine.
+            hop_headers = headers if urlsplit(current).hostname == origin_host else None
+            client = stack.enter_context(_make_client(pins, timeout))
+            request = client.build_request("GET", current, headers=hop_headers)
+            response = client.send(request, stream=True)
+            if response.is_redirect:
+                location = response.headers.get("location", "")
+                response.close()
+                if not location:
+                    raise HttpFetchError(
+                        f"redirection sans 'Location' depuis {current!r}."
+                    )
+                current = str(request.url.join(location))
+                continue
+            try:
+                yield response
+            finally:
+                response.close()
+            return
+        raise HttpFetchError(f"trop de redirections (> {_MAX_REDIRECTS}) pour {url!r}.")
+
+
+def _read_capped(response: httpx.Response, max_bytes: int) -> bytes:
+    chunks: list[bytes] = []
+    total = 0
+    for chunk in response.iter_bytes():
+        total += len(chunk)
+        if total > max_bytes:
+            raise HttpFetchError(f"réponse dépasse le plafond de {max_bytes} octets.")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def fetch_json(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> object:
+    """Récupère et parse un JSON ; anti-SSRF + plafond ``MANIFEST_MAX_BYTES``.
+
+    ``headers`` permet l'authentification d'API (ex. ``Authorization: Token …``) ;
+    il n'est jamais journalisé (les messages d'erreur ne portent que l'URL).
+    """
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            response.raise_for_status()
+            raw = _read_capped(response, MANIFEST_MAX_BYTES)
+    except httpx.HTTPStatusError as exc:
+        raise HttpFetchError(
+            f"statut HTTP {exc.response.status_code} sur {url!r}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise HttpFetchError(f"échec de transport sur {url!r} : {exc}.") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise HttpFetchError(f"réponse non-JSON depuis {url!r} : {exc}.") from exc
+
+
+def download(
+    url: str,
+    dest: Path,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> None:
+    """Télécharge ``url`` vers ``dest`` en **flux disque** ; anti-SSRF + plafond.
+
+    Écrit au fil de l'eau dans un fichier ``.part`` voisin (jamais tout le corps
+    en RAM), plafonne à ``IMAGE_MAX_BYTES``, puis **renomme atomiquement**
+    (``os.replace``) vers ``dest``. À la moindre erreur (statut, dépassement de
+    plafond, I/O, annulation), le ``.part`` est supprimé : **aucun fichier
+    partiel** n'est laissé derrière, et ``dest`` n'apparaît qu'une fois complet.
+
+    ``headers`` (ex. ``Authorization``) n'est transmis qu'à l'hôte d'origine —
+    ``_stream_validated`` le retire sur une redirection cross-hôte (cf. D-050).
+    """
+    part = dest.with_name(dest.name + ".part")
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise HttpFetchError(
+                    f"statut HTTP {exc.response.status_code} sur {url!r}."
+                ) from exc
+            total = 0
+            with part.open("wb") as handle:
+                for chunk in response.iter_bytes():
+                    total += len(chunk)
+                    if total > IMAGE_MAX_BYTES:
+                        raise HttpFetchError(
+                            f"réponse dépasse le plafond de {IMAGE_MAX_BYTES} octets."
+                        )
+                    handle.write(chunk)
+        os.replace(part, dest)
+    except BaseException:
+        part.unlink(missing_ok=True)
+        raise
+
+
+def fetch_bytes(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> bytes:
+    """Récupère un corps **binaire** en mémoire ; anti-SSRF + plafond manifeste.
+
+    Pour les ressources qui doivent être parsées depuis des **octets** (ex. ALTO
+    Gallica : lxml refuse un ``str`` portant une déclaration d'encodage XML).
+    """
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            response.raise_for_status()
+            return _read_capped(response, MANIFEST_MAX_BYTES)
+    except httpx.HTTPStatusError as exc:
+        raise HttpFetchError(
+            f"statut HTTP {exc.response.status_code} sur {url!r}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        # Échec de transport (connexion/timeout/protocole) : on l'enveloppe en
+        # HttpFetchError pour que les appelants n'aient qu'un type réseau à gérer
+        # (jamais une exception httpx brute qui échapperait au repli).
+        raise HttpFetchError(f"échec de transport sur {url!r} : {exc}.") from exc
+
+
+def fetch_text(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> str:
+    """Récupère un corps **texte** (UTF-8, erreurs remplacées) ; anti-SSRF + plafond.
+
+    Pour les endpoints qui ne servent pas du JSON (ex. catalogue HTR-United).
+    """
+    # Accept #15 : un corps distant peut contenir des octets non-UTF-8 isolés ;
+    # `errors="replace"` insère U+FFFD plutôt que d'échouer sur une donnée mal
+    # encodée (le contenu reste exploitable, pas une GT manuelle).
+    return fetch_bytes(url, timeout=timeout, headers=headers).decode(
+        "utf-8", errors="replace"
+    )
+
+
+__all__ = [
+    "CorpusHttpError",
+    "HttpFetchError",
+    "IMAGE_MAX_BYTES",
+    "MANIFEST_MAX_BYTES",
+    "SsrfError",
+    "assert_public_url",
+    "download",
+    "fetch_bytes",
+    "fetch_json",
+    "fetch_text",
+]

cinoc/adapters/corpus/escriptorium.py

@@ -0,0 +1,185 @@
+"""Importeur de corpus **eScriptorium** (API REST) — couche 5.
+
+Rôle : **localiser** les pages d'un document eScriptorium (auth par token →
+liste paginée des *parts* + leur transcription) et retourner un type neutre. La
+**matérialisation disque** (download image + écriture GT → ``CorpusSpec``) vit en
+couche ``app`` (``app/corpus_import.py``).
+
+Contrairement à IIIF, eScriptorium porte une **vérité-terrain** (la couche de
+transcription choisie) → le corpus importé est **scorable** (CER/WER).
+
+API consommée (lecture seule) :
+
+- ``GET /api/documents/{pk}/parts/``                       → pages (paginé) ;
+- ``GET /api/documents/{pk}/parts/{pk}/transcriptions/``   → transcriptions.
+
+Dette de la source **non reprise** : l'export distant de couche OCR, le listing
+projets/connexion (surface morte ~40 %), et surtout le bug latent
+``Corpus(source=…)`` — ici la sortie est un ``CorpusSpec`` (``source`` va dans
+``metadata``), structurellement à l'abri.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_json
+
+logger = logging.getLogger(__name__)
+
+#: Couche de transcription par défaut (libellé eScriptorium usuel pour la GT).
+DEFAULT_LAYER = "manual"
+#: Borne de pagination (un document = au plus quelques milliers de pages).
+_MAX_PAGES = 10_000
+
+
+@dataclass(frozen=True)
+class EScriptoriumPage:
+    """Une page (*part*) : son URL d'image absolue + son texte GT (peut être vide)."""
+
+    pk: int
+    image_url: str
+    gt_text: str
+    title: str
+
+
+def _image_uri(item: dict[str, Any], base_url: str) -> str:
+    """Extrait l'URL d'image d'une *part* (champ ``image`` : str ou objet)."""
+    img = item.get("image")
+    if isinstance(img, dict):
+        img = img.get("uri") or img.get("url") or ""
+    if not isinstance(img, str) or not img:
+        return ""
+    return urljoin(base_url, img)
+
+
+def _layer_name(transcription: dict[str, Any]) -> str:
+    nested = transcription.get("transcription")
+    if isinstance(nested, dict):
+        return str(nested.get("name", ""))
+    return str(transcription.get("name", ""))
+
+
+def extract_gt_text(transcriptions: list[dict[str, Any]], layer: str) -> str:
+    """Texte GT de la couche ``layer`` (lignes jointes, ou ``content``). Pur.
+
+    ``layer`` vide → première transcription rencontrée. Renvoie ``""`` si la
+    couche demandée est absente.
+    """
+    for transcription in transcriptions:
+        if layer and _layer_name(transcription) != layer:
+            continue
+        lines = transcription.get("lines") or []
+        if lines:
+            return "\n".join(
+                str(line.get("content", ""))
+                for line in lines
+                if isinstance(line, dict) and line.get("content")
+            )
+        return str(transcription.get("content", "") or "")
+    return ""
+
+
+class EScriptoriumImporter:
+    """Localise les pages d'un document eScriptorium (auth + API, **sans disque**)."""
+
+    name = "escriptorium"
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        layer: str = DEFAULT_LAYER,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._layer = layer
+        self._timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        # Le token n'est jamais journalisé (cf. _http : erreurs sans en-têtes).
+        return {"Authorization": f"Token {self._token}", "Accept": "application/json"}
+
+    def _get(self, url: str) -> dict[str, Any]:
+        data = fetch_json(url, timeout=self._timeout, headers=self._headers())
+        if not isinstance(data, dict):
+            raise HttpFetchError(
+                f"réponse eScriptorium inattendue (objet JSON attendu) : {url!r}."
+            )
+        return data
+
+    def _paginate(self, path: str) -> list[dict[str, Any]]:
+        """Suit les liens ``next`` jusqu'à épuisement, **sans quitter l'hôte**.
+
+        Le ``next`` est contrôlé par le serveur : on **n'envoie jamais le jeton**
+        vers un hôte différent de ``base_url`` (un ``next`` cross-hôte est ignoré).
+        """
+        base_host = urlsplit(self._base_url).hostname
+        results: list[dict[str, Any]] = []
+        url: str | None = f"{self._base_url}/api/{path.lstrip('/')}"
+        for _ in range(_MAX_PAGES):
+            if not url:
+                break
+            data = self._get(url)
+            page = data.get("results")
+            results.extend(page if isinstance(page, list) else [])
+            nxt = data.get("next")
+            if not (isinstance(nxt, str) and nxt):
+                break
+            if urlsplit(nxt).hostname != base_host:
+                logger.warning(
+                    "[escriptorium] lien 'next' hors hôte ignoré (pas de jeton "
+                    "envoyé à un tiers) : %s",
+                    nxt,
+                )
+                break
+            url = nxt
+        return results
+
+    def _transcriptions(self, doc_pk: int, part_pk: int) -> list[dict[str, Any]]:
+        url = f"{self._base_url}/api/documents/{doc_pk}/parts/{part_pk}/transcriptions/"
+        data = fetch_json(url, timeout=self._timeout, headers=self._headers())
+        if isinstance(data, list):
+            return [t for t in data if isinstance(t, dict)]
+        if isinstance(data, dict):
+            page = data.get("results")
+            if isinstance(page, list):
+                return [t for t in page if isinstance(t, dict)]
+        return []
+
+    def fetch_pages(self, doc_pk: int) -> tuple[EScriptoriumPage, ...]:
+        pages: list[EScriptoriumPage] = []
+        for item in self._paginate(f"documents/{doc_pk}/parts/"):
+            pk = item.get("pk")
+            if not isinstance(pk, int):
+                # Accept #14 : une *part* sans pk entier (schéma inattendu) est
+                # ignorée — on ne devine pas un identifiant. Avertir, pas planter.
+                logger.warning(
+                    "[escriptorium] part sans 'pk' entier ignorée (doc %s) : %r",
+                    doc_pk,
+                    item.get("pk"),
+                )
+                continue
+            transcriptions = self._transcriptions(doc_pk, pk)
+            pages.append(
+                EScriptoriumPage(
+                    pk=pk,
+                    image_url=_image_uri(item, self._base_url),
+                    gt_text=extract_gt_text(transcriptions, self._layer),
+                    title=str(item.get("title", "") or f"part {pk}"),
+                )
+            )
+        return tuple(pages)
+
+
+__all__ = [
+    "DEFAULT_LAYER",
+    "EScriptoriumImporter",
+    "EScriptoriumPage",
+    "extract_gt_text",
+]

cinoc/adapters/corpus/gallica.py

@@ -0,0 +1,160 @@
+"""Importeur de corpus **Gallica** (BnF) — couche 5.
+
+Gallica expose ses images via un **manifeste IIIF** (réutilisé tel quel par
+``IIIFImporter``) et son OCR par page via l'endpoint **ALTO** officiel
+``RequestDigitalElement``. Cet adapter ne porte que la logique propre à Gallica :
+normalisation de l'**ARK**, URL du manifeste IIIF, et récupération de l'OCR d'une
+page (ALTO → texte en ordre de lecture).
+
+Choix : **ALTO** plutôt que ``texteBrut``. L'endpoint ``f{n}.texteBrut`` est
+désormais protégé par un challenge anti-bot (ALTCHA) en accès automatisé, donc
+inutilisable en import ; ``RequestDigitalElement?...&E=ALTO`` reste accessible et
+plus riche (on en extrait le texte via le parseur ALTO de la couche 2).
+
+Bug latent de la source **corrigé** : la numérotation page→OCR ne passe plus par
+une indirection ``selected_indices[i]+1`` (source d'un décalage) — c'est la
+**vue Gallica** lue dans l'URL d'image IIIF (``/f{n}/``) qui *est* le ``Deb`` de
+la requête ALTO. Le mapping est fait par le service ``app`` et prouvé par test.
+
+⚠️ L'OCR Gallica **n'est pas une vérité-terrain manuelle** : c'est la transcription
+automatique de la BnF, utilisable comme *référence* (baseline) à condition de
+l'étiqueter (``gt_source=gallica_ocr`` dans les métadonnées du corpus).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from urllib.parse import urlencode
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_bytes
+from cinoc.domain.errors import CinocError, FormatError
+from cinoc.formats.alto import (
+    AltoBlock,
+    AltoComposedBlock,
+    AltoDocument,
+    AltoTextBlock,
+    parse_alto,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Hôte Gallica de production (surchargeable pour les tests transport).
+GALLICA_BASE = "https://gallica.bnf.fr"
+
+#: ARK normalisé : ``naID/identifiant`` (ex. ``12148/btv1b8453561w``).
+_ARK_RE = re.compile(r"^[0-9]+/[A-Za-z0-9_.\-]+$")
+
+#: Numéro de **vue** Gallica dans une URL d'image IIIF (``…/ark:/12148/X/f3/…``).
+_VUE_RE = re.compile(r"/f(\d+)/")
+
+
+class GallicaArkError(CinocError):
+    """ARK Gallica malformé."""
+
+
+def normalize_ark(ark: str) -> str:
+    """Normalise un ARK (``ark:/12148/x`` | ``12148/x`` → ``12148/x``). Pur."""
+    value = ark.strip()
+    if value.startswith("ark:/"):
+        value = value[len("ark:/"):]
+    value = value.strip("/")
+    if not _ARK_RE.match(value):
+        raise GallicaArkError(
+            f"ARK invalide : {ark!r}. Forme attendue 'naID/identifiant' "
+            "(ex. '12148/btv1b8453561w')."
+        )
+    return value
+
+
+def vue_number(image_url: str) -> int | None:
+    """Numéro de vue Gallica extrait d'une URL d'image (``/f{n}/``), sinon ``None``.
+
+    C'est la source **autoritaire** pour apparier une image à son OCR : se fier à
+    la position dans la liste d'images est faux dès qu'un canvas sans image est
+    sauté par le parseur IIIF (décalage de page).
+    """
+    match = _VUE_RE.search(image_url)
+    return int(match.group(1)) if match else None
+
+
+def _block_lines(blocks: tuple[AltoBlock, ...], out: list[str]) -> None:
+    """Aplatit les ``<TextBlock>`` (récursif sur les ``<ComposedBlock>``) en lignes."""
+    for block in blocks:
+        if isinstance(block, AltoTextBlock):
+            for line in block.lines:
+                text = " ".join(s.content for s in line.strings if s.content)
+                if text:
+                    out.append(text)
+        elif isinstance(block, AltoComposedBlock):
+            _block_lines(block.blocks, out)
+
+
+def alto_to_text(document: AltoDocument) -> str:
+    """Texte d'un ALTO en **ordre de lecture** : lignes (``String/@CONTENT``) jointes.
+
+    Pas de dé-césure (le ``texteBrut`` historique n'en faisait pas non plus) : on
+    rend le contenu brut, ligne par ligne.
+    """
+    lines: list[str] = []
+    for page in document.pages:
+        _block_lines(page.blocks, lines)
+    return "\n".join(lines)
+
+
+class GallicaImporter:
+    """Localise un document Gallica : URL de manifeste IIIF + OCR ALTO par page."""
+
+    name = "gallica"
+
+    def __init__(
+        self,
+        ark: str,
+        *,
+        base_url: str = GALLICA_BASE,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.ark = normalize_ark(ark)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    @property
+    def _identifier(self) -> str:
+        """Identifiant de la numérisation (ARK sans le naID) — param ``O`` de l'ALTO."""
+        return self.ark.split("/", 1)[1]
+
+    @property
+    def manifest_url(self) -> str:
+        return f"{self._base_url}/iiif/ark:/{self.ark}/manifest.json"
+
+    def alto_url(self, page: int) -> str:
+        """URL ALTO officielle d'une vue (``RequestDigitalElement``)."""
+        query = urlencode({"O": self._identifier, "E": "ALTO", "Deb": page})
+        return f"{self._base_url}/RequestDigitalElement?{query}"
+
+    def fetch_ocr_text(self, page: int) -> str:
+        """OCR d'une vue (1-based) via ALTO → texte. ``""`` si absent ou illisible."""
+        try:
+            data = fetch_bytes(self.alto_url(page), timeout=self._timeout)
+        except HttpFetchError as exc:
+            logger.warning(
+                "[gallica] ALTO indisponible pour %s f%d : %s", self.ark, page, exc
+            )
+            return ""
+        try:
+            return alto_to_text(parse_alto(data))
+        except FormatError as exc:  # ALTO malformé ou XML invalide
+            logger.warning(
+                "[gallica] ALTO illisible pour %s f%d : %s", self.ark, page, exc
+            )
+            return ""
+
+
+__all__ = [
+    "GALLICA_BASE",
+    "GallicaArkError",
+    "GallicaImporter",
+    "alto_to_text",
+    "normalize_ark",
+    "vue_number",
+]

cinoc/adapters/corpus/htr_united.py

@@ -0,0 +1,176 @@
+"""Catalogue **HTR-United** (découverte de corpus GT) — couche 5.
+
+HTR-United publie un index communautaire de corpus de vérité-terrain HTR/OCR sous
+forme d'un fichier YAML versionné sur GitHub. Cet adapter **découvre** (télécharge
+l'index + recherche), il ne **matérialise pas** un corpus (les entrées pointent
+vers des dépôts ALTO/PAGE — matérialisation = incrémentale, ultérieure).
+
+Repli **hors-ligne** assumé : si l'index distant est injoignable ou illisible, on
+sert un **socle de démonstration** intégré (petit, pas un dump) avec
+``source="demo"`` / ``is_demo=True`` — l'appelant sait que ce n'est pas le
+catalogue à jour (alimente la future UI de sélection de corpus).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import yaml
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, CorpusHttpError, fetch_text
+
+logger = logging.getLogger(__name__)
+
+#: Index communautaire (YAML brut sur GitHub).
+CATALOGUE_URL = (
+    "https://raw.githubusercontent.com/HTR-United/htr-united/master/htr-united.yml"
+)
+
+
+@dataclass(frozen=True)
+class HTRUnitedEntry:
+    """Une entrée du catalogue (métadonnées de découverte, pas le corpus)."""
+
+    id: str
+    title: str
+    url: str
+    description: str
+    languages: tuple[str, ...]
+
+
+#: Socle de démonstration minimal (corpus HTR-United réels) — repli hors-ligne.
+_DEMO_ENTRIES: tuple[HTRUnitedEntry, ...] = (
+    HTRUnitedEntry(
+        id="cremma-medieval",
+        title="CREMMA Medieval",
+        url="https://github.com/HTR-United/cremma-medieval",
+        description="Manuscrits médiévaux français et latins.",
+        languages=("fr", "la"),
+    ),
+    HTRUnitedEntry(
+        id="lectaurep-repertoires",
+        title="LECTAUREP Répertoires",
+        url="https://github.com/HTR-United/lectaurep-repertoires",
+        description="Répertoires de notaires manuscrits (XIXe-XXe).",
+        languages=("fr",),
+    ),
+    HTRUnitedEntry(
+        id="caroline-minuscule",
+        title="Caroline Minuscule",
+        url="https://github.com/HTR-United/CemmaCarolineMinuscule",
+        description="Minuscule caroline latine.",
+        languages=("la",),
+    ),
+)
+
+
+def _as_languages(raw: object) -> tuple[str, ...]:
+    """Normalise un champ langue (str, liste de str, ou liste de dicts)."""
+    if isinstance(raw, str):
+        return (raw,)
+    if isinstance(raw, list):
+        out: list[str] = []
+        for item in raw:
+            if isinstance(item, str):
+                out.append(item)
+            elif isinstance(item, dict):
+                value = item.get("iso") or item.get("lang") or item.get("label")
+                if value:
+                    out.append(str(value))
+        return tuple(out)
+    return ()
+
+
+def _entry_from_dict(item: dict[str, object]) -> HTRUnitedEntry | None:
+    url = str(item.get("url", "") or "")
+    title = str(item.get("title", "") or "")
+    if not url and not title:
+        return None
+    entry_id = str(item.get("id") or "") or url.rstrip("/").rsplit("/", 1)[-1] or title
+    return HTRUnitedEntry(
+        id=entry_id,
+        title=title or entry_id,
+        url=url,
+        description=str(item.get("description", "") or ""),
+        languages=_as_languages(item.get("language")),
+    )
+
+
+def parse_catalogue(raw_yaml: str) -> tuple[HTRUnitedEntry, ...]:
+    """Parse l'index YAML HTR-United → entrées. Pur (tolérant au schéma)."""
+    data = yaml.safe_load(raw_yaml)
+    if isinstance(data, dict):
+        for key in ("data", "projects", "catalog", "catalogue"):
+            if isinstance(data.get(key), list):
+                data = data[key]
+                break
+    if not isinstance(data, list):
+        return ()
+    entries = [
+        _entry_from_dict(item) for item in data if isinstance(item, dict)
+    ]
+    return tuple(e for e in entries if e is not None)
+
+
+@dataclass(frozen=True)
+class HTRUnitedCatalogue:
+    """Index HTR-United chargé, avec sa provenance (``remote`` | ``demo``)."""
+
+    entries: tuple[HTRUnitedEntry, ...]
+    source: str
+
+    @property
+    def is_demo(self) -> bool:
+        return self.source == "demo"
+
+    @classmethod
+    def from_demo(cls) -> HTRUnitedCatalogue:
+        return cls(entries=_DEMO_ENTRIES, source="demo")
+
+    def search(
+        self, query: str = "", language: str | None = None
+    ) -> tuple[HTRUnitedEntry, ...]:
+        results = self.entries
+        if query:
+            q = query.lower()
+            results = tuple(
+                e
+                for e in results
+                if q in e.title.lower()
+                or q in e.description.lower()
+                or q in e.id.lower()
+                or any(q in lg.lower() for lg in e.languages)
+            )
+        if language:
+            lang = language.lower()
+            results = tuple(
+                e for e in results if any(lang in lg.lower() for lg in e.languages)
+            )
+        return results
+
+
+def fetch_catalogue(
+    *, catalogue_url: str = CATALOGUE_URL, timeout: float = DEFAULT_TIMEOUT
+) -> HTRUnitedCatalogue:
+    """Télécharge l'index HTR-United ; **repli démo** si indisponible/illisible."""
+    try:
+        raw = fetch_text(catalogue_url, timeout=timeout)
+        entries = parse_catalogue(raw)
+    except (CorpusHttpError, yaml.YAMLError) as exc:
+        logger.warning(
+            "[htr_united] index distant indisponible (%s) — repli démo : %s",
+            catalogue_url,
+            exc,
+        )
+        return HTRUnitedCatalogue.from_demo()
+    return HTRUnitedCatalogue(entries=entries, source="remote")
+
+
+__all__ = [
+    "CATALOGUE_URL",
+    "HTRUnitedCatalogue",
+    "HTRUnitedEntry",
+    "fetch_catalogue",
+    "parse_catalogue",
+]

cinoc/adapters/corpus/huggingface.py

@@ -0,0 +1,487 @@
+"""Découverte de datasets HTR/OCR sur **HuggingFace Hub** — couche 5.
+
+Recherche (découverte), pas matérialisation : on liste des datasets candidats
+(socle de **référence** intégré + API publique du Hub). Le téléchargement effectif
+d'un dataset (lib ``datasets``, dépendance lourde) est un extra **ultérieur**
+(`cinoc[huggingface]`), hors de cette tranche.
+
+L'appel API est **best-effort** : s'il échoue, on renvoie le socle de référence
+(``source="reference"``) en journalisant — l'utilisateur n'est jamais bloqué, et
+sait d'où vient chaque résultat (``source`` : ``reference`` | ``api``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from urllib.parse import urlencode
+
+from cinoc.adapters.corpus._http import (
+    DEFAULT_TIMEOUT,
+    IMAGE_MAX_BYTES,
+    CorpusHttpError,
+    fetch_json,
+)
+from cinoc.domain.errors import CinocError
+
+logger = logging.getLogger(__name__)
+
+HF_API_BASE = "https://huggingface.co/api"
+
+#: Tag de convention apposé aux datasets **curés Cinoc** (carte HF) : il rend un
+#: dataset de référence **découvrable** sur un compte sans coller son ``repo_id``.
+#: Émis par ``app.dataset_standardize`` (front-matter), filtré par ``discover_curated``.
+CURATED_DATASET_TAG = "cinoc-corpus"
+
+#: Convention Cinoc (cf. ``docs/corpus_huggingface.md``) : un dataset importable
+#: porte **au minimum** une colonne image et une colonne vérité-terrain. La
+#: segmentation est une extension *future* (non requise ici).
+CINOC_IMAGE_COLUMN = "image"
+CINOC_GT_COLUMN = "ground_truth"
+
+#: Extensions image reconnues (sinon ``.jpg`` par défaut) pour nommer le fichier.
+_IMAGE_EXTS = frozenset({".png", ".jpg", ".jpeg", ".tif", ".tiff", ".jp2", ".webp"})
+
+
+@dataclass(frozen=True)
+class HuggingFaceDataset:
+    """Un dataset candidat (métadonnées de découverte)."""
+
+    dataset_id: str
+    title: str
+    description: str
+    languages: tuple[str, ...]
+    downloads: int
+    source: str  # "reference" | "api"
+
+    @property
+    def hf_url(self) -> str:
+        return f"https://huggingface.co/datasets/{self.dataset_id}"
+
+
+@dataclass(frozen=True)
+class CuratedDatasetRef:
+    """Un dataset **curé Cinoc** découvert sur un compte HF (tag de convention).
+
+    Métadonnées d'affichage **et** d'import en un clic : ``repo_id`` (+ ``revision``
+    si l'API la fournit, pour épingler la repro) alimentent directement
+    ``import_curated_hf_corpus``."""
+
+    repo_id: str
+    title: str
+    revision: str | None
+    last_modified: str
+
+
+def _ref(
+    dataset_id: str, title: str, desc: str, langs: tuple[str, ...], dl: int
+) -> HuggingFaceDataset:
+    return HuggingFaceDataset(
+        dataset_id=dataset_id,
+        title=title,
+        description=desc,
+        languages=langs,
+        downloads=dl,
+        source="reference",
+    )
+
+
+#: Socle de référence minimal (datasets HTR/OCR patrimoniaux connus).
+_REFERENCE_DATASETS: tuple[HuggingFaceDataset, ...] = (
+    _ref(
+        "Teklia/NorHand", "NorHand", "Écriture manuscrite norvégienne.", ("no",), 1200
+    ),
+    _ref(
+        "Teklia/IAM-line",
+        "IAM (lignes)",
+        "Référence anglaise manuscrite.",
+        ("en",),
+        8400,
+    ),
+    _ref(
+        "bnf/gallica-presse-xix",
+        "Gallica Presse XIXe",
+        "Journaux numérisés XIXe (OCR + images).",
+        ("fr",),
+        15200,
+    ),
+)
+
+
+def _matches(ds: HuggingFaceDataset, query: str, language: str | None) -> bool:
+    if query:
+        q = query.lower()
+        if not (
+            q in ds.title.lower()
+            or q in ds.description.lower()
+            or q in ds.dataset_id.lower()
+            or any(q in lg.lower() for lg in ds.languages)
+        ):
+            return False
+    if language and not any(language.lower() in lg.lower() for lg in ds.languages):
+        return False
+    return True
+
+
+def search_reference(
+    query: str = "", language: str | None = None
+) -> tuple[HuggingFaceDataset, ...]:
+    """Filtre le socle de référence intégré. Pur (sans réseau)."""
+    return tuple(ds for ds in _REFERENCE_DATASETS if _matches(ds, query, language))
+
+
+def _parse_api(payload: object) -> tuple[HuggingFaceDataset, ...]:
+    """Mappe la réponse de l'API HF (liste de dicts) → datasets. Pur."""
+    if not isinstance(payload, list):
+        return ()
+    out: list[HuggingFaceDataset] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        dataset_id = str(item.get("id", "") or "")
+        if not dataset_id:
+            continue
+        downloads = item.get("downloads", 0)
+        out.append(
+            HuggingFaceDataset(
+                dataset_id=dataset_id,
+                title=dataset_id,
+                description="",
+                languages=(),
+                downloads=int(downloads) if isinstance(downloads, int) else 0,
+                source="api",
+            )
+        )
+    return tuple(out)
+
+
+class HuggingFaceCatalogue:
+    """Recherche de datasets : socle de référence + API publique (best-effort)."""
+
+    name = "huggingface"
+
+    def __init__(
+        self, *, api_base: str = HF_API_BASE, timeout: float = DEFAULT_TIMEOUT
+    ) -> None:
+        self._api_base = api_base.rstrip("/")
+        self._timeout = timeout
+
+    def _fetch_api(
+        self, query: str, language: str | None, limit: int
+    ) -> tuple[HuggingFaceDataset, ...]:
+        params: dict[str, str] = {
+            "task_categories": "image-to-text",
+            "limit": str(min(limit, 50)),
+        }
+        if query:
+            params["search"] = query
+        if language:
+            params["language"] = language
+        url = f"{self._api_base}/datasets?{urlencode(params)}"
+        return _parse_api(fetch_json(url, timeout=self._timeout))
+
+    def search(
+        self,
+        query: str = "",
+        language: str | None = None,
+        *,
+        limit: int = 20,
+        use_reference: bool = True,
+        include_api: bool = True,
+    ) -> tuple[HuggingFaceDataset, ...]:
+        results: list[HuggingFaceDataset] = []
+        if use_reference:
+            results.extend(search_reference(query, language))
+        if include_api:
+            seen = {ds.dataset_id for ds in results}
+            try:
+                for ds in self._fetch_api(query, language, limit):
+                    if ds.dataset_id not in seen:
+                        results.append(ds)
+                        seen.add(ds.dataset_id)
+            except CorpusHttpError as exc:
+                logger.warning(
+                    "[huggingface] recherche API indisponible — socle de référence "
+                    "seul : %s",
+                    exc,
+                )
+        # Accept #9 : socle de référence d'abord, API ensuite, puis troncature
+        # finale à `limit` — la référence (curée) prime sur l'API si l'union
+        # dépasse. Choix de découverte (display), pas de classement par score.
+        return tuple(results[:limit])
+
+
+class HuggingFaceConventionError(CinocError):
+    """Le dataset ne respecte pas la **convention Cinoc** (colonnes attendues)."""
+
+
+class HuggingFaceUnavailableError(CinocError):
+    """La lib ``datasets`` (extra ``[huggingface]``) n'est pas installée."""
+
+
+@dataclass(frozen=True)
+class HFPage:
+    """Une page **streamée** : octets image encodés + extension + texte GT.
+
+    Type neutre à la frontière adapter→app : l'image est livrée en **octets**
+    (jamais un objet PIL) pour que la matérialisation disque (couche 6) n'ait
+    aucune dépendance image.
+    """
+
+    image_bytes: bytes
+    image_ext: str
+    gt_text: str
+
+
+#: Charge un dataset en streaming → itérable de lignes. Injectable (test).
+HFLoader = Callable[[str, str], Iterable[object]]
+
+
+def _default_loader(dataset_id: str, split: str) -> Iterable[object]:
+    """Charge le dataset HF **en streaming** (jamais de snapshot local complet).
+
+    Import **paresseux** de ``datasets`` (extra ``[huggingface]``) : sans l'extra,
+    lève ``HuggingFaceUnavailableError`` (message actionnable). Les images sont
+    castées en ``Image(decode=False)`` → octets bruts (pas de décodage PIL).
+    """
+    try:
+        from datasets import Image, load_dataset  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise HuggingFaceUnavailableError(
+            "import HuggingFace indisponible : installer 'cinoc[huggingface]' "
+            "(lib 'datasets')."
+        ) from exc
+    dataset = load_dataset(dataset_id, split=split, streaming=True)
+    features = getattr(dataset, "features", None) or {}
+    if CINOC_IMAGE_COLUMN in features:
+        dataset = dataset.cast_column(CINOC_IMAGE_COLUMN, Image(decode=False))
+    return dataset  # type: ignore[no-any-return]
+
+
+def _ext_from_path(path: object) -> str:
+    if isinstance(path, str) and path:
+        suffix = PurePosixPath(path).suffix.lower()
+        if suffix in _IMAGE_EXTS:
+            return suffix
+    return ".jpg"
+
+
+def _extract_image(value: object) -> tuple[bytes, str]:
+    """Octets image + extension depuis une cellule ``image`` (``decode=False``)."""
+    if isinstance(value, dict):
+        raw = value.get("bytes")
+        if isinstance(raw, bytes) and raw:
+            return raw, _ext_from_path(value.get("path"))
+    raise HuggingFaceConventionError(
+        f"colonne {CINOC_IMAGE_COLUMN!r} : octets image absents (le dataset "
+        "doit stocker l'image en octets ; cf. convention Cinoc)."
+    )
+
+
+def _validate_columns(row: dict[str, object]) -> None:
+    missing = [c for c in (CINOC_IMAGE_COLUMN, CINOC_GT_COLUMN) if c not in row]
+    if missing:
+        raise HuggingFaceConventionError(
+            f"dataset non conforme à la convention Cinoc : colonnes manquantes "
+            f"{missing} (attendu : {CINOC_IMAGE_COLUMN!r} + {CINOC_GT_COLUMN!r})."
+        )
+
+
+def stream_pages(
+    dataset_id: str,
+    *,
+    split: str = "train",
+    limit: int | None = None,
+    loader: HFLoader | None = None,
+) -> Iterator[HFPage]:
+    """Streame les pages d'un dataset HF conforme à la **convention Cinoc**.
+
+    Page-par-page (``streaming=True`` côté ``datasets``) : on ne télécharge jamais
+    le snapshot complet ; ``limit`` borne le nombre de pages lues. La conformité
+    (colonnes ``image`` + ``ground_truth``) est validée sur la **1ʳᵉ ligne**. Une
+    image dépassant ``IMAGE_MAX_BYTES`` est **ignorée** (avertie), pas fatale.
+
+    ``loader`` (``(dataset_id, split) → itérable de lignes``) est injectable pour
+    tester sans la lib ``datasets`` ; défaut = streaming réel.
+    """
+    load = loader or _default_loader
+    validated = False
+    count = 0
+    for row in load(dataset_id, split):
+        if not isinstance(row, dict):
+            continue
+        if not validated:
+            _validate_columns(row)
+            validated = True
+        image_bytes, ext = _extract_image(row[CINOC_IMAGE_COLUMN])
+        if len(image_bytes) > IMAGE_MAX_BYTES:
+            logger.warning(
+                "[huggingface] image > %d octets ignorée (dataset %s).",
+                IMAGE_MAX_BYTES,
+                dataset_id,
+            )
+            continue
+        gt_value = row.get(CINOC_GT_COLUMN)
+        gt_text = gt_value if isinstance(gt_value, str) else ""
+        yield HFPage(image_bytes=image_bytes, image_ext=ext, gt_text=gt_text)
+        count += 1
+        if limit is not None and count >= limit:
+            return
+
+
+#: Récupère un JSON depuis une URL. Injectable → ``discover_curated`` se teste
+#: sans réseau (le défaut tape l'API HF via ``fetch_json``).
+CuratedFetcher = Callable[[str], object]
+
+
+def _parse_curated(payload: object, *, tag: str) -> tuple[CuratedDatasetRef, ...]:
+    """Réponse ``/api/datasets`` (liste de dicts) → datasets curés. Pure.
+
+    Re-filtre **défensivement** sur le tag (si la liste porte ``tags``) : on ne
+    présente que de vrais layouts Cinoc, jamais un dataset quelconque du compte."""
+    if not isinstance(payload, list):
+        return ()
+    out: list[CuratedDatasetRef] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        repo_id = str(item.get("id", "") or "")
+        if not repo_id:
+            continue
+        tags = item.get("tags")
+        if isinstance(tags, list) and tag not in tags:
+            continue
+        sha = item.get("sha")
+        out.append(
+            CuratedDatasetRef(
+                repo_id=repo_id,
+                title=str(item.get("id", repo_id)),
+                revision=str(sha) if isinstance(sha, str) and sha else None,
+                last_modified=str(item.get("lastModified", "") or ""),
+            )
+        )
+    return tuple(out)
+
+
+def whoami(
+    token: str,
+    *,
+    api_base: str = HF_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+    fetcher: Callable[[str], object] | None = None,
+) -> str | None:
+    """Handle du compte HF derrière un ``token`` (``/api/whoami-v2``). Best-effort.
+
+    Sert à faire **apparaître automatiquement** les datasets curés de l'opérateur
+    sans qu'il colle son identifiant : on résout son handle depuis sa clé. Échec
+    réseau / token invalide → ``None`` (repli sur ``CINOC_HF_AUTHOR`` ou l'import
+    manuel). Le token n'est jamais journalisé (cf. ``_http``)."""
+    if not token:
+        return None
+    get = fetcher or (
+        lambda url: fetch_json(
+            url, timeout=timeout, headers={"Authorization": f"Bearer {token}"}
+        )
+    )
+    try:
+        payload = get(f"{api_base.rstrip('/')}/whoami-v2")
+    except CorpusHttpError as exc:
+        logger.warning("[huggingface] whoami indisponible : %s", exc)
+        return None
+    if isinstance(payload, dict):
+        name = payload.get("name")
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+    return None
+
+
+def discover_curated(
+    author: str,
+    *,
+    tag: str = CURATED_DATASET_TAG,
+    api_base: str = HF_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+    fetcher: CuratedFetcher | None = None,
+) -> tuple[CuratedDatasetRef, ...]:
+    """Liste les datasets **curés Cinoc** d'un compte HF (``author`` + ``tag``).
+
+    Best-effort : API injoignable → ``()`` en journalisant (l'UI retombe sur
+    l'import manuel par ``repo_id``, jamais un blocage). C'est ce qui fait
+    « apparaître » un dataset publié sans coller son identifiant : on filtre le
+    compte par le tag de convention."""
+    if not author:
+        return ()
+    get = fetcher or (lambda url: fetch_json(url, timeout=timeout))
+    params = {"author": author, "filter": tag, "full": "true", "limit": "100"}
+    url = f"{api_base.rstrip('/')}/datasets?{urlencode(params)}"
+    try:
+        payload = get(url)
+    except CorpusHttpError as exc:
+        logger.warning(
+            "[huggingface] découverte curée indisponible (compte %s) : %s",
+            author,
+            exc,
+        )
+        return ()
+    return _parse_curated(payload, tag=tag)
+
+
+def snapshot_curated_layout(
+    repo_id: str, dest: Path, revision: str | None
+) -> Path:  # pragma: no cover -- réseau réel (test 'live')
+    """Snapshot **partiel** d'un dataset curé Cinoc publié sur HF.
+
+    Ne rapatrie que ``corpus.json`` + ``ground_truth/`` (scorables en local) ; les
+    images restent des **références distantes** : le dataset embarque un layout
+    **IIIF statique** (Image API 3 level0, cf. ``app.dataset_standardize``) servi
+    par la racine ``resolve`` HF épinglée à la révision — l'URL est donc un lien
+    ``huggingface.co`` dont le chemin suit la syntaxe IIIF. Le rapport les affiche
+    (saveur « liens », D-094) et l'orchestrateur les **matérialise au run** (fetch
+    durci) pour les moteurs. ``huggingface_hub`` (extra ``[huggingface]``) est
+    importé paresseusement → sans l'extra, ``HuggingFaceUnavailableError``
+    actionnable ; dépôt/révision injoignable → ``CorpusHttpError`` (→ 422 web).
+    """
+    try:
+        from huggingface_hub import snapshot_download  # type: ignore[import-not-found]
+        from huggingface_hub.utils import (  # type: ignore[import-not-found]
+            HfHubHTTPError,
+        )
+    except ImportError as exc:
+        raise HuggingFaceUnavailableError(
+            "import curé HF indisponible : installer 'cinoc[huggingface]' "
+            "(lib 'huggingface_hub')."
+        ) from exc
+    try:
+        local = snapshot_download(
+            repo_id,
+            repo_type="dataset",
+            revision=revision,
+            allow_patterns=["corpus.json", "ground_truth/*"],
+            local_dir=str(dest),
+        )
+    except HfHubHTTPError as exc:
+        raise CorpusHttpError(
+            f"dataset curé HF {repo_id!r} injoignable : {exc}"
+        ) from exc
+    return Path(local)
+
+
+__all__ = [
+    "HF_API_BASE",
+    "CINOC_GT_COLUMN",
+    "CINOC_IMAGE_COLUMN",
+    "CURATED_DATASET_TAG",
+    "CuratedDatasetRef",
+    "HFPage",
+    "HuggingFaceCatalogue",
+    "HuggingFaceConventionError",
+    "HuggingFaceDataset",
+    "HuggingFaceUnavailableError",
+    "discover_curated",
+    "search_reference",
+    "snapshot_curated_layout",
+    "stream_pages",
+    "whoami",
+]

cinoc/adapters/corpus/iiif.py

@@ -0,0 +1,137 @@
+"""Importeur de corpus **IIIF** (Presentation API v2 & v3) — couche 5.
+
+Rôle : **localiser** les pages d'un manifeste (parsing du schéma → URLs d'image).
+La **matérialisation disque** (téléchargement → ``CorpusSpec``) vit en couche
+``app`` (``app/corpus_import.py``) : un adapter parle protocole, pas filesystem.
+
+Périmètre : **images seules**. Un manifeste IIIF porte des pages numérisées, pas
+de transcription ; le corpus importé est donc sans vérité-terrain (OCR exécutable,
+métriques non applicables tant qu'une GT n'est pas appariée). C'est un choix
+assumé de la tranche, pas un manque.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_json
+
+
+@dataclass(frozen=True)
+class IIIFImage:
+    """Une page du manifeste : son URL d'image + un label lisible."""
+
+    image_url: str
+    label: str
+
+
+def _extract_label(raw: object) -> str:
+    """Aplati les formats de label IIIF (str, liste, map de langue v3)."""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list) and raw:
+        return _extract_label(raw[0])
+    if isinstance(raw, dict):
+        for lang in ("fr", "en", "none", "@value"):
+            val = raw.get(lang)
+            if val:
+                return str(val[0]) if isinstance(val, list) and val else str(val)
+        for val in raw.values():
+            return _extract_label(val)
+    return str(raw) if raw else ""
+
+
+def _service_image_url(service: object) -> str:
+    """Construit ``{service}/full/max/0/default.jpg`` depuis un service Image API."""
+    if isinstance(service, list):
+        service = service[0] if service else {}
+    if not isinstance(service, dict):
+        return ""
+    svc_id = service.get("@id") or service.get("id") or ""
+    if not isinstance(svc_id, str) or not svc_id:
+        return ""
+    return f"{svc_id.rstrip('/')}/full/max/0/default.jpg"
+
+
+def _image_url_v2(canvas: dict[str, Any]) -> str:
+    images = canvas.get("images") or []
+    if not images or not isinstance(images[0], dict):
+        return ""
+    resource = images[0].get("resource", {})
+    if not isinstance(resource, dict):
+        return ""
+    direct = resource.get("@id", "")
+    if isinstance(direct, str) and direct and not direct.endswith("/info.json"):
+        return direct
+    return _service_image_url(resource.get("service", {}))
+
+
+def _image_url_v3(canvas: dict[str, Any]) -> str:
+    for annotation_page in canvas.get("items") or []:
+        for annotation in annotation_page.get("items") or []:
+            body = annotation.get("body", {})
+            if isinstance(body, list):
+                body = body[0] if body else {}
+            if not isinstance(body, dict):
+                continue
+            url = body.get("id") or body.get("@id") or ""
+            if isinstance(url, str) and url and body.get("type") == "Image":
+                return url
+            service_url = _service_image_url(body.get("service", []))
+            if service_url:
+                return service_url
+            if isinstance(url, str) and url:
+                return url
+    return ""
+
+
+def _detect_version(manifest: dict[str, Any]) -> int:
+    context = manifest.get("@context", "")
+    contexts = context if isinstance(context, list) else [context]
+    if any(isinstance(c, str) and "presentation/3" in c for c in contexts):
+        return 3
+    if manifest.get("type") == "Manifest" and "items" in manifest:
+        return 3
+    return 2
+
+
+def parse_manifest(manifest: dict[str, Any]) -> tuple[IIIFImage, ...]:
+    """Parse un manifeste IIIF (v2/v3 auto-détecté) → pages avec image. Pur."""
+    if _detect_version(manifest) == 3:
+        canvases = manifest.get("items") or []
+        extract = _image_url_v3
+    else:
+        sequences = manifest.get("sequences") or []
+        canvases = sequences[0].get("canvases", []) if sequences else []
+        extract = _image_url_v2
+    images: list[IIIFImage] = []
+    for i, canvas in enumerate(canvases, start=1):
+        if not isinstance(canvas, dict):
+            continue
+        url = extract(canvas)
+        if not url:
+            continue
+        label = _extract_label(canvas.get("label", f"canvas_{i}")) or f"canvas_{i}"
+        images.append(IIIFImage(image_url=url, label=label))
+    return tuple(images)
+
+
+class IIIFImporter:
+    """Localise les pages d'un manifeste IIIF (fetch + parse, **sans disque**)."""
+
+    name = "iiif"
+
+    def __init__(self, *, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self._timeout = timeout
+
+    def fetch_images(self, manifest_url: str) -> tuple[IIIFImage, ...]:
+        manifest = fetch_json(manifest_url, timeout=self._timeout)
+        if not isinstance(manifest, dict):
+            raise HttpFetchError(
+                f"manifeste IIIF {manifest_url!r} : objet JSON attendu."
+            )
+        return parse_manifest(manifest)
+
+
+__all__ = ["IIIFImage", "IIIFImporter", "parse_manifest"]

cinoc/adapters/images.py

@@ -0,0 +1,130 @@
+"""Vignettes du rapport : image → dérivé JPEG redimensionné (couche 5, adapter).
+
+Le redimensionnement utilise **Pillow** (interdit en ``reports`` — couche 7) ; il
+vit donc ici. Deux saveurs partagent le **même cœur** ``_render_jpeg`` :
+
+- ``thumbnail_data_uri`` → **data-URI** embarqué dans le HTML (saveur fichier
+  unique) ; les octets ne touchent jamais le ``RunResult``.
+- ``thumbnail_to_file`` → écrit le dérivé dans un dossier d'assets et renvoie un
+  **href relatif** (saveur dossier : HTML léger à liens relatifs).
+
+**Dégradé gracieux** : si Pillow n'est pas installé (extra ``[images]``), si le
+fichier manque ou est illisible → ``None`` (le rapport retombe sur l'aperçu
+synthétique). Aucune exception large.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _render_jpeg(source: str | Path, max_px: int) -> bytes | None:
+    """Octets JPEG d'une image locale redimensionnée ; ``None`` si indisponible.
+
+    Cœur partagé des deux saveurs (data-URI / fichier) : redimensionne pour que le
+    plus grand côté ≤ ``max_px`` (jamais agrandi), convertit en RGB, encode JPEG.
+    ``None`` (avec ``logger.warning``) si Pillow absent, fichier introuvable, ou
+    image illisible — le rendu reste fonctionnel (aperçu synthétique)."""
+    path = Path(source)
+    if not path.is_file():
+        return None
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError as exc:
+        logger.warning(
+            "[images] Pillow indisponible (%s) — vignettes omises, aperçu "
+            "synthétique. Installer l'extra ``[images]``.",
+            exc,
+        )
+        return None
+    try:
+        with Image.open(path) as opened:
+            rgb = opened.convert("RGB")
+            rgb.thumbnail((max_px, max_px))
+            buffer = io.BytesIO()
+            rgb.save(buffer, format="JPEG", quality=82, optimize=True)
+    except (UnidentifiedImageError, OSError) as exc:
+        logger.warning("[images] image illisible %s : %s — vignette omise.", path, exc)
+        return None
+    return buffer.getvalue()
+
+
+def thumbnail_data_uri(source: str | Path, *, max_px: int = 280) -> str | None:
+    """Vignette JPEG **data-URI** d'une image locale ; ``None`` si indisponible.
+
+    Saveur fichier unique : les octets sont inlinés dans le HTML. ``None`` si le
+    dérivé n'a pu être produit (Pillow absent, fichier manquant/illisible)."""
+    raw = _render_jpeg(source, max_px)
+    if raw is None:
+        return None
+    payload = base64.b64encode(raw).decode("ascii")
+    return f"data:image/jpeg;base64,{payload}"
+
+
+def thumbnail_to_file(
+    source: str | Path, dest_dir: str | Path, stem: str, *, max_px: int = 280
+) -> str | None:
+    """Écrit la vignette JPEG dans ``dest_dir/<stem>.jpg`` ; renvoie un href relatif.
+
+    Saveur dossier : le dérivé est **un fichier sur disque** (pas inliné), le HTML
+    n'en porte qu'une **référence relative**. L'href renvoyé est relatif au
+    **parent** de ``dest_dir`` (``f"{dest_dir.name}/{stem}.jpg"``, séparateur ``/``
+    portable) : l'appelant garantit que le HTML est un voisin de ``dest_dir`` (cf.
+    ``app.report_images.write_report_bundle``). ``None`` si le dérivé n'a pu être
+    produit (dégradé gracieux, aucun fichier écrit, aucun dossier créé)."""
+    raw = _render_jpeg(source, max_px)
+    if raw is None:
+        return None
+    folder = Path(dest_dir)
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / f"{stem}.jpg").write_bytes(raw)
+    return f"{folder.name}/{stem}.jpg"
+
+
+def iiif_derivative(
+    source: str | Path, dest_path: str | Path, *, width: int
+) -> tuple[int, int] | None:
+    """Écrit un dérivé JPEG de **largeur exacte** ``width`` (jamais agrandi) à
+    ``dest_path`` ; renvoie ``(largeur, hauteur)`` réels, ou ``None`` (dégradé).
+
+    Variante **largeur-fixe** de ``_render_jpeg`` (qui borne le plus grand côté) :
+    une taille IIIF Image API ``full/{w},/`` exige une largeur exacte, pas un
+    cadrage. Convertit en RGB, ré-échantillonne (Lanczos), crée les dossiers
+    parents. ``None`` (avec ``logger.warning``) si Pillow absent, fichier
+    introuvable ou image illisible — l'outil appelant décide d'échouer ou non."""
+    path = Path(source)
+    if not path.is_file():
+        logger.warning("[images] image introuvable %s — dérivé IIIF omis.", path)
+        return None
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError as exc:
+        logger.warning(
+            "[images] Pillow indisponible (%s) — dérivé IIIF omis. Extra ``[images]``.",
+            exc,
+        )
+        return None
+    try:
+        with Image.open(path) as opened:
+            rgb = opened.convert("RGB")
+            orig_w, orig_h = rgb.size
+            target_w = min(width, orig_w)  # jamais agrandi
+            target_h = max(1, round(orig_h * target_w / orig_w))
+            resized = rgb.resize((target_w, target_h), Image.Resampling.LANCZOS)
+            dest = Path(dest_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            resized.save(dest, format="JPEG", quality=82, optimize=True)
+    except (UnidentifiedImageError, OSError) as exc:
+        logger.warning(
+            "[images] image illisible %s : %s — dérivé IIIF omis.", path, exc
+        )
+        return None
+    return (target_w, target_h)
+
+
+__all__ = ["thumbnail_data_uri", "thumbnail_to_file", "iiif_derivative"]

cinoc/adapters/layout/__init__.py

@@ -0,0 +1,3 @@
+"""Adapters de mise en page (couche 5) — socle ``precomputed``."""
+
+from __future__ import annotations

cinoc/adapters/layout/_base.py

@@ -0,0 +1,114 @@
+"""Contrat **partagé** des segmenteurs de mise en page (couche 5).
+
+Tout segmenteur (PP-DocLayout maison, segmenteur distant HF, futurs) produit la
+même forme : un détecteur rend des **régions brutes** (``LayoutDetection``), qu'on
+convertit en ``CanonicalLayout`` neutre (``to_canonical_layout``) puis qu'on
+sérialise en artefact ``LAYOUT`` (``layout_step_output``, la *queue* d'``execute``).
+
+Ces pièces sont **agnostiques du moteur** : elles vivaient dans ``pp_doclayout``
+(le segmenteur maison), ce qui forçait le segmenteur distant à importer un module
+PaddleX-spécifique pour les réutiliser. Extraites ici, les deux adapters en
+dépendent sans se coupler l'un à l'autre.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import BBox, CanonicalLayout, Geometry, LayoutPage, Region
+from cinoc.pipeline.types import RunContext, StepOutput
+
+
+@dataclass(frozen=True)
+class DetectedRegion:
+    """Une région détectée : étiquette, boîte (pixels) et score de confiance."""
+
+    label: str
+    x: int
+    y: int
+    width: int
+    height: int
+    score: float
+
+
+@dataclass(frozen=True)
+class LayoutDetection:
+    """Sortie brute d'un détecteur : dimensions de page + régions détectées."""
+
+    page_width: int
+    page_height: int
+    regions: tuple[DetectedRegion, ...]
+
+
+#: Détecteur **injectable** : chemin image → détection. Le défaut (PaddleX, appel
+#: distant…) est résolu paresseusement à l'exécution ; les tests injectent un faux.
+DetectorFn = Callable[[str], LayoutDetection]
+
+
+def to_canonical_layout(
+    detection: LayoutDetection, *, min_score: float
+) -> CanonicalLayout:
+    """Détections → ``CanonicalLayout`` (1 page, régions **sans lignes**).
+
+    Filtre au seuil de score, **trie** par position (haut→bas puis gauche→droite)
+    pour un ordre de lecture **déterministe** indépendant de l'ordre de détection,
+    et numérote les régions ``r1..rN``. Le ``label`` du modèle devient le
+    ``region_type`` neutre (``None`` si vide).
+    """
+    kept = [r for r in detection.regions if r.score >= min_score]
+    ordered = sorted(kept, key=lambda r: (r.y, r.x))
+    regions = tuple(
+        Region(
+            id=f"r{index + 1}",
+            region_type=r.label or None,
+            geometry=Geometry(
+                bbox=BBox(x=r.x, y=r.y, width=r.width, height=r.height)
+            ),
+        )
+        for index, r in enumerate(ordered)
+    )
+    page = LayoutPage(
+        width=detection.page_width or None,
+        height=detection.page_height or None,
+        regions=regions,
+        reading_order=tuple(region.id for region in regions),
+    )
+    return CanonicalLayout(pages=(page,))
+
+
+def layout_step_output(
+    layout: CanonicalLayout, context: RunContext, name: str
+) -> StepOutput:
+    """Sérialise un ``CanonicalLayout`` → artefact ``LAYOUT`` (tail d'``execute``
+    partagé par tous les segmenteurs : PP-DocLayout, segmenteur distant…)."""
+    if context.workspace_uri is None:
+        raise AdapterStepError(f"{name} : workspace requis (RunContext.workspace_uri).")
+    payload = layout.model_dump_json().encode("utf-8")
+    output_path = workspace_artifact_path(
+        context.workspace_uri, context.document_id, name, "layout.json"
+    )
+    output_path.write_bytes(payload)
+    return StepOutput(
+        artifacts={
+            ArtifactType.LAYOUT: Artifact(
+                id=f"{context.document_id}:{name}:layout",
+                document_id=context.document_id,
+                type=ArtifactType.LAYOUT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(payload),
+            )
+        }
+    )
+
+
+__all__ = [
+    "DetectedRegion",
+    "DetectorFn",
+    "LayoutDetection",
+    "layout_step_output",
+    "to_canonical_layout",
+]

cinoc/adapters/layout/assembler.py

@@ -0,0 +1,89 @@
+"""``AltoAssembler`` — assemblage ``LAYOUT → ALTO_XML`` (couche 5).
+
+Troisième étage du pipeline de segmentation (``CLAUDE.md`` §3 : *assemblage
+LAYOUT → ALTO_XML*). C'est un **constructeur d'ALTO** au sens du même `Module`
+Protocol que les autres briques : il prend un ``CanonicalLayout`` **rempli**
+(sortie du fan-out, sérialisé JSON) et émet de l'ALTO 4 déterministe
+(``layout_to_alto`` + ``write_alto`` octet-stable).
+
+L'assembleur vit en couche 5 (et non `pipeline`) parce qu'il dépend de `formats`
+(`write_alto`) — un import légal pour un adapter, interdit à `pipeline`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout
+from cinoc.formats.alto import write_alto
+from cinoc.formats.alto.layout_map import layout_to_alto
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+class AltoAssembler:
+    """Assemble un ``LAYOUT`` rempli en ``ALTO_XML`` (ALTO 4, déterministe)."""
+
+    @property
+    def name(self) -> str:
+        return "alto_assembler"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.ALTO_XML})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        layout_art = inputs.get(ArtifactType.LAYOUT)
+        if layout_art is None or layout_art.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact LAYOUT manquant ou sans URI."
+            )
+        layout_path = Path(layout_art.uri)
+        try:
+            layout = CanonicalLayout.model_validate_json(layout_path.read_bytes())
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : LAYOUT illisible ({layout_path.name!r}) : {exc}"
+            ) from exc
+        payload = write_alto(layout_to_alto(layout))
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else layout_path.parent
+        )
+        out_path = out_dir / f"{context.document_id.replace('/', '_')}.alto.xml"
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.ALTO_XML: Artifact(
+                    id=f"{context.document_id}:{self.name}:alto_xml",
+                    document_id=context.document_id,
+                    type=ArtifactType.ALTO_XML,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+__all__ = ["AltoAssembler"]

cinoc/adapters/layout/crop.py

@@ -0,0 +1,72 @@
+"""``crop_region`` — découpe l'image d'un bloc pour l'OCR par région (couche 5).
+
+Brique du pipeline **hybride** « segmentation externe → OCR des blocs » : le
+fan-out (couche 4) fournit une **boîte relative** ``(x0, y0, x1, y1) ∈ [0, 1]``
+(la couche 4 a déjà neutralisé les unités, ALTO ``mm10`` vs pixels) ; ici on
+ouvre l'image, on convertit en pixels et on découpe — le crop réel vit en
+couche 5 car il dépend de ``PIL`` (interdit à ``pipeline``).
+
+``Pillow`` est un extra optionnel, importé **paresseusement** : importer ce
+module n'exige pas la lib, seule l'exécution.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.types import RunContext
+
+_RelBox = tuple[float, float, float, float]
+
+
+def crop_region(
+    page_image: Artifact, rel_bbox: _RelBox, region_id: str, context: RunContext
+) -> Artifact:
+    """Découpe ``rel_bbox`` (relatif) de l'image page → artefact ``IMAGE`` du bloc."""
+    if page_image.uri is None:
+        raise AdapterStepError("crop_region : image page sans URI.")
+    if context.workspace_uri is None:
+        raise AdapterStepError("crop_region : workspace requis pour écrire le crop.")
+    try:
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "crop_region : Pillow non installé (pip install 'cinoc[tesseract]')."
+        ) from exc
+    try:
+        with Image.open(page_image.uri) as image:
+            width, height = image.size
+            box = (
+                max(0, min(width, round(rel_bbox[0] * width))),
+                max(0, min(height, round(rel_bbox[1] * height))),
+                max(0, min(width, round(rel_bbox[2] * width))),
+                max(0, min(height, round(rel_bbox[3] * height))),
+            )
+            if box[2] <= box[0] or box[3] <= box[1]:
+                raise AdapterStepError(
+                    f"crop_region : boîte vide pour la région {region_id!r}."
+                )
+            crop = image.crop(box)
+            stem = quote(region_id, safe="")
+            out_path = Path(context.workspace_uri) / (
+                f"{quote(context.document_id, safe='')}.{stem}.crop.png"
+            )
+            crop.save(out_path)
+    except OSError as exc:
+        raise AdapterStepError(
+            f"crop_region : image illisible ({page_image.uri!r}) : {exc}"
+        ) from exc
+    return Artifact(
+        id=f"{context.document_id}:crop:{region_id}",
+        document_id=context.document_id,
+        type=ArtifactType.IMAGE,
+        uri=str(out_path),
+        content_hash=compute_content_hash(out_path.read_bytes()),
+        region_id=region_id,
+    )
+
+
+__all__ = ["crop_region"]

cinoc/adapters/layout/pp_doclayout.py

@@ -0,0 +1,147 @@
+"""``PPDocLayoutSegmenter`` — segmenteur de mise en page réel (PP-DocLayout).
+
+Détecte les **régions** d'une page (titre, paragraphe, figure, tableau…) et émet
+un ``LAYOUT`` (``CanonicalLayout`` à régions **sans lignes** — la reconnaissance
+les remplit ensuite, cf. fan-out couche 4). Implémente le ``Module`` Protocol
+**directement**, comme les autres adapters.
+
+Module **maison du socle** (≠ plugin tiers découvert) : enregistré par
+``register_default_modules`` → disponible **même en mode public** sur le Space
+(contrairement aux plugins via entry-points, fail-closed). Son SDK (PaddleX,
+Apache-2.0) est un **extra optionnel** (``cinoc[segment]``), importé
+**paresseusement** : importer ce module n'exige ni la lib ni les poids — seule
+l'exécution les requiert.
+
+Le détecteur est **injectable** (``detector=``) : la conversion détections →
+``CanonicalLayout`` se teste sans SDK ni poids (CI), le vrai modèle reste un test
+``live``/``slow`` opt-in. Déterminisme (§12) : à modèle + poids + params figés et
+seuil de score fixe, la sortie est stable ; l'ordre de lecture est **trié**
+(haut→bas puis gauche→droite), indépendant de l'ordre de détection.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.layout._base import (
+    DetectedRegion,
+    DetectorFn,
+    LayoutDetection,
+    layout_step_output,
+    to_canonical_layout,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MIN_SCORE = 0.5
+
+
+#: Modèle PP-DocLayout par défaut. La variante **légère** ``PP-DocLayout-S``
+#: (poids ~10× plus petits) est bakable dans l'image Space pour **tester
+#: l'option** sans peser sur le free-tier ; ``-L`` reste le défaut qualité.
+#: Surchargé par ``CINOC_PPDOCLAYOUT_MODEL`` (lu par le builder) ou ``model=``.
+_DEFAULT_MODEL = "PP-DocLayout-L"
+
+
+def _detect_with_paddle(  # pragma: no cover -- SDK + poids requis (test 'live')
+    image_path: str, model: str = _DEFAULT_MODEL
+) -> LayoutDetection:
+    """Détecte la mise en page via **PaddleX PP-DocLayout**. Isolé → mockable.
+
+    SDK absent → ``AdapterStepError`` explicite (l'extra ``[segment]`` manque) ;
+    le module reste listable, il ne plante pas à l'import. Le corps qui exécute le
+    modèle n'est exercé que par un test ``live`` (SDK + poids installés). ``model``
+    choisit la variante (``-L`` qualité / ``-S`` légère)."""
+    try:
+        from paddlex import create_model  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "pp_doclayout : PaddleX non installé "
+            "(pip install 'cinoc[segment]' + poids PP-DocLayout)."
+        ) from exc
+    results = list(create_model(model).predict(image_path, batch_size=1))
+    if not results:
+        return LayoutDetection(page_width=0, page_height=0, regions=())
+    boxes = results[0].get("boxes", [])
+    regions = tuple(
+        DetectedRegion(
+            label=str(box.get("label", "")),
+            x=int(box["coordinate"][0]),
+            y=int(box["coordinate"][1]),
+            width=int(box["coordinate"][2]) - int(box["coordinate"][0]),
+            height=int(box["coordinate"][3]) - int(box["coordinate"][1]),
+            score=float(box.get("score", 0.0)),
+        )
+        for box in boxes
+    )
+    shape = results[0].get("input_img_shape") or (0, 0)
+    return LayoutDetection(
+        page_width=int(shape[1]), page_height=int(shape[0]), regions=regions
+    )
+
+
+class PPDocLayoutSegmenter:
+    """Segmenteur PP-DocLayout : ``IMAGE → LAYOUT`` (régions sans lignes)."""
+
+    def __init__(
+        self,
+        *,
+        model: str = _DEFAULT_MODEL,
+        min_score: float = _DEFAULT_MIN_SCORE,
+        detector: DetectorFn | None = None,
+    ) -> None:
+        if not 0.0 <= min_score <= 1.0:
+            raise AdapterStepError(
+                f"PPDocLayoutSegmenter : min_score ∈ [0, 1], reçu {min_score}."
+            )
+        self._model = model
+        self._min_score = min_score
+        self._detector = detector
+
+    @property
+    def name(self) -> str:
+        return "pp_doclayout"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def _detect(self, image_path: str) -> LayoutDetection:
+        if self._detector is not None:
+            return self._detector(image_path)
+        return _detect_with_paddle(image_path, self._model)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(
+                f"{self.name} : workspace requis (RunContext.workspace_uri)."
+            )
+        layout = to_canonical_layout(
+            self._detect(image.uri), min_score=self._min_score
+        )
+        return layout_step_output(layout, context, self.name)
+
+
+__all__ = ["PPDocLayoutSegmenter"]

cinoc/adapters/layout/precomputed.py

@@ -0,0 +1,178 @@
+"""Socle ``precomputed`` de la tranche segmentation (couche 5, 0 dép, 0 réseau).
+
+Deux briques, **même ``Module`` Protocol** que les autres adapters, qui font
+tourner le squelette segmentation **sans segmenteur ni OCR réels** :
+
+- ``PrecomputedLayoutSource`` : ``IMAGE → LAYOUT`` — rejoue une mise en page
+  pré-calculée (régions seules) depuis ``<stem>.layout.json``.
+- ``PrecomputedRegionRecognizer`` : ``IMAGE → RAW_TEXT`` — rejoue le texte d'**une
+  région** (clé = ``Artifact.region_id`` de l'IMAGE d'entrée) depuis
+  ``<stem>.<label>.regions.json`` (``{region_id: texte}``). Appelé **une fois par
+  région** par le fan-out (couche 4) ; aucun découpage d'image réel (la donnée
+  est figée).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _require_image(inputs: dict[ArtifactType, Artifact], who: str) -> Path:
+    image = inputs.get(ArtifactType.IMAGE)
+    if image is None or image.uri is None:
+        raise AdapterStepError(f"{who} : artefact IMAGE manquant ou sans URI.")
+    return Path(image.uri)
+
+
+class PrecomputedLayoutSource:
+    """Rejoue une mise en page pré-calculée (``<stem>.layout.json``)."""
+
+    @property
+    def name(self) -> str:
+        return "precomputed_layout"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image_path = _require_image(inputs, self.name)
+        layout_path = image_path.parent / f"{image_path.stem}.layout.json"
+        if not layout_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : mise en page pré-calculée introuvable — "
+                f"{layout_path.name!r} attendu près de {image_path.name!r}."
+            )
+        data = layout_path.read_bytes()
+        try:
+            CanonicalLayout.model_validate_json(data)
+        except ValueError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {layout_path.name!r} n'est pas un "
+                f"CanonicalLayout valide : {exc}"
+            ) from exc
+        return StepOutput(
+            artifacts={
+                ArtifactType.LAYOUT: Artifact(
+                    id=f"{context.document_id}:{self.name}:layout",
+                    document_id=context.document_id,
+                    type=ArtifactType.LAYOUT,
+                    uri=str(layout_path),
+                    content_hash=compute_content_hash(data),
+                )
+            }
+        )
+
+
+class PrecomputedRegionRecognizer:
+    """Rejoue le texte d'une région (``<stem>.<label>.regions.json``)."""
+
+    def __init__(self, *, source_label: str) -> None:
+        if not source_label or not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise AdapterStepError(
+                f"PrecomputedRegionRecognizer : source_label invalide "
+                f"{source_label!r} (alphanumérique + _ - uniquement)."
+            )
+        self._label = source_label
+
+    @property
+    def name(self) -> str:
+        return f"precomputed_region:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs[ArtifactType.IMAGE]
+        if image.region_id is None:
+            raise AdapterStepError(
+                f"{self.name} : IMAGE sans region_id — la reconnaissance par "
+                "région attend une entrée déjà cadrée par le fan-out."
+            )
+        image_path = _require_image(inputs, self.name)
+        regions_path = (
+            image_path.parent / f"{image_path.stem}.{self._label}.regions.json"
+        )
+        if not regions_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : textes par région introuvables — "
+                f"{regions_path.name!r} attendu près de {image_path.name!r}."
+            )
+        try:
+            mapping = json.loads(regions_path.read_bytes())
+        except ValueError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {regions_path.name!r} JSON invalide : {exc}"
+            ) from exc
+        if not isinstance(mapping, dict) or image.region_id not in mapping:
+            raise AdapterStepError(
+                f"{self.name} : région {image.region_id!r} absente de "
+                f"{regions_path.name!r}."
+            )
+        text = str(mapping[image.region_id])
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else image_path.parent
+        )
+        out_path = out_dir / f"{image_path.stem}.{self._label}.{image.region_id}.txt"
+        payload = text.encode("utf-8")
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:{image.region_id}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                    region_id=image.region_id,
+                )
+            }
+        )
+
+
+__all__ = ["PrecomputedLayoutSource", "PrecomputedRegionRecognizer"]

cinoc/adapters/layout/remote.py

@@ -0,0 +1,194 @@
+"""``RemoteSegmenter`` — segmenteur de mise en page **par appel distant**.
+
+Au lieu d'embarquer un modèle lourd (poids dans l'image), ce module **délègue** la
+détection de régions à un modèle hébergé ailleurs : un *Inference Endpoint* HF, un
+Space-modèle, ou tout service exposant l'API **object-detection** de Hugging Face.
+Cinoc **orchestre**, le modèle **tourne à distance** — le Space reste léger (pas de
+poids, pas d'inférence CPU locale).
+
+C'est l'incarnation « distante » du point d'extension unique de Cinoc : il
+implémente le **même ``Module`` Protocol** que ``PPDocLayoutSegmenter`` (et que les
+plugins tiers), donc il apparaît comme **segmenteur sélectionnable** avant un run.
+On change de modèle en changeant l'``endpoint`` — sans rien réinstaller.
+
+Schéma de réponse attendu = sortie **object-detection** HF :
+``[{"label": str, "score": float, "box": {"xmin","ymin","xmax","ymax"}}, …]``.
+
+Le détecteur est **injectable** (``detector=``) : la conversion détections →
+``CanonicalLayout`` se teste sans réseau ; le vrai appel HTTP (``httpx`` + garde
+**anti-SSRF** ``assert_public_url``) n'est exercé qu'en test ``live``. ``httpx`` est
+un extra optionnel (``cinoc[serve]``/``[google]``…), importé paresseusement.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.adapters.corpus._http import SsrfError, assert_public_url
+from cinoc.adapters.layout._base import (
+    DetectedRegion,
+    DetectorFn,
+    LayoutDetection,
+    layout_step_output,
+    to_canonical_layout,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MIN_SCORE = 0.5
+_DEFAULT_TIMEOUT = 60.0
+
+
+def parse_hf_detections(
+    payload: object, *, page_width: int, page_height: int
+) -> LayoutDetection:
+    """Réponse object-detection HF → ``LayoutDetection`` (tolérante aux entrées
+    mal formées : les boîtes invalides sont ignorées, jamais une exception)."""
+    if not isinstance(payload, list):
+        raise AdapterStepError(
+            "remote_segmenter : réponse inattendue (liste de détections attendue)."
+        )
+    regions: list[DetectedRegion] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        box = item.get("box")
+        if not isinstance(box, dict):
+            continue
+        try:
+            x0, y0 = int(box["xmin"]), int(box["ymin"])
+            x1, y1 = int(box["xmax"]), int(box["ymax"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        regions.append(
+            DetectedRegion(
+                label=str(item.get("label", "")),
+                x=x0,
+                y=y0,
+                width=max(0, x1 - x0),
+                height=max(0, y1 - y0),
+                score=float(item.get("score", 0.0)),
+            )
+        )
+    return LayoutDetection(
+        page_width=page_width, page_height=page_height, regions=tuple(regions)
+    )
+
+
+def _image_dims(image_path: str) -> tuple[int, int]:
+    """Dimensions ``(largeur, hauteur)`` de l'image ; ``(0, 0)`` si indisponible
+    (Pillow absent / illisible) — la conversion gère les dimensions nulles."""
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError:
+        return (0, 0)
+    try:
+        with Image.open(image_path) as opened:
+            return (int(opened.width), int(opened.height))
+    except (UnidentifiedImageError, OSError):
+        return (0, 0)
+
+
+class RemoteSegmenter:
+    """Segmenteur ``IMAGE → LAYOUT`` délégué à un endpoint object-detection."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        token: str | None = None,
+        min_score: float = _DEFAULT_MIN_SCORE,
+        timeout: float = _DEFAULT_TIMEOUT,
+        detector: DetectorFn | None = None,
+    ) -> None:
+        if not endpoint:
+            raise AdapterStepError("remote_segmenter : 'endpoint' requis.")
+        if not 0.0 <= min_score <= 1.0:
+            raise AdapterStepError(
+                f"remote_segmenter : min_score ∈ [0, 1], reçu {min_score}."
+            )
+        self._endpoint = endpoint
+        self._token = token
+        self._min_score = min_score
+        self._timeout = timeout
+        self._detector = detector
+
+    @property
+    def name(self) -> str:
+        return "remote_segmenter"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def _detect(self, image_path: str) -> LayoutDetection:
+        if self._detector is not None:
+            return self._detector(image_path)
+        return self._remote_detect(image_path)
+
+    def _remote_detect(  # pragma: no cover -- réseau réel (test 'live')
+        self, image_path: str
+    ) -> LayoutDetection:
+        try:
+            assert_public_url(self._endpoint)
+        except SsrfError as exc:
+            raise AdapterStepError(
+                f"remote_segmenter : endpoint refusé (anti-SSRF) : {exc}"
+            ) from exc
+        try:
+            import httpx
+        except ImportError as exc:
+            raise AdapterStepError(
+                "remote_segmenter : httpx absent (extra réseau requis)."
+            ) from exc
+        headers = {"Content-Type": "application/octet-stream"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        try:
+            with httpx.Client(timeout=self._timeout) as client:
+                response = client.post(
+                    self._endpoint,
+                    content=Path(image_path).read_bytes(),
+                    headers=headers,
+                )
+                response.raise_for_status()
+                payload = response.json()
+        except httpx.HTTPError as exc:
+            raise AdapterStepError(
+                f"remote_segmenter : appel à l'endpoint échoué : {exc}"
+            ) from exc
+        width, height = _image_dims(image_path)
+        return parse_hf_detections(payload, page_width=width, page_height=height)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        layout = to_canonical_layout(
+            self._detect(image.uri), min_score=self._min_score
+        )
+        return layout_step_output(layout, context, self.name)
+
+
+__all__ = ["RemoteSegmenter", "parse_hf_detections"]

cinoc/adapters/layout/to_text.py

@@ -0,0 +1,106 @@
+"""``LayoutToTextExtractor`` — ``LAYOUT rempli → RAW_TEXT`` (couche 5).
+
+Quatrième étage **optionnel** d'un pipeline hybride : une fois les régions
+reconnues (fan-out → ``CanonicalLayout`` rempli), on aplatit le texte dans
+**l'ordre de lecture** pour le rendre **scorable** comme n'importe quelle sortie
+``RAW_TEXT`` (CER/WER à la page). C'est ce qui permet à un run « segmenteur →
+reconnaissance par bloc » d'être un **concurrent du Banc d'essai** comparé à un
+OCR à plat, et plus seulement un ALTO produit dans son coin.
+
+Déterministe : ordre = ``reading_order`` de la page (repli sur l'ordre déclaré),
+lignes d'une région jointes par ``\\n``, régions par ``\\n``, pages par ``\\n``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout, LayoutPage
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _page_text(page: LayoutPage) -> str:
+    """Texte d'une page, régions dans l'ordre de lecture (repli ordre déclaré)."""
+    by_id = {region.id: region for region in page.regions}
+    ordered = [by_id[rid] for rid in page.reading_order if rid in by_id]
+    seen = {region.id for region in ordered}
+    ordered.extend(region for region in page.regions if region.id not in seen)
+    blocks: list[str] = []
+    for region in ordered:
+        lines = "\n".join(line.text for line in region.lines if line.text)
+        if lines:
+            blocks.append(lines)
+    return "\n".join(blocks)
+
+
+class LayoutToTextExtractor:
+    """Aplatit un ``LAYOUT`` rempli en ``RAW_TEXT`` (ordre de lecture, déterministe)."""
+
+    def __init__(self, label: str) -> None:
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"layout_to_text:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        layout_art = inputs.get(ArtifactType.LAYOUT)
+        if layout_art is None or layout_art.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact LAYOUT manquant ou sans URI."
+            )
+        layout_path = Path(layout_art.uri)
+        try:
+            layout = CanonicalLayout.model_validate_json(layout_path.read_bytes())
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : LAYOUT illisible ({layout_path.name!r}) : {exc}"
+            ) from exc
+        text = "\n".join(_page_text(page) for page in layout.pages)
+        payload = text.encode("utf-8")
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else layout_path.parent
+        )
+        out_path = out_dir / f"{context.document_id.replace('/', '_')}.layout.txt"
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+__all__ = ["LayoutToTextExtractor"]

cinoc/adapters/llm/__init__.py

@@ -0,0 +1,15 @@
+"""Adapters LLM/VLM (couche 5) — post-correction texte/image + transcription VLM.
+
+Modes par adapter (``PipelineMode``) : ``text_only`` (tous), ``text_and_image``
+et ``zero_shot`` (openai, mistral, anthropic — vision). ``ollama`` reste
+``text_only`` (socle local minimal).
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.llm.anthropic import AnthropicAdapter
+from cinoc.adapters.llm.mistral import MistralAdapter
+from cinoc.adapters.llm.ollama import OllamaAdapter
+from cinoc.adapters.llm.openai import OpenAIAdapter
+
+__all__ = ["AnthropicAdapter", "MistralAdapter", "OllamaAdapter", "OpenAIAdapter"]

cinoc/adapters/llm/_base.py

@@ -0,0 +1,285 @@
+"""Helpers partagés des adapters LLM/VLM (post-correction + transcription).
+
+Les adapters concrets (openai, anthropic, mistral, ollama) implémentent le
+``Module`` Protocol et ne fournissent que leurs **appels réseau** (isolés,
+mockables). Toute la logique commune — choix des entrées/sorties selon le
+**mode**, chargement du texte OCR et/ou de l'image, écriture de l'artefact —
+vit **ici**, dans ``run_llm_step`` : un seul endroit, aucun mode dupliqué par
+fournisseur (anti « 8+8+8 », cf. CLAUDE.md §8.8).
+
+Modes (``PipelineMode``, source de vérité unique en ``domain``) :
+
+- ``text_only``      — ``RAW_TEXT`` → ``CORRECTED_TEXT`` (le LLM ne voit pas l'image).
+- ``text_and_image`` — ``{RAW_TEXT, IMAGE}`` → ``CORRECTED_TEXT`` (le VLM voit l'image).
+- ``zero_shot``      — ``IMAGE`` → ``RAW_TEXT`` (transcription directe, sans OCR amont).
+"""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, NamedTuple, cast
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.domain.usage import ResourceUsage
+from cinoc.formats.text import read_plaintext
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+#: Prompt de post-correction (modes ``text_only`` / ``text_and_image``) ;
+#: ``{ocr_text}`` est substitué par le texte OCR amont.
+DEFAULT_CORRECTION_PROMPT = (
+    "Tu es un correcteur de transcriptions OCR de documents patrimoniaux. "
+    "Corrige uniquement les erreurs manifestes de reconnaissance, sans "
+    "reformuler ni moderniser l'orthographe historique. Réponds par le seul "
+    "texte corrigé.\n\n{ocr_text}"
+)
+
+#: Prompt de transcription directe (mode ``zero_shot`` : le VLM lit l'image).
+DEFAULT_TRANSCRIPTION_PROMPT = (
+    "Transcris fidèlement le texte de cette image de document patrimonial. "
+    "Conserve l'orthographe historique et la ponctuation d'origine. N'ajoute "
+    "aucun commentaire : réponds par le seul texte transcrit."
+)
+
+#: Extension de fichier → media type (sous-ensemble image courant).
+_MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+}
+
+class LLMCompletion(NamedTuple):
+    """Réponse d'un fournisseur : texte + jetons consommés (si exposés)."""
+
+    text: str
+    tokens_in: int | None = None
+    tokens_out: int | None = None
+
+
+#: Appel d'un LLM texte : ``prompt → réponse`` (fournisseur + modèle capturés).
+TextInvoke = Callable[[str], LLMCompletion]
+#: Appel d'un VLM : ``prompt, media_type, image_b64 → réponse``.
+VisionInvoke = Callable[[str, str, str], LLMCompletion]
+
+
+def usage_tokens(value: Any) -> int | None:
+    """Coercition prudente d'un compteur de jetons SDK (``None`` si absent)."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        return None
+    return value
+
+
+def normalize_llm_content(raw: Any) -> str:
+    """Aplati une réponse LLM (``str`` ou liste de blocs) en chaîne."""
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts: list[str] = []
+        for chunk in raw:
+            if isinstance(chunk, str):
+                parts.append(chunk)
+            elif isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
+                parts.append(chunk["text"])
+            else:
+                text = getattr(chunk, "text", None)
+                if isinstance(text, str):
+                    parts.append(text)
+        return "".join(parts)
+    return str(raw)
+
+
+def validate_llm_label(label: str, adapter: str) -> str:
+    """Valide un label d'adapter LLM (alphanum + ``_ -``) et le renvoie.
+
+    Le label compose le ``name`` du module (``<kind>:<label>``) ; le restreindre
+    garde les noms de modules sûrs et stables (provenance ``RunManifest``).
+    """
+    if not label or not all(c.isalnum() or c in "_-" for c in label):
+        raise AdapterStepError(
+            f"{adapter} : label invalide {label!r} (alphanum + _ -)."
+        )
+    return label
+
+
+def validate_role(role: str, adapter: str, supported: frozenset[str]) -> PipelineMode:
+    """Valide un mode d'adapter contre ceux que le fournisseur supporte."""
+    if role not in supported:
+        raise AdapterStepError(
+            f"{adapter} : mode {role!r} non supporté "
+            f"(modes : {', '.join(sorted(supported))})."
+        )
+    return cast(PipelineMode, role)
+
+
+def llm_input_types(role: PipelineMode) -> frozenset[ArtifactType]:
+    """Types d'entrée requis par le ``role`` (mode du pipeline)."""
+    if role == "text_only":
+        return frozenset({ArtifactType.RAW_TEXT})
+    if role == "text_and_image":
+        return frozenset({ArtifactType.RAW_TEXT, ArtifactType.IMAGE})
+    return frozenset({ArtifactType.IMAGE})  # zero_shot
+
+
+def llm_output_type(role: PipelineMode) -> ArtifactType:
+    """Type produit : ``RAW_TEXT`` en transcription, sinon ``CORRECTED_TEXT``."""
+    return (
+        ArtifactType.RAW_TEXT
+        if role == "zero_shot"
+        else ArtifactType.CORRECTED_TEXT
+    )
+
+
+def default_prompt_for_role(role: PipelineMode) -> str:
+    """Prompt par défaut adapté au mode (transcription vs correction)."""
+    return (
+        DEFAULT_TRANSCRIPTION_PROMPT
+        if role == "zero_shot"
+        else DEFAULT_CORRECTION_PROMPT
+    )
+
+
+def build_prompt(template: str, ocr_text: str) -> str:
+    return template.replace("{ocr_text}", ocr_text)
+
+
+def load_ocr_text(inputs: dict[ArtifactType, Artifact], adapter_name: str) -> str:
+    artifact = inputs.get(ArtifactType.RAW_TEXT)
+    if artifact is None or artifact.uri is None:
+        raise AdapterStepError(
+            f"{adapter_name} : input RAW_TEXT manquant ou sans URI."
+        )
+    return read_plaintext(Path(artifact.uri).read_bytes())
+
+
+def load_image_b64(
+    inputs: dict[ArtifactType, Artifact], adapter_name: str
+) -> tuple[str, str]:
+    """Charge l'``IMAGE`` d'entrée → ``(media_type, base64)`` pour un VLM."""
+    artifact = inputs.get(ArtifactType.IMAGE)
+    if artifact is None or artifact.uri is None:
+        raise AdapterStepError(
+            f"{adapter_name} : input IMAGE manquant ou sans URI."
+        )
+    path = Path(artifact.uri)
+    media_type = _MEDIA_TYPES.get(path.suffix.lower(), "image/png")
+    return media_type, b64encode(path.read_bytes()).decode("ascii")
+
+
+def write_text_artifact(
+    workspace_uri: str,
+    document_id: str,
+    label: str,
+    adapter_name: str,
+    text: str,
+    *,
+    output_type: ArtifactType,
+) -> dict[ArtifactType, Artifact]:
+    """Écrit ``text`` dans le workspace → artefact du type produit par le mode."""
+    is_corrected = output_type == ArtifactType.CORRECTED_TEXT
+    suffix = "corrected.txt" if is_corrected else "raw.txt"
+    output_path = workspace_artifact_path(
+        workspace_uri, document_id, label, suffix
+    )
+    output_path.write_text(text, encoding="utf-8")
+    return {
+        output_type: Artifact(
+            id=f"{document_id}:{adapter_name}:{output_type.value}",
+            document_id=document_id,
+            type=output_type,
+            uri=str(output_path),
+            content_hash=compute_content_hash(text.encode("utf-8")),
+        )
+    }
+
+
+def run_llm_step(
+    *,
+    role: PipelineMode,
+    label: str,
+    name: str,
+    prompt: str,
+    inputs: dict[ArtifactType, Artifact],
+    context: RunContext,
+    control: RunControl,
+    text_invoke: TextInvoke,
+    vision_invoke: VisionInvoke | None,
+) -> StepOutput:
+    """Exécute une étape LLM/VLM selon le ``role`` — logique de mode unique.
+
+    Aiguille sur le mode : charge les bonnes entrées (texte et/ou image), appelle
+    l'invocation fournisseur idoine, écrit l'artefact du bon type. ``zero_shot``
+    et ``text_and_image`` exigent ``vision_invoke`` (un fournisseur texte-seul,
+    ex. ollama, passe ``None`` → ces modes sont refusés proprement). Les jetons
+    exposés par le fournisseur remontent dans ``StepOutput.usage``.
+    """
+    control.raise_if_cancelled()
+    if context.workspace_uri is None:
+        raise AdapterStepError(
+            f"{name} : workspace requis (RunContext.workspace_uri)."
+        )
+    if role == "zero_shot":
+        if vision_invoke is None:
+            raise AdapterStepError(f"{name} : mode zero_shot requiert un VLM (vision).")
+        media_type, image_b64 = load_image_b64(inputs, name)
+        completion = vision_invoke(prompt, media_type, image_b64)
+    elif role == "text_and_image":
+        if vision_invoke is None:
+            raise AdapterStepError(
+                f"{name} : mode text_and_image requiert un VLM (vision)."
+            )
+        ocr_text = load_ocr_text(inputs, name)
+        media_type, image_b64 = load_image_b64(inputs, name)
+        completion = vision_invoke(
+            build_prompt(prompt, ocr_text), media_type, image_b64
+        )
+    else:  # text_only
+        ocr_text = load_ocr_text(inputs, name)
+        completion = text_invoke(build_prompt(prompt, ocr_text))
+    artifacts = write_text_artifact(
+        context.workspace_uri,
+        context.document_id,
+        label,
+        name,
+        completion.text,
+        output_type=llm_output_type(role),
+    )
+    usage = (
+        ResourceUsage(
+            tokens_in=completion.tokens_in, tokens_out=completion.tokens_out
+        )
+        if completion.tokens_in is not None or completion.tokens_out is not None
+        else None
+    )
+    return StepOutput(artifacts=artifacts, usage=usage)
+
+
+__all__ = [
+    "DEFAULT_CORRECTION_PROMPT",
+    "DEFAULT_TRANSCRIPTION_PROMPT",
+    "LLMCompletion",
+    "TextInvoke",
+    "VisionInvoke",
+    "build_prompt",
+    "default_prompt_for_role",
+    "llm_input_types",
+    "llm_output_type",
+    "load_image_b64",
+    "load_ocr_text",
+    "normalize_llm_content",
+    "run_llm_step",
+    "usage_tokens",
+    "validate_llm_label",
+    "validate_role",
+    "write_text_artifact",
+]

cinoc/adapters/llm/anthropic.py

@@ -0,0 +1,193 @@
+"""``AnthropicAdapter`` — post-correction LLM **et** transcription VLM (Claude).
+
+Implémente le ``Module`` Protocol, trois modes (``PipelineMode``) selon le rôle :
+``text_only`` (texte → corrigé), ``text_and_image`` (Claude vision : image +
+texte → corrigé), ``zero_shot`` (Claude vision : image → texte). Clé
+``ANTHROPIC_API_KEY`` ; SDK ``anthropic`` = **extra** importé paresseusement dans
+``_invoke_anthropic`` / ``_invoke_anthropic_vision`` (isolés → **mockables**, CI
+sans clé ni réseau). La ``Deadline`` borne l'appel.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+_MAX_TOKENS = 4096
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_message(response: Any) -> LLMCompletion:
+    """Réponse SDK ``messages.create`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun SDK) → la cartographie usage→jetons
+    (``input_tokens``/``output_tokens``, **noms propres à Claude**) est **testable
+    sur cassette** (étape 2d) ; le client live (``# pragma: no cover``) ne le
+    permettrait pas. Jetons → économie (coût cloud réel).
+    """
+    usage = getattr(response, "usage", None)
+    return LLMCompletion(
+        normalize_llm_content(getattr(response, "content", None)),
+        usage_tokens(getattr(usage, "input_tokens", None)),
+        usage_tokens(getattr(usage, "output_tokens", None)),
+    )
+
+
+def _anthropic_client(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    model: str, content: object, deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``messages.create`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise AdapterStepError("anthropic : ANTHROPIC_API_KEY manquante.")
+    try:
+        from anthropic import (  # type: ignore[import-not-found]
+            Anthropic,
+            AnthropicError,
+        )
+    except ImportError as exc:
+        raise AdapterStepError(
+            "anthropic : SDK non installé (pip install 'cinoc[anthropic]')."
+        ) from exc
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout"] = timeout
+    try:
+        # SDK anthropic typé strictement ; dicts valides à l'exécution (tests live).
+        client = Anthropic(**client_kwargs)  # type: ignore[arg-type]
+
+        def _create() -> Any:
+            return client.messages.create(
+                model=model,
+                max_tokens=_MAX_TOKENS,
+                messages=[{"role": "user", "content": content}],  # type: ignore[typeddict-item]
+            )
+
+        # Cap de concurrence (≤ N appels Anthropic simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("anthropic", _create)
+    except AnthropicError as exc:
+        raise AdapterStepError(
+            f"anthropic a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_message(response)
+
+
+def _invoke_anthropic(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _anthropic_client(model, prompt, deadline)
+
+
+def _invoke_anthropic_vision(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": media_type,
+                "data": image_b64,
+            },
+        },
+    ]
+    return _anthropic_client(model, content, deadline)
+
+
+class AnthropicAdapter:
+    """Adapter Anthropic multi-mode (post-correction texte/image, transcription)."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "AnthropicAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "AnthropicAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"anthropic:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_anthropic(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_anthropic_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+__all__ = ["AnthropicAdapter"]

cinoc/adapters/llm/mistral.py

@@ -0,0 +1,221 @@
+"""``MistralAdapter`` — post-correction LLM **et** transcription VLM (API Mistral).
+
+Implémente le ``Module`` Protocol, trois modes (``PipelineMode``) selon le rôle :
+``text_only`` (texte → corrigé), ``text_and_image`` (Pixtral : image + texte →
+corrigé), ``zero_shot`` (Pixtral : image → texte). Clé ``MISTRAL_API_KEY`` ; SDK
+``mistralai`` = **extra** importé paresseusement dans ``_invoke_mistral`` /
+``_invoke_mistral_vision`` (isolés → **mockables**, CI sans clé ni réseau).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "mistral-small-latest"
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_chat(response: Any) -> LLMCompletion:
+    """Réponse SDK ``chat.complete`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun SDK) → la cartographie usage→jetons
+    (``prompt_tokens``/``completion_tokens``) est **testable sur cassette** (étape
+    2d) ; le client live (``# pragma: no cover``) ne le permettrait pas. Jetons →
+    économie (coût cloud réel).
+    """
+    usage = getattr(response, "usage", None)
+    tokens_in = usage_tokens(getattr(usage, "prompt_tokens", None))
+    tokens_out = usage_tokens(getattr(usage, "completion_tokens", None))
+    choices = getattr(response, "choices", None)
+    if not choices:
+        return LLMCompletion("", tokens_in, tokens_out)
+    return LLMCompletion(
+        normalize_llm_content(choices[0].message.content), tokens_in, tokens_out
+    )
+
+
+def _mistral_client(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    model: str, content: object, deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``chat.complete`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        raise AdapterStepError("mistral : MISTRAL_API_KEY manquante.")
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "mistral : SDK non installé (pip install 'cinoc[mistral]')."
+        ) from exc
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout_ms"] = int(timeout * 1000)
+    try:
+        # Le SDK mistralai 1.x type strictement ses kwargs/messages ; on lui
+        # passe des dicts valides à l'exécution (cf. tests live). ``ignore`` ciblé.
+        client = Mistral(**client_kwargs)  # type: ignore[arg-type]
+
+        def _complete() -> Any:
+            return client.chat.complete(
+                model=model,
+                messages=[{"role": "user", "content": content}],  # type: ignore[arg-type]
+                temperature=0.0,
+            )
+
+        # Cap de concurrence (≤ N appels Mistral simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("mistral", _complete)
+    except Exception as exc:  # le SDK lève des erreurs HTTP/SDK variées
+        raise AdapterStepError(
+            f"mistral a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_chat(response)
+
+
+def _invoke_mistral(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _mistral_client(model, prompt, deadline)
+
+
+def _invoke_mistral_vision(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {"type": "image_url", "image_url": f"data:{media_type};base64,{image_b64}"},
+    ]
+    return _mistral_client(model, content, deadline)
+
+
+class MistralAdapter:
+    """Adapter Mistral multi-mode (post-correction texte/image, transcription VLM)."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "MistralAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "MistralAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"mistral:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_mistral(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_mistral_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+def list_mistral_models(*, timeout: float = 5.0) -> tuple[str, ...]:
+    """IDs des modèles disponibles pour la clé Mistral courante (``models.list``).
+
+    **Best-effort, commodité d'UI** : ``MISTRAL_API_KEY`` absente, SDK absent ou
+    erreur réseau → ``()`` (l'interface retombe sur la saisie libre). Rien de
+    hardcodé : la liste vient **directement de l'API Mistral**.
+    """
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        return ()
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError:
+        return ()
+    try:
+        client = Mistral(api_key=api_key, timeout_ms=int(timeout * 1000))
+        response = client.models.list()
+    except Exception as exc:  # noqa: BLE001 — voir rationale ci-dessous
+        # Catch-all **assumé** : commodité d'UI qui ne doit jamais casser la
+        # page du composeur. Le SDK mistralai **enveloppe** ses erreurs HTTP
+        # (auth/429/5xx) dans ses propres types + propage des erreurs httpx pour
+        # le transport ; narrower au seul ``httpx.HTTPError`` (comme ollama, qui
+        # appelle httpx en direct) laisserait fuir une erreur SDK et casserait la
+        # page. On trace (§7) et on retombe sur la saisie libre.
+        logger.warning("[mistral] liste des modèles indisponible : %s", exc)
+        return ()
+    data = getattr(response, "data", None) or ()
+    ids = [m.id for m in data if isinstance(getattr(m, "id", None), str)]
+    return tuple(sorted(set(ids)))
+
+
+__all__ = ["MistralAdapter", "list_mistral_models"]

cinoc/adapters/llm/ollama.py

@@ -0,0 +1,195 @@
+"""``OllamaAdapter`` — post-correction LLM via un serveur ollama local.
+
+Deuxième famille LLM : prouve que le ``Module`` Protocol **généralise au-delà
+d'openai** — même contrat ``RAW_TEXT`` → ``CORRECTED_TEXT``, sortie identique,
+aucun cas particulier. Transport ``httpx`` (extra), importé paresseusement et
+**isolé** dans ``_invoke_ollama`` (→ mockable, CI sans serveur).
+
+C'est l'**implémentation de référence de l'annulation câblée** : ``_invoke_ollama``
+enregistre ``client.close`` via ``RunControl.register_cancel_handle`` ; un
+``trigger_cancel`` ferme la connexion et **interrompt la requête en vol**. La
+distinction « annulation vs vraie panne réseau » se fait en sondant
+``is_cancelled`` (``_fail_or_cancel``) — pas par une heuristique de message
+fragile (dette de l'implémentation source, corrigée au portage).
+"""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+from cinoc.adapters.llm._base import (
+    DEFAULT_CORRECTION_PROMPT,
+    LLMCompletion,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "llama3"
+_DEFAULT_HOST = "http://localhost:11434"
+
+
+def _fail_or_cancel(control: RunControl, model: str, exc: Exception) -> NoReturn:
+    """Traduit un échec d'appel ollama.
+
+    Si l'annulation a été déclenchée, le ``client.close`` enregistré a fait
+    échouer la requête en vol : on lève alors ``RunCancelledError`` (via
+    ``raise_if_cancelled``). Sinon c'est une vraie panne → ``AdapterStepError``.
+    Sonder ``is_cancelled`` est **fiable**, là où l'implémentation source
+    devinait par le message d'exception (heuristique fragile, D-A).
+    """
+    control.raise_if_cancelled()
+    raise AdapterStepError(f"ollama a échoué ({model}) : {exc}") from exc
+
+
+def _invoke_ollama(  # pragma: no cover -- réseau (serveur ollama ; cf. marqueur 'live')
+    *,
+    model: str,
+    prompt: str,
+    host: str,
+    deadline: Deadline,
+    control: RunControl,
+) -> LLMCompletion:
+    try:
+        import httpx  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "ollama : httpx non installé (pip install 'cinoc[ollama]')."
+        ) from exc
+    payload = {
+        "model": model,
+        "messages": [{"role": "user", "content": prompt}],
+        "stream": False,
+    }
+    client = httpx.Client(timeout=deadline.as_sdk_timeout())
+    # Annulation câblée : fermer le client interrompt la requête en vol.
+    control.register_cancel_handle(client.close)
+    try:
+        # **/api/chat** (et non /api/generate) : applique le gabarit de chat du
+        # modèle. Indispensable pour les modèles *instruct* (ex. churro), qui
+        # échouent sur /api/generate (complétion brute). C'est l'endpoint
+        # qu'utilise ``ollama run``.
+        response = client.post(f"{host}/api/chat", json=payload)
+        response.raise_for_status()
+        data = response.json()
+    except httpx.HTTPError as exc:
+        _fail_or_cancel(control, model, exc)
+    finally:
+        client.close()
+    # Ollama peut renvoyer une **erreur en HTTP 200** (modèle introuvable sous ce
+    # nom, mémoire insuffisante…) : ``raise_for_status`` ne la voit pas. On la
+    # remonte explicitement, sinon la « correction » serait un texte vide silencieux.
+    if isinstance(data, dict) and data.get("error"):
+        raise AdapterStepError(f"ollama a échoué ({model}) : {data['error']}")
+    message = data.get("message") if isinstance(data, dict) else None
+    content = message.get("content") if isinstance(message, dict) else None
+    # /api/chat expose la consommation : prompt_eval_count / eval_count.
+    counts = data if isinstance(data, dict) else {}
+    return LLMCompletion(
+        normalize_llm_content(content),
+        usage_tokens(counts.get("prompt_eval_count")),
+        usage_tokens(counts.get("eval_count")),
+    )
+
+
+def list_installed_models(
+    host: str = _DEFAULT_HOST, *, timeout: float = 3.0
+) -> tuple[str, ...]:
+    """Noms des modèles installés sur le serveur ollama (``GET /api/tags``).
+
+    **Best-effort, commodité d'UI** : serveur injoignable, ``httpx`` absent ou
+    réponse inattendue → ``()`` (l'interface retombe alors sur la saisie libre).
+    Aucune exception propagée. Le ``name`` renvoyé est le **tag exact** servable à
+    ``/api/generate`` (ex. ``gemma3:1b`` ou ``hf.co/…/churro-3B-GGUF:Q4_K_M``).
+    """
+    try:
+        import httpx  # type: ignore[import-not-found]
+    except ImportError:
+        return ()
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(f"{host}/api/tags")
+            response.raise_for_status()
+            data = response.json()
+    except (httpx.HTTPError, ValueError):
+        return ()
+    models = data.get("models") if isinstance(data, dict) else None
+    if not isinstance(models, list):
+        return ()
+    return tuple(
+        m["name"]
+        for m in models
+        if isinstance(m, dict) and isinstance(m.get("name"), str)
+    )
+
+
+class OllamaAdapter:
+    """Post-correction LLM, serveur ollama local : ``RAW_TEXT`` → ``CORRECTED_TEXT``."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        host: str = _DEFAULT_HOST,
+        prompt: str = DEFAULT_CORRECTION_PROMPT,
+    ) -> None:
+        self._label = validate_llm_label(label, "OllamaAdapter")
+        self._model = model
+        self._host = host
+        self._prompt = prompt
+
+    @property
+    def name(self) -> str:
+        return f"ollama:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.CORRECTED_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_ollama(
+                model=self._model,
+                prompt=prompt,
+                host=self._host,
+                deadline=context.deadline,
+                control=control,
+            )
+
+        return run_llm_step(
+            role="text_only",
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=None,
+        )
+
+
+__all__ = ["OllamaAdapter"]

cinoc/adapters/llm/openai.py

@@ -0,0 +1,188 @@
+"""``OpenAIAdapter`` — post-correction LLM **et** transcription VLM (API OpenAI).
+
+Implémente le ``Module`` Protocol. Trois modes (``PipelineMode``) selon le rôle
+passé à la construction : ``text_only`` (``RAW_TEXT`` → ``CORRECTED_TEXT``),
+``text_and_image`` (image + texte → corrigé), ``zero_shot`` (image → texte). La
+clé vient de ``OPENAI_API_KEY`` ; le SDK ``openai`` est un **extra** importé
+paresseusement dans ``_invoke_openai`` / ``_invoke_openai_vision`` (isolés →
+**mockables**, CI sans clé ni réseau). La ``Deadline`` borne l'appel.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "gpt-4o-mini"
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_chat(response: Any) -> LLMCompletion:
+    """Réponse SDK ``chat.completions`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun import SDK) → la cartographie usage→jetons
+    (``prompt_tokens``/``completion_tokens``) est **testable sur une réponse de
+    cassette**, ce que le client live (``# pragma: no cover``) ne permet pas. Les
+    jetons alimentent l'économie (coût réel par modèle).
+    """
+    usage = getattr(response, "usage", None)
+    tokens_in = usage_tokens(getattr(usage, "prompt_tokens", None))
+    tokens_out = usage_tokens(getattr(usage, "completion_tokens", None))
+    choices = getattr(response, "choices", None)
+    if not choices:
+        return LLMCompletion("", tokens_in, tokens_out)
+    return LLMCompletion(
+        normalize_llm_content(choices[0].message.content), tokens_in, tokens_out
+    )
+
+
+def _openai_client(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    model: str, messages: list[dict[str, object]], deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``chat.completions`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise AdapterStepError("openai : OPENAI_API_KEY manquante.")
+    try:
+        from openai import OpenAI, OpenAIError  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "openai : SDK non installé (pip install 'cinoc[openai]')."
+        ) from exc
+    kwargs: dict[str, object] = {
+        "model": model,
+        "messages": messages,
+        "temperature": 0.0,
+    }
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+    try:
+        # SDK openai typé strictement ; kwargs valides à l'exécution (tests live).
+        client = OpenAI(api_key=api_key)
+
+        def _create() -> Any:
+            return client.chat.completions.create(**kwargs)  # type: ignore[call-overload]
+
+        # Cap de concurrence (≤ N appels OpenAI simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("openai", _create)
+    except OpenAIError as exc:
+        raise AdapterStepError(
+            f"openai a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_chat(response)
+
+
+def _invoke_openai(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _openai_client(model, [{"role": "user", "content": prompt}], deadline)
+
+
+def _invoke_openai_vision(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {
+            "type": "image_url",
+            "image_url": {"url": f"data:{media_type};base64,{image_b64}"},
+        },
+    ]
+    return _openai_client(model, [{"role": "user", "content": content}], deadline)
+
+
+class OpenAIAdapter:
+    """Adapter OpenAI multi-mode (post-correction texte/image, transcription VLM)."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "OpenAIAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "OpenAIAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"openai:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_openai(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_openai_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+__all__ = ["OpenAIAdapter"]

cinoc/adapters/ner/__init__.py

@@ -0,0 +1 @@
+"""Adapters NER : extraction d'entités nommées (couche 5)."""

cinoc/adapters/ner/spacy_extractor.py

@@ -0,0 +1,204 @@
+"""``SpacyNerExtractor`` — extraction d'entités nommées via spaCy (couche 5).
+
+Brique de pipeline ``RAW_TEXT|CORRECTED_TEXT → ENTITIES`` (la NER est une étape
+explicite, CLAUDE.md §3). Implémente le ``Module`` Protocol **directement**. Le
+SDK ``spacy`` + le **modèle** sont un extra optionnel (``cinoc[ner]`` + ``python
+-m spacy download <modèle>``), importés paresseusement.
+
+**Anti-silence (réparation R14 amont, bug du modèle source).** Si spaCy ou le
+modèle manque, l'adapter **lève** ``AdapterStepError`` avec le message
+d'installation — il ne renvoie **jamais** ``[]`` (le défaut de la source : un
+benchmark qui « réussit » avec un rappel 0 sans message). L'orchestrateur isole
+alors ce (concurrent × document) ; le document reste simplement non scoré.
+
+L'artefact ``ENTITIES`` embarque **le texte d'entrée** (``{"text", "entities"}``)
+— c'est lui qui rend la reprojection R14 auto-suffisante côté évaluation.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+
+#: Normalisation des labels spaCy vers les conventions courtes HIPE/CoNLL.
+_DEFAULT_LABEL_MAPPING: dict[str, str] = {
+    "PERSON": "PER",
+    "PER": "PER",
+    "LOC": "LOC",
+    "GPE": "LOC",
+    "ORG": "ORG",
+    "DATE": "DATE",
+    "TIME": "DATE",
+    "MISC": "MISC",
+}
+
+#: Texte d'entrée accepté : sortie OCR brute **ou** corrigée par un LLM.
+_INPUT_TYPES = frozenset({ArtifactType.RAW_TEXT, ArtifactType.CORRECTED_TEXT})
+
+
+class SpacyNerExtractor:
+    """NER spaCy : ``RAW_TEXT|CORRECTED_TEXT`` → ``ENTITIES`` (fail-closed)."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = "fr_core_news_sm",
+        loader: Any | None = None,
+    ) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"ner : label invalide {label!r}.")
+        self._label = label
+        self._model = model
+        #: Injectable en test : ``(model_name) -> nlp`` ; défaut = ``spacy.load``.
+        self._loader = loader
+        self._nlp: Any | None = None
+        self._model_version: str | None = None
+
+    @property
+    def name(self) -> str:
+        return f"ner:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return _INPUT_TYPES
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.ENTITIES})
+
+    def system_binaries(self) -> dict[str, str]:
+        """Versions spaCy + modèle **si déjà chargés** (reproductibilité).
+
+        Best-effort sans effet de bord : ne déclenche aucun chargement — renvoie
+        ``{}`` tant que le modèle n'a pas tourné. Fusionné au ``RunManifest`` par
+        l'orchestrateur (duck-typing, comme le binaire tesseract).
+        """
+        if self._nlp is None:
+            return {}
+        out: dict[str, str] = {}
+        if self._model_version is not None:
+            out[f"spacy_model:{self._model}"] = self._model_version
+        try:
+            import spacy  # type: ignore[import-not-found]
+
+            out["spacy"] = str(spacy.__version__)
+        except ImportError:
+            pass
+        return out
+
+    def _load(self) -> Any:
+        """Charge le modèle (idempotent). Fail-closed : lève si SDK/modèle absent."""
+        if self._nlp is not None:
+            return self._nlp
+        if self._loader is not None:
+            self._nlp = self._loader(self._model)
+            self._model_version = self._probe_model_version(self._nlp)
+            return self._nlp
+        try:
+            import spacy  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise AdapterStepError(
+                "ner : spaCy non installé — `pip install 'cinoc[ner]'`."
+            ) from exc
+        try:
+            self._nlp = spacy.load(self._model)
+        except OSError as exc:
+            raise AdapterStepError(
+                f"ner : modèle spaCy {self._model!r} introuvable — "
+                f"`python -m spacy download {self._model}`."
+            ) from exc
+        self._model_version = self._probe_model_version(self._nlp)
+        return self._nlp
+
+    @staticmethod
+    def _probe_model_version(nlp: Any) -> str | None:
+        meta = getattr(nlp, "meta", None)
+        if isinstance(meta, dict):
+            version = meta.get("version")
+            return str(version) if version is not None else None
+        return None
+
+    def _extract(self, text: str) -> list[dict[str, object]]:
+        nlp = self._load()
+        doc = nlp(text)
+        entities: list[dict[str, object]] = []
+        for ent in doc.ents:
+            label = _DEFAULT_LABEL_MAPPING.get(ent.label_, ent.label_)
+            entities.append(
+                {
+                    "label": label,
+                    "start": int(ent.start_char),
+                    "end": int(ent.end_char),
+                    "text": ent.text,
+                }
+            )
+        return entities
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        source = inputs.get(ArtifactType.CORRECTED_TEXT) or inputs.get(
+            ArtifactType.RAW_TEXT
+        )
+        if source is None or source.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact texte (RAW_TEXT/CORRECTED_TEXT) manquant."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(f"{self.name} : workspace requis.")
+        text = _read_text(source.uri, self.name)
+        entities = self._extract(text)
+        payload = json.dumps(
+            {"text": text, "entities": entities}, ensure_ascii=False
+        ).encode("utf-8")
+        out_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "entities.json"
+        )
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.ENTITIES: Artifact(
+                    id=f"{context.document_id}:{self.name}:entities",
+                    document_id=context.document_id,
+                    type=ArtifactType.ENTITIES,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+def _read_text(uri: str, name: str) -> str:
+    from pathlib import Path
+
+    try:
+        return Path(uri).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise AdapterStepError(
+            f"{name} : texte d'entrée illisible {uri!r} : {exc}"
+        ) from exc
+
+
+__all__ = ["SpacyNerExtractor"]

cinoc/adapters/ocr/__init__.py

@@ -0,0 +1,8 @@
+"""Modules OCR/HTR (couche 5)."""
+
+from __future__ import annotations
+
+from cinoc.adapters.ocr.precomputed import PrecomputedTextAdapter
+from cinoc.adapters.ocr.tesseract import TesseractAdapter
+
+__all__ = ["PrecomputedTextAdapter", "TesseractAdapter"]

cinoc/adapters/ocr/_base.py

@@ -0,0 +1,64 @@
+"""Squelette commun des adapters OCR « image → un seul RAW_TEXT » (couche 5).
+
+Le même ``execute()`` était recopié dans chaque adapter OCR mono-sortie : sonde
+d'annulation, garde IMAGE, garde workspace, écriture du ``.txt`` dans le workspace,
+construction de l'artefact ``RAW_TEXT`` (id ``{doc}:{name}:raw_text`` + hash du
+texte). On le mutualise ici (miroir de ``llm/_base``) ; le **détail moteur** (params,
+clé API, deadline) reste dans chaque adapter, porté par la closure ``recognize``.
+
+N'est PAS pour les adapters multi-sorties (``tesseract`` : RAW_TEXT + CONFIDENCES
++ ALTO optionnel) — eux gardent leur ``execute()`` propre. Contrat de l'artefact
+``RAW_TEXT`` figé par ``tests/adapters/test_ocr_artifact_contract_anchor``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+
+def run_image_to_text(
+    *,
+    name: str,
+    label: str,
+    inputs: Mapping[ArtifactType, Artifact],
+    context: RunContext,
+    control: RunControl,
+    recognize: Callable[[str], str],
+) -> StepOutput:
+    """Exécute un OCR image → ``RAW_TEXT`` unique, gardes + persistance mutualisées.
+
+    ``recognize(image_uri) -> texte`` porte la reconnaissance réelle (et ses gardes
+    propres : clé API, modèle…). Ordre identique à l'ancien code par adapter :
+    annulation → IMAGE → workspace → ``recognize`` → écriture ``.txt`` → artefact.
+    """
+    control.raise_if_cancelled()
+    image = inputs.get(ArtifactType.IMAGE)
+    if image is None or image.uri is None:
+        raise AdapterStepError(f"{name} : artefact IMAGE manquant ou sans URI.")
+    if context.workspace_uri is None:
+        raise AdapterStepError(f"{name} : workspace requis.")
+    text = recognize(image.uri)
+    output_path = workspace_artifact_path(
+        context.workspace_uri, context.document_id, label, "txt"
+    )
+    output_path.write_text(text, encoding="utf-8")
+    return StepOutput(
+        artifacts={
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(text.encode("utf-8")),
+            )
+        }
+    )
+
+
+__all__ = ["run_image_to_text"]

cinoc/adapters/ocr/azure_di.py

@@ -0,0 +1,223 @@
+"""``AzureDocIntelAdapter`` — OCR cloud (Azure AI Document Intelligence, modèle Read).
+
+Moteur cloud **first-party**. API **REST** (``httpx``) plutôt que le SDK
+``azure-ai-documentintelligence`` (lourd, auth credential) : transport léger,
+**testable par cassette HTTP**. Auth par **clé d'abonnement**
+(``AZURE_DOC_INTEL_KEY``) + endpoint de la ressource (``AZURE_DOC_INTEL_ENDPOINT``).
+Implémente le ``Module`` Protocol **directement** ; ``httpx`` est l'extra
+``cinoc[azure]``, importé **paresseusement** (mockable, CI sans clé ni réseau).
+
+Flux **asynchrone** propre à Azure DI (fidèlement modélisé) : ``POST …:analyze``
+renvoie ``202`` + un en-tête ``Operation-Location`` ; on **sonde** cette URL
+(GET) jusqu'à ``status == "succeeded"`` (ou ``failed``/délai). Sortie :
+``analyzeResult.content`` du modèle ``prebuilt-read`` — le texte complet d'une page.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from base64 import b64encode
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+if TYPE_CHECKING:  # annotations seules — pas d'import httpx au chargement du module
+    import httpx
+
+_VERSION = "1.0"
+_MODEL = "prebuilt-read"
+_API_VERSION = "2024-11-30"
+_ANALYZE_PATH = f"/documentintelligence/documentModels/{_MODEL}:analyze"
+_KEY_HEADER = "Ocp-Apim-Subscription-Key"
+_ENDPOINT_ENV = "AZURE_DOC_INTEL_ENDPOINT"
+_KEY_ENV = "AZURE_DOC_INTEL_KEY"
+#: Borne dure du *polling* (en plus de la ``Deadline``) — évite la boucle infinie
+#: si le service reste indéfiniment ``running`` sous une deadline infinie.
+_MAX_POLLS = 60
+
+
+def _extract_text(data: object) -> str:
+    """Texte complet de ``analyzeResult.content`` ; page vide → ``""``."""
+    if not isinstance(data, dict):
+        raise AdapterStepError("azure_di : réponse JSON inattendue (objet).")
+    result = data.get("analyzeResult")
+    if not isinstance(result, dict):
+        raise AdapterStepError("azure_di : 'analyzeResult' absent de la réponse.")
+    content = result.get("content")
+    return str(content).strip() if content else ""
+
+
+def _invoke_azure_di(
+    *,
+    endpoint: str,
+    image_path: str,
+    deadline: Deadline,
+    key: str,
+    transport: httpx.BaseTransport | None = None,
+    poll_interval: float = 1.0,
+    sleep: Callable[[float], None] = time.sleep,
+) -> str:
+    """Analyse l'image (POST → sonde l'``Operation-Location``) et renvoie le texte.
+
+    ``endpoint`` vient de la **configuration opérateur** (env), pas de
+    l'utilisateur → endpoint de confiance, pas de durcissement anti-SSRF (≠
+    importeurs de corpus). La clé est en **en-tête** (jamais journalisée : les
+    messages d'erreur ne portent que le statut). ``transport``/``sleep`` injectés
+    → cassette **et** sonde déterministes en test (aucune attente réelle).
+    """
+    try:
+        import httpx
+    except ImportError as exc:
+        raise AdapterStepError(
+            "azure_di : httpx non installé (pip install 'cinoc[azure]')."
+        ) from exc
+    content = b64encode(Path(image_path).read_bytes()).decode("ascii")
+    analyze_url = endpoint.rstrip("/") + _ANALYZE_PATH
+    with httpx.Client(
+        timeout=deadline.as_sdk_timeout(), transport=transport
+    ) as client:
+        operation_url = _submit_analysis(
+            client, analyze_url=analyze_url, key=key, content=content
+        )
+        return _poll_result(
+            client,
+            operation_url=operation_url,
+            key=key,
+            deadline=deadline,
+            poll_interval=poll_interval,
+            sleep=sleep,
+        )
+
+
+def _submit_analysis(
+    client: httpx.Client, *, analyze_url: str, key: str, content: str
+) -> str:
+    """POST l'analyse ; renvoie l'URL ``Operation-Location`` à sonder."""
+    import httpx
+
+    headers = {_KEY_HEADER: key, "Content-Type": "application/json"}
+    try:
+        response = client.post(
+            analyze_url,
+            params={"api-version": _API_VERSION},
+            headers=headers,
+            json={"base64Source": content},
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        raise AdapterStepError(
+            f"azure_di : statut HTTP {exc.response.status_code} (soumission)."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise AdapterStepError(
+            f"azure_di : échec de transport (soumission) : {type(exc).__name__}."
+        ) from exc
+    operation_url = response.headers.get("operation-location")
+    if not operation_url:
+        raise AdapterStepError("azure_di : réponse sans en-tête Operation-Location.")
+    return str(operation_url)
+
+
+def _poll_result(
+    client: httpx.Client,
+    *,
+    operation_url: str,
+    key: str,
+    deadline: Deadline,
+    poll_interval: float,
+    sleep: Callable[[float], None],
+) -> str:
+    """Sonde l'``Operation-Location`` jusqu'à un état terminal (ou délai)."""
+    import httpx
+
+    for _ in range(_MAX_POLLS):
+        try:
+            response = client.get(operation_url, headers={_KEY_HEADER: key})
+            response.raise_for_status()
+            data = response.json()
+        except httpx.HTTPStatusError as exc:
+            raise AdapterStepError(
+                f"azure_di : statut HTTP {exc.response.status_code} (sonde)."
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise AdapterStepError(
+                f"azure_di : échec de transport (sonde) : {type(exc).__name__}."
+            ) from exc
+        status = (
+            str(data.get("status", "")).lower() if isinstance(data, dict) else ""
+        )
+        if status == "succeeded":
+            return _extract_text(data)
+        if status == "failed":
+            raise AdapterStepError("azure_di : analyse échouée (status 'failed').")
+        if deadline.is_expired():
+            break
+        sleep(poll_interval)
+    raise AdapterStepError("azure_di : analyse non terminée (délai de sonde dépassé).")
+
+
+class AzureDocIntelAdapter:
+    """OCR cloud Azure DI : ``IMAGE`` → ``RAW_TEXT`` (texte ``prebuilt-read``)."""
+
+    def __init__(self, *, label: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"azure_di : label invalide {label!r}.")
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"azure_di:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def recognize(image_uri: str) -> str:
+            endpoint = os.environ.get(_ENDPOINT_ENV)
+            key = os.environ.get(_KEY_ENV)
+            if not endpoint:
+                raise AdapterStepError(f"{self.name} : {_ENDPOINT_ENV} manquant.")
+            if not key:
+                raise AdapterStepError(f"{self.name} : {_KEY_ENV} manquante.")
+            return _invoke_azure_di(
+                endpoint=endpoint,
+                image_path=image_uri,
+                deadline=context.deadline,
+                key=key,
+            )
+
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=recognize,
+        )
+
+
+__all__ = ["AzureDocIntelAdapter"]

cinoc/adapters/ocr/calamari.py

@@ -0,0 +1,106 @@
+"""``CalamariAdapter`` — moteur OCR réel (calamari-ocr, reconnaissance de lignes).
+
+Local et sans clé. Implémente le ``Module`` Protocol **directement** — même
+contrat que le socle, livré in-tree (pas de discrimination socle/plugin). La lib
+``calamari_ocr`` est un **extra optionnel** (``cinoc[calamari]``), importée
+**paresseusement** dans ``_invoke_calamari`` : importer ce module ne requiert rien ;
+seule l'exécution exige la lib + un **modèle** (``model`` = checkpoint, obligatoire).
+
+Calamari reconnaît une **ligne** par image : utilisé seul sur une page, il traite
+l'image comme une ligne unique ; son usage naturel est en **recognizer par
+région** dans le pipeline de segmentation (fan-out par bloc). Sortie : ``RAW_TEXT``.
+
+**Non déployé au Space** (dép lourde TensorFlow, free-tier) : listé « indisponible »
+sans l'extra, comme Kraken/PERO.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _invoke_calamari(  # pragma: no cover -- lib + modèle requis (cf. 'live')
+    *, image_path: str, model_path: str
+) -> str:
+    """Reconnaissance Calamari de l'image (ligne) → texte prédit."""
+    try:
+        import numpy as np  # type: ignore[import-not-found]
+        from calamari_ocr.ocr.predict.predictor import (  # type: ignore[import-not-found]
+            Predictor,
+            PredictorParams,
+        )
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "calamari : lib non installée (pip install 'cinoc[calamari]')."
+        ) from exc
+    try:
+        predictor = Predictor.from_checkpoint(
+            params=PredictorParams(), checkpoint=model_path
+        )
+    except (OSError, ValueError, RuntimeError) as exc:  # loader calamari
+        raise AdapterStepError(
+            f"calamari : modèle illisible {model_path!r} : {exc}"
+        ) from exc
+    image = np.array(Image.open(image_path).convert("L"))
+    predictions = predictor.predict_raw([image])
+    texts = [str(prediction.sentence) for prediction in predictions]
+    return " ".join(texts).strip()
+
+
+class CalamariAdapter:
+    """OCR Calamari : ``IMAGE`` → ``RAW_TEXT`` (texte de la ligne reconnue)."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"calamari : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "calamari : paramètre 'model' (checkpoint) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"calamari:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_calamari(
+                image_path=image_uri, model_path=self._model
+            ),
+        )
+
+
+__all__ = ["CalamariAdapter"]

cinoc/adapters/ocr/google_vision.py

@@ -0,0 +1,157 @@
+"""``GoogleVisionAdapter`` — OCR cloud (Google Cloud Vision REST), facturé à l'image.
+
+Moteur cloud **first-party**. On vise l'**API REST** (``httpx``) plutôt que le SDK
+``google-cloud-vision`` (gRPC + auth ADC service-account, lourd et difficile à
+rejouer) : transport léger, **testable par cassette HTTP**, auth par **clé d'API**
+(``GOOGLE_VISION_API_KEY``). Implémente le ``Module`` Protocol **directement** ;
+``httpx`` est l'extra ``cinoc[google]``, importé **paresseusement** dans
+``_invoke_google_vision`` (mockable, CI sans clé ni réseau).
+
+Sortie : ``fullTextAnnotation.text`` de ``DOCUMENT_TEXT_DETECTION`` — le texte
+dense d'une page (le bon mode pour des documents, ≠ ``TEXT_DETECTION`` épars).
+"""
+
+from __future__ import annotations
+
+import os
+from base64 import b64encode
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+if TYPE_CHECKING:  # annotations seules — pas d'import httpx au chargement du module
+    import httpx
+
+_VERSION = "1.0"
+_ENDPOINT = "https://vision.googleapis.com/v1/images:annotate"
+_API_KEY_ENV = "GOOGLE_VISION_API_KEY"
+_FEATURE = "DOCUMENT_TEXT_DETECTION"
+
+
+def _extract_text(payload: object) -> str:
+    """Texte de la 1ʳᵉ réponse Vision ; erreur par image → ``AdapterStepError``.
+
+    Forme : ``{"responses": [{"fullTextAnnotation": {"text": …}}]}`` (ou
+    ``{"error": {"message": …}}`` pour un échec par image). Aucun texte détecté
+    (page blanche) → ``""`` — un résultat valide, pas une erreur.
+    """
+    if not isinstance(payload, dict):
+        raise AdapterStepError("google_vision : réponse JSON inattendue (objet).")
+    responses = payload.get("responses")
+    if not isinstance(responses, list) or not responses:
+        raise AdapterStepError("google_vision : réponse sans 'responses'.")
+    first = responses[0]
+    if not isinstance(first, dict):
+        raise AdapterStepError("google_vision : 'responses[0]' inattendu.")
+    error = first.get("error")
+    if isinstance(error, dict) and error:
+        message = error.get("message", "erreur sans message")
+        raise AdapterStepError(f"google_vision : erreur API : {message}")
+    annotation = first.get("fullTextAnnotation")
+    if isinstance(annotation, dict):
+        text = annotation.get("text")
+        return str(text).strip() if text else ""
+    return ""
+
+
+def _invoke_google_vision(
+    *,
+    image_path: str,
+    deadline: Deadline,
+    api_key: str,
+    transport: httpx.BaseTransport | None = None,
+) -> str:
+    """POST l'image à Vision et renvoie le texte. ``transport`` injecté → cassette.
+
+    Endpoint **fixe et de confiance** (Google) : pas de durcissement anti-SSRF (≠
+    importeurs de corpus, dont l'URL vient de l'utilisateur). La clé d'API est en
+    *query string* (jamais journalisée : les messages d'erreur ne portent que le
+    statut). ``httpx`` paresseux : importer ce module n'exige pas l'extra.
+    """
+    try:
+        import httpx
+    except ImportError as exc:
+        raise AdapterStepError(
+            "google_vision : httpx non installé (pip install 'cinoc[google]')."
+        ) from exc
+    content = b64encode(Path(image_path).read_bytes()).decode("ascii")
+    body = {
+        "requests": [
+            {"image": {"content": content}, "features": [{"type": _FEATURE}]}
+        ]
+    }
+    try:
+        with httpx.Client(
+            timeout=deadline.as_sdk_timeout(), transport=transport
+        ) as client:
+            response = client.post(_ENDPOINT, params={"key": api_key}, json=body)
+            response.raise_for_status()
+            data = response.json()
+    except httpx.HTTPStatusError as exc:
+        raise AdapterStepError(
+            f"google_vision : statut HTTP {exc.response.status_code}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise AdapterStepError(
+            f"google_vision : échec de transport : {type(exc).__name__}."
+        ) from exc
+    return _extract_text(data)
+
+
+class GoogleVisionAdapter:
+    """OCR cloud Google Vision : ``IMAGE`` → ``RAW_TEXT`` (texte dense de la page)."""
+
+    def __init__(self, *, label: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"google_vision : label invalide {label!r}.")
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"google_vision:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def recognize(image_uri: str) -> str:
+            api_key = os.environ.get(_API_KEY_ENV)
+            if not api_key:
+                raise AdapterStepError(f"{self.name} : {_API_KEY_ENV} manquante.")
+            return _invoke_google_vision(
+                image_path=image_uri, deadline=context.deadline, api_key=api_key
+            )
+
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=recognize,
+        )
+
+
+__all__ = ["GoogleVisionAdapter"]

cinoc/adapters/ocr/kraken.py

@@ -0,0 +1,166 @@
+"""``KrakenAdapter`` — moteur HTR réel (kraken, le moteur d'eScriptorium).
+
+Implémente le ``Module`` Protocol directement. Couvre le **manuscrit** (HTR),
+là où tesseract couvre l'imprimé. Le SDK ``kraken`` est un **extra optionnel**
+(``cinoc[kraken]``), importé paresseusement dans ``_invoke_kraken`` — importer
+ce module ne requiert rien ; seule l'exécution exige SDK + **modèle** (.mlmodel,
+paramètre ``model`` obligatoire : pas de modèle par défaut embarqué).
+
+Sorties : ``RAW_TEXT`` (lignes reconnues, ordre de lecture kraken) +
+``CONFIDENCES`` (un jeton par mot, confiance = moyenne des confiances de
+caractères du mot — best-effort, sidecar vide en dégradé).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.confidence import ConfidenceToken
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+
+
+def tokens_from_lines(
+    lines: list[tuple[str, list[float]]],
+) -> list[ConfidenceToken]:
+    """Jetons mot+confiance depuis (texte de ligne, confiances par caractère).
+
+    La confiance d'un mot = moyenne des confiances de ses caractères (bornée
+    [0,1]) ; un mot sans couverture de confiance est ignoré.
+    """
+    tokens: list[ConfidenceToken] = []
+    for text, confidences in lines:
+        cursor = 0
+        for word in text.split():
+            start = text.find(word, cursor)
+            if start < 0:
+                continue
+            cursor = start + len(word)
+            window = confidences[start : start + len(word)]
+            if not window:
+                continue
+            value = max(0.0, min(sum(window) / len(window), 1.0))
+            tokens.append(ConfidenceToken(text=word, confidence=value))
+    return tokens
+
+
+def _invoke_kraken(  # pragma: no cover -- SDK + modèle requis (cf. 'live')
+    *, image_path: str, model_path: str
+) -> list[tuple[str, list[float]]]:
+    """Segmentation + reconnaissance kraken → (texte, confiances/char) par ligne."""
+    try:
+        from kraken import (  # type: ignore[import-not-found]
+            binarization,
+            pageseg,
+            rpred,
+        )
+        from kraken.lib import models  # type: ignore[import-not-found]
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "kraken : SDK non installé (pip install 'cinoc[kraken]')."
+        ) from exc
+    try:
+        model = models.load_any(model_path)
+    except (OSError, ValueError, RuntimeError) as exc:  # loader kraken
+        raise AdapterStepError(
+            f"kraken : modèle illisible {model_path!r} : {exc}"
+        ) from exc
+    image = Image.open(image_path)
+    binarized = binarization.nlbin(image)
+    segmentation = pageseg.segment(binarized)
+    out: list[tuple[str, list[float]]] = []
+    for record in rpred.rpred(model, binarized, segmentation):
+        out.append((str(record), [float(c) for c in record.confidences]))
+    return out
+
+
+class KrakenAdapter:
+    """HTR kraken : ``IMAGE`` → ``RAW_TEXT`` + ``CONFIDENCES``."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"kraken : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "kraken : paramètre 'model' (chemin .mlmodel) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"kraken:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT, ArtifactType.CONFIDENCES})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(f"{self.name} : workspace requis.")
+        lines = _invoke_kraken(image_path=image.uri, model_path=self._model)
+        text = "\n".join(line for line, _ in lines)
+        tokens = tokens_from_lines(lines)
+        text_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "txt"
+        )
+        text_path.write_text(text, encoding="utf-8")
+        sidecar = json.dumps(
+            [token.model_dump() for token in tokens], ensure_ascii=False
+        ).encode("utf-8")
+        sidecar_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label,
+            "confidences.json",
+        )
+        sidecar_path.write_bytes(sidecar)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(text_path),
+                    content_hash=compute_content_hash(text.encode("utf-8")),
+                ),
+                ArtifactType.CONFIDENCES: Artifact(
+                    id=f"{context.document_id}:{self.name}:confidences",
+                    document_id=context.document_id,
+                    type=ArtifactType.CONFIDENCES,
+                    uri=str(sidecar_path),
+                    content_hash=compute_content_hash(sidecar),
+                ),
+            }
+        )
+
+
+__all__ = ["KrakenAdapter", "tokens_from_lines"]

cinoc/adapters/ocr/mistral_ocr.py

@@ -0,0 +1,113 @@
+"""``MistralOCRAdapter`` — OCR cloud (API Mistral OCR), facturé à la page.
+
+Premier moteur **payant à la page** du socle : donne un sens réel à l'axe
+coût du Pareto (économie T10, tarif ``cloud_page_kinds``). Implémente le
+``Module`` Protocol ; SDK ``mistralai`` = extra (``cinoc[mistral]``), importé
+paresseusement dans ``_invoke_mistral_ocr`` (mockable, CI sans clé ni réseau).
+Clé ``MISTRAL_API_KEY``. Sortie : le texte (markdown) des pages, concaténé.
+"""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from pathlib import Path
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "mistral-ocr-latest"
+_MEDIA = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+          ".webp": "image/webp", ".tif": "image/tiff", ".tiff": "image/tiff"}
+
+
+def _invoke_mistral_ocr(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, image_path: str, deadline: Deadline
+) -> str:
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        raise AdapterStepError("mistral_ocr : MISTRAL_API_KEY manquante.")
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "mistral_ocr : SDK non installé (pip install 'cinoc[mistral]')."
+        ) from exc
+    path = Path(image_path)
+    media = _MEDIA.get(path.suffix.lower(), "image/png")
+    image_b64 = b64encode(path.read_bytes()).decode("ascii")
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout_ms"] = int(timeout * 1000)
+    try:
+        client = Mistral(**client_kwargs)  # type: ignore[arg-type]
+        response = client.ocr.process(
+            model=model,
+            document={
+                "type": "image_url",
+                "image_url": f"data:{media};base64,{image_b64}",
+            },
+        )
+    except Exception as exc:  # le SDK lève des erreurs HTTP/SDK variées
+        raise AdapterStepError(
+            f"mistral_ocr a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    pages = getattr(response, "pages", None) or []
+    return "\n\n".join(
+        str(getattr(page, "markdown", "") or "") for page in pages
+    ).strip()
+
+
+class MistralOCRAdapter:
+    """OCR cloud Mistral : ``IMAGE`` → ``RAW_TEXT`` (markdown des pages)."""
+
+    def __init__(self, *, label: str, model: str = _DEFAULT_MODEL) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"mistral_ocr : label invalide {label!r}.")
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"mistral_ocr:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_mistral_ocr(
+                model=self._model, image_path=image_uri, deadline=context.deadline
+            ),
+        )
+
+
+__all__ = ["MistralOCRAdapter"]

cinoc/adapters/ocr/pero.py

@@ -0,0 +1,114 @@
+"""``PeroAdapter`` — moteur OCR/HTR réel (pero-ocr).
+
+Local et sans clé : couvre l'imprimé ancien et le manuscrit via les modèles PERO,
+là où tesseract couvre l'imprimé moderne. Implémente le ``Module`` Protocol
+**directement** — même contrat que le socle, livré in-tree (décision : pas de
+discrimination socle/plugin ; seule la livraison diffère). La lib ``pero_ocr`` est
+un **extra optionnel** (``cinoc[pero]``), importée **paresseusement** dans
+``_invoke_pero`` : importer ce module ne requiert rien ; seule l'exécution exige la
+lib + un **modèle** (``model`` = chemin du fichier de config PERO, obligatoire —
+pas de modèle embarqué). Sortie : ``RAW_TEXT`` (lignes reconnues, ordre PERO).
+
+**Non déployé au Space** (dép lourde, free-tier) : listé « indisponible » sans
+l'extra, comme Kraken — pas d'exécution cloud, pas de clé.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _invoke_pero(  # pragma: no cover -- lib + modèle requis (cf. 'live')
+    *, image_path: str, config_path: str
+) -> str:
+    """Mise en page + reconnaissance PERO → texte (lignes jointes, ordre PERO)."""
+    try:
+        import configparser
+
+        import cv2  # type: ignore[import-not-found]
+        from pero_ocr.document_ocr.layout import (  # type: ignore[import-not-found]
+            PageLayout,
+        )
+        from pero_ocr.document_ocr.page_parser import (  # type: ignore[import-not-found]
+            PageParser,
+        )
+    except ImportError as exc:
+        raise AdapterStepError(
+            "pero : lib non installée (pip install 'cinoc[pero]')."
+        ) from exc
+    config = configparser.ConfigParser()
+    if not config.read(config_path):
+        raise AdapterStepError(f"pero : config illisible {config_path!r}.")
+    image = cv2.imread(image_path)
+    if image is None:
+        raise AdapterStepError(f"pero : image illisible {image_path!r}.")
+    parser = PageParser(config, config_path=str(Path(config_path).parent))
+    layout = PageLayout(id="page", page_size=(image.shape[0], image.shape[1]))
+    layout = parser.process_page(image, layout)
+    lines = [
+        str(line.transcription)
+        for region in layout.regions
+        for line in region.lines
+        if line.transcription
+    ]
+    return "\n".join(lines).strip()
+
+
+class PeroAdapter:
+    """OCR/HTR PERO : ``IMAGE`` → ``RAW_TEXT`` (lignes reconnues)."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"pero : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "pero : paramètre 'model' (chemin de config PERO) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"pero:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_pero(
+                image_path=image_uri, config_path=self._model
+            ),
+        )
+
+
+__all__ = ["PeroAdapter"]

cinoc/adapters/ocr/precomputed.py

@@ -0,0 +1,91 @@
+"""``PrecomputedTextAdapter`` — rejoue un texte OCR pré-calculé depuis le disque.
+
+Module à **zéro dépendance et zéro réseau** : il lit ``<stem>.<source_label>.txt``
+à côté de l'image et renvoie un ``RAW_TEXT``. Brique du *starter pack* — il fait
+tourner le squelette ambulant (``cinoc demo``) et les tests déterministes sans
+moteur réel. Implémente le ``Module`` Protocol (couche 4) **directement**.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+class PrecomputedTextAdapter:
+    """Lit un texte OCR pré-calculé (``<stem>.<label>.txt`` près de l'image)."""
+
+    def __init__(self, *, source_label: str) -> None:
+        if not source_label or not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise AdapterStepError(
+                f"PrecomputedTextAdapter : source_label invalide "
+                f"{source_label!r} (alphanumérique + _ - uniquement)."
+            )
+        self._label = source_label
+
+    @property
+    def name(self) -> str:
+        return f"precomputed:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        image_path = Path(image.uri)
+        text_path = image_path.parent / f"{image_path.stem}.{self._label}.txt"
+        if not text_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : texte pré-calculé introuvable — "
+                f"{text_path.name!r} attendu près de {image_path.name!r}."
+            )
+        data = text_path.read_bytes()
+        try:
+            data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {text_path.name!r} n'est pas en UTF-8 : {exc}"
+            ) from exc
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(text_path),
+                    content_hash=compute_content_hash(data),
+                )
+            }
+        )
+
+
+__all__ = ["PrecomputedTextAdapter"]

cinoc/adapters/ocr/tesseract.py

@@ -0,0 +1,332 @@
+"""``TesseractAdapter`` — moteur OCR réel (Tesseract 5 via ``pytesseract``).
+
+Implémente le ``Module`` Protocol (couche 4) **directement**. L'OCR a lieu dans
+le binaire C ``tesseract`` lancé en sous-processus (le thread relâche le GIL).
+``pytesseract`` est un **extra optionnel** (``cinoc[tesseract]``), importé
+**paresseusement** dans ``_invoke_tesseract`` : importer ce module ne requiert ni
+la lib ni le binaire — seule l'exécution les exige.
+
+Sécurité : ``lang`` est validé (anti-injection ligne de commande) ; ``timeout``
+est borné par la ``Deadline`` (un sous-processus figé ne doit pas geler le run).
+Les **confidences** par mot (TSV natif, 0-100 → [0,1]) sont écrites en
+sidecar JSON (``ConfidenceToken``) et publiées comme artefact ``CONFIDENCES``
+— best-effort : un échec d'extraction dégrade en sidecar vide, jamais en
+panne de l'OCR.
+
+**ALTO natif** (``alto=True``) : Tesseract émet en plus un artefact
+``ALTO_XML`` (géométrie + texte par mot, ``image_to_alto_xml``) — la forme
+ré-importable dans un outil de relecture (eScriptorium, Transkribus). Contrairement
+aux confidences, l'ALTO est ici le **livrable demandé** : un échec d'émission lève
+(``AdapterStepError``), il ne dégrade pas en silence.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+from collections.abc import Callable
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.confidence import ConfidenceToken
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+_DEFAULT_TIMEOUT = 120.0
+
+#: Codes langue Tesseract : ISO 639-3 (≥3 lettres ASCII), combinables par ``+``
+#: (``fra+lat``). ``lang`` finit sur la ligne de commande tesseract → on refuse
+#: tout caractère interprétable comme flag/séparateur (anti-injection).
+_LANG_RE = re.compile(r"^[a-zA-Z]{3,}(?:\+[a-zA-Z]{3,})*$")
+
+#: Lanceur de sous-processus, injectable → version sondable en test sans binaire.
+BinaryRunner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+def tesseract_binary_version(*, run: BinaryRunner = subprocess.run) -> str | None:
+    """Version du binaire ``tesseract`` (1ʳᵉ ligne de ``tesseract --version``).
+
+    **Best-effort, jamais bloquant** : binaire absent, timeout, ou sortie illisible
+    → ``None`` (jamais une panne). Sert la **reproductibilité** (``RunManifest`` §12) :
+    deux runs ne sont comparables qu'à version de binaire égale — la version
+    d'*adapter* (``_VERSION``) ne dit rien du Tesseract réellement installé.
+    ``run`` est injecté → la sonde est déterministe en test, sans le binaire.
+
+    Tesseract émet sa bannière tantôt sur ``stdout`` tantôt sur ``stderr`` selon le
+    build → on lit les deux et garde la 1ʳᵉ ligne non vide (ex. ``tesseract 5.3.0``).
+    """
+    try:
+        completed = run(
+            ["tesseract", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    lines = ((completed.stdout or "") + "\n" + (completed.stderr or "")).splitlines()
+    for line in lines:
+        if line.strip():
+            return line.strip()
+    return None
+
+
+def _invoke_tesseract(  # pragma: no cover -- binaire requis (cf. marqueur 'live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> str:
+    """Lance tesseract et renvoie le texte. **Isolé → mockable** (CI sans binaire)."""
+    try:
+        import pytesseract  # type: ignore[import-not-found, import-untyped]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "tesseract : pytesseract non installé "
+            "(pip install 'cinoc[tesseract]' + binaire tesseract)."
+        ) from exc
+    config = f"--oem {oem} --psm {psm}"
+    try:
+        text = pytesseract.image_to_string(
+            image_path, lang=lang, config=config, timeout=timeout
+        )
+    except (
+        pytesseract.TesseractNotFoundError,
+        pytesseract.TesseractError,
+        RuntimeError,
+    ) as exc:
+        raise AdapterStepError(
+            f"tesseract a échoué sur {image_path!r} : {type(exc).__name__}: {exc}"
+        ) from exc
+    return str(text).strip()
+
+
+def _invoke_tesseract_alto(  # pragma: no cover -- binaire requis ('live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> bytes:
+    """ALTO XML natif via ``image_to_alto_xml`` (géométrie + texte par mot).
+
+    Renvoie les octets XML bruts (déjà conformes ALTO) — destinés à la
+    ré-importation dans un outil de relecture. Une panne du binaire lève
+    ``AdapterStepError`` : l'ALTO est le livrable demandé, pas un extra dégradable.
+    """
+    try:
+        import pytesseract  # type: ignore[import-not-found, import-untyped]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "tesseract : pytesseract non installé "
+            "(pip install 'cinoc[tesseract]' + binaire tesseract)."
+        ) from exc
+    try:
+        xml = pytesseract.image_to_alto_xml(
+            image_path, lang=lang, config=f"--oem {oem} --psm {psm}", timeout=timeout
+        )
+    except (
+        pytesseract.TesseractNotFoundError,
+        pytesseract.TesseractError,
+        RuntimeError,
+    ) as exc:
+        raise AdapterStepError(
+            f"tesseract ALTO a échoué sur {image_path!r} : "
+            f"{type(exc).__name__}: {exc}"
+        ) from exc
+    return bytes(xml)
+
+
+def _invoke_tesseract_confidences(  # pragma: no cover -- binaire requis ('live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> list[ConfidenceToken]:
+    """Confidences par mot via ``image_to_data`` (TSV natif, conf 0-100)."""
+    import pytesseract  # type: ignore[import-not-found]
+
+    data = pytesseract.image_to_data(
+        image_path,
+        lang=lang,
+        config=f"--psm {psm} --oem {oem}",
+        timeout=timeout,
+        output_type=pytesseract.Output.DICT,
+    )
+    tokens: list[ConfidenceToken] = []
+    for word, conf in zip(data["text"], data["conf"], strict=False):
+        if not isinstance(word, str) or not word.strip():
+            continue
+        value = float(conf)
+        if value < 0:  # -1 : entrée non textuelle du TSV
+            continue
+        tokens.append(
+            ConfidenceToken(text=word.strip(), confidence=min(value / 100.0, 1.0))
+        )
+    return tokens
+
+
+class TesseractAdapter:
+    """OCR Tesseract 5 ; écrit le texte dans le workspace, renvoie un ``RAW_TEXT``."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        lang: str = "fra",
+        psm: int = 6,
+        oem: int = 3,
+        alto: bool = False,
+    ) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(
+                f"TesseractAdapter : label invalide {label!r} "
+                "(alphanumérique + _ - uniquement)."
+            )
+        if not _LANG_RE.fullmatch(lang):
+            raise AdapterStepError(
+                f"TesseractAdapter : lang invalide {lang!r} "
+                "(ISO 639-3, combinable par '+' : ex. 'fra+lat')."
+            )
+        if not 0 <= psm <= 13:
+            raise AdapterStepError(f"TesseractAdapter : psm ∈ [0, 13], reçu {psm}.")
+        if not 0 <= oem <= 3:
+            raise AdapterStepError(f"TesseractAdapter : oem ∈ [0, 3], reçu {oem}.")
+        self._label = label
+        self._lang = lang
+        self._psm = psm
+        self._oem = oem
+        #: Émet en plus un artefact ``ALTO_XML`` (ré-import eScriptorium/Transkribus).
+        self._alto = alto
+
+    @property
+    def name(self) -> str:
+        return f"tesseract:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    def system_binaries(self) -> dict[str, str]:
+        """Version du **binaire externe** pour le ``RunManifest`` (reproductibilité).
+
+        Hook de **provenance optionnel** (hors ``Module`` Protocol, qui reste le
+        contrat d'exécution unique) : l'orchestrateur l'appelle par *duck-typing*
+        sur les modules qui l'exposent et fusionne le résultat dans
+        ``system_binaries_lock``. Best-effort : binaire absent → ``{}``.
+        """
+        version = tesseract_binary_version()
+        return {"tesseract": version} if version is not None else {}
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        types = {ArtifactType.RAW_TEXT, ArtifactType.CONFIDENCES}
+        if self._alto:
+            types.add(ArtifactType.ALTO_XML)
+        return frozenset(types)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(
+                f"{self.name} : workspace requis (RunContext.workspace_uri)."
+            )
+        timeout = max(0.001, context.deadline.clamp_to_remaining(_DEFAULT_TIMEOUT))
+        text = _invoke_tesseract(
+            image_path=image.uri,
+            lang=self._lang,
+            psm=self._psm,
+            oem=self._oem,
+            timeout=timeout,
+        )
+        output_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "txt"
+        )
+        output_path.write_text(text, encoding="utf-8")
+        # Confidences best-effort : un échec d'extraction ne doit pas faire
+        # échouer un OCR réussi — sidecar vide + avertissement.
+        try:
+            tokens = _invoke_tesseract_confidences(
+                image_path=image.uri,
+                lang=self._lang,
+                psm=self._psm,
+                oem=self._oem,
+                timeout=timeout,
+            )
+        except (
+            AdapterStepError,
+            ImportError,
+            RuntimeError,
+            ValueError,
+            OSError,
+        ) as exc:
+            logger.warning(
+                "[tesseract] confidences dégradées (sidecar vide) : %s", exc
+            )
+            tokens = []
+        sidecar = json.dumps(
+            [token.model_dump() for token in tokens], ensure_ascii=False
+        ).encode("utf-8")
+        sidecar_path = workspace_artifact_path(
+            context.workspace_uri,
+            context.document_id,
+            self._label,
+            "confidences.json",
+        )
+        sidecar_path.write_bytes(sidecar)
+        artifacts: dict[ArtifactType, Artifact] = {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(text.encode("utf-8")),
+            ),
+            ArtifactType.CONFIDENCES: Artifact(
+                id=f"{context.document_id}:{self.name}:confidences",
+                document_id=context.document_id,
+                type=ArtifactType.CONFIDENCES,
+                uri=str(sidecar_path),
+                content_hash=compute_content_hash(sidecar),
+            ),
+        }
+        if self._alto:
+            # ALTO demandé → livrable : un échec lève (≠ confidences best-effort).
+            alto_bytes = _invoke_tesseract_alto(
+                image_path=image.uri,
+                lang=self._lang,
+                psm=self._psm,
+                oem=self._oem,
+                timeout=timeout,
+            )
+            alto_path = workspace_artifact_path(
+                context.workspace_uri,
+                context.document_id,
+                self._label,
+                "alto.xml",
+            )
+            alto_path.write_bytes(alto_bytes)
+            artifacts[ArtifactType.ALTO_XML] = Artifact(
+                id=f"{context.document_id}:{self.name}:alto_xml",
+                document_id=context.document_id,
+                type=ArtifactType.ALTO_XML,
+                uri=str(alto_path),
+                content_hash=compute_content_hash(alto_bytes),
+            )
+        return StepOutput(artifacts=artifacts)
+
+
+__all__ = ["TesseractAdapter", "tesseract_binary_version"]

cinoc/adapters/storage/__init__.py

@@ -0,0 +1,24 @@
+"""Stockage (couche 5) : état des jobs de run lancés via le web/CLI long.
+
+En mémoire par choix : suffit au lanceur mono-worker du Space. Le journal
+d'événements du ``JobStore`` porte la reprise SSE ``Last-Event-ID`` (réserve
+R-10 d'ANALYSE_COUCHE_5, levée).
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.storage.history_store import (
+    HistoryRecord,
+    HistoryStore,
+    Regression,
+)
+from cinoc.adapters.storage.job_store import Job, JobState, JobStore
+
+__all__ = [
+    "HistoryRecord",
+    "HistoryStore",
+    "Job",
+    "JobState",
+    "JobStore",
+    "Regression",
+]

cinoc/adapters/storage/history_store.py

@@ -0,0 +1,191 @@
+"""``HistoryStore`` — historique **longitudinal** des runs, en SQLite (couche 5).
+
+Persiste, run après run, la **valeur agrégée de chaque métrique** par pipeline et
+par vue, pour suivre l'évolution dans le temps (tendance) et **détecter les
+régressions** (un moteur dont le CER se dégrade d'un run au suivant).
+
+Le store ne connaît **que des enregistrements primitifs** (``HistoryRecord``) : il
+n'importe pas ``RunResult`` (couche 3) — c'est la couche ``app`` qui aplatit un
+``RunResult`` en enregistrements (``app/history.py``). Persistance pure, réutilisable
+et testable avec de la donnée simple.
+
+Concurrence : **une connexion par opération** (``sqlite3.connect`` est bon marché),
+donc aucun partage de connexion entre threads. Ré-enregistrer un même run est
+**idempotent** (clé primaire ``(run_id, pipeline, view, metric)``).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterable
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS run_metrics (
+    run_id       TEXT NOT NULL,
+    completed_at TEXT NOT NULL,
+    corpus_name  TEXT NOT NULL,
+    code_version TEXT NOT NULL,
+    pipeline     TEXT NOT NULL,
+    view         TEXT NOT NULL,
+    metric       TEXT NOT NULL,
+    value        REAL NOT NULL,
+    PRIMARY KEY (run_id, pipeline, view, metric)
+);
+CREATE INDEX IF NOT EXISTS idx_run_metrics_lookup
+    ON run_metrics (view, metric, pipeline, completed_at);
+"""
+
+_COLUMNS = (
+    "run_id, completed_at, corpus_name, code_version, pipeline, view, metric, value"
+)
+
+
+@dataclass(frozen=True)
+class HistoryRecord:
+    """Une valeur de métrique agrégée pour un run (ligne d'historique)."""
+
+    run_id: str
+    completed_at: str  # ISO 8601 (UTC) — triable lexicographiquement
+    corpus_name: str
+    code_version: str
+    pipeline: str
+    view: str
+    metric: str
+    value: float
+
+
+@dataclass(frozen=True)
+class Regression:
+    """Dégradation d'un pipeline entre ses deux runs les plus récents."""
+
+    pipeline: str
+    view: str
+    metric: str
+    previous_run_id: str
+    latest_run_id: str
+    previous: float
+    latest: float
+    delta: float  # latest - previous (signé)
+
+
+class HistoryStore:
+    """Historique longitudinal sur un fichier SQLite."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        # **Initialisation paresseuse** : on ne touche pas au filesystem ici.
+        # ``create_app`` peut instancier le store avec un chemin par défaut
+        # (``/data`` sur un Space) non writable au moment de la construction ;
+        # le dossier + le schéma sont créés à la **première** opération réelle.
+        self._path = Path(db_path)
+
+    def _connect(self) -> sqlite3.Connection:
+        """Ouvre une connexion, créant dossier + schéma au besoin (idempotent)."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self._path)
+        conn.executescript(_SCHEMA)
+        return conn
+
+    def add(self, records: Iterable[HistoryRecord]) -> int:
+        """Enregistre des lignes (``INSERT OR REPLACE``) ; renvoie le compte."""
+        rows = [
+            (
+                r.run_id,
+                r.completed_at,
+                r.corpus_name,
+                r.code_version,
+                r.pipeline,
+                r.view,
+                r.metric,
+                r.value,
+            )
+            for r in records
+        ]
+        if not rows:
+            return 0
+        with closing(self._connect()) as conn:
+            conn.executemany(
+                f"INSERT OR REPLACE INTO run_metrics ({_COLUMNS}) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                rows,
+            )
+            conn.commit()
+        return len(rows)
+
+    def history(
+        self, pipeline: str, view: str, metric: str
+    ) -> tuple[HistoryRecord, ...]:
+        """Suite chronologique (croissante) d'une métrique pour un pipeline/vue."""
+        with closing(self._connect()) as conn:
+            cur = conn.execute(
+                f"SELECT {_COLUMNS} FROM run_metrics "
+                "WHERE pipeline = ? AND view = ? AND metric = ? "
+                "ORDER BY completed_at, run_id",  # run_id = bris d'égalité déterministe
+                (pipeline, view, metric),
+            )
+            return tuple(HistoryRecord(*row) for row in cur.fetchall())
+
+    def all_records(self, *, limit: int = 1000) -> tuple[HistoryRecord, ...]:
+        """Lignes les plus récentes d'abord, **bornées** (pour la vue Historique)."""
+        with closing(self._connect()) as conn:
+            cur = conn.execute(
+                f"SELECT {_COLUMNS} FROM run_metrics "
+                "ORDER BY completed_at DESC, run_id, pipeline, view, metric "
+                "LIMIT ?",
+                (limit,),
+            )
+            return tuple(HistoryRecord(*row) for row in cur.fetchall())
+
+    def regressions(
+        self,
+        view: str,
+        metric: str,
+        *,
+        threshold: float = 0.0,
+        higher_is_better: bool = False,
+    ) -> tuple[Regression, ...]:
+        """Pipelines dont la métrique s'est dégradée entre les 2 derniers runs.
+
+        ``higher_is_better=False`` (défaut, CER/WER) : régression = la valeur a
+        **augmenté** de plus de ``threshold``. ``True`` inverse le sens.
+        """
+        with closing(self._connect()) as conn:
+            cur = conn.execute(
+                "SELECT pipeline, completed_at, value, run_id FROM run_metrics "
+                "WHERE view = ? AND metric = ? "
+                "ORDER BY pipeline, completed_at, run_id",  # bris d'égalité stable
+                (view, metric),
+            )
+            rows = cur.fetchall()
+
+        by_pipeline: dict[str, list[tuple[str, float, str]]] = {}
+        for pipeline, completed_at, value, run_id in rows:
+            by_pipeline.setdefault(pipeline, []).append((completed_at, value, run_id))
+
+        out: list[Regression] = []
+        for pipeline, series in by_pipeline.items():
+            if len(series) < 2:
+                continue
+            _, prev_value, prev_run = series[-2]
+            _, last_value, last_run = series[-1]
+            delta = last_value - prev_value
+            worse = -delta if higher_is_better else delta
+            if worse > threshold:
+                out.append(
+                    Regression(
+                        pipeline=pipeline,
+                        view=view,
+                        metric=metric,
+                        previous_run_id=prev_run,
+                        latest_run_id=last_run,
+                        previous=prev_value,
+                        latest=last_value,
+                        delta=delta,
+                    )
+                )
+        return tuple(out)
+
+
+__all__ = ["HistoryRecord", "HistoryStore", "Regression"]

cinoc/adapters/storage/job_store.py

@@ -0,0 +1,159 @@
+"""``JobStore`` — état des jobs de run, **en mémoire et thread-safe** (couche 5).
+
+Un job = une exécution asynchrone d'un ``RunSpec`` (lancée par le ``JobRunner``,
+couche 6). Le store ne *fait* rien : il garde l'état observable (la machine à
+états ci-dessous) pour que le web le restitue et qu'un ``cancel`` soit traçable.
+
+Concurrence : un seul verrou protège le dict ; ``Job`` est **immuable** (pydantic
+``frozen``), donc un lecteur (requête HTTP) reçoit un instantané cohérent sans
+risque de course avec le worker qui le remplace sous verrou.
+
+Chaque transition est aussi **journalisée** (``_history``) : un instantané ``Job``
+par changement d'état, indexé par un id monotone (1-based). C'est la matière
+première du **flux SSE** + de la reprise ``Last-Event-ID`` (couche 8) — rejouable
+même après la fin du job.
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+from cinoc.domain.errors import CinocError
+from cinoc.domain.run import utcnow
+
+
+class JobState(StrEnum):
+    """États d'un job. Terminaux : ``DONE``, ``FAILED``, ``CANCELLED``."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in _TERMINAL
+
+
+_TERMINAL = frozenset({JobState.DONE, JobState.FAILED, JobState.CANCELLED})
+
+
+class JobError(CinocError):
+    """Job introuvable."""
+
+
+class Job(BaseModel):
+    """Instantané immuable de l'état d'un job."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str
+    state: JobState
+    created_at: str
+    updated_at: str
+    #: Stem du ``RunResult`` JSON écrit quand ``state == DONE`` (sinon ``None``).
+    report_name: str | None = None
+    #: Message d'erreur quand ``state == FAILED`` (sinon ``None``).
+    error: str | None = None
+    #: URL distante du rapport publié si la persistance est active, sinon ``None``.
+    published_url: str | None = None
+    #: Progression : unités (document × concurrent) traitées / total. ``0/0`` =
+    #: inconnu (job pas encore démarré). Alimente la barre de progression (SSE).
+    done: int = 0
+    total: int = 0
+
+
+class JobStore:
+    """Dictionnaire thread-safe ``job_id → Job`` (instantanés immuables)."""
+
+    def __init__(self) -> None:
+        self._jobs: dict[str, Job] = {}
+        self._history: dict[str, list[Job]] = {}
+        self._lock = threading.Lock()
+
+    def create(self) -> Job:
+        """Crée un job ``PENDING`` (id généré) et le renvoie."""
+        now = utcnow().isoformat()
+        job = Job(id=uuid.uuid4().hex, state=JobState.PENDING, created_at=now,
+                  updated_at=now)
+        with self._lock:
+            self._jobs[job.id] = job
+            self._history[job.id] = [job]
+        return job
+
+    def get(self, job_id: str) -> Job | None:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def all_jobs(self) -> tuple[Job, ...]:
+        """Tous les jobs, du plus récent au plus ancien."""
+        with self._lock:
+            jobs = tuple(self._jobs.values())
+        return tuple(sorted(jobs, key=lambda j: j.created_at, reverse=True))
+
+    def update(
+        self,
+        job_id: str,
+        *,
+        state: JobState,
+        report_name: str | None = None,
+        error: str | None = None,
+        published_url: str | None = None,
+    ) -> Job:
+        """Remplace l'instantané du job (sous verrou). Lève si inconnu."""
+        with self._lock:
+            current = self._jobs.get(job_id)
+            if current is None:
+                raise JobError(f"job {job_id!r} introuvable.")
+            updated = current.model_copy(
+                update={
+                    "state": state,
+                    "report_name": report_name,
+                    "error": error,
+                    "published_url": published_url,
+                    "updated_at": utcnow().isoformat(),
+                }
+            )
+            self._jobs[job_id] = updated
+            self._history[job_id].append(updated)
+        return updated
+
+    def progress(self, job_id: str, done: int, total: int) -> Job:
+        """Met à jour la progression (``done``/``total``) **sans changer l'état**.
+
+        Ajoute un instantané au journal → un **événement SSE** (de type ``running``)
+        par unité traitée, que l'UI consomme pour la barre de progression. Les
+        autres champs (état, rapport…) sont préservés (``model_copy`` ciblé).
+        """
+        with self._lock:
+            current = self._jobs.get(job_id)
+            if current is None:
+                raise JobError(f"job {job_id!r} introuvable.")
+            updated = current.model_copy(
+                update={
+                    "done": done,
+                    "total": total,
+                    "updated_at": utcnow().isoformat(),
+                }
+            )
+            self._jobs[job_id] = updated
+            self._history[job_id].append(updated)
+        return updated
+
+    def history_since(self, job_id: str, after_id: int) -> list[tuple[int, Job]]:
+        """Instantanés (``event_id``, ``Job``) du journal **après** ``after_id``.
+
+        ``event_id`` est la position 1-based dans le journal du job → c'est l'id
+        d'événement SSE (``Last-Event-ID``). Job inconnu → liste vide.
+        """
+        with self._lock:
+            history = list(self._history.get(job_id, ()))
+        return [(i, job) for i, job in enumerate(history, start=1) if i > after_id]
+
+
+__all__ = ["Job", "JobError", "JobState", "JobStore"]

cinoc/adapters/storage/publisher.py

@@ -0,0 +1,147 @@
+"""Publication d'un ``RunResult`` vers un dépôt distant (persistance).
+
+Le disque d'un HF Space est **éphémère** : un run calculé est perdu au
+redémarrage. Ce module **pousse** le ``RunResult`` JSON vers un dépôt GitHub
+(API *contents*) après chaque run réussi, ce qui le rend **durable** et alimente
+la vitrine publique.
+
+Sécurité & opt-in :
+
+- **Désactivé par défaut.** Sans dépôt **et** jeton (secrets), on renvoie un
+  ``NoopPublisher`` : aucune sortie réseau. La vitrine read-only (sans secret)
+  reste donc inerte.
+- Le **jeton vient d'un secret** (``CINOC_PUBLISH_TOKEN``) et n'est **jamais
+  journalisé** (il ne vit que dans l'en-tête ``Authorization``).
+- Aucune dépendance ajoutée : l'appel HTTP réel utilise ``urllib`` (stdlib),
+  importé et exécuté seulement à la publication (chemin *live*, hors CI).
+
+La construction de la requête (:func:`build_put_request`) est **pure** et
+testée ; seul l'envoi réseau est non couvert.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import NamedTuple, Protocol
+from urllib.parse import quote
+
+from pydantic import BaseModel, ConfigDict
+
+logger = logging.getLogger(__name__)
+
+_API = "https://api.github.com"
+
+
+class PublishTarget(BaseModel):
+    """Cible de publication (dépôt GitHub) — résolue depuis les secrets."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    repo: str  # "owner/name"
+    token: str
+    branch: str = "main"
+    subdir: str = "reports"
+
+
+class PutRequest(NamedTuple):
+    """Requête HTTP prête à envoyer (pure, testable sans réseau)."""
+
+    url: str
+    headers: dict[str, str]
+    body: bytes
+
+
+class ResultPublisher(Protocol):
+    """Publie un ``RunResult`` ; renvoie l'URL distante, ou ``None`` si inactif."""
+
+    def publish(self, name: str, run_result_path: Path) -> str | None: ...
+
+
+class NoopPublisher:
+    """Publisher inactif (aucun secret configuré) : ne fait rien."""
+
+    def publish(self, name: str, run_result_path: Path) -> str | None:
+        return None
+
+
+def build_put_request(target: PublishTarget, name: str, content: bytes) -> PutRequest:
+    """Construit la requête *PUT contents* GitHub pour ``<subdir>/<name>.json``."""
+    path = quote(f"{target.subdir}/{name}.json", safe="/")
+    body = json.dumps(
+        {
+            "message": f"cinoc: publie le rapport {name}",
+            "content": base64.b64encode(content).decode("ascii"),
+            "branch": target.branch,
+        }
+    ).encode("utf-8")
+    headers = {
+        "Authorization": f"Bearer {target.token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "Content-Type": "application/json",
+    }
+    return PutRequest(f"{_API}/repos/{target.repo}/contents/{path}", headers, body)
+
+
+class GitHubPublisher:
+    """Pousse le ``RunResult`` JSON vers un dépôt GitHub (API *contents*)."""
+
+    def __init__(self, target: PublishTarget) -> None:
+        self._target = target
+
+    def publish(self, name: str, run_result_path: Path) -> str | None:
+        content = run_result_path.read_bytes()
+        request = build_put_request(self._target, name, content)
+        return self._send(request)
+
+    def _send(self, request: PutRequest) -> str | None:  # pragma: no cover (réseau)
+        import urllib.request
+
+        req = urllib.request.Request(
+            request.url, data=request.body, headers=request.headers, method="PUT"
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+        content = payload.get("content") or {}
+        return content.get("html_url")
+
+
+def resolve_publish_target(
+    get_env: Callable[[str], str | None] = os.environ.get,
+) -> PublishTarget | None:
+    """Cible depuis les secrets, ou ``None`` si dépôt **ou** jeton manquant."""
+    repo = (get_env("CINOC_PUBLISH_REPO") or "").strip()
+    token = (get_env("CINOC_PUBLISH_TOKEN") or "").strip()
+    if not repo or "/" not in repo or not token:
+        return None
+    return PublishTarget(
+        repo=repo,
+        token=token,
+        branch=(get_env("CINOC_PUBLISH_BRANCH") or "main").strip(),
+        subdir=(get_env("CINOC_PUBLISH_DIR") or "reports").strip(),
+    )
+
+
+def resolve_publisher(
+    get_env: Callable[[str], str | None] = os.environ.get,
+) -> ResultPublisher:
+    """``GitHubPublisher`` si configuré (secrets), sinon ``NoopPublisher``."""
+    target = resolve_publish_target(get_env)
+    return GitHubPublisher(target) if target is not None else NoopPublisher()
+
+
+__all__ = [
+    "GitHubPublisher",
+    "NoopPublisher",
+    "PublishTarget",
+    "PutRequest",
+    "ResultPublisher",
+    "build_put_request",
+    "resolve_publish_target",
+    "resolve_publisher",
+]

cinoc/app/ANALYSE_COUCHE_6.md

@@ -0,0 +1,263 @@
+# ANALYSE_COUCHE_6.md — `app` (Picarones → Cinoc)
+
+> **Type** : session d'ANALYSE (guide de portage durable). **Aucun code Cinoc écrit.**
+> **Couche 6 = `app`** (orchestration applicative) dans
+> `domain(1) ← formats(2) ← evaluation(3) ← pipeline(4) ← adapters(5) ← app(6) ← reports(7) ← interfaces(8)`.
+> **Source figée** : `Picarones/picarones/app/` — **27 fichiers, 6 648 LOC**.
+> **Méthode** : 4 sous-agents d'exploration en parallèle (un par cluster), synthèse + recoupement
+> personnel des points décisifs dans le code (couplages inter-couches, sécurité, code mort, shim).
+> **Deux natures de savoir** (CLAUDE.md §9) : **Partie 1** = analyse source (durable) ;
+> **Partie 2** = réorg cible (périssable, « à confirmer à la tranche »). Verdicts **PROVISOIRES**.
+
+---
+
+## PARTIE 0 — Vérification anti-contradiction (obligatoire)
+
+Aucune conclusion ne contredit `CLAUDE.md` ni une couche mergée (domain ✅, formats ✅ ; evaluation = plan). Au contraire, l'analyse **confirme** trois décisions déjà actées ailleurs :
+
+| Décision actée (où) | Confirmé dans le code Picarones |
+|---|---|
+| `RunSpec`/`StepSpec` → `domain`, **séparés du loader YAML** (backlog domain ; couche 1 §9) | `run_spec.py` mêle effectivement type déclaratif + loader YAML + résolution dotted-path → split nécessaire |
+| `_benchmark_*` : double format `BenchmarkResult↔RunResult` supprimé + calcul rapatrié en `evaluation/runner` (CLAUDE.md §8.1 ; couche 3 §6,§11,§12-4) | `_benchmark_converter` calcule (compute_metrics, hooks, aggregate) ; `_benchmark_ner` calcule du NER ; les deux vivent à tort en `app/` |
+| Persistance / store → `adapters/storage` (couche 3 §8) | `benchmark_service.persist()` écrit du JSONL ; `job_runner` parle à `adapters.storage.JobStore` |
+| Registre + factory + **découverte entry-points en `app`** (CLAUDE.md §3) | `registry_service.bootstrap_default_registries()` + `resolve_adapter_class()` + `_resolve_entity_extractor()` = les **germes** (mais enregistrement codé en dur, **pas** d'entry-points) |
+
+**Nuance importante à ne pas violer** (CLAUDE.md §3) : le **seul** point d'extension tiers = les **briques de pipeline**. Métriques, projecteurs, importeurs restent **internes**. Or `registry_service` mélange aujourd'hui registre de **métriques** (interne) et résolution d'**adapters** (extensible) — à scinder en cible.
+
+---
+
+# PARTIE 1 — ANALYSE DE LA SOURCE PICARONES (durable)
+
+## 1.1 Inventaire par cluster (27 fichiers / 6 648 LOC)
+
+| Cluster | Fichiers | LOC | Rôle global vérifié |
+|---|---|---|---|
+| **A. Colonne vertébrale + API** | `__init__.py`(27), `results.py`(24), `services/__init__.py`(96), `schemas/__init__.py`(49), `schemas/run_spec.py`(559) | **755** | Headers de paquet, façades de re-export, DTO YAML + loader |
+| **B. Shim double-format `_benchmark_*`** | `_benchmark_adapter_resolver.py`(313), `_benchmark_conversions.py`(255), `_benchmark_converter.py`(236), `_benchmark_helpers.py`(266), `_benchmark_ner.py`(189), `_benchmark_persistence.py`(55), `benchmark_service.py`(407) | **1 721** | Conversion `RunResult`↔`BenchmarkResult` (legacy) + calcul de métriques mal placé + runner v2 |
+| **C. Orchestration / jobs / reprise** | `run_orchestrator.py`(500), `run_orchestrator_execution.py`(310), `run_orchestrator_helpers/{__init__(55),builders(241),factories(119),legacy(308),loaders(43)}`, `_orchestrator_partial.py`(256), `job_runner.py`(267), `partial_store.py`(360) | **2 459** | `RunOrchestrator`, exécution asynchrone, reprise partielle (fingerprint SHA-256) |
+| **D. Services transverses** | `path_security.py`(454), `corpus_service.py`(541), `registry_service.py`(327), `python_helpers.py`(277), `dependencies.py`(114) | **1 713** | Sécurité chemins (invariant §12), import ZIP corpus, bootstrap registres, bridge Python, capture deps |
+
+**5 fichiers > 400 LOC** (budget Cinoc) : `run_spec`(559), `corpus_service`(541), `run_orchestrator`(500), `path_security`(454), `benchmark_service`(407).
+
+## 1.2 Couplages inter-couches & consommateurs réels
+
+**`app/` importe** (orientation **respectée** : que des couches internes ; **jamais** `reports/` ni `interfaces/`) :
+
+| Vers | Symboles principaux | Cluster qui couple |
+|---|---|---|
+| `domain` | errors, artifacts (ArtifactType/Artifact), corpus (CorpusSpec), documents (DocumentRef/GroundTruthRef), pipeline_spec, evaluation_spec, run_manifest | tous |
+| `evaluation` | **benchmark_result, metric_hooks, metric_result, metrics.{text,ner,over_normalization,search,alto_structural}, views, projectors, registry, corpus** | **B** (calcul/shim) + **D** (registry_service) |
+| `pipeline` | runner.CorpusRunner, types.{PipelineResult,RunContext}, run_result.RunResult, llm_pipeline_builder | B, C |
+| `formats` | alto.parser.parse_alto, text.normalization.get_builtin_profile | C (loaders), legacy |
+| `adapters` | storage.JobStore, ocr.base.BaseOCRAdapter, corpus._fallback_log | B, C |
+
+**Qui consomme `app/`** (grep hors `tests/`) — seulement **2 frontières** (sain) :
+
+| Consommateur | Importe | Usage |
+|---|---|---|
+| `picarones/__init__.py` (API top-level) | `RunSpec`, `RunSpecLoadError`, `load_run_spec_from_yaml`, `RunOrchestrator`, `OrchestrationResult`, `prepare_preset_args`, `run_result_to_benchmark_result` | API publique + ⚠️ auto-déclenche `register_default_metrics()` à l'import (effet de bord) |
+| `interfaces/cli/_workflows.py` | `RunOrchestrator`, `prepare_preset_args`, `run_result_to_benchmark_result` | `prepare → execute_preset → convertir en BenchmarkResult` |
+| `interfaces/web/{benchmark_utils,_path_helpers,security_paths}.py` | `path_security.*`, `RunOrchestrator`, `prepare_preset_args`, `run_result_to_benchmark_result` | endpoints `/api/benchmark/start`, sandbox chemins |
+
+> **Pattern consommateur clé** : CLI et web font tous deux
+> `RunResult → run_result_to_benchmark_result() → BenchmarkResult` **parce que les renderers
+> (couche 7) consomment `BenchmarkResult`, pas `RunResult`**. C'est la racine du double format.
+> En Cinoc (format unique `RunResult`, reports le lit direct) **cette conversion disparaît entièrement**.
+
+## 1.3 La dette centrale : double format de sortie + god-module éclaté
+
+- Picarones produit **deux** formats : `RunResult` (couche 4, `pipeline/run_result.py`) **et** `BenchmarkResult` (couche 3, `evaluation/benchmark_result.py`). Le cluster B est presque entièrement le **pont** entre les deux.
+- Historique vérifié : un god-module **`benchmark_runner.py` (~1 700 LOC)** a été éclaté en `_benchmark_*` lors d'une « Phase 6 audit code-quality ». **`benchmark_runner.py` n'existe plus** — toutes les docstrings qui le citent (≈ 15 fichiers) sont **périmées**. Idem `report_service.py` (cité, inexistant).
+- Réconciliation du « ~1 570 LOC de shim » (CLAUDE.md §8.1) : shim strict ≈ `_benchmark_converter`(236) + `_benchmark_helpers`(266) + `_benchmark_persistence`(55) + ~½ `_benchmark_conversions`(255) + ~½ `_benchmark_adapter_resolver`(313) ≈ **950–1 000 LOC**, + le pont `run_orchestrator_helpers/legacy.py`(308) + le mort `partial_store.py`(360, legacy) → **~1 600 LOC de code legacy/shim/double-format** au total. ✅ cohérent.
+
+## 1.4 Code mort & doc morte confirmés (recoupés dans le code)
+
+| Élément | Preuve | Note |
+|---|---|---|
+| **`partial_store.py` : `_load_partial`, `_save_partial_line`, `_delete_partial`, `partial_path_for_engine`** | **0 consommateur hors-tests** ; servaient `run_benchmark_via_service` | ⚠️ ~½ du fichier est **mort** depuis la suppression de cette fonction |
+| **`run_benchmark_via_service`** | **aucun `def`** dans `picarones/` ; ne subsistent que docstrings/commentaires (dont l'avis de dépréciation de `__init__.py`) | fonction **supprimée** mais « fantôme » partout en prose |
+| Réfs à **`benchmark_runner.py`** (~15 fichiers) | `find` → inexistant | doc morte (god-module éclaté) |
+| Réfs à **`_benchmark_execution.py`** (factories/builders) | inexistant | pattern copié-commenté, pas importé |
+| Réf à **`report_service.py`** (`services/__init__` docstring) | inexistant | doc morte |
+| `run_orchestrator._build_pipelines`/`_load_corpus` (staticmethods l.472-494) | wrappers qui ne délèguent qu'aux fonctions globales | conservés **pour un test** uniquement |
+
+## 1.5 Bugs / fragilités notables (vérifiés)
+
+| Fichier | Problème | Gravité |
+|---|---|---|
+| `run_orchestrator.py` | `progress_callback`/`cancel_event` **acceptés mais ignorés** sur le chemin `bench.run()` (consommés seulement si `partial_dir`) — le caller croit son callback branché | moyen (silencieux) |
+| `run_orchestrator_execution.py` | appelle `BenchmarkService._evaluate_document_in_views()` (**privée**) pour recalculer les vues des docs repris | fragile (couplage privé) |
+| `factories.py` | `counter_state` (lock+dict) partagé par closure ; OK seulement si chaque run a une factory fraîche | risque multithread |
+| `partial_store.py` / `_orchestrator_partial.py` | fingerprint = path+size+mtime (pas de hash de contenu) → ne détecte pas une modif d'image à id constant | acceptable (documenté) |
+| `run_spec.py` | 9 champs « Phase B » (`char_exclude`, `normalization_profile`, `partial_dir`, `entity_extractor`, `profile`, `output_json`, `timeout_seconds_per_doc`, `max_in_flight`, `poll_interval_seconds`) **validés mais à demi-consommés** (migration B1→B2.x inachevée) | dette de migration |
+| `python_helpers.py` | `_dummy_pipeline_yaml()` = pipeline **bidon** juste pour satisfaire `RunSpec.pipelines (min_len=1)` en mode preset ; `adapter_kwargs` vide → `RunManifest` non reproductible sans le code Python | hack |
+| `picarones/__init__.py` | `register_default_metrics()` **auto-déclenché à l'import** | anti-pattern (interdit Cinoc §7) |
+
+## 1.6 Verdicts par fichier — **PROVISOIRES — à confirmer au build**
+
+> Légende : **GARDER** (concept à reporter ~tel quel) · **MODIFIER** (concept gardé, forme à revoir/dégonfler/splitter) · **DÉPLACER** (change de couche) · **SUPPRIMER**.
+> Le verdict décrit l'intention **pour le port Cinoc** ; les faits (rôle/conso) sont, eux, durables.
+
+### Cluster A — colonne vertébrale (755 LOC)
+| Fichier | LOC | Rôle réel vérifié | Verdict PROVISOIRE + raison |
+|---|---|---|---|
+| `__init__.py` | 27 | header paquet, `__all__` vide, sans effet de bord | **GARDER** — réécrire docstring, purger « 6 P0 du S1 » |
+| `results.py` | 24 | **shim** re-export `RunResult/RunDocumentResult/ReportRenderer` ← `pipeline/run_result` | **SUPPRIMER** — en Cinoc `RunResult` vit en `evaluation/result.py`, reports le lit direct (zéro shim §5.1) |
+| `services/__init__.py` | 96 | façade re-export (dont le converter `run_result_to_benchmark_result`) | **MODIFIER** — `__init__` mince §7 ; ne pas ré-exporter de shim |
+| `schemas/__init__.py` | 49 | façade re-export `run_spec` | **MODIFIER/fusionner** avec le split ci-dessous |
+| `schemas/run_spec.py` | 559 | `RunSpec`/`StepSpec`/`PipelineSpecYaml` (DTO YAML, 7 validators) + `load_run_spec_from_yaml` + `resolve_adapter_class` (importlib dotted-path) + `CANONICAL_VIEW_NAMES` | **DÉPLACER (split)** — type déclaratif `RunSpec`/`StepSpec` → **`domain`** (backlog confirmé) ; **loader YAML + `resolve_adapter_class`** → restent **`app`** ; **purger les 9 champs Phase B** (implémenter pour de vrai ou retirer) ; budget <400 |
+
+### Cluster B — shim double-format (1 721 LOC)
+| Fichier | LOC | Rôle réel vérifié | Verdict PROVISOIRE + raison |
+|---|---|---|---|
+| `benchmark_service.py` | 407 | **runner v2 propre** : orchestre `CorpusRunner`(4) + `view_executor`(3), assemble `RunResult`, persiste JSONL ; 0 import `_benchmark_*` | **MODIFIER (split)** — *pas « garder tel quel »* : assemblage `RunResult` + éval vues → **`evaluation/runner`** (3) ; persistance JSONL → **`adapters/storage`** (5) ; il ne reste en `app` qu'une coquille d'orchestration mince |
+| `_benchmark_converter.py` | 236 | cœur du shim `RunResult→BenchmarkResult` ; **calcule** CER/WER + hooks + agrégation | **SUPPRIMER** — double format éliminé ; le calcul est déjà en `evaluation/`, juste appelé d'ici |
+| `_benchmark_helpers.py` | 266 | extracteurs de texte + fingerprint pour le converter | **SUPPRIMER** — récupérer au plus 1-2 extracteurs `Artifact→texte` utiles → `pipeline`/`evaluation` |
+| `_benchmark_persistence.py` | 55 | `asdict(BenchmarkResult)→JSON` | **SUPPRIMER** — pas de `BenchmarkResult` ; persistance `RunResult` → `adapters/storage` |
+| `_benchmark_ner.py` | 189 | **calcule** NER (`compute_ner_metrics`) puis l'attache au `BenchmarkResult` | **DÉPLACER → `evaluation`** — le NER est une métrique (couche 3) |
+| `_benchmark_conversions.py` | 255 | `Corpus`(3, chargé) → `CorpusSpec`(1, déclaratif) + `Document→DocumentRef` ; `_safe_doc_id` (normalisation) | **MODIFIER** — pont qui dépend du modèle corpus Cinoc (à confirmer) ; **garder la normalisation `doc_id`** (utile, réutilisée par NER + corpus_service) |
+| `_benchmark_adapter_resolver.py` | 313 | `engine(BaseOCRAdapter / OCRLLMPipelineConfig) → PipelineSpec` + `build_adapter_resolver` (`name→StepExecutor`) | **MODIFIER** — le **resolver `name→executor` = germe du registre/factory** (garder, → registre `app`) ; la conversion `engine→spec` legacy disparaît (en Cinoc on déclare `PipelineSpec` direct) |
+
+### Cluster C — orchestration / jobs / reprise (2 459 LOC)
+| Fichier | LOC | Rôle réel vérifié | Verdict PROVISOIRE + raison |
+|---|---|---|---|
+| `run_orchestrator.py` | 500 | `RunOrchestrator.execute()` **et** `execute_preset()` → `OrchestrationResult` ; orchestre vraiment (corpus→registres→pipelines→service) | **MODIFIER** — concept d'orchestrateur `app` à **garder** ; dégonfler : fusionner `execute`/`execute_preset` (le 2ᵉ existe pour les engines en mémoire legacy), retirer la persistance `output_json` legacy + les callbacks « acceptés-ignorés » ; budget <400 |
+| `run_orchestrator_execution.py` | 310 | `execute_with_partial()` (reprise par pipeline) ; recalcule les vues via méthode **privée** du service | **MODIFIER/différer** — feature réelle mais couplage fragile ; à reconcevoir proprement **à la tranche reprise** (≠ MVP) |
+| `run_orchestrator_helpers/__init__.py` | 55 | re-export pour préserver l'API historique | **SUPPRIMER** — pas d'API historique à préserver (zéro shim) |
+| `…/builders.py` | 241 | `_load_corpus`/`_build_pipelines`/`_build_views`/`_build_benchmark_service` | **MODIFIER** — helpers d'assemblage à **garder** mais replier dans l'orchestrateur/registre |
+| `…/factories.py` | 119 | `_default_gt_factory`/`_default_inputs_factory`/`_make_context_factory` (closure progress, thread-safe) | **GARDER (concept)** — frontière « doc → artefacts » + `RunContext` par doc |
+| `…/legacy.py` | 308 | pont `BenchmarkResult` : `_PipelineEngineProxy`, `_resolve_entity_extractor` (dotted-path→callable NER), `_persist_legacy_benchmark_json` | **SUPPRIMER** — `BenchmarkResult` disparu ; **garder le concept** `_resolve_entity_extractor` = résolution de module tiers (→ entry-points `app`) |
+| `…/loaders.py` | 43 | `_filesystem_payload_loader` (disque→payload ALTO/texte) + `_kwargs_signature` | **GARDER (concept)** — chargement payload = I/O (`app` ou `adapters/storage`) |
+| `_orchestrator_partial.py` | 256 | reprise **par pipeline** (fingerprint, load/append/delete/filter) ; système **vivant** | **MODIFIER** — devenir le **seul** mécanisme de reprise (différer à sa tranche) |
+| `job_runner.py` | 267 | `JobRunner` thread daemon + `JobStore` ; annulation **best-effort non branchée** | **GARDER (concept)** pour `serve` — mais brancher une vraie annulation via `Deadline`/`RunControl` (couche 4, invariant §12) ; couple à `adapters/storage` |
+| `partial_store.py` | 360 | reprise **par engine** (legacy) ; **~½ mort** ; seuls `compute_run_fingerprint`+`_partial_path` vivants | **SUPPRIMER** — garder seulement le **concept fingerprint**, fusionné dans le mécanisme partial unique |
+
+### Cluster D — services transverses (1 713 LOC)
+| Fichier | LOC | Rôle réel vérifié | Verdict PROVISOIRE + raison |
+|---|---|---|---|
+| `path_security.py` | 454 | **invariant §12** : `validated_path` (resolve+`is_relative_to`), `WorkspaceManager` (sandbox/session, anti-symlink post-mkdir), `safe_report_name`, `validated_prompt_filename` | **GARDER** — porter **fidèlement** (→ package `security/` §8.5) ; dédupliquer `prompt_filename`/`report_name`, moderniser (`is_relative_to` natif 3.11), splitter <400 |
+| `corpus_service.py` | 541 | import ZIP sandboxé (anti zip-bomb/traversal/symlink) + appariement image/GT (`.gt.alto.xml`…) → `CorpusSpec` | **GARDER/DÉPLACER ?** — défenses à garder ; place à confirmer (`app` vs `adapters/corpus` qui porte déjà IIIF/Gallica/…) ; splitter <400 (extraction · catalogage · appariement) |
+| `registry_service.py` | 327 | `bootstrap_default_registries()` (boucle **codée en dur** sur métriques+projecteurs), `RegistriesBundle` ; **pas** d'entry-points | **MODIFIER (scinder)** — registre **métriques/projecteurs** = interne (couche 3) ; registre **modules de pipeline** + **découverte entry-points** (`cinoc.modules`) + `register()` = couche `app` (CLAUDE.md §3) |
+| `python_helpers.py` | 277 | `prepare_preset_args`/`PresetArgs` : bridge engines-en-mémoire→`RunSpec` ; `_dummy_pipeline_yaml` (hack) | **SUPPRIMER/reconcevoir** — existe pour les objets engine legacy ; en Cinoc on déclare `PipelineSpec` direct ; si une API Python est voulue, la rebâtir proprement |
+| `dependencies.py` | 114 | `capture_dependencies_lock` + `capture_system_binaries_lock` → `RunManifest` (reproductibilité §12) ; pur, stateless | **GARDER** — invariant repro ; étendre la table binaires au-delà de Tesseract (starter pack) ; place `app` vs `adapters` à confirmer |
+
+---
+
+# PARTIE 2 — RÉORGANISATION CIBLE Cinoc (périssable — à confirmer à la tranche)
+
+> ⚠️ Périssable. Le contact du code amont (evaluation/pipeline/adapters non encore mergés) corrigera ces formes.
+> **On ne construit PAS la couche `app` de haut en bas** : elle **apparaît par tranches verticales**, au fur et à mesure que `interfaces` en a besoin.
+
+## 2.1 Rôle d'`app` en Cinoc = **coquille mince** (les deux axes, CLAUDE.md §2)
+
+`app` orchestre, **ne calcule jamais** (« l'app appelle, ne calcule plus »). Elle :
+1. charge/valide une spec (`RunSpec`) et résout les modules par nom ;
+2. appelle `pipeline`(4) puis `evaluation`(3) ; l'assemblage de `RunResult` est fait **par `evaluation`** ;
+3. délègue la persistance à `adapters/storage`(5) et le rendu à `reports`(7, via callable injecté) ;
+4. applique les invariants transverses : **sécurité chemins** (§12), **reproductibilité** (deps/binaires → `RunManifest`), **annulation/timeout** (`Deadline`/`RunControl`).
+
+| Axe | Contenu `app` | Quand |
+|---|---|---|
+| **Enveloppe (plein-scope, maintenant)** | contrat d'orchestration ; **registre de modules + factory + découverte entry-points** (`cinoc.modules`) + `register()` ; `RunSpec` (en `domain`) + loader YAML (en `app`) ; sécurité chemins | conçu d'office |
+| **Surface (incrémentale, élaguée)** | quels workflows CLI (`run/report/compare/demo/serve`), quels importeurs branchés, le job-runner web, la reprise partielle | une tranche à la fois |
+
+## 2.2 Où va chaque concept Picarones (table de transfert)
+
+| Concept Picarones (app) | Destination Cinoc | Note |
+|---|---|---|
+| `RunSpec`/`StepSpec` (déclaratif) | **`domain`** (couche 1) | frère de `PipelineSpec`/`EvaluationSpec` ; backlog confirmé |
+| `load_run_spec_from_yaml` + `resolve_adapter_class` | **`app`** (loader/résolution = I/O + import dynamique) | « séparer du loader YAML » |
+| `RunOrchestrator` (mince) + builders/factories | **`app`** | un seul `execute`, pas de `execute_preset` |
+| assemblage `RunResult` + éval vues (`benchmark_service`) | **`evaluation/runner`** (couche 3) | RunResult = sortie d'évaluation |
+| persistance JSONL / store longitudinal | **`adapters/storage`** (couche 5) | tidy store (couche 3 §8) |
+| `_benchmark_ner` (calcul NER) | **`evaluation/metrics`** (couche 3) | NER = métrique |
+| `path_security` | **`app/security/`** (package, §8.5) | invariant §12, port fidèle |
+| `corpus_service` (import ZIP + appariement) | **`app`** ou **`adapters/corpus`** | à confirmer (adapters/corpus porte déjà les importeurs) |
+| `dependencies` (capture deps/binaires) | **`app`** (ou `adapters`) | reproductibilité |
+| `registry_service` (modules de pipeline) | **`app`** (+ entry-points) | seul point d'extension tiers |
+| `job_runner` | **`app`** | pour `serve` ; annulation réelle via `RunControl` |
+| `_orchestrator_partial` (reprise) | **`app`** (1 seul système) | à la tranche reprise |
+| `results.py`, `legacy.py`, `_benchmark_{converter,helpers,persistence}`, `partial_store` (mort), `python_helpers` (preset), `…helpers/__init__` re-export | **SUPPRIMÉ** | shim/double-format/legacy/mort |
+
+## 2.3 Esquisse d'arborescence cible (à confirmer)
+
+```
+cinoc/app/
+├── __init__.py            mince, zéro effet de bord (pas de register_* auto)
+├── orchestrator.py        RunOrchestrator unique → appelle pipeline + evaluation, assemble via eval
+├── spec_loader.py         load_run_spec_from_yaml + resolve dotted-path/entry-point (RunSpec vit en domain)
+├── modules/               registre + factory + découverte entry-points (cinoc.modules) + register()
+├── security/              validated_path, WorkspaceManager, safe_* (invariant §12)
+├── corpus_import.py       (?) import ZIP + appariement image/GT → CorpusSpec  [ou adapters/corpus]
+├── reproducibility.py     (?) capture deps + binaires → RunManifest            [ou adapters]
+└── jobs.py                JobRunner (serve) + annulation coopérative
+```
+*(Tous < 400 LOC ; `corpus_import`/`reproducibility` peut-être en `adapters` — décidé à la tranche.)*
+
+## 2.4 Apparition par tranches (≠ couche complète)
+
+| Tranche (cf. couche 3 §15) | Ce que `app` matérialise alors |
+|---|---|
+| **1. Squelette `demo`** (corpus pré-calculé → CER → RunResult → HTML → CLI) | orchestrateur **minimal** + registre de modules (1 module `precomputed`) + `RunSpec` minimal. Prouve que la coquille tient. |
+| **2. Épaississement texte** (`run`, profils, `compare`) | loader YAML complet, sécurité chemins, capture repro, plus de modules au registre |
+| **3. `serve`** | `JobRunner` + sandbox session + annulation |
+| **4. reprise partielle** | mécanisme partial unique (fingerprint), si justifié par un consommateur réel |
+
+---
+
+# PARTIE 3 — RISQUES DE TRANSFERT & DETTES (comment détecter / désamorcer)
+
+| # | Risque / dette | Détection | Désamorçage |
+|---|---|---|---|
+| **R1** | **Réintroduire le double format** en gardant un `BenchmarkResult` ou un converter « le temps de migrer » | test `no-legacy-imports` (interdire `benchmark_result`, `run_result_to_benchmark_result`) ; 1 seul type de sortie | tout consommateur lit `RunResult` direct ; **reports + web + compare migrés en bloc** (couche 3 §12-4 : ~30 conso) |
+| **R2** | **Calcul qui reste en `app`** (NER, hooks, agrégation) | `test_layer_dependencies` : `app` n'importe **pas** `evaluation/metrics*` pour calculer ; revue « app appelle, ne calcule pas » | NER/hooks/agrégation → `evaluation/runner` |
+| **R3** | **Mélanger registre interne (métriques) et registre extensible (modules)** → ouvrir une prise de trop | revue : entry-points `cinoc.modules` **uniquement** pour briques de pipeline (CLAUDE.md §3) | deux registres distincts ; métriques/projecteurs non pluggables |
+| **R4** | **Sécurité chemins affaiblie au portage** (path-traversal/symlink/zip-bomb) | tests obligatoires : `..`, chemin absolu, symlink, zip-bomb, octet nul **doivent échouer** ; `validated_path` partout | porter `path_security` + `corpus_service._extract_safely` **fidèlement**, tester d'abord |
+| **R5** | **Champs de spec à demi-câblés** (les 9 « Phase B ») recopiés tels quels | revue : tout champ `RunSpec` a un consommateur réel en CI (« pas de conso = supprimé ») | n'ajouter un champ que quand sa tranche le consomme |
+| **R6** | **Reproductibilité perdue** (mode preset Picarones perdait `adapter_kwargs`) | golden `RunManifest` byte-stable ; test : run reproductible **depuis le manifest seul** | pas de chemin « engines en mémoire » ; toute brique déclare `version` (§3) |
+| **R7** | **Annulation/timeout fantômes** (Picarones : callbacks acceptés-ignorés, cancel best-effort) | test : un `Deadline` dépassé **interrompt** ; annulation observable | brancher `Deadline`/`RunControl` (couche 4) dès `job_runner` |
+| **R8** | **Doc/commentaires périmés recopiés** (`benchmark_runner.py`, `report_service.py`, `run_benchmark_via_service`, sprints S/A/Phase) | grep anti-narration ; `test_no_legacy_imports` | « garder le pourquoi, jeter la datation » (couche 2 MIG-3) |
+| **R9** | **Code mort transféré** (½ `partial_store`, staticmethods test-only, `_dummy_pipeline_yaml`) | couverture CI ; « pas de conso = supprimé » | ne pas porter ; reprise = 1 seul système |
+| **R10** | **Budgets explosés** (5 fichiers >400) | `test_file_budgets` strict | splitter dès l'écriture (orchestrateur / sécurité / corpus) |
+| **R11** | **Effet de bord à l'import** (`register_default_metrics()` auto) | `test_no_side_effect_imports` | enregistrement **explicite, idempotent, testable** (§7) |
+
+---
+
+## Résumé pour la future session de CONSTRUCTION (3–5 points)
+
+1. **`app` = coquille d'orchestration mince qui NE CALCULE PAS.** Elle appelle `pipeline`(4) puis `evaluation`(3) ; l'assemblage de `RunResult` se fait **dans `evaluation/runner`**, la persistance dans **`adapters/storage`**. Le seul « gros » runner sain de Picarones (`benchmark_service.py`) se **scinde** entre ces couches — ce n'est pas un « garder tel quel ».
+2. **Tout le cluster `_benchmark_*` + `results.py` + `legacy.py` + ½ `partial_store` + `python_helpers`(preset) = SUPPRIMÉ** : c'est le double format `BenchmarkResult↔RunResult` (+ un god-module éclaté, + une fonction `run_benchmark_via_service` déjà morte qui laisse du code orphelin). En Cinoc, `RunResult` est unique et **les reports le lisent direct** → la conversion n'existe plus. Le **NER** part en `evaluation` (c'est une métrique).
+3. **Deux germes d'enveloppe à concevoir plein-scope, sans les remplir** : (a) `RunSpec`/`StepSpec` **en `domain`** + loader YAML/résolution **en `app`** (split « séparer du loader ») ; (b) **registre de modules de pipeline + factory + découverte entry-points** (`cinoc.modules`) — **uniquement** pour les briques de pipeline, jamais les métriques/importeurs.
+4. **Invariants à porter fidèlement et à tester EN PREMIER** : sécurité chemins (`validated_path`/`WorkspaceManager`/anti zip-bomb-traversal-symlink, §12), reproductibilité (`dependencies` → `RunManifest`), annulation coopérative (`Deadline`/`RunControl` — Picarones ne la branche pas vraiment, à corriger).
+5. **Ne pas bâtir `app` en bloc** : elle naît par tranches. Tranche 1 (`demo`) = orchestrateur minimal + registre (1 module `precomputed`) + `RunSpec` minimal — juste assez pour prouver que la coquille tient. Budgets <400, zéro shim, zéro effet de bord à l'import, zéro champ de spec sans consommateur.
+
+## DoD vivante (couche 6) — **autorité de détail** ; le `MIGRATION_PLAN.md` indexe
+
+> **T8 (D-066)** : l'orchestrateur collecte un `DocumentUsage` par (pipeline × document) réussi et le passe à `evaluate_run` → `RunResult.usage` trié (déterministe). Preuve : `tests/app/test_orchestrator.py::test_run_result_carries_sorted_usage`.
+
+> **T14 (D-072)** : builders `kraken`/`mistral_ocr` + sondes `engine_statuses` (SDK/clé) + `_OCR_ENGINES` étendu — matrice CLI/web alignée. Preuves : `tests/app/test_module_registry.py` · `test_engines.py`.
+
+> **T15 (D-073)** : `+ resume.py` (`ResumeStore` + `unit_key`) — cache d'exécution par empreinte, branché à l'orchestrateur (`resume_store=`) et à la CLI (`run --resume-dir`) ; évaluation toujours recalculée. Preuves : `tests/app/test_resume.py`.
+
+> Tri-état : `[x]` fait **+ preuve** · `[ ]` à faire · `[~]` différé/réserve + raison.
+> Maj dans le **même commit** que le code. **Statut : ✅ T2** — orchestrateur (+ **workspace** par run) + registre/factory + `RunSpec` + **loader YAML** + **sécurité chemins** verts. **+ T6 découverte entry-points** : `discover_plugins` (groupe `cinoc.modules`, builder tiers enregistré comme le socle ; **fail-closed mode public** ; câblé CLI + web). **Prouvé de bout en bout** : loader injecté + **vrai `EntryPoint`** (résolution dotted-path) + **paquet réellement pip-installé auto-découvert** (`importlib.metadata`, test `slow` isolé). — *preuves : `tests/app/test_plugin_discovery.py`, `tests/app/test_plugin_install.py` + plugins de réf. `tests/fixtures/sample_segmenter_plugin.py` & `…/sample_plugin_pkg/`*. **+ T7 `history.py`** : trait d'union `RunResult`→`HistoryStore` — `records_from_run` aplatit les agrégats par pipeline/vue en `HistoryRecord` (métriques `None` écartées), `record_run` persiste. La connaissance de la forme `RunResult` vit **ici** (couche 6), pas dans le store (couche 5 = persistance pure). — *preuves : `tests/app/test_history.py`*. **Câblage auto livré (S6, D-046)** : `JobRunner` prend un `history_store` optionnel et appelle `record_run` après chaque run terminé (best-effort, comme `publish`) → **différé D-042 levé** ; `create_app` instancie un `HistoryStore` sous `catalog_dir`. — *preuves : `tests/app/test_history_recording.py`*. Différé : reprise partielle, deps-lock (hors CI).
+
+**Enveloppe :**
+- [x] `app` = **coquille mince qui NE CALCULE PAS** (appelle pipeline puis `evaluate_run` ; l'assemblage métrique vit en `evaluation`). — *preuve : `test_app_imports_are_allowed` ; l'orchestrateur délègue, n'importe aucune `evaluation.metrics*`*
+- [x] **Registre + factory** (`name→Module` via builder enregistré, convention `<kind>:<label>`) — socle en dur, **seul** point d'extension. — *preuve : `test_module_registry` (build `precomputed` ; kind inconnu ; kwargs incohérents)*
+- [ ] Découverte **entry-points `cinoc.modules`** + `register()` tiers. — *T6*
+- [x] `RunSpec` → `domain` (compose `PipelineSpec` **directement**, sans `StepSpec` — D-010) ; orchestrateur assemble `RunManifest` (`adapter_kwargs` capturés). — *preuve : `test_run_spec` + `test_orchestrator`*
+- [x] **loader YAML** (`RunSpec.model_validate`, `extra="forbid"`) + **sécurité chemins** (`validated_path` : rejet `..`/absolu-hors-base/octet-nul/symlink, §12 ; **GT `must_exist=True`** → erreur typée au chargement, pas d'`OSError` opaque en run) — **pas** de `resolve_adapter_class` (le registre résout `name→Module`, D-010). — *preuve : `test_loader` (+ GT manquante rejetée) + `test_security`*
+- [x] **Isolation des workspaces par pipeline** (sous-dossier dédié) : deux pipelines partageant un `adapter_name` **écrivain** (ex. `openai:gpt`) n'écrasent plus mutuellement leur sortie → zéro contamination inter-pipelines. — *preuve : `test_orchestrator::test_pipelines_sharing_a_writer_do_not_contaminate`* — **corrigé à l'audit T3.**
+- [x] **`RunManifest.module_versions`** : version déclarée de chaque module exécuté capturée (R-2). — *preuve : `test_orchestrator::test_manifest_captures_module_versions`.* `[~]` deps/binaires lock (`dependencies_lock`/`system_binaries_lock`, dont version **binaire** tesseract) : capture live, **différée** (hors CI).
+
+**Garde-fous :**
+- [x] `no_side_effect_imports` (**pas de `register_default_*()` auto** ni singleton module-level ; `register_default_modules`/`metrics` explicites) · `file_budgets` · `layer_dependencies`. — *preuve : suite archi verte*
+
+**Validation par tranche :** `MIGRATION_PLAN.md` §3 — orchestrateur minimal + registre 1 module + `RunSpec` minimal (T1) · sécurité chemins testée d'abord + repro (T2) · entry-points + plugin (T6).
+
+- [~] **Supprimé** : tout `_benchmark_*` (double format) · `results.py`/`legacy.py` (shim) · ½ `partial_store` mort · `python_helpers` (preset). **Différé** : reprise partielle (1 seul mécanisme, à sa tranche).
+
+---
+
+*(Tous les verdicts ci-dessus sont **PROVISOIRES — à confirmer au build** ; le contact du code amont non encore mergé prévaut.)*

cinoc/app/__init__.py

@@ -0,0 +1,34 @@
+"""Couche 6 — ``app`` : orchestration + registre de modules (coquille mince).
+
+``app`` câble les couches internes et **ne calcule pas** : il appelle pipeline
+puis evaluation. ``__init__`` mince, sans effet de bord.
+"""
+
+from __future__ import annotations
+
+from cinoc.app.loader import RunSpecError, load_run_spec
+from cinoc.app.modules.registry import (
+    ModuleRegistry,
+    ModuleResolutionError,
+    register_default_modules,
+)
+from cinoc.app.orchestrator import OrchestrationError, run
+from cinoc.app.results import RunResultError, dump_run_result, load_run_result
+from cinoc.app.security import PathSecurityError, validated_path
+from cinoc.app.versioning import resolve_code_version
+
+__all__ = [
+    "ModuleRegistry",
+    "ModuleResolutionError",
+    "OrchestrationError",
+    "PathSecurityError",
+    "RunResultError",
+    "RunSpecError",
+    "dump_run_result",
+    "load_run_result",
+    "load_run_spec",
+    "register_default_modules",
+    "resolve_code_version",
+    "run",
+    "validated_path",
+]

cinoc/app/alto_store.py

@@ -0,0 +1,72 @@
+"""Persistance des exports **ALTO XML** d'un run (couche 6).
+
+Un run avec ``Competitor.alto`` produit un artefact ``ALTO_XML`` par document que
+le ``RunResult`` (métriques scalaires) **ne porte pas** et que le workspace
+temporaire du run **détruit** à la fin. Ce store le **persiste**, indexé par
+``run_id``, pour qu'un endpoint web le restitue en archive ZIP — la forme
+ré-importable dans un outil de relecture (eScriptorium, Transkribus).
+
+Un seul chemin : le sink du ``JobRunner`` y dépose les ALTO produits ; le routeur
+des rapports les rezippe à la demande. Pas de second format, pas de cache pré-écrit.
+"""
+
+from __future__ import annotations
+
+import io
+import threading
+import zipfile
+from pathlib import Path
+
+from cinoc.app.security import PathSecurityError, safe_stem, validated_path
+
+
+class AltoStore:
+    """Registre disque des exports ALTO (``base_dir/<run>/<entrée>.alto.xml``)."""
+
+    def __init__(self, base_dir: Path) -> None:
+        self._base = base_dir
+        self._lock = threading.Lock()
+
+    def save(
+        self, run_id: str, document_id: str, pipeline_name: str, xml: bytes
+    ) -> None:
+        """Persiste un ALTO XML pour ``(run_id, pipeline_name, document_id)``."""
+        with self._lock:
+            folder = self._base / safe_stem(run_id)
+            folder.mkdir(parents=True, exist_ok=True)
+            stem = safe_stem(f"{pipeline_name}::{document_id}")
+            (folder / f"{stem}.alto.xml").write_bytes(xml)
+
+    def has(self, run_id: str) -> bool:
+        """``True`` si au moins un ALTO est persisté pour ce run."""
+        folder = self._folder(run_id)
+        if folder is None or not folder.is_dir():
+            return False
+        return any(folder.glob("*.alto.xml"))
+
+    def archive(self, run_id: str) -> bytes | None:
+        """Archive ZIP **déterministe** (entrées triées) des ALTO du run, ou ``None``.
+
+        ``None`` si aucun ALTO n'est persisté (run sans export) → le routeur répond
+        ``404``. Les octets XML ne sont jamais altérés (ré-import fidèle)."""
+        folder = self._folder(run_id)
+        if folder is None or not folder.is_dir():
+            return None
+        files = sorted(folder.glob("*.alto.xml"))
+        if not files:
+            return None
+        buffer = io.BytesIO()
+        with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+            for path in files:
+                archive.writestr(path.name, path.read_bytes())
+        return buffer.getvalue()
+
+    def _folder(self, run_id: str) -> Path | None:
+        """Dossier du run, **chemin validé** (anti path-traversal sur le run_id URL)."""
+        try:
+            return validated_path(safe_stem(run_id), self._base)
+        except PathSecurityError:
+            return None
+
+
+__all__ = ["AltoStore"]

cinoc/app/corpus_import.py

@@ -0,0 +1,449 @@
+"""Matérialisation d'un corpus IIIF en ``CorpusSpec`` (couche 6).
+
+Sépare **localiser** (l'adapter ``IIIFImporter`` parle IIIF) de **matérialiser**
+(ici : télécharger les images sous ``dest`` validé, fabriquer le ``CorpusSpec``).
+Sortie **unique** : un ``CorpusSpec`` (jamais un dict-manifeste), prêt pour un run.
+
+Images seules → ``DocumentRef`` sans vérité-terrain : le corpus est OCR-able mais
+non scoré tant qu'une GT n'est pas appariée (cf. ``adapters/corpus/iiif.py``).
+
+``importer`` et ``download`` sont **injectables** → le chemin de matérialisation
+se teste sans réseau ; le test ``live`` couvre le vrai fetch IIIF.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Protocol
+from urllib.parse import urlsplit
+
+from cinoc.adapters.corpus import _http
+from cinoc.adapters.corpus.escriptorium import DEFAULT_LAYER, EScriptoriumImporter
+from cinoc.adapters.corpus.gallica import GALLICA_BASE, GallicaImporter, vue_number
+from cinoc.adapters.corpus.huggingface import (
+    HFPage,
+    snapshot_curated_layout,
+    stream_pages,
+)
+from cinoc.adapters.corpus.iiif import IIIFImage, IIIFImporter
+from cinoc.app.security import PathSecurityError, validated_path
+from cinoc.domain.artifacts import ArtifactType
+from cinoc.domain.corpus import CorpusSpec
+from cinoc.domain.documents import DocumentRef, GroundTruthRef
+from cinoc.domain.errors import CinocError
+
+logger = logging.getLogger(__name__)
+
+#: Extensions d'image reconnues pour nommer le fichier téléchargé.
+_IMAGE_EXT = frozenset({".png", ".jpg", ".jpeg", ".tif", ".tiff", ".jp2"})
+_DEFAULT_EXT = ".jpg"
+
+ImageFetcher = Callable[[str], "tuple[IIIFImage, ...]"]
+OcrFetcher = Callable[[int], str]
+#: Streame les pages d'un dataset HF conforme. Injectable (test sans ``datasets``).
+HFStreamer = Callable[..., "Iterator[HFPage]"]
+
+
+class Downloader(Protocol):
+    """Télécharge ``url`` vers ``dest`` ; ``headers`` optionnels (auth même-hôte)."""
+
+    def __call__(
+        self, url: str, dest: Path, *, headers: dict[str, str] | None = None
+    ) -> None: ...
+
+
+class CorpusImportError(CinocError):
+    """L'import d'un corpus distant n'a produit aucune page exploitable."""
+
+
+def _image_ext(image_url: str) -> str:
+    suffix = Path(urlsplit(image_url).path).suffix.lower()
+    return suffix if suffix in _IMAGE_EXT else _DEFAULT_EXT
+
+
+def _download_image(
+    fetch_bytes: Downloader,
+    image_url: str,
+    doc_id: str,
+    dest_dir: Path,
+    *,
+    headers: dict[str, str] | None = None,
+) -> str:
+    """Télécharge une image sous ``dest_dir`` (chemin validé) ; renvoie l'URI local.
+
+    ``headers`` (ex. ``Authorization``) n'est fourni que pour un média **même-hôte**
+    (cf. ``import_escriptorium_corpus``) ; les imports publics (IIIF/Gallica)
+    passent ``None``.
+    """
+    target = validated_path(f"{doc_id}{_image_ext(image_url)}", dest_dir)
+    fetch_bytes(image_url, target, headers=headers)
+    return str(target)
+
+
+def import_iiif_corpus(
+    manifest_url: str,
+    dest: str | Path,
+    *,
+    name: str,
+    limit: int | None = None,
+    importer: IIIFImporter | None = None,
+    download: Downloader | None = None,
+) -> CorpusSpec:
+    """Importe un manifeste IIIF → images téléchargées sous ``dest`` → ``CorpusSpec``.
+
+    ``limit`` borne le nombre de pages (les premières). ``dest`` est créé au besoin ;
+    chaque fichier passe par ``validated_path`` (anti-traversal).
+    """
+    fetch_images: ImageFetcher = (importer or IIIFImporter()).fetch_images
+    fetch_bytes: Downloader = download or _http.download
+    dest_dir = Path(dest)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    images = fetch_images(manifest_url)
+    if limit is not None:
+        images = images[:limit]
+    if not images:
+        raise CorpusImportError(
+            f"aucune image exploitable dans le manifeste {manifest_url!r}."
+        )
+
+    documents: list[DocumentRef] = []
+    for index, image in enumerate(images, start=1):
+        doc_id = f"page_{index:04d}"
+        image_uri = _download_image(fetch_bytes, image.image_url, doc_id, dest_dir)
+        documents.append(
+            DocumentRef(id=doc_id, image_uri=image_uri, ground_truths=())
+        )
+
+    return CorpusSpec(
+        name=name,
+        documents=tuple(documents),
+        metadata={"source": "iiif", "manifest_url": manifest_url},
+    )
+
+
+def import_escriptorium_corpus(
+    base_url: str,
+    token: str,
+    doc_pk: int,
+    dest: str | Path,
+    *,
+    name: str | None = None,
+    layer: str = DEFAULT_LAYER,
+    limit: int | None = None,
+    importer: EScriptoriumImporter | None = None,
+    download: Downloader | None = None,
+) -> CorpusSpec:
+    """Importe un document eScriptorium → corpus **scorable** sous ``dest``.
+
+    Pour chaque page : télécharge l'image et écrit le texte de la couche ``layer``
+    comme vérité-terrain (``.gt.txt`` → ``GroundTruthRef`` ``RAW_TEXT``). Une page
+    sans texte reste image-seule ; une page sans image est ignorée (avertie).
+
+    Média gardé : le jeton ``Authorization`` n'est joint au download que si le
+    média est **sur le même hôte** que ``base_url`` (règle host de D-050). Un média
+    servi par un autre hôte (CDN tiers) est téléchargé **sans jeton** — on ne livre
+    pas le credential à un tiers (un média gardé y répondra 401, sans fuite).
+    """
+    imp = importer or EScriptoriumImporter(base_url, token, layer=layer)
+    fetch_bytes: Downloader = download or _http.download
+    base_host = urlsplit(base_url).hostname
+    media_auth = {"Authorization": f"Token {token}"}
+    dest_dir = Path(dest)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    pages = imp.fetch_pages(doc_pk)
+    if limit is not None:
+        pages = pages[:limit]
+
+    documents: list[DocumentRef] = []
+    for page in pages:
+        if not page.image_url:
+            logger.warning("[escriptorium] part %s sans image — ignorée.", page.pk)
+            continue
+        doc_id = f"part_{page.pk:05d}"
+        same_host = urlsplit(page.image_url).hostname == base_host
+        headers = media_auth if same_host else None
+        if not same_host:
+            logger.warning(
+                "[escriptorium] média part %s hors hôte (%s) — téléchargé sans "
+                "jeton (pas de fuite vers un tiers).",
+                page.pk,
+                urlsplit(page.image_url).hostname,
+            )
+        image_uri = _download_image(
+            fetch_bytes, page.image_url, doc_id, dest_dir, headers=headers
+        )
+        ground_truths: tuple[GroundTruthRef, ...] = ()
+        if page.gt_text.strip():
+            gt_target = validated_path(f"{doc_id}.gt.txt", dest_dir)
+            gt_target.write_text(page.gt_text, encoding="utf-8")
+            ground_truths = (
+                GroundTruthRef(type=ArtifactType.RAW_TEXT, uri=str(gt_target)),
+            )
+        documents.append(
+            DocumentRef(id=doc_id, image_uri=image_uri, ground_truths=ground_truths)
+        )
+
+    if not documents:
+        raise CorpusImportError(
+            f"document eScriptorium {doc_pk} : aucune page avec image exploitable."
+        )
+    return CorpusSpec(
+        name=name or f"escriptorium-{doc_pk}",
+        documents=tuple(documents),
+        metadata={
+            "source": "escriptorium",
+            "base_url": base_url.rstrip("/"),
+            "doc_pk": str(doc_pk),
+            "layer": layer,
+        },
+    )
+
+
+def import_gallica_corpus(
+    ark: str,
+    dest: str | Path,
+    *,
+    base_url: str = GALLICA_BASE,
+    name: str | None = None,
+    limit: int | None = None,
+    include_ocr: bool = True,
+    image_importer: IIIFImporter | None = None,
+    download: Downloader | None = None,
+    fetch_ocr: OcrFetcher | None = None,
+) -> CorpusSpec:
+    """Importe un document Gallica (ARK) → images (via IIIF) + OCR Gallica optionnel.
+
+    Les images viennent du **manifeste IIIF** Gallica ; si ``include_ocr``, l'OCR
+    brut de chaque vue (``texteBrut``) est écrit comme **référence étiquetée** :
+    type domaine ``REFERENCE_TEXT`` (≠ vérité-terrain manuelle) + métadonnée
+    ``gt_source=gallica_ocr``. Une vue d'évaluation par défaut **ne le score pas**
+    comme une GT ; seule une vue *référence* dédiée (opt-in) le compare.
+
+    Le numéro de vue est **lu dans l'URL de l'image** (``/f{n}/``), pas déduit de la
+    position : un canvas sans image sauté par le parseur IIIF décalerait sinon tout
+    l'OCR (le bug ``selected_indices+1`` réintroduit). Position 1-based = repli si
+    l'URL ne porte pas de ``/f{n}/``.
+    """
+    gallica = GallicaImporter(ark, base_url=base_url)
+    fetch_bytes: Downloader = download or _http.download
+    ocr_of: OcrFetcher = fetch_ocr or gallica.fetch_ocr_text
+    dest_dir = Path(dest)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    images = (image_importer or IIIFImporter()).fetch_images(gallica.manifest_url)
+    if limit is not None:
+        images = images[:limit]
+    if not images:
+        raise CorpusImportError(f"aucune image pour l'ARK Gallica {gallica.ark!r}.")
+
+    documents: list[DocumentRef] = []
+    has_ocr_gt = False
+    for position, image in enumerate(images, start=1):
+        vue = vue_number(image.image_url) or position
+        doc_id = f"f{vue:04d}"
+        image_uri = _download_image(fetch_bytes, image.image_url, doc_id, dest_dir)
+        ground_truths: tuple[GroundTruthRef, ...] = ()
+        if include_ocr:
+            text = ocr_of(vue)
+            if text.strip():
+                gt_target = validated_path(f"{doc_id}.gallica_ocr.txt", dest_dir)
+                gt_target.write_text(text, encoding="utf-8")
+                ground_truths = (
+                    GroundTruthRef(
+                        type=ArtifactType.REFERENCE_TEXT, uri=str(gt_target)
+                    ),
+                )
+                has_ocr_gt = True
+        documents.append(
+            DocumentRef(id=doc_id, image_uri=image_uri, ground_truths=ground_truths)
+        )
+
+    metadata = {
+        "source": "gallica",
+        "ark": gallica.ark,
+        "manifest_url": gallica.manifest_url,
+    }
+    if has_ocr_gt:
+        metadata["gt_source"] = "gallica_ocr"
+    return CorpusSpec(
+        name=name or f"gallica-{gallica.ark.split('/')[-1]}",
+        documents=tuple(documents),
+        metadata=metadata,
+    )
+
+
+def import_hf_corpus(
+    dataset_id: str,
+    dest: str | Path,
+    *,
+    name: str | None = None,
+    split: str = "train",
+    limit: int | None = None,
+    stream: HFStreamer | None = None,
+) -> CorpusSpec:
+    """Importe un dataset **HuggingFace** (convention Cinoc) → ``CorpusSpec`` scorable.
+
+    Streamé **page-par-page** (jamais de snapshot complet) : chaque page écrit son
+    image et son texte de vérité-terrain. La GT d'un dataset Cinoc curé est une
+    **vraie GT** (``GroundTruthRef`` ``RAW_TEXT``), pas une référence OCR. ``limit``
+    borne le nombre de pages. ``stream`` est injectable (test sans ``datasets``).
+    """
+    pages = (stream or stream_pages)(dataset_id, split=split, limit=limit)
+    dest_dir = Path(dest)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    documents: list[DocumentRef] = []
+    for index, page in enumerate(pages, start=1):
+        doc_id = f"page_{index:04d}"
+        target = validated_path(f"{doc_id}{page.image_ext}", dest_dir)
+        target.write_bytes(page.image_bytes)
+        ground_truths: tuple[GroundTruthRef, ...] = ()
+        if page.gt_text.strip():
+            gt_target = validated_path(f"{doc_id}.gt.txt", dest_dir)
+            gt_target.write_text(page.gt_text, encoding="utf-8")
+            ground_truths = (
+                GroundTruthRef(type=ArtifactType.RAW_TEXT, uri=str(gt_target)),
+            )
+        documents.append(
+            DocumentRef(id=doc_id, image_uri=str(target), ground_truths=ground_truths)
+        )
+
+    if not documents:
+        raise CorpusImportError(
+            f"dataset HuggingFace {dataset_id!r} (split {split!r}) : aucune page."
+        )
+    return CorpusSpec(
+        name=name or f"hf-{dataset_id.replace('/', '-')}",
+        documents=tuple(documents),
+        metadata={"source": "huggingface", "dataset_id": dataset_id, "split": split},
+    )
+
+
+def _curated_entry(entry: object, root: Path, base_url: str | None) -> DocumentRef:
+    """Une entrée ``corpus.json`` → ``DocumentRef`` (image = référence, GT = vraie).
+
+    Image : ``base_url`` + chemin relatif si fourni — le chemin est un dérivé
+    **IIIF statique** du layout (``iiif/<id>/full/…``), et ``base_url`` la racine
+    ``resolve`` HF épinglée (ou un serveur IIIF d'institution) ; sinon chemin
+    local du dérivé medium. La référence est matérialisée **au run** par
+    l'orchestrateur. GT : ``RAW_TEXT`` sur le ``.gt.txt`` local. Chemins relatifs
+    durcis (``validated_path`` rejette ``..``) — un dataset tiers hostile ne peut
+    pas pointer hors du layout."""
+    if not isinstance(entry, dict):
+        raise CorpusImportError(f"entrée corpus.json invalide : {entry!r}")
+    try:
+        doc_id, image_rel, gt_rel = entry["id"], entry["image"], entry["ground_truth"]
+    except (KeyError, TypeError) as exc:
+        raise CorpusImportError(f"entrée corpus.json incomplète : {entry!r}") from exc
+    try:
+        gt_path = validated_path(str(gt_rel), root)  # rejette le path-traversal
+        image_local = validated_path(str(image_rel), root)  # idem + valide la forme
+    except PathSecurityError as exc:
+        raise CorpusImportError(f"chemin non sûr dans corpus.json : {exc}") from exc
+    image_uri = (
+        f"{base_url.rstrip('/')}/{str(image_rel).lstrip('/')}"
+        if base_url
+        else str(image_local)
+    )
+    stratum = entry.get("stratum")
+    return DocumentRef(
+        id=str(doc_id),
+        image_uri=image_uri,
+        ground_truths=(GroundTruthRef(type=ArtifactType.RAW_TEXT, uri=str(gt_path)),),
+        metadata={"stratum": str(stratum)} if stratum else {},
+    )
+
+
+def import_curated_corpus(
+    layout_dir: str | Path,
+    *,
+    base_url: str | None = None,
+    revision: str | None = None,
+    name: str | None = None,
+) -> CorpusSpec:
+    """Importe un **layout dataset canonique Cinoc** → ``CorpusSpec`` scorable.
+
+    Variante **par référence** de ``import_hf_corpus`` (même sortie, pas un format
+    parallèle) : produit par ``app.dataset_standardize`` ou snapshot d'un dataset
+    HF publié. L'image est une **référence** (``base_url`` + dérivé IIIF statique
+    du layout — en pratique une URL ``resolve`` HF épinglée ; sinon chemin local
+    du dérivé medium), matérialisée au run par l'orchestrateur ; la GT est une
+    **vraie GT** ``RAW_TEXT``. ``base_url`` + ``revision`` (SHA HF) →
+    reproductibilité pinnée (``RunManifest``).
+    """
+    root = Path(layout_dir)
+    manifest_path = root / "corpus.json"
+    if not manifest_path.is_file():
+        raise CorpusImportError(f"layout cur�� sans corpus.json : {root}")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise CorpusImportError(f"corpus.json illisible ({root}) : {exc}") from exc
+    entries = manifest.get("documents") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list) or not entries:
+        raise CorpusImportError(f"corpus.json sans documents : {root}")
+
+    documents = tuple(_curated_entry(e, root, base_url) for e in entries)
+    corpus_meta: dict[str, str] = {"source": "curated"}
+    if revision:
+        corpus_meta["revision"] = revision
+    licenses = manifest.get("license")
+    if isinstance(licenses, dict):
+        for key, value in licenses.items():
+            corpus_meta[f"license_{key}"] = str(value)
+    return CorpusSpec(
+        name=name or str(manifest.get("name") or root.name),
+        documents=documents,
+        metadata=corpus_meta,
+    )
+
+
+#: Télécharge un layout curé HF → dossier local (au moins ``corpus.json`` + GT).
+#: Injectable → l'import distant se teste sans réseau ni ``huggingface_hub``.
+CuratedFetcher = Callable[[str, Path, "str | None"], Path]
+
+
+def _hf_resolve_base(repo_id: str, revision: str | None) -> str:
+    """Racine ``resolve`` d'un dataset HF, épinglée à ``revision`` (sinon ``main``)."""
+    return f"https://huggingface.co/datasets/{repo_id}/resolve/{revision or 'main'}"
+
+
+def import_curated_hf_corpus(
+    repo_id: str,
+    dest: str | Path,
+    *,
+    revision: str | None = None,
+    name: str | None = None,
+    fetch: CuratedFetcher | None = None,
+) -> CorpusSpec:
+    """Importe un **dataset curé Cinoc publié sur HF** → ``CorpusSpec`` scorable.
+
+    Variante **distante** de ``import_curated_corpus`` : télécharge **uniquement**
+    le manifeste + la GT (les images restent des références IIIF HF, épinglées à
+    ``revision``), puis délègue à l'importeur local. Un corpus de référence publié
+    devient ainsi sélectionnable au Banc d'essai en quelques secondes, sans
+    rapatrier les images. ``fetch`` est injectable (test sans réseau).
+    """
+    layout_dir = (fetch or snapshot_curated_layout)(repo_id, Path(dest), revision)
+    return import_curated_corpus(
+        layout_dir,
+        base_url=_hf_resolve_base(repo_id, revision),
+        revision=revision,
+        name=name,
+    )
+
+
+__all__ = [
+    "CorpusImportError",
+    "import_curated_corpus",
+    "import_curated_hf_corpus",
+    "import_escriptorium_corpus",
+    "import_gallica_corpus",
+    "import_hf_corpus",
+    "import_iiif_corpus",
+]