Merge pull request #57 from maribakulj/claude/repo-analysis-cukvm

Migration legacy → rewrite : 165+ shims supprimés (Lots A à J + fix templates)

.github/workflows/ci.yml

@@ -5,7 +5,7 @@
 #   - Linux, macOS, Windows
 #   - Couverture exigée >= 85 % (--cov-fail-under, plancher 2 pts sous baseline 87 %)
 #   - Timeout pytest 5 min par test individuel (pytest-timeout, mode thread)
-#   - Type-check mypy (strict sur picarones/core/, lax ailleurs — durci en A11)
+#   - Type-check mypy (strict sur picarones/domain/, lax ailleurs — durci en A11)
 #   - Scanners sécurité : bandit (statique) + pip-audit (CVE deps) + trivy (image)
 #   - Build de la distribution Python
 #   - Vérification de l'exécutable demo
@@ -92,22 +92,55 @@ jobs:
       # ── Tests ───────────────────────────────────────────────────
       # Sprint A1 : --cov-fail-under=85 (baseline mesuré 87 %, marge 2 pts).
       # pytest-timeout est configuré dans pyproject.toml [tool.pytest.ini_options].
-      # ``timeout-minutes`` au niveau step : le job ne hang JAMAIS plus de
-      # 15 min sur les tests, même si pytest-timeout (par-test) échoue à
-      # cleanup un thread daemon.
+      #
+      # Garde-fous anti-hang :
+      #
+      # 1. ``timeout-minutes: 12`` au niveau step : cap dur GitHub si
+      #    tout le reste échoue.
+      # 2. ``timeout`` GNU autour de pytest : SIGTERM à 9 minutes,
+      #    SIGKILL 30s après si Python n'a pas obéi.  Couvre
+      #    spécifiquement le cas d'un hang de SHUTDOWN de
+      #    l'interpréteur Python 3.12+ (threads non-daemon, connexions
+      #    sqlite non fermées, ResourceWarnings — observé sur ubuntu
+      #    3.12 où pytest finit en 3:21 et l'interpréteur reste 12 min
+      #    avant de rendre la main).
+      # 3. ``-X faulthandler`` : si le hang revient, on aura les stack
+      #    traces de tous les threads dans le log avant le SIGKILL.
+      # 4. ``PYTHONFAULTHANDLER=1`` redondance ceinture-bretelles.
+      #
+      # Le code de retour 124 (SIGTERM par GNU timeout) ou 137 (SIGKILL)
+      # est traité comme un échec normal — on perd l'info pytest mais
+      # on préserve la latence de la CI.
       - name: Run tests
         # Sur Python 3.13, on continue malgré une erreur pour ne pas bloquer
         # le merge pendant la fenêtre informationnelle de 6 mois (m-8).
         continue-on-error: ${{ matrix.python-version == '3.13' }}
-        timeout-minutes: 15
+        timeout-minutes: 12
         shell: bash
         run: |
-          pytest tests/ -q --tb=short --no-header \
-            --cov=picarones --cov-report=xml --cov-report=term-missing \
-            --cov-fail-under=85
+          # ``timeout`` n'est pas standard sur macOS (BSD vs GNU) — on
+          # détecte et on adapte.  Sur Windows, le shell bash de
+          # Git-Bash n'a pas timeout : on retombe sur python direct.
+          if command -v timeout >/dev/null 2>&1; then
+            timeout --signal=SIGTERM --kill-after=30 540 \
+              python -X faulthandler -m pytest tests/ -q --tb=short --no-header \
+                --cov=picarones --cov-report=xml --cov-report=term-missing \
+                --cov-fail-under=85
+          elif command -v gtimeout >/dev/null 2>&1; then
+            # macOS Homebrew coreutils.
+            gtimeout --signal=SIGTERM --kill-after=30 540 \
+              python -X faulthandler -m pytest tests/ -q --tb=short --no-header \
+                --cov=picarones --cov-report=xml --cov-report=term-missing \
+                --cov-fail-under=85
+          else
+            python -X faulthandler -m pytest tests/ -q --tb=short --no-header \
+              --cov=picarones --cov-report=xml --cov-report=term-missing \
+              --cov-fail-under=85
+          fi
         env:
           PYTHONIOENCODING: utf-8
           PYTHONUTF8: "1"
+          PYTHONFAULTHANDLER: "1"
 
       # ── Couverture ──────────────────────────────────────────────
       # Conditions :
@@ -245,7 +278,7 @@ jobs:
   # Job 5 : Type-checking — Sprint A1 (item M-4)
   #
   # mypy est configuré dans pyproject.toml [tool.mypy] :
-  # - strict sur picarones.core.* (10 modules)
+  # - strict sur picarones.domain.* (couche 1 du rewrite, ex-picarones.core)
   # - lax ailleurs (follow_imports=silent)
   # Deux checks pré-existants désactivés (disallow_any_generics et
   # warn_return_any), à ré-activer en Sprint A11 après fix des
@@ -270,8 +303,8 @@ jobs:
           python -m pip install --upgrade pip setuptools wheel
           pip install -e ".[dev,web,stats]"
 
-      - name: Run mypy on picarones/core (strict)
-        run: python -m mypy picarones/core/
+      - name: Run mypy on picarones/domain (strict)
+        run: python -m mypy picarones/domain/
 
   # ──────────────────────────────────────────────────────────────────
   # Job 6 : Sécurité — Sprint A1 (item B-7)

.gitignore

@@ -28,9 +28,19 @@ jobs.db-shm
 jobs.db-wal
 
 # Exceptions : fichiers HTML sources du package (templates Jinja2, pas rapports)
-!picarones/report/templates/*.html
 !picarones/web/templates/*.html
+# Lot G fix (mai 2026) — Phase 5.E avait migré les templates de
+# picarones/report/templates/ vers picarones/reports_v2/html/templates/
+# mais oublié l'exception .gitignore correspondante : les 10 .html
+# avaient donc été silencieusement ignorés par git lors du commit
+# cc53ead, faisant échouer ~91 tests (TemplateNotFound _header.html
+# etc.).  Cette nouvelle exception remplace l'ancienne (plus en
+# vigueur depuis la suppression de picarones/report/ au Lot F).
+!picarones/reports_v2/html/templates/*.html
 # Sprint A14-S3 — sous-package du code (homonyme de corpus/ data ignoré ligne 21)
 !picarones/adapters/corpus/
 !picarones/adapters/corpus/**
+# Phase 4-quater (cleanup) : ré-ignorer __pycache__/ dans ce sous-package
+# (la négation ci-dessus est trop large et casse la règle ligne 1).
+picarones/adapters/corpus/**/__pycache__/
 _version.py

.well-known/security.txt

@@ -0,0 +1,18 @@
+# Picarones — security.txt (RFC 9116)
+#
+# This file is meant to be served at:
+#   https://<deployment-host>/.well-known/security.txt
+#
+# Institutional deployments (BnF, LoC, BL) MUST update the values
+# below before going live — the canonical contact for the upstream
+# project is the GitHub Security Advisories endpoint, but each
+# deployment SHOULD designate its own security contact.
+
+Contact: https://github.com/maribakulj/Picarones/security/advisories/new
+Expires: 2027-05-31T23:59:59.000Z
+Encryption: https://github.com/maribakulj/Picarones/security/advisories/new
+Acknowledgments: https://github.com/maribakulj/Picarones/security/advisories
+Preferred-Languages: fr, en
+Canonical: https://github.com/maribakulj/Picarones/blob/main/.well-known/security.txt
+Policy: https://github.com/maribakulj/Picarones/blob/main/SECURITY.md
+Hiring: https://github.com/maribakulj/Picarones/issues

CHANGELOG.md

@@ -7,9 +7,15 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ---
 
-## [Unreleased] — fix CI Windows + cap timeout — 2026-05
+## [Unreleased] — towards 1.3.0 (release institutionnelle BnF) — 2026-05
 
-### Bug Windows : `:` dans les clés du store
+> Section unique conforme à Keep-a-Changelog.  Les chantiers actifs
+> sont regroupés ci-dessous par thème ; chaque thème reflète un audit
+> ou un fix livré sur la branche ``claude/repo-analysis-cukvm``.
+
+### Fix CI : Windows + cap timeout (S59)
+
+#### Bug Windows : `:` dans les clés du store
 
 Le ``FilesystemArtifactStore`` produisait des filenames de la forme
 ``<step_hash>:<output_type>.json`` (séparateur ``:``).  ``:`` est un
@@ -29,7 +35,7 @@ les ``ArtifactType`` et tous les caractères Windows réservés.
 acceptable.  Aucun impact sur les artefacts persistés (l'index
 ``index.jsonl`` est régénéré automatiquement).
 
-### CI : exclusion des tests live + timeout codecov
+#### CI : exclusion des tests live + timeout codecov
 
 Voir commit `ce30e80` :
 
@@ -40,11 +46,9 @@ Voir commit `ce30e80` :
   ``timeout-minutes: 5`` sur ``Upload coverage to Codecov`` ;
   ``fail_ci_if_error: false`` sur codecov.
 
----
-
-## [Unreleased] — audit institutionnel S58-S59 (post-S57) — 2026-05
+### Audit institutionnel S58-S59 (post-S57)
 
-### ⚠️ BREAKING CHANGES (déprécations en cours, suppression en 2.0)
+#### ⚠️ BREAKING CHANGES (déprécations en cours, suppression en 2.0)
 
 Trois symboles supprimés au S57 sont **restaurés en S59** comme alias
 dépréciés avec `DeprecationWarning` à l'accès.  Ils seront supprimés
@@ -142,17 +146,15 @@ réseau (TimeoutError, ConnectionError, URLError).
 - `tests/architecture/test_manifest_reproducibility.py` : 4 tests.
 - `tests/interfaces/web/test_rate_limit_xff.py` : 7 tests.
 
----
-
-## [Unreleased] — rewrite A14 (S27-S46) + audit remediation (S47-S57) — 2026-05
+### Rewrite A14 (S27-S46) + audit remediation (S47-S57)
 
-> Cette section couvre la phase **rewrite ciblé** (S27-S46) puis les
-> **6 vagues de remédiation** des dettes identifiées en audit
-> *institutional readiness 2026-05* (S47-S57).  Détail complet dans
-> `docs/migration/rewrite-status-s46.md` et
-> `docs/audits/remediation-plan-2026-05.md`.
+Cette section couvre la phase **rewrite ciblé** (S27-S46) puis les
+**6 vagues de remédiation** des dettes identifiées en audit
+*institutional readiness 2026-05* (S47-S57).  Détail complet dans
+`docs/migration/rewrite-status-s46.md` et
+`docs/audits/remediation-plan-2026-05.md`.
 
-### Phase rewrite (S27-S46) — partial rewrite
+#### Phase rewrite (S27-S46) — partial rewrite
 
 20 sprints sur la directive *« rewrite tout, le plus solide, sans dette
 technique »*.  Stratégie : **rewrite parallèle**, pas full rewrite — le
@@ -177,7 +179,7 @@ benchmark, jobs), JobStore SQLite, UI Jinja2 + i18n FR/EN.
 SearchView).  Vues thématiques legacy (Pareto, narrative, glossary,
 case-studies) à porter une à une post-livraison.
 
-### Phase remédiation (S47-S57) — 30 dettes adressées en 6 vagues
+#### Phase remédiation (S47-S57) — 30 dettes adressées en 6 vagues
 
 | Vague | Sprint | Issues | Thème |
 |-------|--------|--------|-------|
@@ -191,7 +193,7 @@ case-studies) à porter une à une post-livraison.
 
 **Tous les 30 issues sont adressés au S57**.
 
-### S57 — détail des rectifications
+#### S57 — détail des rectifications
 
 - **#15 Lazy imports SDK tiers** : confirmé intentionnel — `mistralai`,
   `anthropic`, `openai`, `ollama` sont importés à l'intérieur des
@@ -254,11 +256,9 @@ case-studies) à porter une à une post-livraison.
   qualité d'image, présence de notes marginales).  Un seuil à 10
   points faisait échouer la CI sur du bruit légitime.
 
----
-
-## [Unreleased] — fix CI perf_regression — 2026-05
+### Fix CI perf_regression
 
-### ⚠️ BREAKING CHANGE — sémantique `--fail-if-cer-above`
+#### ⚠️ BREAKING CHANGE — sémantique `--fail-if-cer-above`
 
 L'option `picarones run --fail-if-cer-above` interprétait sa valeur
 comme un **pourcentage** (ex : `15.0` = 15 %).  Désormais elle attend
@@ -1889,7 +1889,7 @@ sur des monolithes globaux.
   ingénieur qui veut **brancher son propre module** dans Picarones
   (correcteur LLM, reconstructeur ALTO, classifieur d'entités,
   re-segmenteur…) trouve maintenant un guide complet bout-en-bout.
-  - Nouveau document `docs/user/writing-a-pipeline-module.md` :
+  - Nouveau document `docs/tutorials/writing-a-pipeline-module.md` :
     - **TL;DR** avec un exemple `MyCorrector` minimal en 25 lignes.
     - Section **« Le contrat ``BaseModule`` »** : tableau des
       champs obligatoires (``input_types``, ``output_types``,
@@ -3437,7 +3437,7 @@ sur des monolithes globaux.
   `CONFIDENCE_WARNING`, `cost_unit_pages=1000` propagé dans
   `PARETO_ALTERNATIVE`/`COST_OUTLIER`, paramètre `select_facts(..., type_order=...)`,
   test stabilité bootstrap (±0,5 pp inter-seeds), test E2E synthèse EN.
-  Doc « Politique éditoriale » dans `docs/developer/narrative-engine.md`.
+  Doc « Politique éditoriale » dans `docs/explanation/narrative-engine.md`.
 - **Sprint 24** — durcissement sécurité institutionnelle : mode public
   (`PICARONES_PUBLIC_MODE=1`), `PICARONES_BROWSE_ROOTS`, validation Pillow
   sur upload (CVE-2023-50447), rate limit + sémaphore concurrence,
@@ -3520,7 +3520,7 @@ sur des monolithes globaux.
   vue opt-in « score composite personnel » avec curseurs à 0 par défaut
   et formule visible. État persisté en URL. +21 tests.
 - **Sprint 22** — études de cas (`docs/case-studies/`),
-  `docs/user/reading-a-report.md`, trois guides développeur dans
+  `docs/tutorials/reading-a-report.md`, trois guides développeur dans
   `docs/developer/`. Garde-fou « pas de fausses études prétendant
   être réelles ». +18 tests.
 

GOVERNANCE.md

@@ -97,7 +97,7 @@ prestation (cf. modalités à définir au cas par cas).
 ## Politique de breaking changes
 
 L'API publique de Picarones est définie par
-[`docs/api-stable.md`](docs/api-stable.md). Elle inclut :
+[`docs/reference/api-stable.md`](docs/reference/api-stable.md). Elle inclut :
 
 - les symboles ré-exportés depuis `picarones/__init__.py` ;
 - les commandes CLI `picarones X` documentées dans le README ;

NOTICE

@@ -0,0 +1,28 @@
+Picarones
+Copyright 2025-2026 the Picarones contributors
+
+Licensed under the Apache License, Version 2.0 (the "License"); you
+may not use this software except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied.  See the License for the specific language governing
+permissions and limitations under the License.
+
+────────────────────────────────────────────────────────────────────
+Third-party software
+────────────────────────────────────────────────────────────────────
+
+This product includes software developed by third parties.  The
+authoritative list of third-party dependencies, their licenses and
+their copyright notices is maintained in:
+
+    docs/legal/THIRD_PARTY_LICENSES.md
+
+That file is regenerated by ``scripts/gen_third_party_licenses.py``
+on every release.  In case of discrepancy, the file in the
+``docs/legal/`` directory at the time of release prevails.

README.md

@@ -102,7 +102,7 @@ Three families of metrics calibrated for historical documents:
   trend with change-point detection; controlled per-slot ANOVA-like
   comparison.
 
-For the full list with definitions, see [`docs/views.md`](docs/views.md)
+For the full list with definitions, see [`docs/reference/views.md`](docs/reference/views.md)
 and the contextual glossary embedded in every report (25 bilingual
 entries).
 
@@ -189,7 +189,7 @@ picarones serve --port 8080
 ```
 
 For Docker, institutional deployment, or HuggingFace Spaces, see
-[`INSTALL.md`](INSTALL.md) and
+[`docs/how-to/install.md`](docs/how-to/install.md) and
 [`docs/operations/deployment-institutional.md`](docs/operations/deployment-institutional.md).
 
 ---
@@ -210,12 +210,12 @@ For Docker, institutional deployment, or HuggingFace Spaces, see
 
 LLM/VLM adapters (used through pipelines, not as standalone OCR
 engines): GPT-4o, Claude, Mistral Large, Ollama (local). See
-[`docs/cli-workflows.md`](docs/cli-workflows.md).
+[`docs/how-to/cli-workflows.md`](docs/how-to/cli-workflows.md).
 
 The `Engine` table is regenerated automatically by
 `scripts/gen_readme_tables.py` — adding a new adapter under
-`picarones/engines/` makes the next CI run update this table or
-fail.
+`picarones/adapters/legacy_engines/` makes the next CI run update
+this table or fail.
 
 ---
 
@@ -244,7 +244,7 @@ fail.
 <!-- /generated:cli -->
 
 Each command supports `--help` for full options. See
-[`docs/cli-workflows.md`](docs/cli-workflows.md) for end-to-end
+[`docs/how-to/cli-workflows.md`](docs/how-to/cli-workflows.md) for end-to-end
 examples.
 
 ---
@@ -299,7 +299,7 @@ client generation.
 
 Picarones ships **11 built-in normalization profiles** for historical
 text comparison (defined in
-[`picarones/measurements/normalization.py`](picarones/measurements/normalization.py),
+[`picarones/formats/text/normalization.py`](picarones/formats/text/normalization.py),
 exposed via `/api/normalization/profiles`):
 
 `nfc`, `caseless`, `minimal`, `medieval_french`,
@@ -309,7 +309,7 @@ exposed via `/api/normalization/profiles`):
 
 Custom profiles can be loaded from YAML files with user-defined
 diplomatic tables and `exclude_chars` sets. See
-[`docs/profiles.md`](docs/profiles.md).
+[`docs/reference/normalization-profiles.md`](docs/reference/normalization-profiles.md).
 
 A traceability table mapping each profile to its source standard
 (MUFI v4.0, TEI P5, DEAF) will ship in Sprint A12 (B-6).
@@ -320,24 +320,23 @@ A traceability table mapping each profile to its source standard
 
 ```
 picarones/
-├── core/                       Cercle 1 — pure abstractions (7 modules)
-├── measurements/               Cercle 2 — official metrics (~70 modules + narrative engine)
-├── engines/                    Cercle 2 — 5 OCR adapters
-├── llm/                        Cercle 2 — 4 LLM adapters
-├── pipelines/                  Cercle 2 — OCR+LLM pipelines
-├── modules/                    Cercle 2 — official BaseModule modules
-├── extras/                     Cercle 3 — plugins (importers, historical)
-├── report/                     Cercle 3 — HTML rendering
-├── cli/                        Cercle 3 — Click CLI (15 commands)
-├── web/                        Cercle 3 — FastAPI app + 11 routers
-├── prompts/                    8 versioned prompt templates
-└── data/                       Indicative tables (pricing.yaml)
+├── domain/         Layer 1 — pure types (Pydantic, stdlib only)
+├── formats/        Layer 2 — parsing/serialization (ALTO, PAGE XML)
+├── evaluation/     Layer 3 — metrics & analyses
+├── pipeline/       Layer 4 — canonical pipeline executor
+├── adapters/       Layer 5 — external libs (OCR, LLM, VLM, corpus)
+├── app/            Layer 6 — application services
+├── reports_v2/     Layer 7 — HTML / JSON / CSV report renderers
+└── interfaces/     Layer 8 — CLI Click, Web FastAPI
 ```
 
-Strict 3-circle architecture: imports flow only from outer to inner.
-Enforced by `tests/core/test_circle_dependencies.py` (Sprint A3).
-See [`docs/architecture.md`](docs/architecture.md) for the full
-manifesto.
+Legacy paths (`core/, measurements/, engines/, llm/, pipelines/,
+report/, modules/`) still present as shims, in active retirement
+(see `docs/migration/`).  Strict 8-layer architecture: imports flow
+outer → inner. Enforced by
+`tests/architecture/test_layer_dependencies.py`. See
+[`docs/explanation/architecture.md`](docs/explanation/architecture.md)
+for the full manifesto.
 
 ---
 
@@ -396,7 +395,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~5030 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~5000 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when
@@ -456,11 +455,11 @@ experimental demonstrator and the CLI as the supported interface.
 
 | Audience | Entry point |
 |----------|-------------|
-| **End user** | [`docs/user/reading-a-report.md`](docs/user/reading-a-report.md) ([EN](docs/user/reading-a-report.en.md)) |
+| **End user** | [`docs/tutorials/reading-a-report.md`](docs/tutorials/reading-a-report.md) ([EN](docs/tutorials/reading-a-report.en.md)) |
 | **Developer** | [`docs/developer/index.md`](docs/developer/index.md) ([EN](docs/developer/index.en.md)) |
 | **Operations / DSI** | [`docs/operations/deployment-institutional.md`](docs/operations/deployment-institutional.md), [`docs/operations/data-retention-rgpd.md`](docs/operations/data-retention-rgpd.md), [`docs/operations/release-process.md`](docs/operations/release-process.md) |
-| **Architect** | [`docs/architecture.md`](docs/architecture.md), [`docs/api-stable.md`](docs/api-stable.md) |
-| **Researcher** | [`docs/case-studies/`](docs/case-studies/), [`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md) |
+| **Architect** | [`docs/explanation/architecture.md`](docs/explanation/architecture.md), [`docs/reference/api-stable.md`](docs/reference/api-stable.md) |
+| **Researcher** | [`docs/case-studies/`](docs/case-studies/), [`docs/reference/reproducibility-snapshots.md`](docs/reference/reproducibility-snapshots.md) |
 | **Contributor** | [`CONTRIBUTING.md`](CONTRIBUTING.md), [`GOVERNANCE.md`](GOVERNANCE.md), [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) |
 | **Security** | [`SECURITY.md`](SECURITY.md) |
 | **Accessibility** | [`ACCESSIBILITY.md`](ACCESSIBILITY.md) |
@@ -477,7 +476,7 @@ shipped (see [`BACKLOG_POST_LIVRAISON.md`](BACKLOG_POST_LIVRAISON.md)).
 Cite the GitHub repository with the commit SHA used in your benchmark.
 Every Picarones report embeds the commit hash and a snapshot of the
 parameters used (cf.
-[`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md))
+[`docs/reference/reproducibility-snapshots.md`](docs/reference/reproducibility-snapshots.md))
 so the cited commit is sufficient to attribute the result.
 
 ---

SECURITY.en.md

@@ -0,0 +1,109 @@
+<!-- translation: machine + human review pending -->
+
+# SECURITY — Picarones (English)
+
+> French version: [`SECURITY.md`](SECURITY.md) (canonical).
+> Detailed threat model: [`docs/security/threat-model.md`](docs/security/threat-model.md).
+>
+> This is a summary translation focused on what an English-speaking
+> auditor needs.  The canonical FR version remains authoritative
+> for institutional sign-off.  Full alignment scheduled for a
+> dedicated human-review sprint.
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability in Picarones, please **do
+not file a public GitHub issue**.  Instead, use one of the following
+private channels:
+
+- **GitHub Security Advisories** (preferred):
+  https://github.com/maribakulj/Picarones/security/advisories/new
+- **`/.well-known/security.txt`** on any institutional deployment
+  (RFC 9116) — the contact address is documented there.
+
+We acknowledge reports within **72 hours** and aim to ship a fix
+within **30 days** for HIGH severity issues, **90 days** for MEDIUM.
+A coordinated disclosure agreement is offered for non-trivial issues.
+
+## Supported versions
+
+| Version | Status | Security fixes |
+|---------|--------|----------------|
+| 1.x (current) | Active | Yes |
+| 0.x | End of life | No — please upgrade |
+| Pre-release branches | Best effort | On request |
+
+## Deployment contexts
+
+Picarones is designed for three deployment contexts:
+
+1. **Developer machine** (Codespaces, laptop) — local access only,
+   relaxed defaults to keep iteration fast.
+2. **Institutional server** (intranet, scientific cluster) —
+   authenticated internal access, with cost guards (rate limit, body
+   size limit, max concurrent jobs).
+3. **Public space** (HuggingFace Space, online demo) — anyone can
+   reach the API; cloud API keys (OpenAI, Anthropic, Mistral, Azure…)
+   must NOT be exposed to financial DoS.
+
+## Security controls — quick reference
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `PICARONES_PUBLIC_MODE` | off | If `1`/`true`, refuses cloud OCR/LLM with shared keys and enables rate limit |
+| `PICARONES_MAX_UPLOAD_MB` | `100` | Max upload size in MiB |
+| `PICARONES_MAX_CONCURRENT_JOBS` | `2` | Max parallel benchmark jobs (in-process semaphore) |
+| `PICARONES_RATE_LIMIT_PER_HOUR` | `5` (public mode) | Max jobs per IP per hour, `0` disables |
+| `PICARONES_CSP` | hardened policy | Override Content-Security-Policy |
+| `PICARONES_CSRF_REQUIRED` | off | If `1`/`true`, enables CSRF protection (double-submit cookie + HMAC) |
+| `PICARONES_CSRF_SECRET` | auto | HMAC secret for CSRF tokens; **must be set in production** |
+
+## In-process middlewares
+
+The `picarones.interfaces.web.security` module provides four
+middlewares that institutional operators wire via `create_app(...)`:
+
+- `SecurityHeadersMiddleware` — adds CSP, X-Frame-Options,
+  X-Content-Type-Options, Referrer-Policy, Permissions-Policy to
+  every response.
+- `BodySizeLimitMiddleware` — rejects requests where
+  `Content-Length` exceeds a threshold.  **Known limitation**: does
+  not catch `Transfer-Encoding: chunked`; nginx
+  `client_max_body_size` is recommended in front.
+- `RateLimitMiddleware` — sliding window, in-memory,
+  `trust_proxy_count: int` for safe `X-Forwarded-For` parsing,
+  LRU eviction on `max_clients=10000` to bound memory.
+- `AuthenticationMiddleware` — opt-in wrapper around an
+  `AuthenticationBackend` Protocol; the institution plugs in its
+  SSO/LDAP/JWT scheme.
+
+## Audit trail
+
+Sensitive job mutations (`POST /api/jobs`, `DELETE /api/jobs/{id}`)
+emit a structured `[audit]` log line at INFO level with the source
+IP, ready to be ingested by the institution's SIEM.
+
+## Reproducibility and integrity
+
+`RunManifest` is byte-deterministic (`model_dump_json` with ordered
+fields).  The SHA-256 hash of a manifest can be cited in a scientific
+publication to anchor the run.  Cryptographic signing of manifests
+(Sigstore) is on the roadmap.
+
+## Cloud API key management
+
+Cloud keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `MISTRAL_API_KEY`,
+`GOOGLE_APPLICATION_CREDENTIALS`, `AZURE_DOC_INTEL_*`) are read from
+environment variables only.  Adapters never log keys.  For
+institutional deployments, source the env from a secrets vault
+(HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, etc.) at
+process startup.
+
+See also [`docs/operations/runbook.md`](docs/operations/runbook.md)
+for incident response and [`docs/legal/dpa-template.md`](docs/legal/dpa-template.md)
+for the data processing agreement template covering cloud
+sub-processors.
+
+## Last revised
+
+2026-05.  This document is reviewed at every major release.

SPECS.md

@@ -23,7 +23,7 @@
 ## Table des matières
 
 1. [Vision et positionnement](#1-vision-et-positionnement)
-2. [Architecture en 3 cercles](#2-architecture-en-3-cercles)
+2. [Architecture en 8 couches concentriques](#2-architecture-en-8-couches-concentriques)
 3. [Module 1 — Corpus et imports](#3-module-1--corpus-et-imports)
 4. [Module 2 — Adaptateurs OCR / HTR](#4-module-2--adaptateurs-ocr--htr)
 5. [Module 3 — Pipelines OCR+LLM et pipelines composables](#5-module-3--pipelines-ocrllm-et-pipelines-composables)
@@ -125,72 +125,108 @@ plusieurs briques nouvelles dans l'écosystème OCR/HTR open-source :
 
 ---
 
-## 2. Architecture en 3 cercles
+## 2. Architecture en 8 couches concentriques
 
 ```
-   Cercle 3 (extras, report, cli, web)
-   │
-   ▼
-   Cercle 2 (measurements, engines, llm, pipelines, modules)
-   │
-   ▼
-   Cercle 1 (core)
+domain → formats → evaluation → pipeline → adapters → app → reports_v2 → interfaces
 ```
 
 **Règle de dépendance** : les imports vont uniquement de
-l'extérieur vers l'intérieur. Aucun shim — un module a un seul
-emplacement. La règle est appliquée par
-`tests/core/test_circle_dependencies.py` (Sprint A3) qui parse
+l'extérieur vers l'intérieur (de gauche à droite dans le
+diagramme).  La règle est appliquée par
+`tests/architecture/test_layer_dependencies.py` qui parse
 l'AST de chaque fichier et bloque toute violation au merge.
 
-### 2.1 Cercle 1 — abstractions pures
-
-7 modules dans `picarones/core/` :
-
-- `corpus.py` — `Document`, `Corpus`, `GTLevel.{TEXT,ALTO,PAGE,ENTITIES,READING_ORDER}`,
-  payloads typés, loader auto-détectant les fichiers `.gt.alto.xml`,
-  `.gt.page.xml`, `.gt.entities.json`, `.gt.reading_order.json`.
-- `modules.py` — `BaseModule`, `ArtifactType`. Interface commune
-  à OCR, mappeurs, rewriters, classifieurs.
-- `metric_registry.py` — `MetricSpec`, `@register_metric`,
-  `select_metrics`, `compute_at_junction`. Sélection par signature
-  de types exacte (pas de coercion).
-- `metric_hooks.py` — registre legacy compatible (Sprint 16-).
-- `metrics.py` — `MetricsResult`, `aggregate_metrics`.
-- `results.py` — `DocumentResult`, `EngineReport`, `BenchmarkResult`,
-  sérialisation JSON.
-- `facts.py` — `Fact`, `FactType` (20 entrées), `FactImportance`,
-  `DetectorRegistry`. Modèle de données du moteur narratif.
-- `diff_utils.py` — `compute_word_diff`, `compute_char_diff`,
-  `diff_stats` (déplacé Cercle 3 → Cercle 1 en A3).
-- `pipeline.py` — `PipelineRunner`, `PipelineSpec`, `PipelineStep`.
-- `xml_utils.py` — `safe_parse_xml` (defusedxml).
-
-### 2.2 Cercle 2 — logique métier
-
-5 sous-packages :
-
-- `measurements/` — ~70 modules de calcul de métriques + le
-  moteur narratif (`narrative/` avec arbiter, registry, renderer,
-  20 détecteurs en 6 familles).
-- `engines/` — adaptateurs OCR : Tesseract, Pero OCR, Mistral OCR,
-  Google Vision, Azure Document Intelligence (5 adapters).
-- `llm/` — adaptateurs LLM : OpenAI, Anthropic, Mistral, Ollama
-  (4 adapters).
-- `pipelines/` — orchestration OCR+LLM (3 modes historiques).
-- `modules/` — modules `BaseModule` officiels (ALTO text→region
-  mappers).
-
-### 2.3 Cercle 3 — entrées et rendu
-
-- `report/` — générateur HTML, ~25 modules de rendu, vendor
-  Chart.js, templates Jinja2 (10 partials), i18n FR/EN, glossaire
-  contextuel (25 entrées bilingues).
-- `cli/` — Click CLI (15 commandes) en package `picarones/cli/`.
-- `web/` — FastAPI (app + 11 routers + sécurité + jobs SQLite +
-  maintenance auto-purge).
-- `extras/` — plugins : importers (IIIF, Gallica, HTR-United, HF
-  Datasets, eScriptorium), modules historiques.
+> **Note sur le legacy** : le projet est en cours de retrait
+> du legacy.  Une arborescence historique
+> (``picarones/{core,measurements,engines,llm,pipelines,
+> report,modules}``) cohabite encore et est en train de
+> disparaître phase par phase.  Cf.
+> [`docs/migration/legacy-retirement-plan.md`](docs/migration/legacy-retirement-plan.md)
+> pour le statut et le calendrier.  Tout nouveau code va
+> dans l'arborescence canonique ; les chemins legacy
+> existants sont des shims minimaux destinés à être
+> supprimés.
+
+### 2.1 `picarones/domain/` — types purs
+
+Cercle le plus interne.  Stdlib + Pydantic uniquement, aucune
+I/O, aucun framework, aucun module legacy.
+
+| Module | Contenu |
+|---|---|
+| `artifacts.py` | `Artifact`, `ArtifactType` (10 types : IMAGE, RAW_TEXT, CORRECTED_TEXT, ALTO_XML, PAGE_XML, CANONICAL_DOCUMENT, ENTITIES, READING_ORDER, ALIGNMENT, CONFIDENCES) |
+| `corpus.py` | `CorpusSpec` |
+| `documents.py` | `DocumentRef` |
+| `evaluation_spec.py` | `MetricSpec`, `EvaluationView`, `EvaluationSpec` |
+| `pipeline_spec.py` | `PipelineSpec`, `PipelineStep`, `INITIAL_STEP_ID` |
+| `projection_spec.py` | `ProjectionSpec` |
+| `provenance.py` | `ProvenanceRecord` |
+| `run_manifest.py` | `RunManifest` |
+| `module_protocol.py` | `BaseModule` (ABC, voie de retrait au profit de `StepExecutor`) |
+| `facts.py` | `Fact`, `FactType`, `FactImportance`, `DetectorRegistry` |
+| `errors.py` | Hiérarchie d'exceptions (`PicaronesError`, `AdapterStepError`, …) |
+
+### 2.2 `picarones/formats/` — parsing / sérialisation
+
+ALTO 4, PAGE XML, JSON, XML utilitaires.  Stdlib + lxml +
+defusedxml.  Pas de logique métier.
+
+### 2.3 `picarones/evaluation/` — métriques et calcul
+
+Cœur de la valeur ajoutée.  Stdlib + numpy + scipy + jiwer +
+spacy + rapidfuzz.
+
+| Sous-paquet | Contenu |
+|---|---|
+| `metrics/` | ~30 métriques (CER, WER, MUFI, philological, NER, calibration, taxonomy, …) |
+| `statistics/` | Wilcoxon, Friedman/Nemenyi, bootstrap, Pareto, clustering, CDD |
+| `views/`, `projectors/` | EvaluationView (Sprint S13+), projecteurs `AltoToText`, `PageToText`, `CanonicalToText` |
+| `corpus.py` | `Document`, `Corpus`, `GTLevel`, payloads (legacy en cours de retrait) |
+| `metric_registry.py`, `metric_hooks.py`, `metric_result.py` | Registres typés + hooks + dataclasses résultats |
+| `pipeline.py`, `pipeline_benchmark.py`, `pipeline_comparison.py` | `PipelineRunner` legacy + orchestration corpus-wide (en cours de convergence vers `pipeline.executor`) |
+| `benchmark_result.py` | `BenchmarkResult`, `EngineReport`, `DocumentResult`, sérialisation JSON |
+| `engines/` | OCR engines legacy (`BaseOCREngine`-based) — temporairement avant suppression complète |
+| `_diff_utils.py` | `compute_word_diff`, `compute_char_diff`, `diff_stats` |
+
+### 2.4 `picarones/pipeline/` — orchestration canonique
+
+`PipelineExecutor` instance-based, `StepExecutor` Protocol,
+`ExecutionPlan` immuable.  Cible canonique pour le bench
+d'axe B (pipelines composées).
+
+### 2.5 `picarones/adapters/` — adapters externes
+
+Adapters OCR / LLM / VLM consommant des libs externes
+(pytesseract, mistralai, openai, anthropic, google.cloud,
+azure.*, pero_ocr, ollama).  Implémentent `StepExecutor`.
+
+| Sous-paquet | Contenu |
+|---|---|
+| `ocr/` | `TesseractAdapter`, `PeroOCRAdapter`, `MistralOCRAdapter`, `GoogleVisionAdapter`, `AzureDocIntelAdapter`, `PrecomputedAdapter` |
+| `llm/` | `BaseLLMAdapter` + Mistral / OpenAI / Anthropic / Ollama |
+| `vlm/` | Adapters VLM (zero-shot OCR via vision-language models) |
+| `corpus/` | Loaders externes : IIIF, Gallica, HTR-United, HuggingFace |
+| `storage/` | `ArtifactStore`, `JobStore` (S29 + S47) |
+| `legacy_engines/`, `legacy_modules/` | Engines + modules legacy `BaseModule`-based (en cours de retrait, cf. Phase 7.A) |
+
+### 2.6 `picarones/app/` — services applicatifs
+
+`BenchmarkService`, `CorpusRunner`, `RunOrchestrator`.
+Orchestrent les pipelines canoniques sur corpus.
+
+### 2.7 `picarones/reports_v2/` — rendu HTML / JSON / CSV
+
+Rapport final consommant un `BenchmarkResult` ou `RunResult`.
+22 renderers thématiques + 5 vues (advanced_taxonomy,
+diagnostics, economics, pipeline, robustness) +
+`ReportGenerator` orchestrateur + templates Jinja2 +
+glossaire bilingue (25 entrées) + i18n FR/EN.
+
+### 2.8 `picarones/interfaces/` — entrées utilisateur
+
+CLI Click, Web FastAPI, IIIF/Gallica/eScriptorium importers
+exposés en interface.
 
 ---
 
@@ -263,7 +299,7 @@ Endpoint `POST /api/corpus/upload`. Validation Pillow
 ### 4.1 Architecture des adaptateurs
 
 Chaque moteur OCR est une classe Python qui hérite de
-`BaseOCREngine` (`picarones/engines/base.py`), elle-même héritière
+`BaseOCREngine` (`picarones/adapters/legacy_engines/base.py`), elle-même héritière
 de `BaseModule` (Sprint 33). Une instance déclare son
 `execution_mode` (`"io"` ou `"cpu"`) que le runner utilise pour
 choisir entre `ThreadPoolExecutor` (cloud APIs) et
@@ -431,7 +467,7 @@ canonique (champ `reference`).
 
 ### 6.2 Profils de normalisation
 
-11 profils livrés (`picarones/measurements/normalization.py`,
+11 profils livrés (`picarones/formats/text/normalization.py`,
 exposés via `/api/normalization/profiles`) : `nfc`, `caseless`,
 `minimal`, `medieval_french`, `early_modern_french`,
 `medieval_latin`, `medieval_english`, `early_modern_english`,
@@ -649,7 +685,7 @@ qui contient :
   git, paquets installés (top 200).
 
 Procédure complète de re-jeu d'un benchmark à 5 ans d'écart :
-[`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md)
+[`docs/reference/reproducibility-snapshots.md`](docs/reference/reproducibility-snapshots.md)
 (Sprint A8 / M-12).
 
 ### 9.2 Reproductibilité des builds

docs/api/adapters.md

@@ -0,0 +1,82 @@
+# `picarones.adapters` — implémentations concrètes
+
+## OCR
+
+::: picarones.adapters.ocr.base
+    options:
+      show_root_heading: true
+
+::: picarones.adapters.ocr.tesseract
+    options:
+      show_root_heading: true
+      members: ["TesseractAdapter"]
+
+::: picarones.adapters.ocr.pero_ocr
+    options:
+      show_root_heading: true
+      members: ["PeroOCRAdapter"]
+
+::: picarones.adapters.ocr.mistral_ocr
+    options:
+      show_root_heading: true
+      members: ["MistralOCRAdapter"]
+
+::: picarones.adapters.ocr.google_vision
+    options:
+      show_root_heading: true
+      members: ["GoogleVisionAdapter"]
+
+::: picarones.adapters.ocr.azure_doc_intel
+    options:
+      show_root_heading: true
+      members: ["AzureDocIntelAdapter"]
+
+## LLM
+
+::: picarones.adapters.llm.base
+    options:
+      show_root_heading: true
+      members: ["BaseLLMAdapter", "LLMAdapterError", "LLMResult", "normalize_llm_content"]
+
+::: picarones.adapters.llm.anthropic_adapter
+    options:
+      show_root_heading: true
+
+::: picarones.adapters.llm.openai_adapter
+    options:
+      show_root_heading: true
+
+::: picarones.adapters.llm.mistral_adapter
+    options:
+      show_root_heading: true
+
+::: picarones.adapters.llm.ollama_adapter
+    options:
+      show_root_heading: true
+
+## VLM
+
+::: picarones.adapters.vlm.base
+    options:
+      show_root_heading: true
+      members: ["BaseVLMAdapter", "VLMAdapterError"]
+
+## Storage
+
+::: picarones.adapters.storage.artifact_store
+    options:
+      show_root_heading: true
+
+::: picarones.adapters.storage.job_store
+    options:
+      show_root_heading: true
+
+## Helpers
+
+::: picarones.adapters.output_paths
+    options:
+      show_root_heading: true
+
+::: picarones.adapters._retry
+    options:
+      show_root_heading: true

docs/api/app.md

@@ -0,0 +1,39 @@
+# `picarones.app` — services applicatifs
+
+## Schémas
+
+::: picarones.app.schemas.run_spec
+    options:
+      show_root_heading: true
+
+## Services
+
+::: picarones.app.services.run_orchestrator
+    options:
+      show_root_heading: true
+
+::: picarones.app.services.benchmark_service
+    options:
+      show_root_heading: true
+
+::: picarones.app.services.job_runner
+    options:
+      show_root_heading: true
+
+::: picarones.app.services.dependencies
+    options:
+      show_root_heading: true
+
+::: picarones.app.services.path_security
+    options:
+      show_root_heading: true
+
+::: picarones.app.services.registry_service
+    options:
+      show_root_heading: true
+
+## Résultats
+
+::: picarones.app.results
+    options:
+      show_root_heading: true

docs/api/domain.md

@@ -0,0 +1,30 @@
+# `picarones.domain` — types purs
+
+::: picarones.domain.artifacts
+    options:
+      show_root_heading: true
+      members_order: source
+
+::: picarones.domain.documents
+    options:
+      show_root_heading: true
+
+::: picarones.domain.corpus
+    options:
+      show_root_heading: true
+
+::: picarones.domain.evaluation_spec
+    options:
+      show_root_heading: true
+
+::: picarones.domain.pipeline_spec
+    options:
+      show_root_heading: true
+
+::: picarones.domain.run_manifest
+    options:
+      show_root_heading: true
+
+::: picarones.domain.errors
+    options:
+      show_root_heading: true

docs/api/evaluation.md

@@ -0,0 +1,47 @@
+# `picarones.evaluation` — métriques et vues
+
+## Vues
+
+::: picarones.evaluation.views.base
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.views.executor
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.views.text_view
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.views.alto_view
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.views.search_view
+    options:
+      show_root_heading: true
+
+## Registre
+
+::: picarones.evaluation.registry.registry
+    options:
+      show_root_heading: true
+
+## Projecteurs
+
+::: picarones.evaluation.projectors.base
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.projectors.alto
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.projectors.canonical
+    options:
+      show_root_heading: true
+
+::: picarones.evaluation.projectors.pagexml
+    options:
+      show_root_heading: true

docs/api/index.md

@@ -0,0 +1,51 @@
+# API Reference (auto-générée)
+
+> **Audience** : développeur tiers, contributeur, mainteneur.  Cette
+> référence est **générée automatiquement** depuis les docstrings du
+> code par [mkdocstrings](https://mkdocstrings.github.io/), au build
+> du site de documentation.
+>
+> Pour la **politique de stabilité** de l'API publique (semver,
+> deprecation periods, symboles cibles), voir
+> [`../reference/api-stable.md`](../reference/api-stable.md).
+>
+> Pour l'**architecture** et le **pourquoi** des choix de design,
+> voir [`../explanation/architecture.md`](../explanation/architecture.md).
+
+## Build local
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve  # hot-reload sur http://localhost:8000
+```
+
+ou
+
+```bash
+mkdocs build  # site statique dans site/
+```
+
+## Structure
+
+L'API publique est groupée par cercle architectural :
+
+| Cercle | Référence |
+|--------|-----------|
+| Domain (types purs) | [`domain.md`](domain.md) |
+| Pipeline (orchestration) | [`pipeline.md`](pipeline.md) |
+| Evaluation (métriques + vues) | [`evaluation.md`](evaluation.md) |
+| Adapters (OCR/LLM/VLM) | [`adapters.md`](adapters.md) |
+| App services (orchestrateur, jobs) | [`app.md`](app.md) |
+
+## Stabilité
+
+Tous les symboles documentés ici sont de l'**API publique** ce qui
+signifie :
+
+- Suivent semver — un retrait nécessite une release majeure et une
+  deprecation period d'au moins une release mineure (`DeprecationWarning`
+  émis depuis la version N, suppression en N+2 majeure).
+- Sont vérifiés par `tests/core/test_public_api_signatures.py`.
+
+Les symboles **privés** (préfixe `_` ou non listés dans `__all__`)
+peuvent changer sans préavis.

docs/api/pipeline.md

@@ -0,0 +1,25 @@
+# `picarones.pipeline` — orchestration mono-document
+
+::: picarones.pipeline.executor
+    options:
+      show_root_heading: true
+
+::: picarones.pipeline.planner
+    options:
+      show_root_heading: true
+
+::: picarones.pipeline.runner
+    options:
+      show_root_heading: true
+
+::: picarones.pipeline.validation
+    options:
+      show_root_heading: true
+
+::: picarones.pipeline.types
+    options:
+      show_root_heading: true
+
+::: picarones.pipeline.protocols
+    options:
+      show_root_heading: true

docs/architecture.md

@@ -1,179 +0,0 @@
-# Architecture Picarones — manifeste
-
-Picarones est un **banc d'essai** pour pipelines OCR/HTR sur documents
-patrimoniaux. Le code est organisé en **3 cercles concentriques** avec
-une règle de dépendance stricte : les flèches d'import vont uniquement
-de l'extérieur vers l'intérieur.
-
-```
-   Cercle 3 (extras, report, cli, web)
-   │
-   ▼
-   Cercle 2 (measurements, engines, llm, pipelines, modules)
-   │
-   ▼
-   Cercle 1 (core)
-```
-
-## Cercle 1 — `picarones/core/` : abstractions de domaine
-
-Pas de logique métier, pas d'I/O. Uniquement des **contrats** que les
-cercles supérieurs implémentent.
-
-| Module | Contenu |
-|---|---|
-| `modules.py` | `BaseModule`, `ArtifactType`, `validate_inputs`/`validate_outputs` |
-| `corpus.py` | `Document`, `Corpus`, `GTLevel`, payloads typés (`TextGT`, `AltoGT`, `PageGT`, `EntitiesGT`, `ReadingOrderGT`) |
-| `results.py` | `DocumentResult`, `EngineReport`, `BenchmarkResult` |
-| `metric_registry.py` | `MetricSpec`, `register_metric`, `select_metrics`, `compute_at_junction` |
-| `metric_hooks.py` | `register_document_metric`, `register_corpus_aggregator`, profils de calcul |
-| `pipeline.py` | `PipelineRunner`, `PipelineSpec`, `PipelineStep` (DAG de modules) |
-| `facts.py` | `Fact`, `FactType`, `FactImportance`, `DetectorRegistry` |
-
-**Règle** : un module du cercle 1 peut importer un autre module du
-cercle 1. Il ne peut **rien** importer des cercles 2 ou 3.
-
-## Cercle 2 — implémentations officielles
-
-Les implémentations distribuées par défaut dans le package `picarones`.
-
-### `picarones/measurements/` — métriques (~50 modules)
-
-| Catégorie | Modules |
-|---|---|
-| Coeur | `metrics.py`, `statistics/` (sous-package), `runner.py`, `builtin_hooks.py`, `builtin_metrics.py`, `normalization.py` |
-| Erreurs | `confusion.py`, `taxonomy.py`, `taxonomy_comparison.py`, `taxonomy_cooccurrence.py`, `taxonomy_intra_doc.py` |
-| Lignes/structure | `line_metrics.py`, `structure.py`, `worst_lines.py`, `char_scores.py` |
-| Calibration/fiabilité | `calibration.py`, `reliability.py`, `hallucination.py` |
-| Image | `image_quality.py`, `image_predictive.py`, `difficulty.py` |
-| Robustesse | `robustness.py`, `robustness_projection.py` |
-| Inter-moteurs | `inter_engine.py`, `specialization.py` |
-| Statistique avancée | `baseline_comparison.py`, `longitudinal.py`, `incremental_comparison.py` |
-| Contenu | `searchability.py`, `numerical_sequences.py`, `rare_tokens.py`, `readability.py` |
-| Structure ALTO | `layout.py`, `reading_order.py`, `ner.py`, `ner_backends.py`, `error_absorption.py` |
-| Économie | `cost_projection.py`, `marginal_cost.py`, `pricing.py`, `throughput.py` |
-| Philologie historique | `mufi.py`, `abbreviations.py`, `unicode_blocks.py`, `early_modern_typography.py`, `modern_archives.py`, `roman_numerals.py`, `lexical_modernization.py`, `philological_runner.py` |
-| Pipelines composées | `pipeline_benchmark.py`, `pipeline_comparison.py`, `pipeline_spec_loader.py`, `alto_metrics.py` |
-| Divers | `equivalence_profile.py`, `levers.py`, `module_policy.py`, `history.py` |
-| Runners adaptifs | `readability_runner.py`, `searchability_runner.py`, `numerical_sequences_runner.py` |
-| Narratif | `narrative/` (arbiter, renderer, registry, 18 détecteurs en 6 familles) |
-
-### `picarones/engines/` — adapters OCR (5)
-
-`tesseract.py`, `pero_ocr.py`, `mistral_ocr.py`, `google_vision.py`,
-`azure_doc_intel.py`. Tous héritent de `picarones.core.engine.BaseOCREngine`
-(qui vit dans `engines/base.py` pour la lisibilité).
-
-### `picarones/llm/` — adapters LLM (4)
-
-`mistral_adapter.py`, `openai_adapter.py`, `anthropic_adapter.py`,
-`ollama_adapter.py`. Interface commune dans `base.py`.
-
-### `picarones/pipelines/` — pipelines OCR+LLM intégrés
-
-`base.py` (`OCRLLMPipeline`, qui hérite de `BaseOCREngine`),
-`over_normalization.py`.
-
-### `picarones/modules/` — modules `BaseModule` officiels
-
-Démonstrateurs qui prouvent l'axe B du plan d'évolution :
-`alto_text_to_mono_region.py`.
-
-## Cercle 3 — extensions et présentation
-
-### `picarones/extras/importers/` — connecteurs corpus
-
-`iiif.py`, `gallica.py`, `htr_united.py`, `huggingface.py`,
-`escriptorium.py`, `_http.py`. Plugins pluggable, certains expérimentaux.
-
-### `picarones/report/` — rendu HTML
-
-| Sous-dossier | Contenu |
-|---|---|
-| `generator.py` | Orchestration Jinja2 |
-| `views/` | 5 vues thématiques (economics, advanced_taxonomy, diagnostics, pipeline, robustness) |
-| `templates/` | Jinja2 (base, header, footer, vues, partials) |
-| `i18n/` | FR/EN |
-| `glossary/` | 25 entrées bilingues |
-| `vendor/` | Chart.js |
-| `*_render.py` | ~22 renderers (calibration, NER, Pareto, Sankey, etc.) |
-
-Pas de sous-dossier `extras/render/` — tout le rendu est ici.
-
-### `picarones/cli/` — Click (7 fichiers)
-
-Point d'entrée `picarones.cli:cli` (référencé dans `pyproject.toml`).
-15 sous-commandes : `run`, `diagnose`, `economics`, `edition`,
-`compare`, `metrics`, `engines`, `info`, `report`, `demo`, `serve`,
-`history`, `robustness`, `pipeline run/compare`, `import`.
-
-### `picarones/web/` — FastAPI
-
-Interface web (`app.py`).
-
-## Données
-
-| Dossier | Rôle |
-|---|---|
-| `picarones/prompts/` | Prompts LLM versionnés (8 fichiers, FR + EN) |
-| `picarones/data/` | Tables indicatives (pricing, etc.) |
-| `picarones/fixtures.py` | Corpus de démonstration |
-
-## Règles de migration
-
-1. **Pas de shim** : un module a un seul emplacement physique. Les
-   imports pointent directement vers la vraie source.
-2. **Pas de double API** : une fonction a un seul nom canonique. Les
-   alias historiques sont supprimés et les tests mis à jour.
-3. **Frontières strictes** : si un module Y du cercle N importe le
-   module X, alors le cercle de X est ≤ N. Une exception
-   pragmatique : `engines/base.py` est conceptuellement cercle 1
-   mais physiquement dans `engines/` pour rester avec ses
-   implémentations.
-4. **Les dépendances optionnelles** (`scipy`, `spacy`, etc.) sont
-   gérées par try/except à l'import — pas par shim.
-
-## Tests
-
-Organisés par cercle : `tests/core/`, `tests/measurements/`,
-`tests/engines/`, `tests/extras/`, `tests/report/`,
-`tests/integration/` (tests E2E croisant plusieurs cercles).
-
-Un test du cercle N **n'importe pas** les implémentations des
-cercles > N (sauf `tests/integration/`).
-
-## Convention de découpage des modules > 400 lignes
-
-Quand un module Python dépasse 400 lignes ET contient plusieurs
-responsabilités disjointes, le découper en **sous-package** plutôt
-qu'en plusieurs modules à plat. Modèle de référence :
-[`picarones/measurements/statistics/`](../picarones/measurements/statistics/)
-issu du sprint « découpage de statistics.py » (mai 2026).
-
-Convention :
-
-1. **Renommer** `X.py` en `X/__init__.py` via `git mv` (préserve
-   l'historique du fichier original).
-2. **Créer** dans `X/` un sous-module par famille fonctionnelle
-   (`bootstrap.py`, `wilcoxon.py`, `friedman_nemenyi.py`, etc.).
-   Chaque sous-module doit faire moins de ~400 lignes ; sinon
-   re-décomposer.
-3. **`X/__init__.py`** ne contient QUE des ré-exports rétrocompat —
-   tous les symboles publics de l'ancien `X.py` doivent rester
-   importables via `from picarones.X import …`. Les symboles privés
-   ré-exportés doivent être ceux **réellement** consommés par les
-   tests (vérifié par grep, pas par supposition).
-4. **`__all__`** explicite dans chaque sous-module et dans le
-   `__init__.py`.
-5. **Tests architecture** (`tests/architecture/test_*.py`) doivent
-   continuer à passer : si nécessaire, étendre `_measurements_modules()`
-   ou `_imports_target_*` pour reconnaître les sous-packages.
-6. **Préfixer les modules de rendu** par leur domaine
-   (`cdd_render.py` plutôt que `render_cdd.py`) pour cohérence avec
-   `picarones/report/*_render.py`.
-
-**Quand NE PAS découper** : si les responsabilités sont fortement
-couplées (ex: un orchestrateur qui appelle 12 sous-fonctions au
-même endroit), le maintien dans un seul fichier > 400 lignes est
-acceptable. Le budget par fichier (`tests/architecture/test_file_budgets.py`)
-documente ces dérogations conscientes.

docs/developer/extending-i18n.md

@@ -48,7 +48,7 @@ automatiquement sur `fr` si une langue manque.
 
 ## Format YAML pour les templates narratifs
 
-Voir `docs/developer/narrative-engine.md` pour le détail. En bref :
+Voir `docs/explanation/narrative-engine.md` pour le détail. En bref :
 
 ```yaml
 fact_type_value: >-

docs/developer/index.en.md

@@ -13,7 +13,7 @@ module.
 ## Architecture
 
 Picarones uses a **3-circle architecture** (manifesto in
-[`docs/architecture.md`](../architecture.md)):
+[`docs/explanation/architecture.md`](../architecture.md)):
 
 ```
    Circle 3 (extras, report, cli, web)

docs/developer/index.md

@@ -5,33 +5,49 @@ fondamentaux du projet.
 
 ## Architecture
 
-Voir [CLAUDE.md](../../CLAUDE.md) pour la cartographie complète des
-modules. En résumé :
+Voir [CLAUDE.md](../../CLAUDE.md) et
+[`docs/explanation/architecture.md`](../explanation/architecture.md)
+pour la cartographie complète.  En résumé : architecture **8
+couches concentriques** (post-rewrite, canonique) :
 
 ```
 picarones/
-├── core/                # cœur analytique pur Python (Cercle 1)
-│   ├── pipeline.py      # PipelineRunner pour pipelines composées
-│   ├── corpus.py        # Document, Corpus, GTLevel
-│   ├── results.py       # DocumentResult, EngineReport, BenchmarkResult
-│   ├── modules.py       # BaseModule, ArtifactType
+├── domain/              # Layer 1 — types purs (Pydantic, stdlib only)
+│   ├── artifacts.py     # Artifact, ArtifactType (10 types)
+│   ├── corpus.py        # CorpusSpec
+│   ├── documents.py     # DocumentRef
+│   ├── pipeline_spec.py # PipelineSpec, PipelineStep (Pydantic immutable)
+│   ├── module_protocol.py # BaseModule (ABC, en cours de retrait au profit de StepExecutor)
 │   ├── facts.py         # Fact, FactType, registre narratif
 │   └── …
-├── measurements/        # métriques officielles (Cercle 2)
-│   ├── runner.py        # orchestration ThreadPool/ProcessPool
-│   ├── metrics.py       # CER/WER/MER/WIL via jiwer
-│   ├── statistics/      # Wilcoxon, Friedman, Nemenyi, Pareto
-│   │   (sous-package depuis le sprint « découpage statistics.py »)
-│   ├── narrative/       # moteur de synthèse factuelle
-│   ├── pricing.py       # modèle de coût pour la vue Pareto
-│   └── …
-├── engines/             # adaptateurs OCR (Tesseract, Pero, Mistral OCR…)
-├── llm/                 # adaptateurs LLM (OpenAI, Anthropic, Mistral, Ollama)
-├── pipelines/           # OCRLLMPipeline (3 modes)
-├── report/              # générateur HTML + templates Jinja2 + i18n + glossaire
-└── web/                 # FastAPI + SPA vanilla JS
+├── formats/             # Layer 2 — parsing/serialization (ALTO 4, PAGE XML, JSON)
+├── evaluation/          # Layer 3 — métriques et calcul
+│   ├── metrics/         # ~30 métriques (CER/WER, MUFI, philological, NER, …)
+│   ├── statistics/      # Wilcoxon, Friedman/Nemenyi, bootstrap, Pareto
+│   ├── views/, projectors/  # EvaluationView (S13+), projecteurs Alto/Page/CanonicalToText
+│   ├── corpus.py        # Document, Corpus, GTLevel (legacy en cours de retrait)
+│   ├── pipeline.py      # PipelineRunner legacy (en cours de retrait)
+│   └── benchmark_result.py # BenchmarkResult, EngineReport, DocumentResult
+├── pipeline/            # Layer 4 — PipelineExecutor canonique (instance-based)
+├── adapters/            # Layer 5 — adapters externes (libs externes autorisées)
+│   ├── ocr/             # Tesseract, Pero, Mistral OCR, Google Vision, Azure DI
+│   ├── llm/             # OpenAI, Anthropic, Mistral, Ollama
+│   ├── vlm/             # Adapters VLM (zero-shot)
+│   ├── corpus/          # IIIF, Gallica, HTR-United, HuggingFace
+│   ├── storage/         # ArtifactStore, JobStore
+│   └── legacy_engines/, legacy_modules/  # legacy BaseModule-based, en retrait
+├── app/                 # Layer 6 — services applicatifs (BenchmarkService, …)
+├── reports_v2/          # Layer 7 — rendu HTML / JSON / CSV (22 renderers + 5 vues)
+└── interfaces/          # Layer 8 — CLI Click, Web FastAPI
+
+# Arborescence legacy en cours de retrait (cf. docs/migration/) :
+# core/, measurements/, engines/, llm/, pipelines/, report/, modules/
 ```
 
+Règle d'import stricte : les flèches d'import vont uniquement
+de l'extérieur vers l'intérieur (de bas en haut dans le diagramme).
+Vérifié par `tests/architecture/test_layer_dependencies.py`.
+
 ## Guides d'extension
 
 - [Étendre le moteur narratif](narrative-engine.md) — ajouter un type

docs/developer/module-policy.md

@@ -14,7 +14,7 @@ qu'un module soit acceptable.
 
 Pour qu'un module soit acceptable :
 
-1. Il **hérite** de `picarones.core.modules.BaseModule` (Sprint 33).
+1. Il **hérite** de `picarones.domain.module_protocol.BaseModule` (Sprint 33).
 2. Il déclare ses `input_types` et `output_types` (parmi
    `ArtifactType.{IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER}`).
 3. Il fournit un `ModuleManifest` avec **5 champs obligatoires** :
@@ -80,11 +80,12 @@ manifest = ModuleManifest(
 ## Contrat `BaseModule`
 
 Tout module exécutable hérite de
-`picarones.core.modules.BaseModule` (Sprint 33). Le contrat minimal
+`picarones.domain.module_protocol.BaseModule` (Sprint 33). Le contrat minimal
 est :
 
 ```python
-from picarones.core.modules import ArtifactType, BaseModule
+from picarones.domain.artifacts import ArtifactType
+from picarones.domain.module_protocol import BaseModule
 
 class MyLlmCorrecteur(BaseModule):
     name = "my-llm-correcteur"

docs/explanation/architecture.md

@@ -0,0 +1,190 @@
+# Architecture Picarones — manifeste
+
+> **Audience** : développeurs et mainteneurs.  Ce document explique
+> *pourquoi* le code est organisé comme il l'est, pas seulement *où
+> sont les fichiers*.  Pour la liste exhaustive des modules, lire
+> directement le code — il est typé et documenté.
+
+## Deux arborescences cohabitent par design
+
+Le projet est en transition entre une arborescence **legacy** (héritée
+de la fondation 2025) et une arborescence **post-rewrite** (refondation
+ciblée S27-S46, 2026).  Cette cohabitation est explicite et finie dans
+le temps :
+
+| Arbo | Statut | Utilisation |
+|------|--------|-------------|
+| **Post-rewrite** | Canonique | **Tout nouveau code va ici.** |
+| **Legacy** | Transitionnel | Reste exécutable le temps que les callers externes (HuggingFace Space, scripts BnF, notebooks de chercheurs) migrent. |
+
+Le retrait du legacy est calendrier dans le CHANGELOG ; cf. aussi
+`docs/migration/rewrite-status-s46.md`.
+
+## Arbo canonique — 8 cercles concentriques
+
+```
+domain → formats → evaluation → pipeline → adapters → app → reports_v2 → interfaces
+```
+
+**Règle de dépendance stricte** : les flèches d'import vont uniquement
+de l'extérieur vers l'intérieur.  Vérifié par
+`tests/architecture/test_layer_dependencies.py`.  Aucun shim — un
+module a un seul emplacement canonique.
+
+### `picarones/domain/` — types purs
+
+Couche 1 (la plus interne).  Aucune dépendance d'exécution,
+aucun I/O, aucun framework.  Pydantic et stdlib uniquement.
+
+| Module | Contenu |
+|---|---|
+| `artifacts.py` | `Artifact`, `ArtifactType` (10 types : IMAGE, RAW_TEXT, ALTO_XML, PAGE_XML, ENTITIES, READING_ORDER, ALIGNMENT, CORRECTED_TEXT, CANONICAL_DOCUMENT, CONFIDENCES) |
+| `artifact_key.py` | `ArtifactKey` — clé canonique multi-paramètres pour la reprise par hash |
+| `corpus.py` | `CorpusSpec`, métadonnées de corpus |
+| `documents.py` | `DocumentRef`, `GroundTruthRef` |
+| `evaluation_spec.py` | `MetricSpec`, `EvaluationView`, `EvaluationSpec` |
+| `pipeline_spec.py` | `PipelineSpec`, `PipelineStep`, `INITIAL_STEP_ID` |
+| `projection_spec.py` | `ProjectionSpec` (transformation candidate avant évaluation) |
+| `provenance.py` | `ProvenanceRecord` |
+| `run_manifest.py` | `RunManifest` — empreinte immuable d'un run, sérialisée en `run_manifest.json` |
+| `errors.py` | Hiérarchie d'exceptions (`PicaronesError`, `AdapterStepError`, `ArtifactValidationError`, …) |
+
+### `picarones/formats/` — parsers et sérialiseurs
+
+Lecture/écriture des formats externes : ALTO XML, PAGE XML, texte
+normalisé.  Dépend du domain ; aucune logique d'évaluation.
+
+### `picarones/evaluation/` — moteurs d'évaluation
+
+| Sous-package | Rôle |
+|---|---|
+| `metrics/` | Métriques (CER/WER, philologiques, calibration, NER, layout…). Enregistrées via `@register_metric` au registre typé |
+| `projectors/` | Projections inter-types (ALTO → texte, canonical → texte) avec `ProjectionReport` |
+| `views/` | Vues d'évaluation : `TextView`, `AltoView`, `SearchView`.  L'`EvaluationViewExecutor` aligne candidate + GT, applique normalisation + projection, calcule les métriques |
+| `evaluation_engine.py` | Moteur central qui exécute une `EvaluationView` |
+| `projection_engine.py` | Moteur de projection |
+| `registry/` | `MetricRegistry` — découverte typée par signature `(input_type, output_type)` |
+
+### `picarones/pipeline/` — DAG d'étapes
+
+Orchestration mono-document d'une pipeline composée :
+
+| Module | Rôle |
+|---|---|
+| `executor.py` | `PipelineExecutor` — exécute un `PipelineSpec` step par step, capture `StepResult`, filtre outputs sur `step.output_types` |
+| `planner.py` | `PipelinePlanner` — résout les `inputs_from`, valide la spec, calcule les métriques aux jonctions |
+| `validation.py` | Validation statique d'une `PipelineSpec` (types s'enchaînent, pas de cycle) |
+| `runner.py` | `CorpusRunner` — orchestration corpus-wide avec ProcessPool/ThreadPool, backpressure, timeout, cancellation |
+| `cache.py`, `cache_helpers.py`, `cache_protocol.py` | Reprise par hash via `ArtifactCachePort` |
+| `yaml_io.py` | Sérialisation YAML déterministe d'une `PipelineSpec` |
+
+### `picarones/adapters/` — implémentations concrètes
+
+C'est ici que vivent les **dépendances externes** (pytesseract, pero,
+mistralai, openai, anthropic, google-cloud-vision, …).
+
+| Sous-package | Adapters |
+|---|---|
+| `ocr/` | TesseractAdapter, PeroOCRAdapter, MistralOCRAdapter, GoogleVisionAdapter, AzureDocIntelAdapter, PrecomputedTextAdapter |
+| `llm/` | AnthropicLLMAdapter, OpenAILLMAdapter, MistralLLMAdapter, OllamaLLMAdapter |
+| `vlm/` | AnthropicVLMAdapter, OpenAIVLMAdapter, MistralVLMAdapter, OllamaVLMAdapter (héritage multiple `BaseVLMAdapter + BaseLLMAdapter`, MRO guard) |
+| `corpus/` | local folder, IIIF, Gallica, HTR-United, HuggingFace Datasets, eScriptorium |
+| `storage/` | `InMemoryArtifactStore`, `FilesystemArtifactStore`, `JobStore` (SQLite) |
+| `output_paths.py` | Helper partagé `resolve_output_path` (workspace-aware, read-only-mount-safe) |
+| `_retry.py` | Helper partagé `call_with_retry` (3 retries, backoff 2/4/8s, sur 429+5xx+timeout réseau) |
+
+**Règle** : un adapter peut importer le domain et ses libs externes.
+Il ne doit **jamais** importer `app/` ou `interfaces/`.  Il n'a aucune
+logique d'évaluation (un OCR adapter ne calcule pas le CER — il
+produit un artefact texte que `evaluation/` consommera).
+
+### `picarones/app/` — services applicatifs
+
+Orchestration entre adapters et evaluation.
+
+| Module | Rôle |
+|---|---|
+| `services/run_orchestrator.py` | `RunOrchestrator.execute(RunSpec)` — point d'entrée d'un run complet |
+| `services/benchmark_service.py` | `BenchmarkService.run` — exécute pipelines × vues × corpus, produit `RunResult` |
+| `services/job_runner.py` | `JobRunner` — soumission asynchrone (thread daemon) avec persistance `JobStore` |
+| `services/corpus_service.py` | Loading + sandboxing + extraction ZIP avec zip-slip protection |
+| `services/dependencies.py` | `capture_dependencies_lock()` via `importlib.metadata` pour le `RunManifest` |
+| `services/path_security.py` | `WorkspaceManager` — sandboxe par session |
+| `services/registry_service.py` | Découverte des adapters et vues canoniques |
+| `schemas/run_spec.py` | `RunSpec`, `StepSpec` — modèles YAML user-facing |
+| `results.py` | `RunResult`, `RunDocumentResult`, `ReportRenderer` (alias type unique) |
+
+### `picarones/reports_v2/` — rendu déterministe
+
+| Sous-package | Rôle |
+|---|---|
+| `csv/render.py` | `CsvReportRenderer` — un CSV plat (`run_id, doc, pipeline, view, metric, value, status`) |
+| `json/render.py` | `JsonReportRenderer` — manifest + documents en JSON déterministe |
+| `html/render.py` | `HtmlReportRenderer` — rapport autonome (TextView, AltoView, SearchView) |
+
+Le rendu est strict : pas de JS dynamique, pas d'I/O, déterministe
+bit-for-bit à entrée constante.  Permet à un relecteur 5 ans plus tard
+de hasher un rapport et de le citer.
+
+### `picarones/interfaces/` — points d'entrée user-facing
+
+| Sous-package | Rôle |
+|---|---|
+| `cli/` | Click — `picarones-rewrite run`, `import_corpus`, `report` |
+| `web/` | FastAPI — skeleton, routers (corpus, benchmark, jobs), middlewares de sécurité |
+
+## Arbo legacy — `picarones/{cli,web,engines,llm,pipelines,report,measurements,extras,modules,core}/`
+
+Reste exécutable.  Ne pas y ajouter de nouveau code.  Une partie est
+re-exportée depuis l'arbo canonique via des shims dépréciés (cf.
+`picarones/pipeline/spec.py`, alias `DEFAULT_*_PROMPT` singuliers
+dans `BaseLLMAdapter`/`BaseVLMAdapter`) qui émettent
+`DeprecationWarning` à l'usage.  Suppression effective prévue en 2.0.
+
+## Principes architecturaux
+
+### Pas de shim hors deprecation period
+
+Un module a un seul emplacement canonique.  Quand un module migre,
+on choisit explicitement entre :
+
+- **Suppression dure** (pour la dette interne, pas de caller externe).
+- **Shim avec `DeprecationWarning`** (pour la stabilité d'API publique).
+  Le shim a une date de retrait inscrite dans le CHANGELOG.
+
+### Pas d'`except Exception: pass`
+
+Toute fonctionnalité optionnelle qui échoue émet un
+`logger.warning("[module] feature dégradée : %s", exc)` avec contexte.
+Vérifié par `tests/architecture/test_no_side_effect_imports.py`.
+
+### Tests architecturaux comme garde-fous
+
+Plusieurs tests verrouillent des invariants structurels que la revue
+de code humaine raterait :
+
+- `test_layer_dependencies.py` — circles strictement orientés
+- `test_file_budgets.py` — pas de god-modules
+- `test_doc_paths.py` — chemins cités dans la doc existent
+- `test_output_paths_uniformity.py` — tous les adapters passent par `resolve_output_path`
+- `test_storage_keys_filesystem_safe.py` — clés du store filesystem-safe (Windows)
+- `test_manifest_reproducibility.py` — `RunManifest` capture tout pour rejouer
+- `test_module_coverage.py` — chaque module a un test associé
+
+### Reproductibilité bit-for-bit
+
+Le `RunManifest` capture systématiquement : `code_version`,
+`pipeline_specs` complets, `adapter_kwargs`, `dependencies_lock`
+(via `importlib.metadata`), `view_specs`, timestamps.  La
+sérialisation est déterministe (Pydantic ordered fields, JSON
+sorted keys).  Le hash du manifest peut être cité dans une
+publication scientifique.
+
+## Évolution
+
+L'évolution de l'architecture est documentée :
+
+- Plans : [`docs/roadmap/evolution-2026.md`](../roadmap/evolution-2026.md)
+- État du rewrite : [`docs/migration/rewrite-status-s46.md`](../migration/rewrite-status-s46.md)
+- Audits institutionnels : [`docs/audits/`](../audits/)
+- Politique d'API publique : [`docs/reference/api-stable.md`](../reference/api-stable.md)

docs/{developer → explanation}/narrative-engine.en.md

@@ -1,5 +1,5 @@
 <!-- translation: machine + human review pending -->
-<!-- canonical: docs/developer/narrative-engine.md (FR) -->
+<!-- canonical: docs/explanation/narrative-engine.md (FR) -->
 
 # Extending the narrative engine
 
@@ -13,7 +13,7 @@ contradiction), and renders them through YAML templates with
 
 ## Add a new detector in 5 steps
 
-### 1. Add a `FactType` in `picarones/core/facts.py`
+### 1. Add a `FactType` in `picarones/domain/facts.py`
 
 ```python
 class FactType(str, Enum):

docs/{cli-workflows.md → how-to/cli-workflows.md}

@@ -216,5 +216,5 @@ pour découvrir la sortie sans corpus réel.
   run, diagnose, economics, edition, compare + helper `_run_workflow`.
 - [`picarones/cli/_pipeline.py`](../picarones/cli/_pipeline.py) —
   pipeline group.
-- Voir aussi [`docs/profiles.md`](profiles.md) et
-  [`docs/views.md`](views.md).
+- Voir aussi [`docs/reference/normalization-profiles.md`](profiles.md) et
+  [`docs/reference/views.md`](views.md).

INSTALL.md → docs/how-to/install.md

@@ -1,7 +1,13 @@
 # Guide d'installation — Picarones
 
 > Guide détaillé pour Linux, macOS et Windows.
-> Pour une installation en 5 minutes : voir [README.md](README.md#installation-rapide).
+> Pour une installation en 5 minutes, voir le bloc *Setup* du
+> [README](../../README.md).
+>
+> Audience : opérateur ou développeur qui installe Picarones en
+> local ou sur un serveur.  Pour un déploiement institutionnel
+> (BnF, LoC, BL), voir aussi
+> [`../operations/deployment-institutional.md`](../operations/deployment-institutional.md).
 
 ---
 
@@ -236,19 +242,7 @@ config_path: /path/to/pero_model/config.yaml
 EOF
 ```
 
-### 5.3 Kraken (optionnel)
-
-```bash
-pip install kraken
-
-# Télécharger un modèle
-kraken get 10.5281/zenodo.XXXXXXX
-
-# Lister les modèles installés
-kraken list
-```
-
-### 5.4 Ollama (LLMs locaux)
+### 5.3 Ollama (LLMs locaux)
 
 ```bash
 # Installer Ollama
@@ -290,11 +284,6 @@ MISTRAL_API_KEY=...
 # Google Vision
 GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
 
-# AWS Textract
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-AWS_DEFAULT_REGION=eu-west-1
-
 # Azure Document Intelligence
 AZURE_DOC_INTEL_ENDPOINT=https://...cognitiveservices.azure.com/
 AZURE_DOC_INTEL_KEY=...

docs/index.md

@@ -0,0 +1,160 @@
+# Documentation Picarones — index par rôle
+
+> **Architecture documentaire** : ce projet adopte le modèle
+> [Diataxis](https://diataxis.fr/) — quatre quadrants :
+> *tutorials* (apprendre), *how-to* (résoudre), *reference*
+> (consulter), *explanation* (comprendre).  Plus deux dossiers
+> institutionnels : *governance* et *operations*.
+>
+> **Bilingue** : la **langue canonique est le français**.  Une
+> surface publique réduite est traduite en anglais — README,
+> CONTRIBUTING, SECURITY, ACCESSIBILITY, deux tutoriels clés.
+> Le reste reste FR.  Politique assumée plutôt que bilingue partiel
+> brouillé.
+
+---
+
+## Je suis…
+
+### …un chercheur ou archiviste qui veut benchmarker un corpus
+
+Vous voulez exécuter Picarones sur vos documents, lire un rapport,
+comprendre les chiffres.
+
+1. Installer : [`how-to/install.md`](how-to/install.md)
+2. Premier benchmark : [`tutorials/first-benchmark.md`](tutorials/first-benchmark.md)
+3. Lire le rapport produit : [`tutorials/reading-a-report.md`](tutorials/reading-a-report.md)
+   ([EN](tutorials/reading-a-report.en.md))
+4. Cas d'école pédagogiques : [`case-studies/`](case-studies/)
+5. Glossaire des métriques : [`reference/normalization-profiles.md`](reference/normalization-profiles.md),
+   [`reference/views.md`](reference/views.md)
+
+### …un opérateur qui doit déployer en environnement institutionnel
+
+Vous installez Picarones sur un NAS BnF, un cluster LoC, un serveur BL.
+
+1. Déploiement institutionnel : [`operations/deployment-institutional.md`](operations/deployment-institutional.md)
+2. Conformité RGPD : [`operations/data-retention-rgpd.md`](operations/data-retention-rgpd.md)
+3. Runbook incidents : [`operations/runbook.md`](operations/runbook.md)
+4. Observabilité (logs, métriques, alerting) : [`operations/observability.md`](operations/observability.md)
+5. Process de release : [`operations/release-process.md`](operations/release-process.md)
+
+### …un développeur qui veut contribuer du code
+
+Vous ajoutez un adapter, une vue, une métrique, un détecteur narratif.
+
+1. Vue d'ensemble du projet : [`/CONTRIBUTING.md`](../CONTRIBUTING.md)
+   ([EN](../CONTRIBUTING.en.md))
+2. Architecture en cercles : [`explanation/architecture.md`](explanation/architecture.md)
+3. Politique modules contribués : [`developer/module-policy.md`](developer/module-policy.md)
+4. Étendre un sous-système :
+   [glossaire](developer/extending-glossary.md) ([EN](developer/extending-glossary.en.md)) ·
+   [i18n](developer/extending-i18n.md) ([EN](developer/extending-i18n.en.md)) ·
+   [moteur narratif](developer/narrative-engine.md) ([EN](developer/narrative-engine.en.md))
+5. Écrire un module pour le banc d'essai : [`user/writing-a-pipeline-module.md`](user/writing-a-pipeline-module.md)
+
+### …un mainteneur ou auditeur de sécurité
+
+Vous évaluez Picarones avant un déploiement, un audit, une revue.
+
+1. Politique de gouvernance : [`/GOVERNANCE.md`](../GOVERNANCE.md)
+2. Politique de sécurité : [`/SECURITY.md`](../SECURITY.md)
+   ([EN](../SECURITY.en.md))
+3. Threat model STRIDE : [`security/threat-model.md`](security/threat-model.md)
+4. API publique stable et politique de versioning : [`reference/api-stable.md`](reference/api-stable.md)
+5. Audits historiques : [`audits/`](audits/)
+6. État du rewrite et migration : [`migration/rewrite-status-s46.md`](migration/rewrite-status-s46.md)
+7. Reproductibilité bit-for-bit : [`reference/reproducibility-snapshots.md`](reference/reproducibility-snapshots.md)
+
+### …un Délégué à la Protection des Données (DPO)
+
+Vous évaluez les implications RGPD avant signature.
+
+1. Politique de rétention RGPD : [`operations/data-retention-rgpd.md`](operations/data-retention-rgpd.md)
+2. Modèle d'accord de sous-traitance (DPA) : [`legal/dpa-template.md`](legal/dpa-template.md)
+3. Threat model : [`security/threat-model.md`](security/threat-model.md)
+4. Liste des sous-traitants potentiels (services cloud) :
+   `pricing.yaml` + section *Adapters cloud* dans
+   [`reference/api-stable.md`](reference/api-stable.md)
+
+---
+
+## Index thématique
+
+### Tutorials — j'apprends
+
+| Document | Public | Langue |
+|----------|--------|--------|
+| [`tutorials/first-benchmark.md`](tutorials/first-benchmark.md) | Chercheur découvrant l'outil | FR |
+| [`tutorials/reading-a-report.md`](tutorials/reading-a-report.md) | Chercheur lisant un rapport | FR + EN |
+| [`tutorials/writing-a-pipeline-module.md`](tutorials/writing-a-pipeline-module.md) | Développeur tiers | FR |
+
+### How-to — je résous un problème concret
+
+| Document | Cible |
+|----------|-------|
+| [`how-to/install.md`](how-to/install.md) | Installer en local ou serveur |
+| [`how-to/cli-workflows.md`](how-to/cli-workflows.md) | Utiliser la CLI au quotidien |
+
+### Reference — je consulte le contrat
+
+| Document | Sujet |
+|----------|-------|
+| [`reference/api-stable.md`](reference/api-stable.md) | API Python publique + politique semver |
+| [`reference/views.md`](reference/views.md) | Vues d'évaluation (text, alto, search) |
+| [`reference/normalization-profiles.md`](reference/normalization-profiles.md) | Profils de normalisation textuelle |
+| [`reference/reproducibility-snapshots.md`](reference/reproducibility-snapshots.md) | Reproductibilité bit-for-bit |
+
+### Explanation — je comprends pourquoi
+
+| Document | Sujet |
+|----------|-------|
+| [`explanation/architecture.md`](explanation/architecture.md) | Architecture en cercles, principes |
+| [`explanation/narrative-engine.md`](explanation/narrative-engine.md) | Comment le moteur narratif fonctionne |
+
+### Operations — je déploie et j'opère
+
+| Document | Sujet |
+|----------|-------|
+| [`operations/deployment-institutional.md`](operations/deployment-institutional.md) | Déploiement institutionnel |
+| [`operations/runbook.md`](operations/runbook.md) | Réponse aux incidents |
+| [`operations/observability.md`](operations/observability.md) | Logs, métriques, alerting |
+| [`operations/data-retention-rgpd.md`](operations/data-retention-rgpd.md) | Conformité RGPD |
+| [`operations/release-process.md`](operations/release-process.md) | Cycle de release |
+
+### Governance / security / legal
+
+| Document | Sujet |
+|----------|-------|
+| [`/GOVERNANCE.md`](../GOVERNANCE.md) | Gouvernance |
+| [`/SECURITY.md`](../SECURITY.md) | Sécurité (FR + EN) |
+| [`/CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) | Code de conduite |
+| [`/ACCESSIBILITY.md`](../ACCESSIBILITY.md) | Accessibilité |
+| [`security/threat-model.md`](security/threat-model.md) | Threat model STRIDE |
+| [`legal/dpa-template.md`](legal/dpa-template.md) | DPA RGPD §28 |
+
+### Archives et historique
+
+| Document | Sujet |
+|----------|-------|
+| [`/CHANGELOG.md`](../CHANGELOG.md) | Journal des versions (Keep-a-Changelog) |
+| [`audits/`](audits/) | Audits historiques figés |
+| [`migration/`](migration/) | Notes de migration entre versions majeures |
+| [`roadmap/`](roadmap/) | Plans stratégiques |
+
+---
+
+## Conventions
+
+- **Une seule arborescence canonique post-rewrite** :
+  `domain → formats → evaluation → pipeline → adapters → app → reports_v2 → interfaces`.
+  L'arbo legacy `picarones/{cli,web,engines,llm,pipelines,report}/`
+  reste exécutable mais n'accepte plus de nouveau code.
+- **Tout chemin `picarones/.../X.py` cité dans la doc doit exister**.
+  Vérifié par `tests/architecture/test_doc_paths.py` (baseline 73,
+  doit décroître).
+- **Les chiffres en prose qui dépendent de l'état du code** (compte
+  de tests, nombre d'adapters) sont régénérés par
+  `scripts/gen_readme_tables.py` — modifier le code, pas la doc.
+- **Cohérence FR/EN** : un fichier `xxx.md` en FR + un fichier
+  `xxx.en.md` en EN miroir.  Pas de fragments mêlés.

docs/legal/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,155 @@
+# Third-party licenses
+
+> **Audience** : équipe juridique, DSI institutionnelle, mainteneur
+> de release.  Audit des licences des dépendances tierces utilisées
+> par Picarones, requis par Apache 2.0 §4(d) et par les politiques
+> d'achat institutionnelles (BnF, LoC, BL).
+>
+> **Régénération** : ce fichier est censé être régénéré à chaque
+> release par `scripts/gen_third_party_licenses.py` (à venir, cf.
+> [`docs/roadmap/backlog.md`](../roadmap/backlog.md)).  Tant que le
+> script n'existe pas, mise à jour manuelle au moment de la release.
+>
+> **Date du dernier rafraîchissement** : 2026-05.
+
+## Politique générale
+
+Picarones est distribué sous **Apache License 2.0**.  Cette licence
+est compatible avec toutes les licences listées ci-dessous (MIT, BSD,
+PSF, Apache 2.0 elles-mêmes ; pas de dépendance GPL/LGPL/AGPL en
+runtime).
+
+Les dépendances optionnelles (extras `[mistral]`, `[anthropic]`,
+`[openai]`, `[ollama]`, `[google]`, `[azure]`, `[hf]`, `[escriptorium]`,
+`[iiif]`, `[stats]`, `[ner]`) ne sont chargées qu'à la demande de
+l'utilisateur ; elles n'affectent pas la licence du distribué de base.
+
+## Dépendances de runtime (cœur)
+
+| Paquet | Licence | Copyright | Usage |
+|--------|---------|-----------|-------|
+| [click](https://palletsprojects.com/p/click/) | BSD-3-Clause | © Pallets | CLI |
+| [jiwer](https://github.com/jitsi/jiwer) | Apache-2.0 | © 8x8, Inc. | CER / WER |
+| [Pillow](https://python-pillow.org/) | HPND (MIT-style) | © Jeffrey A. Clark + Pillow contributors | Images |
+| [PyYAML](https://pyyaml.org/) | MIT | © Kirill Simonov | YAML |
+| [pytesseract](https://github.com/madmaze/pytesseract) | Apache-2.0 | © Matthias A. Lee | OCR Tesseract wrapper |
+| [tqdm](https://tqdm.github.io/) | MIT + MPL-2.0 | © tqdm contributors | Barres de progression |
+| [numpy](https://numpy.org/) | BSD-3-Clause | © NumPy developers | Calculs numériques |
+| [jinja2](https://palletsprojects.com/p/jinja/) | BSD-3-Clause | © Pallets | Templating HTML |
+| [defusedxml](https://github.com/tiran/defusedxml) | PSF-2.0 | © Christian Heimes | Parsing XML sécurisé |
+| [pydantic](https://docs.pydantic.dev/) | MIT | © Samuel Colvin and contributors | Modèles immuables |
+
+## Dépendances de runtime — extras
+
+### `[web]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [fastapi](https://fastapi.tiangolo.com/) | MIT | API web |
+| [uvicorn](https://www.uvicorn.org/) | BSD-3-Clause | Serveur ASGI |
+| [python-multipart](https://github.com/Kludex/python-multipart) | Apache-2.0 | Upload form-data |
+| [starlette](https://www.starlette.io/) | BSD-3-Clause | (transitif via FastAPI) |
+| [httpx](https://www.python-httpx.org/) | BSD-3-Clause | Client HTTP (tests) |
+
+### `[mistral]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [mistralai](https://github.com/mistralai/client-python) | Apache-2.0 | SDK Mistral OCR + chat/vision |
+
+### `[anthropic]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [anthropic](https://github.com/anthropics/anthropic-sdk-python) | MIT | SDK Claude |
+
+### `[openai]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [openai](https://github.com/openai/openai-python) | Apache-2.0 | SDK OpenAI |
+
+### `[ollama]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [ollama](https://github.com/ollama/ollama-python) | MIT | Client Ollama local |
+
+### `[google]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [google-cloud-vision](https://github.com/googleapis/python-vision) | Apache-2.0 | OCR Google Vision |
+
+### `[azure]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [azure-ai-documentintelligence](https://github.com/Azure/azure-sdk-for-python) | MIT | OCR Azure DI |
+
+### `[hf]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [datasets](https://github.com/huggingface/datasets) | Apache-2.0 | Datasets HuggingFace |
+| [huggingface-hub](https://github.com/huggingface/huggingface_hub) | Apache-2.0 | Hub HuggingFace |
+
+### `[ner]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [spacy](https://spacy.io/) | MIT | NER |
+
+### `[stats]`
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| [scipy](https://scipy.org/) | BSD-3-Clause | Tests statistiques (Friedman, Nemenyi) |
+
+## Dépendances de développement
+
+Les paquets utilisés uniquement en développement (tests, lint,
+sécurité) ne sont pas redistribués avec Picarones et n'apparaissent
+dans aucun wheel.  Pour traçabilité supply-chain :
+
+| Paquet | Licence | Usage |
+|--------|---------|-------|
+| pytest | MIT | Tests unitaires |
+| pytest-cov | MIT | Couverture |
+| pytest-timeout | MIT | Timeout par test |
+| ruff | MIT | Lint |
+| mypy | MIT | Type checking |
+| bandit | Apache-2.0 | Audit sécurité statique |
+| pip-audit | Apache-2.0 | Audit CVE des dépendances |
+
+## Modèles tiers
+
+Picarones n'embarque **aucun modèle tiers** dans ses wheels.  Les
+modèles sont :
+
+- soit **téléchargés à l'usage** par l'utilisateur (Tesseract `*.traineddata`,
+  Pero OCR via Zenodo, modèles spaCy via `python -m spacy download`) ;
+- soit **invoqués via des APIs cloud** sous le contrat du fournisseur
+  (Mistral AI, Anthropic, OpenAI, Google, Azure).
+
+Les conditions d'utilisation de chaque modèle / API sont à la charge
+de l'utilisateur et de l'institution déployant Picarones.
+
+## Police d'écriture / fontes
+
+Picarones n'embarque aucune fonte.  Les rapports HTML utilisent les
+fontes système du navigateur.
+
+## Données
+
+Aucun corpus, aucune image, aucune vérité terrain n'est embarquée
+dans les wheels.  Les fixtures de test (`tests/fixtures/`) sont
+synthétiques (générées) ou citées depuis leur source originale (cf.
+`tests/fixtures/reference_corpus/README.md`).
+
+## Comment signaler une omission
+
+Une dépendance manquante, une licence incorrecte, un copyright
+mal attribué : ouvrir une issue avec le label `legal` ou écrire à
+l'adresse de contact dans [`/SECURITY.md`](../../SECURITY.md).  Une
+correction sera publiée dans la prochaine release patch.

docs/legal/dpa-template.md

@@ -0,0 +1,218 @@
+# Modèle d'Accord de Sous-Traitance (DPA)
+
+> **Audience** : Délégué à la Protection des Données (DPO) de
+> l'institution déployant Picarones, équipe juridique de cette même
+> institution, mainteneur du projet.
+>
+> **Statut** : modèle de référence — à adapter et à signer entre
+> l'institution (responsable de traitement) et chaque sous-traitant
+> activé via les adapters cloud.  Ce document **n'est pas un contrat
+> en lui-même** ; il définit les clauses minimales à inclure.
+>
+> **Référence légale** : Article 28 du Règlement (UE) 2016/679 (RGPD),
+> [version consolidée](https://eur-lex.europa.eu/eli/reg/2016/679/oj).
+
+## Pourquoi un DPA ?
+
+Lorsqu'une institution patrimoniale (BnF, LoC, BL) déploie Picarones
+en activant des adapters cloud (Mistral OCR, OpenAI, Anthropic,
+Google Vision, Azure Document Intelligence), elle envoie des
+documents qui peuvent contenir des **données à caractère personnel**
+(PII) — typiquement :
+
+- Registres d'état civil (naissances, mariages, décès).
+- Recensements (noms, adresses, professions).
+- Correspondance personnelle (lettres privées, journaux).
+- Notes manuscrites avec mentions nominatives.
+
+L'envoi de ces données à un tiers (le fournisseur cloud) constitue
+une **sous-traitance** au sens RGPD §28 ; un accord écrit (DPA) est
+**obligatoire** entre l'institution (responsable de traitement) et
+chaque sous-traitant.
+
+## Périmètre
+
+Ce modèle couvre la sous-traitance des opérations de transcription
+OCR/HTR effectuées par des services cloud activés par l'institution
+via Picarones.  **Il ne couvre pas** :
+
+- Le déploiement Picarones lui-même (l'institution est seule
+  responsable de l'instance).
+- Les adapters locaux (Tesseract, Pero OCR, Ollama) qui n'envoient
+  rien à l'extérieur.
+
+## Clauses minimales (RGPD §28.3)
+
+### 1. Objet et durée du traitement
+
+Transcription automatique de documents numérisés via OCR, HTR ou VLM
+cloud, pour la durée du marché entre l'institution et le fournisseur.
+
+### 2. Nature et finalité du traitement
+
+- **Nature** : envoi d'images de documents et/ou de fragments de
+  texte ; réception de transcriptions textuelles ou de descriptions
+  structurées (ALTO, JSON canonique).
+- **Finalité** : fournir à l'institution un benchmark comparatif de
+  pipelines OCR/HTR sur son corpus, dans le cadre d'une évaluation
+  technique préalable à un déploiement de production.
+
+### 3. Type de données à caractère personnel
+
+Selon le corpus envoyé.  L'institution **doit identifier en amont**
+si le corpus contient :
+
+- Données nominatives (noms, prénoms, dates de naissance/décès…).
+- Données sensibles au sens RGPD §9 (origine raciale ou ethnique,
+  opinions politiques, convictions religieuses, données de santé,
+  orientation sexuelle…).
+
+Pour les corpus sensibles, l'institution **doit privilégier les
+adapters locaux** (Tesseract, Pero OCR, Ollama) ou anonymiser le
+corpus avant envoi.
+
+### 4. Catégories de personnes concernées
+
+- Personnes citées dans les documents historiques (typiquement
+  défuntes, sauf mention contraire).
+- Auteurs ou correspondants des documents.
+
+### 5. Obligations du sous-traitant
+
+Le sous-traitant cloud s'engage à :
+
+a) ne traiter les données que sur **instruction documentée** du
+   responsable (l'institution).  Pas de réutilisation pour
+   entraînement de modèles, sauf consentement explicite (cf. §10).
+
+b) garantir que les **personnes autorisées** à traiter les données
+   sont soumises à une obligation de confidentialité.
+
+c) mettre en œuvre les **mesures de sécurité** énumérées au RGPD
+   §32 (chiffrement en transit, contrôle d'accès, journalisation,
+   tests réguliers).
+
+d) ne pas recourir à un **autre sous-traitant** sans autorisation
+   écrite préalable et spécifique du responsable.
+
+e) **assister** le responsable dans la réponse aux demandes
+   d'exercice de droits (accès, rectification, effacement…) et dans
+   les obligations de notification de violations.
+
+f) **supprimer ou retourner** les données à la fin de la prestation,
+   sauf obligation légale de conservation.
+
+g) mettre à disposition du responsable toutes les **informations
+   nécessaires** pour démontrer la conformité au §28.
+
+### 6. Localisation des traitements
+
+L'institution **doit privilégier** les fournisseurs offrant un
+hébergement et un traitement strictement dans l'Espace économique
+européen (EEE).
+
+| Adapter | Localisation par défaut | Disponibilité EEE |
+|---------|------------------------|-------------------|
+| Mistral OCR / chat | France (cf. [Mistral Trust](https://mistral.ai/security/)) | Oui |
+| OpenAI | États-Unis | EU residency dispo via Enterprise |
+| Anthropic Claude | États-Unis | EU residency limitée |
+| Google Vision | Multi-régions | EEE configurable |
+| Azure Document Intelligence | Multi-régions | EEE configurable |
+
+Pour un transfert hors EEE, **clauses contractuelles types** (CCT)
+2021/914/UE applicables OBLIGATOIRES.
+
+### 7. Sécurité
+
+Mesures minimales :
+
+- Chiffrement TLS 1.2+ en transit.
+- Pas d'enregistrement des prompts/réponses pour entraînement
+  (option à activer côté fournisseur, cf. §10).
+- Logs d'accès conservés < 30 jours sauf incident de sécurité.
+- Tests de pénétration au moins annuels (à charge du sous-traitant).
+
+### 8. Sous-sous-traitance
+
+Liste des sous-sous-traitants autorisés à fournir au démarrage et à
+chaque modification.  L'institution dispose d'un droit d'objection
+à toute nouvelle sous-sous-traitance.
+
+### 9. Audit
+
+L'institution se réserve le droit, à ses frais et avec préavis
+raisonnable (30 jours), de conduire un audit du sous-traitant ou de
+mandater un tiers indépendant pour vérifier la conformité des
+mesures techniques et organisationnelles.
+
+### 10. Réutilisation pour entraînement de modèles
+
+**Disposition critique** pour le patrimoine numérique : les
+documents envoyés sont la propriété intellectuelle de l'institution
+(et parfois du domaine public) ; les fournisseurs ne doivent **PAS**
+les utiliser pour entraîner leurs modèles sans accord écrit.
+
+Configuration recommandée par fournisseur :
+
+| Fournisseur | Comment opt-out |
+|-------------|------------------|
+| OpenAI | Compte Enterprise ou via API avec `data_retention=zero` |
+| Anthropic | Compte Enterprise ; pas d'option opt-out sur API standard |
+| Mistral | API Enterprise tier ; opt-out par défaut sur certains plans |
+| Google Vision | Activer Workspace Data Loss Prevention |
+| Azure | Activer "Customer-Managed Keys" + opt-out training |
+
+### 11. Notification de violation
+
+Le sous-traitant s'engage à notifier l'institution **dans les 24
+heures** de la connaissance d'une violation de données à caractère
+personnel les concernant, par e-mail ET courrier signé.
+
+### 12. Effacement à fin de prestation
+
+À la fin du marché ou à la résiliation, le sous-traitant restitue
+ou supprime toutes les données dans un délai de 30 jours, et
+fournit une **attestation de destruction**.
+
+## Annexes
+
+### Annexe 1 — Description du traitement
+
+À compléter par l'institution :
+
+- [ ] Nom du corpus traité
+- [ ] Volume estimé (nombre de documents, taille en GB)
+- [ ] Période de traitement (du / au)
+- [ ] Liste des adapters cloud activés
+- [ ] Volume de PII estimé dans le corpus
+
+### Annexe 2 — Mesures de sécurité
+
+À compléter par le sous-traitant — référence :
+[ANSSI Référentiel Général de Sécurité](https://www.ssi.gouv.fr/).
+
+### Annexe 3 — Liste des sous-sous-traitants autorisés
+
+À compléter par le sous-traitant.
+
+## Procédure de signature
+
+1. L'institution remplit les annexes en fonction du corpus prévu.
+2. Le DPO de l'institution valide la liste des adapters cloud
+   activés (`AdapterRegistry`).
+3. Le contrat est signé par les deux parties (institution +
+   fournisseur cloud) AVANT activation de l'adapter en production.
+4. Une copie est conservée dans le dossier de conformité du
+   traitement (durée minimale : 5 ans après la fin du traitement).
+
+## Référence légale
+
+- [Règlement (UE) 2016/679 — RGPD](https://eur-lex.europa.eu/eli/reg/2016/679/oj)
+- [Lignes directrices CEPD sur les sous-traitants](https://edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-072020-concepts-controller-and-processor-gdpr_fr)
+- [Décision d'adéquation EU-US Data Privacy Framework (2023)](https://commission.europa.eu/document/fa09cbad-dd7d-4684-ace5-c1e932f3eda7_en)
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (S60), modèle aligné RGPD §28 |

docs/migration/SESSION_HANDOVER.md

@@ -0,0 +1,508 @@
+# Handover entre sessions Claude Code
+
+> Ce document est lu en premier par chaque nouvelle session pour
+> reprendre le travail sans se tromper.  Il pointe vers les
+> sources de vérité, signale les pièges connus, et donne la
+> prochaine action concrète.
+
+---
+
+## 0. Principe directeur (mis à jour 2026-05)
+
+**Suppression agressive, pas de shim qui survit à son usage.**
+
+- Le projet est en stand-by jusqu'à la fin de la migration
+  complète.  Personne (ni externe ni HuggingFace Space) ne
+  consommera l'API legacy avant cette fin.
+- Pas de préservation de l'API publique : breaking changes
+  acceptés.
+- Dès qu'un caller migre vers le canonique, son shim est
+  **supprimé** (pas conservé pour un usage hypothétique).
+- Tout symbole legacy public doit être tracé dans
+  ``tests/architecture/test_legacy_canonical_parity.py`` :
+  `canonical: ...` (équivalent canonique existe), `dropped: ...`
+  (volontairement abandonné, justifié), ou `unmigrated: ...`
+  (cible prévue, en cours).
+
+Le test ``test_legacy_canonical_parity`` garantit qu'**aucune
+fonctionnalité legacy n'est silencieusement perdue** au cours
+de la migration.  C'est le journal de bord vivant.
+
+---
+
+## 1. Sources de vérité (par ordre de priorité)
+
+1. **[`legacy-retirement-plan.md`](legacy-retirement-plan.md)** —
+   plan maître des Phases 0-11 du retrait du legacy.  Chaque
+   phase a un statut explicite (✅ terminée / ⏳ en cours / 📋 à
+   venir).
+2. **[`pipeline-convergence-plan.md`](pipeline-convergence-plan.md)** —
+   sous-plan détaillé de la convergence ``BaseModule`` /
+   ``PipelineRunner`` → ``StepExecutor`` / ``PipelineExecutor``
+   (Sub-phases 7.A-7.D).
+3. **[`../../tests/architecture/test_legacy_canonical_parity.py`](../../tests/architecture/test_legacy_canonical_parity.py)** —
+   journal vivant de la migration : table 3-états des symboles
+   legacy avec leur équivalent canonique.  À mettre à jour à
+   chaque migration.
+4. **[`../../CLAUDE.md`](../../CLAUDE.md)** — règles d'architecture
+   à respecter, statut de la migration, et liens vers le reste.
+5. **`git log --oneline -10`** — les 10 derniers commits
+   donnent l'état réel.  Le dernier commit message décrit
+   souvent la prochaine sub-phase à exécuter.
+
+---
+
+## 2. Vérifications avant de toucher au code
+
+```bash
+# 1. Bonne branche ?
+git branch --show-current
+# → doit retourner: claude/repo-analysis-cukvm
+
+# 2. Working tree propre ?
+git status
+# → doit retourner: nothing to commit, working tree clean
+
+# 3. Tests verts à l'état initial ?
+python -m pytest tests/ -q --no-header --tb=line
+# → doit retourner: 5085 passed (au moment de la pause de session)
+
+# 4. Lint vert ?
+ruff check picarones/ tests/
+# → doit retourner: All checks passed!
+```
+
+Si l'une de ces vérifications échoue : **NE PAS** continuer le
+sprint.  Investiguer d'abord pourquoi l'état initial diverge de
+celui annoncé dans CLAUDE.md.
+
+---
+
+## 3. Pièges connus (apprentissages des phases précédentes)
+
+### 3.A Architecture des couches
+
+Voir CLAUDE.md section « Règles d'architecture critiques ».
+Résumé :
+
+- ``evaluation/`` ne peut pas importer ``pipeline.types`` —
+  c'est l'autre sens.
+- ``evaluation/`` whitelist limitée : pas de pytesseract /
+  mistralai / azure / google / pero_ocr.  Ces libs externes
+  vont dans ``adapters/``.
+- ``reports_v2/`` ne peut importer que les canoniques
+  (``evaluation/metrics/``), pas les shims legacy
+  (``measurements/X.py``).
+
+### 3.B Pattern shim — UNIQUEMENT TRANSITOIRE
+
+⚠️ **Principe** : un shim n'existe que pour la durée d'un
+sprint.  Dès que tous ses consommateurs ont migré, il est
+**supprimé**.
+
+Pour un shim minimal (transitoire) :
+
+```python
+"""``picarones.X.Y`` — shim re-export (déprécié, suppression imminente).
+
+Canonique : :mod:`picarones.canonical.path`.  Phase X.Y du
+retrait du legacy.  Ce shim disparaît dès que tous les callers
+auront migré (généralement dans le commit suivant).
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from picarones.canonical.path import *  # noqa: F401, F403
+# Si des callers consomment des noms privés (_FOO, etc.),
+# les ré-exporter explicitement :
+from picarones.canonical.path import _FOO  # noqa: F401
+
+warnings.warn(
+    "picarones.X.Y is deprecated and will be removed in 2.0.  "
+    "Import from picarones.canonical.path instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+```
+
+**Avant de créer un shim**, demandez-vous : « est-ce que je peux
+juste migrer tous les callers maintenant et supprimer le legacy
+en bloc ? »  Si oui, faites-le — pas de shim intermédiaire.
+
+### 3.C ``test_module_coverage::TEST_ONLY_BASELINE``
+
+Quand un shim ``measurements/X.py`` n'a plus de consommateur
+production (parce qu'un renderer a migré vers le canonique
+direct), ajouter ``"X"`` à ``TEST_ONLY_BASELINE`` dans
+``tests/architecture/test_module_coverage.py``.  Sinon le test
+``test_no_new_test_only_modules`` échoue.
+
+### 3.D ``test_file_budgets``
+
+Tout fichier ≥ 400 LOC doit avoir une entrée dans
+``FILE_BUDGETS`` avec budget = LOC actuel + ~15 %.  Quand on
+relocalise un fichier, retirer l'entrée du chemin legacy et
+en créer une au chemin canonique avec le même budget.
+
+### 3.E ``test_doc_paths::BROKEN_PATHS_BASELINE``
+
+Si un sub-plan ou doc référence un futur chemin Python
+(``picarones/X/Y.py``) qui n'existe pas encore, le test
+``test_broken_doc_paths_below_baseline`` détecte la
+référence cassée.  Soit :
+
+- Bumper ``BROKEN_PATHS_BASELINE`` du même montant.
+- Ou reformuler la référence en code/backticks pour échapper
+  au pattern (``picarones/X/Y.py``).
+
+Quand le fichier sera créé en réalité, abaisser
+``BROKEN_PATHS_BASELINE``.
+
+### 3.F Test parité legacy ↔ canonique
+
+``tests/architecture/test_legacy_canonical_parity.py`` maintient
+une table 3-états (``LEGACY_PARITY``) :
+
+- ``canonical: <module.symbol>`` — équivalent canonique existe.
+  Le test vérifie présence + signatures compatibles.
+- ``dropped: <raison>`` — feature volontairement abandonnée
+  avec justification écrite.
+- ``unmigrated: <cible prévue>`` — migration prévue ; cible
+  peut ne pas encore exister.
+
+À chaque migration d'un symbole, **mettre à jour la table**.
+Les symboles non trackés sont comptés via
+``BOOTSTRAP_BASELINE`` (à diminuer à chaque session).
+
+Limites du test : il ne vérifie que la **présence** et les
+**signatures**, pas le comportement réel.  Les différences
+sémantiques sont signalées via le champ ``behavior_diff``
+optionnel.
+
+### 3.G README généré
+
+Le compteur de tests dans `README.md` et `CLAUDE.md` est
+synchronisé par `scripts/gen_readme_tables.py`.  À chaque
+fois que le nombre de tests change (ajout/retrait), lancer :
+
+```bash
+python scripts/gen_readme_tables.py
+```
+
+Sinon le test ``test_readme_tables_consistent_with_code``
+échoue.
+
+---
+
+## 4. Inventaire actuel — quel legacy reste à migrer ?
+
+(Snapshot au moment de la pause de session, mesuré via AST,
+fiable.)
+
+### 4.A Imports legacy dans les tests
+
+**62 fichiers** avec **361 statements** d'import depuis les
+paquets legacy (``measurements``, ``llm``, ``pipelines``) —
+Lots A à G terminés (cf. 4.D ci-dessous).  Les paquets
+``engines/``, ``modules/``, ``report/`` et ``core/`` ont été
+**entièrement supprimés**.  Restent uniquement
+``measurements/`` (~25 modules de catégorie B/C/D),
+``llm/``, ``pipelines/`` et les sous-paquets d'interfaces
+(``cli/``, ``web/``, ``extras/``).
+
+Top chemins consommés :
+
+| Imports | Chemin legacy                                                 |
+|---------|---------------------------------------------------------------|
+| 29      | ``from picarones.measurements.runner import run_benchmark``   |
+| 18      | ``from picarones.measurements.metrics import MetricsResult``  |
+| 16      | ``from picarones.measurements.statistics import wilcoxon_test`` |
+| 13      | ``from picarones.measurements.metrics import compute_metrics`` |
+| 10      | ``from picarones.measurements.robustness import degrade_image_bytes`` |
+
+**Pourquoi c'est important** : ces tests passent par les shims
+au lieu de pointer vers le canonique.  Tant que ces imports
+existent, on **ne peut pas supprimer les shims** (le test casse).
+
+**Stratégie** : sed batch par chemin, valider les tests,
+commit, avancer.  Shims supprimés dans les Lots A
+(``core.modules`` + ``core.facts``), B
+(``core.metric_registry`` + ``core.metric_hooks`` +
+``core.metrics``), C (``core.results`` + ``core.corpus`` +
+``core.pipeline``) et D (34 shims plats de ``measurements/``
+vers ``evaluation.metrics/``) sur la branche
+``claude/migrate-core-to-domain-8ubIT``.
+
+### 4.B Imports legacy en production (hors shims eux-mêmes)
+
+**12 fichiers** avec **41 statements** dans des paquets
+non-legacy qui pointent encore vers le legacy.  À résoudre
+sprint par sprint en migrant chaque caller.
+
+### 4.C Symboles legacy non tracés dans la table de parité
+
+**110 symboles** publics dans les paquets legacy ne sont pas
+encore dans
+``tests/architecture/test_legacy_canonical_parity.py::LEGACY_PARITY``.
+Répartition :
+
+- ``measurements/`` : 104
+- ``pipelines/`` : 6
+
+Le test ``test_no_untracked_legacy_symbol_above_baseline``
+autorise temporairement 110 (``BOOTSTRAP_BASELINE = 110``).
+À diminuer à chaque session.
+
+### 4.D Plan de bataille pour les imports tests
+
+L'ordre recommandé, par lots de symboles cohérents :
+
+1. ✅ **Lot A — domain** (~40 imports migrés, shims supprimés) :
+   - ``core.modules.{ArtifactType, BaseModule, ExecutionMode}``
+     → ``domain.{artifacts, module_protocol}``
+   - ``core.facts.*`` → ``domain.facts.*``
+   - Shims ``picarones.core.modules`` + ``picarones.core.facts``
+     supprimés ; doc utilisateur (tutorials/, developer/,
+     reference/api-stable.md, explanation/narrative-engine.en.md)
+     pointe maintenant vers les canoniques.
+2. ✅ **Lot B — evaluation/metric_*** (~45 imports migrés, shims
+   supprimés) :
+   - ``core.metric_registry.*`` → ``evaluation.metric_registry.*``
+   - ``core.metric_hooks.*`` → ``evaluation.metric_hooks.*``
+   - ``core.metrics.*`` → ``evaluation.metric_result.*``
+   - Shims ``picarones.core.metric_registry`` +
+     ``picarones.core.metric_hooks`` + ``picarones.core.metrics``
+     supprimés ; ``docs/reference/normalization-profiles.md`` et
+     ``docs/reference/api-stable.md`` migrés vers les chemins
+     canoniques.
+3. ✅ **Lot C — evaluation/{benchmark_result, corpus, pipeline}**
+   (~75 imports migrés, shims supprimés) :
+   - ``core.results.*`` → ``evaluation.benchmark_result.*``
+   - ``core.corpus.*`` → ``evaluation.corpus.*``
+   - ``core.pipeline.*`` → ``evaluation.pipeline.*``
+   - Shims ``picarones.core.{results, corpus, pipeline}``
+     supprimés ; sections de ``docs/reference/api-stable.md``
+     migrées vers les chemins canoniques ; logger filter dans
+     ``test_sprint32_multi_level_gt`` aligné sur
+     ``picarones.evaluation.corpus``.
+4. ✅ **Lot D — evaluation/metrics/*** (~100 imports + 44
+   prod migrés, 34 shims supprimés en bloc) :
+   - ``measurements.{baseline_comparison, calibration,
+     char_scores, confusion, cost_projection, difficulty,
+     error_absorption, hallucination, image_predictive,
+     image_quality, incremental_comparison, inter_engine,
+     layout, levers, lexical_modernization, line_metrics,
+     longitudinal, marginal_cost, module_policy, ner_backends,
+     normalization, numerical_sequences, pricing, rare_tokens,
+     robustness_projection, roman_numerals, specialization,
+     structure, taxonomy, taxonomy_comparison,
+     taxonomy_cooccurrence, taxonomy_intra_doc, throughput,
+     worst_lines}`` → ``evaluation.metrics.{...}``.
+   - ``picarones/measurements/__init__.py`` réécrit pour
+     refléter la nouvelle composition (modules legacy
+     restants + `import picarones.evaluation.metrics`
+     unique pour déclencher les décorateurs).
+   - ``test_no_flat_files_in_measurements::WHITELIST_FLAT_FILES_S3``
+     réduit de 60 → 25 entrées.
+   - ``test_module_coverage::TEST_ONLY_BASELINE`` réduit
+     de 16 → 4 entrées.
+   - ``test_file_budgets::FILE_BUDGETS`` débarrassé des
+     entrées orphelines (inter_engine, levers,
+     normalization).
+5. ✅ **Lot E — adapters/legacy_*** (8 shims supprimés en bloc,
+   0 import à migrer) :
+   - ``engines.*`` → ``adapters.legacy_engines.*``
+   - ``modules.alto_text_to_mono_region`` →
+     ``adapters.legacy_modules.alto_text_to_mono_region``
+   - Tous les callers tests + production avaient déjà été
+     migrés en amont (Lots A-D), donc le Lot E n'a fait que
+     supprimer les 8 shims orphelins.
+   - ``LEGACY_PACKAGES`` réduit (retrait d'``engines`` et
+     ``modules``) dans
+     ``test_no_legacy_imports_in_rewrite.py`` et
+     ``test_legacy_canonical_parity.py``.
+   - ``ENGINES_DIR`` dans
+     ``tests/docs/test_readme_consistency.py`` redirigé vers
+     ``picarones/adapters/legacy_engines/``.
+6. ✅ **Lot F — reports_v2** (37 shims supprimés en bloc, 7
+   imports tests à migrer + ``scripts/gen_readme_tables.py``
+   redirigé) :
+   - ``report.*_render`` → ``reports_v2.html.renderers.*`` (29 shims)
+   - ``report.{generator, comparison, snapshot}`` →
+     ``reports_v2.html.*`` (3 shims)
+   - ``report.{assets, colors, render_helpers}`` →
+     ``reports_v2._helpers.*`` (3 shims)
+   - ``report.diff_utils`` → ``evaluation._diff_utils`` (1 shim)
+   - ``report.glossary`` → ``reports_v2.glossary`` (sous-package)
+   - ``scripts/gen_readme_tables.py`` redirigé vers
+     ``picarones/adapters/legacy_engines/`` ;
+     ``docs/reference/views.md`` migré en place vers
+     ``picarones/reports_v2/html/{views, generator, renderers,
+     templates}``.
+7. ⏳ **Lot G — measurements/runner et co.** (reporté car
+   canonique absent — phase 6 du plan maître).
+   Réalisé partiellement : suppression des 2 derniers shims
+   de ``picarones/core/`` (``diff_utils``, ``xml_utils``).
+   Le sous-paquet ``core/`` n'existe plus du tout.
+
+   La part majeure du Lot G originel (``measurements/runner``
+   + ``pipelines/``) reste à faire ; elle nécessite **d'abord
+   la création** des canoniques ``app/services/run_orchestrator``
+   et ``adapters/llm/pipeline`` (couvrant ``OCRLLMPipeline``,
+   ``PipelineMode``, ``over_normalization``, ``run_benchmark``,
+   ``_compute_document_result``).  Sans ces canoniques, un
+   simple sed est impossible — il faudrait migrer les 76
+   imports vers des modules qui n'existent pas encore.
+
+8. ✅ **Lot H — measurements.statistics → evaluation.statistics**
+   (~70 imports migrés, 9 shims supprimés en bloc) :
+   - ``measurements.statistics.{bootstrap, cdd_render,
+     clustering, correlation, distributions, friedman_nemenyi,
+     pareto, wilcoxon}`` → ``evaluation.statistics.{...}``.
+   - ``measurements/statistics/`` (sous-paquet entier)
+     supprimé.
+
+9. ✅ **Lot I — extras.importers → adapters.corpus**
+   (3 shims supprimés, ~15 imports migrés) :
+   - ``extras.importers.htr_united`` →
+     ``adapters.corpus.htr_united``.
+   - ``extras.importers.huggingface`` →
+     ``adapters.corpus.huggingface``.
+   - ``extras.importers._fallback_log`` →
+     ``adapters.corpus._fallback_log``.
+
+10. ✅ **Lot J — measurements.metrics.{MetricsResult,
+   aggregate_metrics} → evaluation.metric_result** (~25
+   imports migrés, 0 shim supprimé) :
+   - Migration partielle uniquement des symboles canoniquement
+     migrés (``MetricsResult``, ``aggregate_metrics``).
+   - ``compute_metrics`` reste dans
+     ``picarones.measurements.metrics`` car aucun canonique
+     n'existe pour cette fonction (sera traité avec le Lot G
+     reporté).
+
+À chaque lot : sed → tests → commit.  Les shims devenus
+orphelins après le lot peuvent être **supprimés** dans le même
+commit (principe « no shim survives its caller »).
+
+---
+
+## 5. Prochaine sub-phase à exécuter
+
+**Sub-phase 7.B.2** — refactoriser le corps de
+``PipelineRunner.run`` dans
+``picarones/evaluation/pipeline.py`` (lignes 384-590) pour
+qu'il délègue au canonique ``PipelineExecutor`` via le
+wrapper ``_BaseModuleAdapter`` créé en 7.B.1.
+
+### Plan d'exécution
+
+1. **Lire** ``picarones/evaluation/pipeline.py:PipelineRunner.run``
+   en entier pour comprendre la logique actuelle (résolution
+   d'inputs versionnés, exécution chronométrée, capture
+   d'erreur, évaluation auto vs GT, conversion outputs).
+
+2. **Lire** ``picarones/pipeline/_legacy_module_adapter.py``
+   en entier pour comprendre les outils disponibles
+   (``_BaseModuleAdapter``, ``_PayloadRegistry``,
+   ``wrap_initial_inputs``).
+
+3. **Écrire** un nouveau corps de ``PipelineRunner.run`` qui :
+   - Crée un ``_PayloadRegistry`` par appel.
+   - Wrappe les ``initial_inputs`` legacy via
+     ``wrap_initial_inputs(...)``.
+   - Convertit la ``PipelineSpec`` legacy en ``PipelineSpec``
+     canonique (``picarones.domain.pipeline_spec.PipelineSpec``).
+     Chaque ``PipelineStep.module: BaseModule`` devient un
+     ``adapter_name: str``, et l'adapter est
+     ``_BaseModuleAdapter(module, registry)``.
+   - Construit un ``adapter_resolver`` qui retourne le
+     wrapper de chaque module.
+   - Construit un ``RunContext``.
+   - Convertit le ``Document`` legacy en ``DocumentRef``.
+   - Invoque ``PipelineExecutor.run(canonical_spec,
+     document_ref, canonical_inputs, context)``.
+   - Reconvertit le ``PipelineResult`` canonique en
+     ``PipelineResult`` legacy.
+   - Calcule ``junction_metrics`` en post-étape (parcourt
+     les ``StepResult.produced_artifacts``, lit le payload
+     du registre, appelle ``compute_at_junction`` contre la
+     GT du document si ``GTLevel`` correspond).
+
+4. **Tester** : tous les tests existants doivent toujours
+   passer (les 7 fichiers axe B + ``test_sprint63_pipeline_runner``,
+   etc.).  C'est l'invariant de la sub-phase 7.B.2.
+
+5. **Lint** : ``ruff check picarones/ tests/``.
+
+6. **Commit + push** avec message décrivant ce qui a été
+   fait + pointer vers la sub-phase 7.B.3 comme prochaine
+   étape.
+
+### Alternative pragmatique
+
+Si le refactor 7.B.2 est trop gros pour une session,
+**commencer par le Lot A de la section 4.D** (migrer les ~30
+imports tests qui consomment ``core.modules`` et
+``core.facts`` vers leur canonique ``domain/``).  Cela vide
+une portion de la table de parité et permet de **supprimer les
+shims** ``core.modules.py`` et ``core.facts.py`` en bloc —
+résultat tangible et bien aligné avec le principe
+« suppression agressive ».
+
+Pareil pour Lots B-F : chaque lot est indépendant, fait
+progresser la migration, et démontre concrètement la
+suppression du legacy.
+
+### Pièges anticipés pour 7.B.2
+
+- **Sémantique différente des inputs entre legacy et canonique** :
+  le legacy passe ``Document.image_path`` comme un string
+  pur dans ``initial_inputs[ArtifactType.IMAGE]`` ; le canonique
+  attend un ``Artifact(uri=...)``.  ``wrap_initial_inputs``
+  fait la conversion mais il faut s'assurer que les modules
+  consomment bien le ``uri`` côté `_BaseModuleAdapter`.
+
+- **``junction_metrics`` calcul** : le legacy
+  ``PipelineRunner.run`` calcule ``junction_metrics`` à
+  chaque step (cf. ligne 519-540 actuellement).  Le canonique
+  ``PipelineExecutor`` ne le fait pas.  Il faut donc faire
+  ce calcul **après** l'exécution canonique, en parcourant
+  les artefacts produits et en lisant les payloads via le
+  registre.
+
+- **``output_types`` partial** : si un module produit un
+  output type non déclaré, le legacy le tolère (on remplit
+  ``StepResult.output_types`` avec ce qui est effectivement
+  produit, pas ce qui est déclaré).  Le canonique
+  ``PipelineExecutor`` rejette en ``error="missing_output: ..."``.
+  Vérifier la sémantique attendue par les tests.
+
+- **Spec conversion** : ``PipelineStep`` legacy a
+  ``inputs_from: dict[ArtifactType, str]`` (mapping
+  type→step_name).  ``PipelineStep`` canonique a
+  ``inputs_from: tuple[InputBinding, ...]``.  Conversion
+  attentive nécessaire.
+
+---
+
+## 6. Commande de démarrage de la nouvelle session
+
+Le user envoie simplement :
+
+```
+Reprends la migration. Lis docs/migration/SESSION_HANDOVER.md
+en entier d'abord, puis commence par les vérifications de la
+section 2.
+```
+
+Ou pour aller direct à l'action :
+
+```
+Continue la sub-phase 7.B.2.
+```
+
+(Claude Code va automatiquement lire CLAUDE.md à l'init, qui
+pointera vers ce SESSION_HANDOVER.md et les plans détaillés.)

docs/migration/legacy-retirement-plan.md

@@ -0,0 +1,1239 @@
+# Plan de retrait complet du legacy — vers la 2.0
+
+> **Décision stratégique** : pas de cohabitation legacy + rewrite à
+> long terme.  La 2.0 est livrée **sans aucune ligne legacy**.
+> L'arborescence cible (domain → formats → evaluation → pipeline →
+> adapters → app → reports_v2 → interfaces) est unique.
+>
+> **Critère absolu** : zéro bricolage, zéro semi-rendu, zéro
+> régression de comportement éditorial.  Une institution comme la
+> BnF ne tolère pas un *partial rewrite*.
+>
+> **Pas de contrainte de date** : on livre quand tout est propre.
+>
+> **Document vivant** : ce plan est mis à jour à chaque phase
+> achevée.  Toute exception ou découverte doit être inscrite ici.
+
+## Définition de « done » universelle
+
+Chaque phase est terminée quand **tous** les critères suivants sont
+remplis :
+
+1. **Code** : les modules legacy de la phase ont été soit migrés,
+   soit déclarés sans équivalent et supprimés (avec justification).
+2. **Tests** : tous les tests qui pointaient vers le legacy sont
+   migrés vers le rewrite ; les nouveaux tests couvrent le rewrite
+   à un niveau ≥ celui du legacy.
+3. **Régression** : le harness `tests/regression/legacy_vs_rewrite/`
+   prouve que le rewrite produit les mêmes résultats que le legacy
+   sur les corpus de référence (tolérance ε explicite par métrique).
+4. **Doc** : la doc utilisateur, opérationnelle et architecturale
+   ne mentionne plus le legacy de la phase ; les chemins cassés
+   `tests/architecture/test_doc_paths.py` baseline diminue.
+5. **Lint** : `ruff check picarones/ tests/` clean.
+6. **Suite complète** : `pytest tests/` 100 % vert sur 3 OS × 3
+   versions Python (3.11, 3.12, 3.13).
+7. **Coverage** : ≥ 85 %, pas de dégradation > 0,5 pt vs. la phase
+   précédente.
+
+## Phases
+
+### Phase 0 — Foundation ✅ terminée
+
+**Objectif** : poser les garde-fous qui rendent les 11 phases
+suivantes **vérifiables** sans introduire de régression invisible.
+
+**Livrables** :
+
+- [x] `docs/migration/legacy-retirement-plan.md` (ce document) —
+  inventaire complet, phases, acceptance criteria.
+- [x] `docs/migration/regression-tolerances.md` — table des
+  tolérances acceptables par métrique et type d'output (CER ε=0,
+  Wilcoxon ε=1e-9, HTML diff sémantique, narrative facts égalité
+  ensembliste, etc.).
+- [x] `tests/regression/legacy_vs_rewrite/` — harness scaffolding :
+  fixtures de corpus synthétique (small=3 docs, medium=30 docs,
+  large laissé pour ajout opportuniste) + gestion golden snapshot
+  avec flag `--regen-golden` + comparateurs sémantiques (floats,
+  sets, JSON).  Marker `regression` enregistré et exclu de
+  ``addopts`` par défaut (opt-in via `pytest -m regression`).
+  Smoke test couvre les 16 invariants du harness lui-même.
+- [x] `tests/architecture/test_no_legacy_imports_in_rewrite.py` —
+  garantit qu'aucun fichier des paquets `domain/`, `formats/`,
+  `evaluation/`, `pipeline/`, `adapters/`, `app/`, `reports_v2/`,
+  `interfaces/` n'importe depuis un paquet legacy.  AST-based,
+  pas regex syntaxique.  État initial : **vert** — le rewrite est
+  déjà clean.
+
+**Acceptance** : ✅ remplie.  Le harness est prêt à recevoir les
+tests de régression de chaque phase suivante (`test_phase1_*.py`,
+`test_phase2_*.py`, etc.).  Toute fonctionnalité migrée DOIT
+avoir son test de régression ajouté ici en même temps que le
+code.
+
+### Phase 1 — Foundation conceptuelle (`core/`, `domain/`) — partielle ✅
+
+**Audit de migrabilité réelle** : 5 modules `core/` sur 9 dépendent
+de `core/modules.py` (legacy `BaseModule` + `ArtifactType` 6 valeurs,
+incompatible avec le superset `domain/artifacts.ArtifactType` 10
+valeurs).  Les migrer ferait dériver le comportement des callers
+legacy — à reporter en **Phase 4** quand le runner et les métriques
+seront rewrités.
+
+**Migrés en Phase 1 — 3 modules** (sans dépendance à `core/modules`) :
+
+| Legacy | Canonique rewrite | Statut |
+|--------|-------------------|--------|
+| `core/xml_utils.py` (44 LOC) | `formats/_xml_utils.py` + re-export `picarones.formats.safe_parse_xml` | ✅ shim posé |
+| `core/diff_utils.py` (89 LOC) | `evaluation/_diff_utils.py` + re-export `picarones.evaluation.{compute_word_diff,compute_char_diff,diff_stats}` | ✅ shim posé |
+| `core/facts.py` (229 LOC) | `domain/facts.py` + re-export `picarones.domain.{Fact,FactType,FactImportance,DetectorRegistry,detect_all}` | ✅ shim posé |
+
+**Reportés en Phase 4** (couplage à `core/modules.ArtifactType` legacy
+ou au modèle du runner legacy) :
+
+| Legacy | Bloqueur |
+|--------|----------|
+| `core/results.py` (677 LOC, `BenchmarkResult` + 30 champs agrégés) | Modèle central du runner legacy ; convergence avec `app.results.RunResult` en Phase 4 (rewrite de `measurements/runner/`) |
+| `core/pipeline.py` (571 LOC, legacy `PipelineSpec` + `BaseModule`) | Concept différent du `domain.pipeline_spec.PipelineSpec` ; convergence en Phase 6 (`pipelines/` legacy) |
+| `core/corpus.py` (511 LOC, `Document` avec payloads typés) | Modèle data legacy ≠ `DocumentRef` du rewrite ; convergence en Phase 4 |
+| `core/modules.py` (173 LOC, `BaseModule` + `ArtifactType` 6 valeurs) | Type legacy partagé par 50+ modules ; déprécation en Phase 4 |
+| `core/metric_registry.py` + `metric_hooks.py` (686 LOC) | Importe `core.modules.ArtifactType` ; convergence en Phase 4 |
+| `core/metrics.py` (144 LOC, `MetricsResult`) | Schéma legacy ≠ `ViewResult.metric_values` du rewrite ; convergence en Phase 4 |
+
+**Effort consommé Phase 1** : ~1 jour (3 modules + audit + tests).
+**Effort restant — reporté en Phase 4** : ~5-7 jours.
+
+**Acceptance Phase 1 partielle** : 3 modules `core/` sont des shims
+re-export propres avec `DeprecationWarning`.  Le test architectural
+`test_no_legacy_imports_in_rewrite.py` reste vert.  `picarones/__init__.py`
+top-level pointe désormais vers le canonique pour les modules
+migrés (pas de spam de warning à `import picarones`).  Les 6 autres
+modules `core/` fonctionnent inchangés ; ils seront migrés au
+moment de la migration de leurs callers.
+
+### Phase 2 — Statistics (`measurements/statistics/`) — ✅ terminée
+
+**Modules migrés** : 8 modules (`wilcoxon.py`, `friedman_nemenyi.py`,
+`bootstrap.py`, `pareto.py`, `clustering.py`, `correlation.py`,
+`distributions.py`, `cdd_render.py`).
+
+**Canonique** : `picarones/evaluation/statistics/`.
+
+**Travaux** :
+
+- 8 modules copiés bit-for-bit dans `evaluation/statistics/`.
+- 1 import legacy dans `clustering.py` migré
+  (`picarones.core.diff_utils.compute_word_diff`
+  → `picarones.evaluation.compute_word_diff`).
+- 1 import auto-référencé dans `friedman_nemenyi.py` migré
+  (`picarones.measurements.statistics.wilcoxon._normal_sf`
+  → `picarones.evaluation.statistics.wilcoxon._normal_sf`).
+- `evaluation/statistics/__init__.py` ré-exporte 14 symboles
+  publics (`bootstrap_ci`, `wilcoxon_test`, `compute_pairwise_stats`,
+  `friedman_test`, `nemenyi_posthoc`, `build_critical_difference_svg`,
+  `compute_pareto_front`, `ErrorCluster`, `cluster_errors`,
+  `compute_correlation_matrix`, `compute_reliability_curve`,
+  `compute_venn_data`, `_SCIPY_AVAILABLE`, `_chi_square_sf`,
+  `_nemenyi_critical_value`, `_normal_sf`, `_rank_row`).
+- 8 shims `measurements/statistics/<X>.py` + 1 shim
+  `measurements/statistics/__init__.py` avec `DeprecationWarning`,
+  `__all__` complet pour rétrocompat des callers (5 fichiers
+  `report/`, 6 fichiers tests).
+
+**Effort réel** : ~1 jour (vs estimation 5-7 j — code mathématique
+pur, pas de couplage applicatif comme prévu, mais aussi script
+de génération de shims qui a accéléré).
+
+**Acceptance** : suite par défaut 5019+ passed (inchangée), tests
+ciblés sur les statistiques 226 passed, test architectural
+anti-imports legacy reste vert (3 passed).  Pas de régression
+détectée — les algorithmes scipy/numpy sont déterministes par
+construction (seed=42 partout) ; le rendu SVG est strictement
+identique parce que c'est le même fichier.
+
+### Phase 3 — Narrative engine (`measurements/narrative/`) — ✅ terminée
+
+**Modules migrés** : 11 modules + 2 templates YAML.
+
+| Legacy | Canonique |
+|--------|-----------|
+| `measurements/narrative/__init__.py` | `reports_v2/narrative/__init__.py` |
+| `measurements/narrative/arbiter.py` | `reports_v2/narrative/arbiter.py` |
+| `measurements/narrative/registry.py` | `reports_v2/narrative/registry.py` |
+| `measurements/narrative/renderer.py` | `reports_v2/narrative/renderer.py` |
+| `measurements/narrative/detectors/__init__.py` | `reports_v2/narrative/detectors/__init__.py` |
+| `measurements/narrative/detectors/_helpers.py` | `reports_v2/narrative/detectors/_helpers.py` |
+| `measurements/narrative/detectors/ensemble.py` | `reports_v2/narrative/detectors/ensemble.py` (1 détecteur) |
+| `measurements/narrative/detectors/history.py` | `reports_v2/narrative/detectors/history.py` (3 détecteurs) |
+| `measurements/narrative/detectors/pareto.py` | `reports_v2/narrative/detectors/pareto.py` (2 détecteurs) |
+| `measurements/narrative/detectors/quality.py` | `reports_v2/narrative/detectors/quality.py` (4 détecteurs) |
+| `measurements/narrative/detectors/ranking.py` | `reports_v2/narrative/detectors/ranking.py` (5 détecteurs) |
+| `measurements/narrative/detectors/stratum.py` | `reports_v2/narrative/detectors/stratum.py` (3 détecteurs) |
+| `measurements/narrative/templates/fr.yaml` | `reports_v2/narrative/templates/fr.yaml` |
+| `measurements/narrative/templates/en.yaml` | `reports_v2/narrative/templates/en.yaml` |
+
+Total : **18 détecteurs en 6 familles + arbitre + renderer + 36
+templates YAML FR/EN** migrés.
+
+**Cible architecturale** : `picarones/reports_v2/narrative/` (le
+narratif est de la **présentation**, pas du domaine — il vit du
+côté rapport, pas de l'évaluation).
+
+**Travaux** :
+
+- 14 fichiers (11 .py + 1 _helpers.py + 2 .yaml) copiés depuis le
+  legacy vers le canonique.
+- Tous les imports `picarones.core.facts` (11 occurrences) migrés
+  vers `picarones.domain.facts` (Phase 1 a déjà migré ce module).
+- Tous les imports auto-référencés `picarones.measurements.narrative`
+  réécrits en `picarones.reports_v2.narrative`.
+- Path des templates YAML auto-ajusté (relatif à `__file__`).
+- 12 shims `measurements/narrative/*.py` + `_helpers.py` shim
+  manuel (privé, pas d'`__all__`).
+- `_DEFAULT_REGISTRY` (singleton du registre des détecteurs)
+  ré-exporté explicitement par le shim `__init__.py` pour la
+  rétrocompat des tests S19.
+
+**Effort réel** : ~1 jour (vs estimation 8-12 j — script de
+génération de shims a fortement accéléré ; pas d'aléatoire ni
+d'I/O dans les détecteurs, donc régression triviale par
+construction).
+
+**Acceptance** : tous les tests narratifs passent — Sprints 16,
+19, 23, 29, 36, 44, 46, 73, 90, 92, baseline_comparison, chantier
+5, reproducibility_ops.  322 tests ciblés passed.  Test architectural
+anti-imports legacy : 3 passed (le rewrite reste autonome).
+Garde-fou anti-hallucination préservé (les détecteurs lisent
+toujours le dict JSON d'entrée, pas une source externe).
+
+### Phase 4 — 35 mesures legacy (`measurements/*.py`) — partielle ✅
+
+**Audit de migrabilité** : sur 35 mesures legacy, **24 étaient
+déjà des re-exports** (Phase 4 partielle pré-existante avec un
+canonique `evaluation/metrics/X.py`).  Sur les 11 modules réellement
+"contenu" :
+
+- **9 sont migrés en Phase 4 (cette session)** sans toucher à
+  `core.modules` : autonomes ou en cascade vers d'autres modules
+  migrables.
+- **13 modules réels** restent bloqués par
+  `core.modules.ArtifactType` (enum legacy 6 valeurs incompatible
+  avec le superset `domain.artifacts.ArtifactType` 10 valeurs ;
+  `TEXT` ≠ `RAW_TEXT`, `ALTO` ≠ `ALTO_XML`, `PAGE` ≠ `PAGE_XML`).
+  Substitution non transparente — exigerait un travail de
+  remapping sémantique sur chaque caller.
+
+**Migrés en Phase 4 — 9 modules** :
+
+| Legacy | Canonique | Notes |
+|--------|-----------|-------|
+| `measurements/char_scores.py` (307) | `evaluation/metrics/char_scores.py` | Autonome |
+| `measurements/difficulty.py` (161) | `evaluation/metrics/difficulty.py` | Autonome |
+| `measurements/ner_backends.py` (186) | `evaluation/metrics/ner_backends.py` | Autonome |
+| `measurements/normalization.py` (51) | `evaluation/metrics/normalization.py` | Autonome |
+| `measurements/structure.py` (182) | `evaluation/metrics/structure.py` | Autonome |
+| `measurements/cost_projection.py` (140) | `evaluation/metrics/cost_projection.py` | dep `pricing` (déjà migré) |
+| `measurements/specialization.py` (158) | `evaluation/metrics/specialization.py` | dep `inter_engine` (re-export déjà) |
+| `measurements/taxonomy.py` (294) | `evaluation/metrics/taxonomy.py` | dep `char_scores` (en cascade) |
+| `measurements/taxonomy_intra_doc.py` (178) | `evaluation/metrics/taxonomy_intra_doc.py` | dep `taxonomy` (en cascade) |
+
+Total : **1657 lignes de code migrées + 9 shims legacy**.
+
+**Bloqués — 13 modules + 1 sous-package + 6 modules `core/`** :
+
+Reportés à une phase dédiée **« Phase 4-bis : ArtifactType
+migration »** dont le périmètre est :
+
+1. Décider le mapping sémantique TEXT → RAW_TEXT vs CORRECTED_TEXT
+   (par module, en lisant le contexte d'usage).
+2. Migrer `core/modules.py` (`BaseModule` + `ArtifactType` 6
+   valeurs) vers `domain/module_protocol.py`.
+3. Migrer `core/metric_registry.py` + `core/metric_hooks.py` vers
+   `evaluation/registry/`.
+4. Adapter chaque module bloqué : `mufi.py`, `abbreviations.py`,
+   `early_modern_typography.py`, `modern_archives.py`,
+   `roman_numerals.py`, `unicode_blocks.py`, `equivalence_profile.py`,
+   `philological_hooks.py`, `ner.py`, `readability.py`,
+   `readability_hooks.py`, `searchability.py`,
+   `searchability_hooks.py`, `reading_order.py`, `alto_metrics.py`,
+   `numerical_sequences.py`, `numerical_sequences_hooks.py`,
+   `builtin_hooks.py`, `builtin_metrics.py`, `metrics.py`,
+   `pipeline_benchmark.py`, `pipeline_comparison.py`,
+   `pipeline_spec_loader.py`, `robustness.py`, `reliability.py`,
+   `history.py`.
+5. Migrer le sous-package `measurements/runner/` (orchestrateur
+   legacy → fondre dans `pipeline/` + `app/services/`).
+6. Migrer `core/results.py` (`BenchmarkResult` + 30 champs agrégés
+   → typed Artifacts dans `domain/`).
+7. Migrer `core/corpus.py` (`Document`/`Corpus`/`GTLevel` → modèle
+   convergent avec `domain.corpus`).
+
+**Effort estimé Phase 4-bis** : 18-22 jours (vs 23-28 j initialement
+estimés pour Phase 4 complète — la moitié déjà faite par les
+re-exports pré-existants et les 9 modules de cette session).
+
+**Acceptance Phase 4 partielle** : 9 modules migrés, 1191 tests
+mesures passent (inchangés), test architectural anti-imports
+legacy reste vert.  Les 13 modules réels + 6 modules `core/`
+restants sont documentés comme dépendant d'une migration
+ArtifactType.
+
+#### Tentative Phase 4-bis (avortée — diagnostic posé)
+
+Une tentative de migration coordonnée de l'``ArtifactType`` a été
+explorée puis revertée :
+
+**Stratégie testée** : exploiter le mécanisme natif d'aliases
+d'``Enum`` Python (un membre avec la même valeur qu'un autre devient
+un alias).  Ajout de ``TEXT = "raw_text"``, ``ALTO = "alto_xml"``,
+``PAGE = "page_xml"`` à ``domain.artifacts.ArtifactType`` + hook
+``_missing_`` pour accepter les valeurs string legacy.  Puis
+transformation de ``core/modules.py`` en shim qui ré-exporte
+``ArtifactType`` et ``BaseModule`` depuis le canonique.
+
+**Conservé en place** : les aliases + ``_missing_`` dans
+``domain.artifacts.ArtifactType``.  Inoffensif — aucun code legacy
+ne les voit puisqu'aucun module legacy n'importe encore depuis le
+canonique.
+
+**Reverté** : le shim ``core/modules.py``.  Cause : passer le
+``core.modules.ArtifactType`` du legacy enum 6 valeurs au superset
+canonique change silencieusement ``ArtifactType.TEXT.value`` de
+``"text"`` à ``"raw_text"``.  Or 27 tests legacy
+(``test_sprint63_pipeline_runner``, ``test_sprint65_pipeline_comparison``,
+``test_sprint68_pipeline_comparison_html`` etc.) reposent sur le
+fait que les clés des dicts ``junction_metrics`` produites par le
+runner legacy sont les valeurs string legacy.  Quand le runner
+utilise ``at.value`` pour stocker, il stocke maintenant ``"raw_text"``,
+et les tests qui cherchaient ``junction_metrics["text"]`` cassent.
+
+Le diagnostic est plus profond qu'un simple rename : le legacy
+``BenchmarkResult.junction_metrics`` est un ``dict[str, dict]``
+indexé par valeur string ; sa stabilité de format est implicitement
+testée.  Migrer ``core.modules.ArtifactType`` exige un travail
+**par module** d'identification des dicts indexés par valeur
+string, et soit (a) double-clé pour rétrocompat, (b) migration
+ordonnée tests-en-même-temps.
+
+**Plan rectifié pour Phase 4-bis** :
+
+1. Lister exhaustivement les dicts indexés par ``ArtifactType.value``
+   dans le legacy (``core/results.py``, ``core/pipeline.py``,
+   ``measurements/runner/``, ``measurements/pipeline_*``).
+2. Décider la stratégie par module : double-clé pendant la
+   migration vs migration coordonnée tests + code.
+3. Migrer un cluster à la fois en validant la suite après chaque.
+
+**Effort rectifié** : 25-30 jours (vs 18-22 estimés initialement —
+le couplage implicite des dicts indexés par valeur string n'avait
+pas été vu à l'audit).
+
+**Statut Phase 4-bis** : analyse posée, exécution reportée à un
+sprint dédié de plusieurs sessions.
+
+#### Phase 4-bis — Reprise et complétion (2026-05)
+
+La reprise s'appuie sur le **diagnostic de la tentative avortée**
+en adoptant la stratégie « double-clé » : on garde les aliases
+legacy ``TEXT``/``ALTO``/``PAGE`` dans
+``domain.artifacts.ArtifactType``, et on s'engage à ce que tout
+dict indexé par ``ArtifactType.value`` présente en parallèle la
+clé canonique (``"raw_text"``) **et** la clé legacy (``"text"``)
+quand un alias existe.
+
+**Ajouts dans le canonique** :
+
+- ``LEGACY_VALUE_ALIASES = {"raw_text": "text", "alto_xml": "alto",
+  "page_xml": "page"}`` dans ``domain.artifacts``.
+- ``expand_legacy_keys(d)`` qui mute un dict pour y copier les
+  valeurs canoniques sous les alias legacy.
+- ``BaseModule`` canonique dans ``domain/module_protocol.py``
+  (10 valeurs vs 6 legacy).
+
+**Sites mis à jour** :
+
+- ``core/pipeline.py`` : ``StepResult.junction_metrics`` enrichi
+  via ``expand_legacy_keys`` à la production.
+  ``PipelineResult.junction_metrics_for`` essaie la clé canonique
+  puis l'alias legacy.
+  ``_artifact_type_to_gt_level`` utilise une map explicite
+  ``ArtifactType → GTLevel`` (les valeurs canoniques
+  ``"raw_text"``/``"alto_xml"``/``"page_xml"`` ne matchent plus
+  ``GTLevel`` qui garde ``"text"``/``"alto"``/``"page"``).
+- ``measurements/pipeline_benchmark.py`` :
+  ``StepAggregate.junction_metrics`` enrichi via
+  ``expand_legacy_keys`` après agrégation.
+- ``measurements/pipeline_comparison.py`` :
+  ``_final_metric_value`` essaie canonique puis legacy.
+- ``evaluation/metrics/module_policy.py`` : la comparaison
+  manifest vs déclaration normalise via les aliases (``"text"``
+  match ``"raw_text"``).
+
+**Migration des callers** : 16 modules ``measurements/`` + 6
+modules `core/`/`engines/`/`modules/`/`cli/`/`report/` migrés
+de ``from picarones.core.modules import ArtifactType`` vers
+``from picarones.domain.artifacts import ArtifactType`` (et
+``from picarones.domain.module_protocol import BaseModule``
+quand applicable).
+
+**``core/modules.py``** : transformé en shim avec
+``DeprecationWarning`` à l'import.
+
+**Tests adaptés** :
+
+- ``test_public_api.py::test_artifact_type_values`` —
+  asserte le set canonique 10 valeurs.
+- ``test_sprint33_module_interface.py::test_repr_shows_io_types``
+  — asserte ``"raw_text→raw_text"``.
+- ``test_sprint68_pipeline_comparison_html.py::test_display_label_default``
+  — asserte ``"raw_text.cer"``.
+
+**Acceptance Phase 4-bis** : 5019 tests passent (vs 5008 avant la
+reprise — 11 tests étaient cassés par la première tentative et
+sont maintenant verts).  Les 24 fichiers de tests qui importent
+encore ``from picarones.core.modules`` continuent à fonctionner via
+le shim — ils ne deviendront erronés que quand le shim sera retiré
+en 2.0.
+
+**Reportés à Phase 4-ter** :
+
+- ``core/metric_registry.py`` (263 l) et ``core/metric_hooks.py``
+  (423 l) restent en place : ils sont consommés par 30+ modules
+  ``measurements/`` via le décorateur ``@register_metric`` et les
+  hooks ``register_document_metric``/``register_corpus_aggregator``.
+  Le canonique existant ``evaluation/registry/registry.py`` utilise
+  un design **instance-based** (``MetricRegistry()`` explicite,
+  pas de décorateur module-level) qui est incompatible avec le
+  pattern legacy.  La migration exige un choix de design (garder
+  les deux, fondre dans une API unique, etc.) qui dépasse Phase
+  4-bis.
+- ``core/metrics.py`` (144 l, ``MetricsResult`` +
+  ``aggregate_metrics``) reste en place : pas d'équivalent
+  canonique dans ``domain/`` ou ``evaluation/`` à ce jour.  La
+  conversion nécessitera d'abord de créer le destinataire dans
+  ``domain.measurements`` (typé Pydantic au lieu de dataclass) ou
+  ``evaluation.aggregation``.
+- ``core/results.py`` (``BenchmarkResult`` + champs agrégés) :
+  même statut.
+- ``core/corpus.py`` (``Document``/``Corpus``/``GTLevel``) :
+  même statut.  Note : ``GTLevel`` étant intentionnellement
+  conservé en parallèle d'``ArtifactType``, son retrait dépend
+  de la fin de migration des callers qui parsent les types de GT
+  par leur valeur string.
+
+#### Phase 4-ter — Relocalisation Cercle 1 → Cercle 2 (2026-05)
+
+Stratégie « relocaliser sans redessiner » : on déplace
+verbatim les modules legacy de ``core/`` (Cercle 1) vers
+``evaluation/`` (Cercle 2) où ils appartiennent sémantiquement,
+sans toucher à leur API publique.  Le pattern module-level
+décorateur (``@register_metric``, ``@register_document_metric``,
+``@register_corpus_aggregator``) est **conservé** — sa
+convergence avec l'instance-based ``evaluation.registry.MetricRegistry``
+(Sprint A14-S5) est laissée à un futur sprint dédié quand un
+caller institutionnel le demandera.
+
+**Migrations effectuées (A-D)** :
+
+| Source legacy | Destination canonique | Lignes |
+|---|---|---|
+| ``core/metric_registry.py`` | ``evaluation/metric_registry.py`` | 264 |
+| ``core/metric_hooks.py``    | ``evaluation/metric_hooks.py``    | 427 |
+| ``core/metrics.py``         | ``evaluation/metric_result.py``   | 145 |
+| ``core/results.py``         | ``evaluation/benchmark_result.py``| 702 |
+
+Total : **1538 lignes** déplacées du Cercle 1 vers le Cercle 2.
+Les chemins ``core/X.py`` deviennent des shims minimaux
+(< 30 lignes chacun) avec ``DeprecationWarning`` à l'import.
+
+**Adaptations transverses** :
+
+- ``evaluation/benchmark_result.py`` ne peut pas importer
+  ``picarones.__version__`` (cycle d'import via
+  ``measurements/``).  La résolution de version utilise
+  désormais ``importlib.metadata`` directement avec fallback
+  ``"1.0.0"``.
+- ``tests/architecture/test_file_budgets.py`` mis à jour
+  pour pointer vers les nouveaux chemins canoniques.
+- ``tests/core/test_public_api.py::TestCercle1IsLean.EXPECTED_CERCLE1``
+  ne contient plus que ``corpus.py`` et ``pipeline.py``
+  (les seuls modules ``core/`` réels qui restent).
+
+**Reporté à Phase 4-quater** :
+
+``core/corpus.py`` (511 l, ``Document``/``Corpus``/``GTLevel`` +
+payloads + ``load_corpus_from_directory``) reste en place.
+Raison : il y a déjà ``domain.corpus.CorpusSpec`` (Pydantic,
+immutable, structural) et ``domain.documents.DocumentRef``
+en parallèle.  La convergence des deux modèles
+(``Document``/``Corpus`` historiques riches en behavior vs
+``CorpusSpec``/``DocumentRef`` purement déclaratifs) est un
+choix de design (fondre, garder les deux, marquer l'un comme
+view-de-l'autre…) qui dépasse Phase 4-ter.  L'objectif Phase
+4-quater est de produire un RFC qui tranche cette question
+puis migre les 14 callers en une fois.
+
+**Acceptance Phase 4-ter (A-D)** : 5019 tests passent, lint
+vert, architecture vérifiée (anti-cycles, file budgets,
+EXPECTED_CERCLE1 mis à jour).  Les 24+ fichiers de tests qui
+importent encore via les chemins ``core/`` continuent à
+fonctionner via les shims — déprécation visible mais
+non-bloquante.
+
+#### Phase 4-quater — Relocalisation de ``core/corpus.py`` (2026-05)
+
+Décision RFC : **garder les deux modèles en parallèle**, sans
+fusion.  ``evaluation.corpus`` (riche en behavior, dataclass,
+chargé en mémoire, runner-friendly) et
+``domain.corpus.CorpusSpec`` (Pydantic, immutable, déclaratif,
+pipeline-executor-friendly) sont des projections différentes
+d'un même domaine ; un convertisseur explicite
+``CorpusSpec ↔ Corpus`` viendra quand un caller institutionnel
+l'exigera concrètement.  Tenter une convergence prématurée
+casserait soit le runner historique (qui consomme
+``Document.get_gt(level)`` + ``Corpus.has_ocr_text``), soit le
+pipeline executor canonique (qui consomme l'immutabilité de
+``CorpusSpec`` pour la sérialisation YAML).
+
+Migration effectuée
+-------------------
+
+| Source legacy        | Destination canonique         | Lignes |
+|----------------------|-------------------------------|--------|
+| ``core/corpus.py``   | ``evaluation/corpus.py``      |   533  |
+
+Le chemin ``core/corpus.py`` devient un shim minimal
+(< 30 lignes) avec ``DeprecationWarning`` à l'import.  Les 14
+callers de production (``cli/_pipeline``, ``cli/_robustness``,
+``cli/_workflows``, ``web/benchmark_utils``,
+``measurements/pipeline_benchmark``,
+``measurements/pipeline_comparison``,
+``measurements/robustness``, ``measurements/runner/orchestration``,
+``measurements/runner/ner_attach``,
+``extras/importers/{iiif,gallica,escriptorium}``,
+``core/pipeline``, et ``picarones/__init__.py``) sont migrés
+vers ``picarones.evaluation.corpus``.
+
+Note : ``GTLevel`` reste consommé en parallèle d'``ArtifactType``
+par le runner — la convergence de ces deux énumérations est
+liée au retrait du runner legacy lui-même (Phase 6+ du plan).
+
+Adaptations transverses
+-----------------------
+
+- ``test_file_budgets.py`` : entrée ``core/corpus.py`` retirée,
+  remplacée par ``evaluation/corpus.py`` (budget identique 600).
+- ``test_public_api.py::EXPECTED_CERCLE1`` : ``corpus.py``
+  retiré de la liste — il ne reste plus que ``pipeline.py``
+  comme module Cercle 1 réel.
+
+État final de ``core/`` après Phase 4-quater
+--------------------------------------------
+
+Le répertoire ``picarones/core/`` ne contient désormais qu'**un
+seul module réel** :
+
+- ``pipeline.py`` (~570 l) — ``PipelineRunner`` + ``PipelineSpec``
+  + ``StepResult`` + ``PipelineResult``.
+
+Tous les autres fichiers (``corpus.py``, ``modules.py``,
+``metric_registry.py``, ``metric_hooks.py``, ``metrics.py``,
+``results.py``, ``facts.py``, ``diff_utils.py``,
+``xml_utils.py``) sont des shims < 30 lignes avec
+``DeprecationWarning``.
+
+**Acceptance Phase 4-quater** : 5019 tests passent (inchangé
+depuis Phase 4-ter), lint vert, architecture vérifiée.  Le
+``__init__.py`` racine (``picarones/__init__.py``) importe
+maintenant directement depuis les chemins canoniques (Cercle
+1 ``domain/`` + Cercle 2 ``evaluation/``), seul ``core.pipeline``
+reste référencé pour ses types.
+
+**Reporté à Phase 5** :
+
+- ``core/pipeline.py`` (``PipelineRunner``) — convergence avec
+  le pipeline executor canonique
+  (``picarones/pipeline/executor.py``, ``planner.py``,
+  ``runner.py``).  C'est le dernier module ``core/`` réel ;
+  son retrait suppose que tous les callers passent par le
+  pipeline executor, ce qui implique l'écriture du sucre
+  syntaxique pour les benchmarks OCR mono-étape (typique
+  ``run_benchmark(corpus, [engine_a, engine_b])``).
+- Convergence ``GTLevel`` ↔ ``ArtifactType`` (en attente du
+  retrait du runner legacy).
+
+### Phase 5 — Reports HTML (`report/`)
+
+**Modules** :
+
+- 22 renderers thématiques : `baseline_render.py`, `calibration_render.py`,
+  `difficulty_render.py`, `error_absorption_render.py`,
+  `image_predictive_render.py`, `incremental_comparison_render.py`,
+  `inter_engine_render.py`, `levers_render.py`,
+  `lexical_modernization_render.py`, `longitudinal_render.py`,
+  `marginal_cost_render.py`, `module_audit_render.py`,
+  `multirun_stability_render.py`, `ner_render.py`,
+  `numerical_sequences_render.py`, `philological_render.py`,
+  `pipeline_dag_render.py`, `pipeline_render.py`,
+  `rare_token_recall_render.py`, `readability_render.py`,
+  `robustness_projection_render.py`, `searchability_render.py`,
+  `specialization_render.py`, `stratification_render.py`,
+  `taxonomy_comparison_render.py`, `taxonomy_cooccurrence_render.py`,
+  `taxonomy_intra_doc_render.py`, `throughput_render.py`,
+  `worst_lines_render.py`.
+- 5 vues : `views/{advanced_taxonomy,diagnostics,economics,
+  pipeline,robustness}.py`.
+- `generator.py` (orchestrateur), `comparison.py`, `snapshot.py`,
+  `assets.py`, `colors.py`, `render_helpers.py`, `report_data/`.
+- `templates/` (~10 fichiers Jinja2), `glossary/` (2 YAML, 25
+  entrées), `i18n/`, `vendor/`.
+
+**Cible** : `picarones/reports_v2/html/views/<theme>.py` + helpers
+partagés dans `reports_v2/html/_helpers/`.  Glossaire dans
+`reports_v2/html/glossary/`.  Templates Jinja2 dans
+`reports_v2/html/templates/`.
+
+**Effort** : 12-18 jours.
+
+**Acceptance** : régression bit-for-bit sur le HTML produit pour
+les 3 corpus de référence.  Aucun renderer legacy laissé.
+
+#### Phase 5.A+B — Helpers + glossary + i18n (2026-05)
+
+Première tranche du retrait du legacy ``report/`` : les utilitaires
+purs et les ressources statiques, sans toucher aux 22 renderers
+thématiques (qui consomment ``BenchmarkResult`` legacy et seront
+migrés au fil des phases ultérieures, par lots).
+
+**Migrations effectuées** :
+
+| Source legacy                        | Destination canonique                          |
+|--------------------------------------|------------------------------------------------|
+| ``report/colors.py``                 | ``reports_v2/_helpers/colors.py``              |
+| ``report/render_helpers.py``         | ``reports_v2/_helpers/render_helpers.py``      |
+| ``report/assets.py`` + ``vendor/``   | ``reports_v2/_helpers/assets.py`` + ``vendor/``|
+| ``report/glossary/{fr,en}.yaml``     | ``reports_v2/glossary/{fr,en}.yaml``           |
+| ``report/i18n/{fr,en}.json``         | ``reports_v2/i18n/{fr,en}.json``               |
+
+``report/diff_utils.py`` redirige désormais directement vers
+``picarones.evaluation`` (au lieu du double-shim via
+``core.diff_utils``).
+
+**Shims** : tous les chemins legacy ``report/X`` restent disponibles
+via des shims minimaux (< 25 lignes) avec ``DeprecationWarning``
+à l'import.
+
+**Adaptations transverses** :
+
+- ``picarones/i18n.py`` : ``_I18N_DIR`` pointe désormais vers
+  ``reports_v2/i18n/``.
+- 22 renderers ``report/*_render.py`` migrés sur leurs imports
+  internes vers ``picarones.reports_v2._helpers.*``.
+- 28 fichiers de tests mis à jour (chemins ``picarones/report/i18n/*``
+  remplacés par ``picarones/reports_v2/i18n/*``).
+- ``test_layer_dependencies.py::EXTERNAL_ALLOWED["reports_v2"]``
+  étendu à ``PIL`` (Pillow utilisé par ``_helpers/assets.py``
+  pour le redimensionnement d'images).
+- ``test_file_budgets.py`` : entrée ``report/render_helpers.py``
+  remplacée par ``reports_v2/_helpers/render_helpers.py``
+  (budget 480 inchangé).
+
+**Acceptance Phase 5.A+B** : 5019 tests passent, lint vert,
+architecture vérifiée (anti-cycles, file budgets).  Aucune
+régression sur les renderers thématiques (toujours legacy).
+
+#### Phase 5.C.batch1 — Lot 1 : 5 renderers les plus petits (2026-05)
+
+Première vague de migration des 22 renderers thématiques.  On
+relocalise verbatim, sans toucher au contrat avec
+``BenchmarkResult`` legacy — la convergence avec ``RunResult``
+canonique reste un sprint à part entière (5.D ou 5.E selon
+priorité).
+
+Convention de nommage : ``picarones.report.<theme>_render`` →
+``picarones.reports_v2.html.renderers.<theme>``.  Le suffixe
+``_render`` est retiré (déjà implicite dans la position).
+
+**Migrations effectuées** :
+
+| Source legacy                            | Destination canonique                                |
+|------------------------------------------|------------------------------------------------------|
+| ``report/searchability_render.py`` (103) | ``reports_v2/html/renderers/searchability.py``       |
+| ``report/specialization_render.py`` (113)| ``reports_v2/html/renderers/specialization.py``      |
+| ``report/marginal_cost_render.py`` (111) | ``reports_v2/html/renderers/marginal_cost.py``       |
+| ``report/rare_token_recall_render.py`` (116)| ``reports_v2/html/renderers/rare_token_recall.py``|
+| ``report/readability_render.py`` (126)   | ``reports_v2/html/renderers/readability.py``         |
+
+Total : ~569 lignes relocalisées.  Les chemins ``report/X_render.py``
+deviennent des shims minimaux (< 20 lignes) avec
+``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- ``reports_v2/html/renderers/specialization.py`` import canonique
+  ``picarones.evaluation.metrics.specialization`` (au lieu du shim
+  legacy ``picarones.measurements.specialization``) pour respecter
+  la règle layer-dependencies (interdiction d'importer du legacy
+  depuis ``reports_v2/``).
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu à
+  ``"specialization"`` : son shim legacy n'a plus de consommateur
+  production (le renderer est désormais dans ``reports_v2/``).
+- 3 tests (``test_extra_metrics.py``,
+  ``test_sprint86_aii5_html.py``,
+  ``test_sprint87_readability_html.py``,
+  ``test_sprint89_specialization.py``) mis à jour pour pointer
+  vers les nouveaux chemins canoniques.
+- ``picarones/report/generator.py`` mis à jour pour importer les
+  5 renderers depuis ``reports_v2/html/renderers/``.
+
+**Acceptance batch 1** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+**Reporté aux batches suivants** :
+
+- Batch 2 ✅ (cf. ci-dessous) — 5 renderers (45-165 LOC).
+- Batch 3 ✅ (cf. ci-dessous) — 5 renderers (173-222 LOC).
+- Batch 4 ✅ (cf. ci-dessous) — 5 renderers (188-321 LOC).
+- Batch 5 ✅ (cf. ci-dessous) — 5 renderers (148-314 LOC).
+- Batch 6 ✅ (cf. ci-dessous) — 2 renderers (``levers``, ``philological``).
+- Batch 7 ✅ (cf. ci-dessous) — pré-requis migrés
+  (``roman_numerals``, ``numerical_sequences``,
+  ``pipeline_benchmark``, ``pipeline_comparison``,
+  ``core/pipeline``) puis 2 renderers
+  (``numerical_sequences``, ``pipeline``).
+- Phase 5.D ✅ — 5 vues (``views/*.py``).
+- Phase 5.E ✅ — ``generator.py``, ``comparison.py``,
+  ``snapshot.py``, ``report_data/`` (8 fichiers), templates
+  Jinja2 (13 fichiers), ``picarones/i18n.py``.
+
+Phase 5 est **terminée** côté ``report/``.
+
+**Note sur ``core/pipeline.py``** : la Phase 5.C.batch7 a
+*relocalisé* le ``PipelineRunner`` legacy de ``core/pipeline.py``
+vers ``evaluation/pipeline.py``, mais **n'a pas effectué la
+convergence** avec le canonique ``picarones.pipeline.executor``
+(designs incompatibles : ``BaseModule`` vs ``StepExecutor``,
+payloads bruts vs ``Artifact`` typés, dataclass mutable vs
+Pydantic immutable, ...).  L'audit détaillé + sub-plan est dans
+``docs/migration/pipeline-convergence-plan.md``.  La
+recommandation est la stratégie « wrapper legacy → canonique »
+(3-4 sessions) qui préserve l'API publique des callers tout en
+unifiant le moteur.  Décision sur quand exécuter la convergence
+laissée au prochain sprint dédié.
+
+#### Phase 5.C.batch2 — Lot 2 : 5 renderers moyens (2026-05)
+
+Deuxième vague.  Substitution dans la sélection initiale :
+``numerical_sequences_render`` reporté au batch 3 (sa dépendance
+``measurements/numerical_sequences.py`` dépend elle-même de
+``measurements/roman_numerals.py``, deux modules legacy non
+migrés vers ``evaluation/metrics/`` ; le renderer ne peut donc pas
+les importer depuis le canonique).  Remplacé par
+``longitudinal_render`` qui n'a pas de dépendance legacy.
+
+**Migrations effectuées** :
+
+| Source legacy                                | Destination canonique                                |
+|----------------------------------------------|------------------------------------------------------|
+| ``report/difficulty_render.py`` (45)         | ``reports_v2/html/renderers/difficulty.py``          |
+| ``report/lexical_modernization_render.py`` (114) | ``reports_v2/html/renderers/lexical_modernization.py`` |
+| ``report/multirun_stability_render.py`` (151)| ``reports_v2/html/renderers/multirun_stability.py``  |
+| ``report/throughput_render.py`` (154)        | ``reports_v2/html/renderers/throughput.py``          |
+| ``report/longitudinal_render.py`` (165)      | ``reports_v2/html/renderers/longitudinal.py``        |
+
+Total : ~629 lignes relocalisées.  5 nouveaux shims minimaux
+(< 20 lignes) avec ``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- ``reports_v2/html/renderers/lexical_modernization.py`` import
+  canonique ``picarones.evaluation.metrics.lexical_modernization``
+  (au lieu du shim legacy ``picarones.measurements.lexical_modernization``).
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu à
+  ``"lexical_modernization"`` (même rationale que ``specialization``
+  au batch 1).
+- Tests + ``picarones/report/generator.py`` mis à jour pour les
+  5 chemins canoniques.
+
+**Acceptance batch 2** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+**Cumul Phase 5.C** (batches 1+2) : 10 / 22 renderers migrés
+(~1198 lignes).  12 renderers restants.
+
+#### Phase 5.C.batch3 — Lot 3 : 5 renderers moyens (2026-05)
+
+Troisième vague.  Tous les renderers sélectionnés sont
+**purs sur le contrat** : import depuis ``_helpers/`` uniquement,
+pas de dépendance sur des modules legacy non-migrés.
+
+**Migrations effectuées** :
+
+| Source legacy                                  | Destination canonique                                  |
+|------------------------------------------------|--------------------------------------------------------|
+| ``report/module_audit_render.py`` (173)        | ``reports_v2/html/renderers/module_audit.py``          |
+| ``report/incremental_comparison_render.py`` (201)| ``reports_v2/html/renderers/incremental_comparison.py``|
+| ``report/image_predictive_render.py`` (207)    | ``reports_v2/html/renderers/image_predictive.py``      |
+| ``report/error_absorption_render.py`` (210)    | ``reports_v2/html/renderers/error_absorption.py``      |
+| ``report/ner_render.py`` (222)                 | ``reports_v2/html/renderers/ner.py``                   |
+
+Total : ~1013 lignes relocalisées.  5 nouveaux shims minimaux
+(< 20 lignes) avec ``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- Tests + ``picarones/report/generator.py`` mis à jour pour les
+  5 chemins canoniques.
+
+**Acceptance batch 3** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+**Cumul Phase 5.C** (batches 1+2+3) : 15 / 22 renderers migrés
+(~2211 lignes).  7 renderers restants.
+
+#### Phase 5.C.batch4 — Lot 4 : 5 renderers moyens-gros (2026-05)
+
+Quatrième vague.  Tous les renderers sélectionnés sont **purs sur
+le contrat externe** (import depuis ``_helpers/`` uniquement).
+``robustness_projection`` avait un import lazy interne vers
+``picarones.measurements.robustness_projection`` qui a été redirigé
+vers le canonique ``picarones.evaluation.metrics.robustness_projection``.
+
+**Migrations effectuées** :
+
+| Source legacy                                  | Destination canonique                                  |
+|------------------------------------------------|--------------------------------------------------------|
+| ``report/stratification_render.py`` (188)      | ``reports_v2/html/renderers/stratification.py``        |
+| ``report/baseline_render.py`` (238)            | ``reports_v2/html/renderers/baseline.py``              |
+| ``report/inter_engine_render.py`` (245)        | ``reports_v2/html/renderers/inter_engine.py``          |
+| ``report/robustness_projection_render.py`` (252) | ``reports_v2/html/renderers/robustness_projection.py``|
+| ``report/calibration_render.py`` (321)         | ``reports_v2/html/renderers/calibration.py``           |
+
+Total : ~1244 lignes relocalisées.  5 nouveaux shims minimaux
+(< 20 lignes) avec ``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu à
+  ``"robustness_projection"`` (même rationale que les batches
+  précédents).
+- Tests + ``picarones/report/generator.py`` mis à jour pour les
+  5 chemins canoniques.
+
+**Acceptance batch 4** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+**Cumul Phase 5.C** (batches 1+2+3+4) : 20 / 22 renderers migrés
+(~3455 lignes).  2 renderers restants : ``pipeline_render`` (707 l)
+et ``philological_render`` (595 l) — les XXL — auront leur propre
+batch dédié.
+
+#### Phase 5.C.batch5 — Lot 5 : 5 renderers moyens-gros (2026-05)
+
+Cinquième vague.  Inclut les 3 renderers de la famille
+``taxonomy``, ``worst_lines`` et ``pipeline_dag``.  Restera ensuite
+batch 6 (XXL + ``levers``) et la migration des 5 vues
+(``views/*.py``).
+
+**Migrations effectuées** :
+
+| Source legacy                                   | Destination canonique                                |
+|-------------------------------------------------|------------------------------------------------------|
+| ``report/taxonomy_intra_doc_render.py`` (148)   | ``reports_v2/html/renderers/taxonomy_intra_doc.py``  |
+| ``report/taxonomy_cooccurrence_render.py`` (161)| ``reports_v2/html/renderers/taxonomy_cooccurrence.py``|
+| ``report/worst_lines_render.py`` (164)          | ``reports_v2/html/renderers/worst_lines.py``         |
+| ``report/taxonomy_comparison_render.py`` (233)  | ``reports_v2/html/renderers/taxonomy_comparison.py`` |
+| ``report/pipeline_dag_render.py`` (314)         | ``reports_v2/html/renderers/pipeline_dag.py``        |
+
+Total : ~1020 lignes relocalisées.
+
+**Adaptations transverses** :
+
+- ``reports_v2/html/renderers/worst_lines.py`` :
+  - import ``WorstLineEntry`` redirigé vers
+    ``picarones.evaluation.metrics.worst_lines``
+  - import ``compute_char_diff`` redirigé vers
+    ``picarones.evaluation`` (au lieu de ``picarones.core.diff_utils``,
+    rejeté par la règle layer-dependencies sur ``reports_v2``).
+
+**Cumul Phase 5.C** (batches 1+2+3+4+5) : 20 + 5 = **25 renderers
+migrés**, soit l'intégralité moins ``pipeline_render`` et
+``philological_render`` (XXL) et ``levers`` (oublié dans le plan
+initial).  Reste batch 6 (3 renderers) puis Phase 5.D (5 vues).
+
+#### Phase 5.C.batch6 — Lot 6 : levers + philological (2026-05)
+
+Sixième vague.  Inclut le plus gros renderer non-bloqué
+(``philological``, 527 LOC) et ``levers`` (249 LOC).
+``pipeline_render`` (707 l) reporté à un batch 7 dédié car il
+dépend de ``measurements/pipeline_benchmark`` et
+``measurements/pipeline_comparison`` non encore migrés vers
+``evaluation/`` (rejetés par layer-dependencies).
+``numerical_sequences_render`` (149 l) reporté pour la même
+raison (dépendance vers ``measurements/numerical_sequences``
+qui dépend de ``measurements/roman_numerals``).
+
+**Migrations effectuées** :
+
+| Source legacy                               | Destination canonique                                |
+|---------------------------------------------|------------------------------------------------------|
+| ``report/levers_render.py`` (249)           | ``reports_v2/html/renderers/levers.py``              |
+| ``report/philological_render.py`` (527)     | ``reports_v2/html/renderers/philological.py``        |
+
+Total : ~776 lignes relocalisées.
+
+**Adaptations transverses** :
+
+- ``test_sprint82_levers.py`` : monkeypatch sur `_FORMATTERS`
+  pointe désormais vers le module canonique
+  ``picarones.reports_v2.html.renderers.levers``.
+- ``test_file_budgets.py`` : entrée
+  ``report/philological_render.py`` retirée, remplacée par
+  ``reports_v2/html/renderers/philological.py`` (budget
+  inchangé à 700).
+
+**Cumul Phase 5.C** (batches 1-6) : 27 / 29 renderers migrés
+(~5232 lignes).  2 renderers restants pour batch 7 :
+``pipeline_render`` (707) et ``numerical_sequences_render`` (149).
+
+**Acceptance batch 6** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+#### Phase 5.C.batch7 — Lot 7 : pré-requis + 2 derniers renderers (2026-05)
+
+Le batch 7 finalise Phase 5.C en migrant **d'abord** les
+modules de mesure dont dépendent les renderers
+``numerical_sequences`` et ``pipeline`` :
+
+| Source legacy                                  | Destination canonique                          |
+|------------------------------------------------|------------------------------------------------|
+| ``measurements/roman_numerals.py`` (478)       | ``evaluation/metrics/roman_numerals.py``       |
+| ``measurements/numerical_sequences.py`` (422)  | ``evaluation/metrics/numerical_sequences.py``  |
+| ``measurements/pipeline_benchmark.py`` (367)   | ``evaluation/pipeline_benchmark.py``           |
+| ``measurements/pipeline_comparison.py`` (301)  | ``evaluation/pipeline_comparison.py``          |
+| ``core/pipeline.py`` (607)                     | ``evaluation/pipeline.py``                     |
+
+Puis les 2 derniers renderers :
+
+| Source legacy                                  | Destination canonique                                |
+|------------------------------------------------|------------------------------------------------------|
+| ``report/numerical_sequences_render.py`` (149) | ``reports_v2/html/renderers/numerical_sequences.py`` |
+| ``report/pipeline_render.py`` (707)            | ``reports_v2/html/renderers/pipeline.py``            |
+
+Total : ~3031 lignes relocalisées dans ce batch.  7 nouveaux
+shims minimaux (< 25 lignes) avec ``DeprecationWarning``.
+
+État final de ``picarones/core/``
+---------------------------------
+
+Le répertoire ``picarones/core/`` est désormais **entièrement
+constitué de shims** (10 fichiers, tous < 30 lignes).  Aucun
+module Cercle 1 réel ne subsiste — les abstractions vivent dans
+``domain/`` (Pydantic immutable) et ``evaluation/`` (riche en
+behavior).  ``EXPECTED_CERCLE1`` du test
+``test_public_api.py::TestCercle1IsLean`` est désormais un set
+vide, documentant explicitement que la Phase 1 du retrait du
+legacy est complète au niveau ``core/``.
+
+Adaptations transverses
+-----------------------
+
+- Imports internes mis à jour entre modules canoniques
+  (``evaluation/metrics/numerical_sequences.py`` → canonique
+  ``roman_numerals``, ``evaluation/pipeline_comparison.py`` →
+  canonique ``pipeline_benchmark``, etc.).
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu à
+  ``"numerical_sequences"``, ``"numerical_sequences_hooks"``,
+  ``"pipeline_benchmark"``, ``"pipeline_comparison"``.
+- ``test_file_budgets.py`` : 4 entrées legacy retirées,
+  remplacées par les chemins canoniques.
+- ``test_public_api.py::EXPECTED_CERCLE1`` : ``pipeline.py``
+  retiré (set désormais vide).
+- ``docs/tutorials/writing-a-pipeline-module.md`` : tous les
+  imports mis à jour vers les chemins canoniques.
+
+**Cumul Phase 5.C** (batches 1-7) : **29 / 29 renderers migrés**
+(~8263 lignes au total).  Phase 5.C est terminée.
+
+**Acceptance batch 7** : 5019 tests passent, lint vert,
+architecture vérifiée (anti-cycles, file budgets,
+EXPECTED_CERCLE1 vide).
+
+Restantes pour Phase 5
+----------------------
+
+- Phase 5.D ✅ — 5 vues (``views/*.py``) migrées vers
+  ``reports_v2/html/views/``.
+- Phase 5.E : ``generator.py``, ``comparison.py``,
+  ``snapshot.py``, ``report_data/``, templates Jinja2.
+
+#### Phase 5.D — Migration des 5 vues thématiques (2026-05)
+
+Phase 5.D migre les 5 vues thématiques (orchestrateurs des
+renderers) vers ``reports_v2/html/views/``.  Ces vues prennent un
+``report_data`` dict et composent plusieurs renderers en blocs
+``<details>`` collapsibles, avec adaptive masking.
+
+**Migrations effectuées** :
+
+| Source legacy                                  | Destination canonique                              |
+|------------------------------------------------|----------------------------------------------------|
+| ``report/views/__init__.py`` (65)              | ``reports_v2/html/views/__init__.py``              |
+| ``report/views/advanced_taxonomy.py`` (245)    | ``reports_v2/html/views/advanced_taxonomy.py``     |
+| ``report/views/diagnostics.py`` (247)          | ``reports_v2/html/views/diagnostics.py``           |
+| ``report/views/economics.py`` (219)            | ``reports_v2/html/views/economics.py``             |
+| ``report/views/pipeline.py`` (237)             | ``reports_v2/html/views/pipeline.py``              |
+| ``report/views/robustness.py`` (101)           | ``reports_v2/html/views/robustness.py``            |
+
+Total : ~1114 lignes relocalisées.  6 nouveaux shims minimaux
+(< 25 lignes) avec ``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- 6 imports de modules de mesure dans les vues redirigés vers
+  leurs canoniques ``evaluation/metrics/`` :
+  ``taxonomy_comparison``, ``incremental_comparison``,
+  ``levers``, ``image_predictive``, ``worst_lines``,
+  ``throughput``.
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu de 6
+  modules supplémentaires (mêmes raisons que les renderers).
+- Renderers ``reports_v2/html/renderers/`` cross-référencés
+  par les vues — toujours au canonique.
+
+**Acceptance Phase 5.D** : 5019 tests passent, lint vert,
+architecture vérifiée.
+
+#### Phase 5.E — Migration generator + comparison + snapshot + report_data + templates + i18n (2026-05)
+
+Phase 5.E finalise Phase 5 en migrant les derniers composants
+``report/`` :
+
+**Migrations effectuées** :
+
+| Source legacy                                  | Destination canonique                              |
+|------------------------------------------------|----------------------------------------------------|
+| ``report/generator.py`` (466)                  | ``reports_v2/html/generator.py``                   |
+| ``report/comparison.py`` (409)                 | ``reports_v2/html/comparison.py``                  |
+| ``report/snapshot.py`` (266)                   | ``reports_v2/html/snapshot.py``                    |
+| ``report/report_data/__init__.py`` (132)       | ``reports_v2/html/data/__init__.py``               |
+| ``report/report_data/_helpers.py`` (30)        | ``reports_v2/html/data/_helpers.py``               |
+| ``report/report_data/documents.py`` (167)      | ``reports_v2/html/data/documents.py``              |
+| ``report/report_data/engines.py`` (103)        | ``reports_v2/html/data/engines.py``                |
+| ``report/report_data/extra_metrics.py`` (272)  | ``reports_v2/html/data/extra_metrics.py``          |
+| ``report/report_data/pareto.py`` (159)         | ``reports_v2/html/data/pareto.py``                 |
+| ``report/report_data/scatter.py`` (56)         | ``reports_v2/html/data/scatter.py``                |
+| ``report/report_data/statistics.py`` (216)     | ``reports_v2/html/data/statistics.py``             |
+| ``report/templates/`` (13 fichiers)            | ``reports_v2/html/templates/`` (13 fichiers)       |
+| ``picarones/i18n.py`` (124)                    | ``picarones/reports_v2/i18n/__init__.py``          |
+| ``report/__init__.py`` (3)                     | shim re-export                                     |
+
+Total : ~2400 lignes relocalisées + 13 templates Jinja2 + le
+loader i18n.  Au total **12 nouveaux shims minimaux** (< 25
+lignes) avec ``DeprecationWarning``.
+
+**Adaptations transverses** :
+
+- ``reports_v2/html/snapshot.py`` ne peut pas importer
+  ``picarones.__version__`` (interdit par layer-deps) : utilise
+  ``importlib.metadata`` avec fallback (idem qu'au Phase 4-ter).
+- ``reports_v2/html/snapshot.py`` import ``pricing`` redirigé
+  vers le canonique ``evaluation/metrics/pricing``.
+- ``reports_v2/html/generator.py`` toutes les ~30 imports
+  internes redirigés vers ``reports_v2/html/{data,renderers,
+  views,snapshot}`` et ``evaluation/{statistics,metric_result,
+  benchmark_result}``.
+- ``reports_v2/html/data/`` : 7 imports vers
+  ``measurements/{statistics,difficulty,pricing,marginal_cost,
+  rare_tokens,taxonomy_cooccurrence,taxonomy_intra_doc}``
+  redirigés vers ``evaluation/{statistics,metrics/...}``.
+- ``reports_v2/html/views/`` : 6 imports vers
+  ``measurements/{taxonomy_comparison,incremental_comparison,
+  levers,image_predictive,worst_lines,throughput}`` redirigés
+  vers ``evaluation/metrics/...``.
+- ``picarones/reports_v2/__init__.py`` : nouveau loader
+  ``from picarones.reports_v2.html.generator import ReportGenerator``.
+- ``test_module_coverage.py::TEST_ONLY_BASELINE`` étendu à 3
+  modules : ``statistics``, ``pricing``, ``difficulty``.
+- ``test_file_budgets.py`` : 2 entrées legacy retirées,
+  remplacées par les chemins canoniques ; templates dir
+  référencé via ``reports_v2/html/templates/``.
+- 28+ chemins de templates dans les tests redirigés vers
+  ``reports_v2/html/templates/``.
+- Tests qui faisaient ``from picarones import i18n`` redirigés
+  vers ``from picarones.reports_v2 import i18n`` (le shim ne
+  ré-exporte pas ``_get_labels_cached`` — privé).
+
+État final de ``picarones/report/``
+-----------------------------------
+
+Le répertoire ``picarones/report/`` ne contient désormais
+**que des shims** (~30 fichiers).  Aucun module avec du
+contenu réel ne subsiste.  Le canonique vit intégralement
+dans ``picarones/reports_v2/html/`` (générateur + renderers
++ vues + données + templates + comparaison + snapshot).
+
+**Acceptance Phase 5.E + Phase 5 entière** : 5019 tests
+passent, lint vert, architecture vérifiée (anti-cycles,
+file budgets, module coverage).
+
+### Phase 6 — Pipelines OCR+LLM (`pipelines/`)
+
+**Modules** : `pipelines/base.OCRLLMPipeline` (3 modes), `pipelines/
+over_normalization.detect_over_normalization`.
+
+**Cible** :
+
+- Les 3 modes deviennent des `PipelineSpec` YAML composés (OCR
+  adapter → LLM adapter avec `inputs_from`).
+- `over_normalization` devient une métrique enregistrée dans
+  `evaluation/metrics/over_normalization.py`.
+
+**Effort** : 3-5 jours.
+
+**Acceptance** : les 3 callers internes (`web/benchmark_utils.py`,
+`measurements/runner/document.py`, `fixtures.py`) consomment des
+`PipelineSpec` YAML rewrite.
+
+### Phase 7 — Modules officiels (`modules/`)
+
+**Module** : `modules/alto_text_to_mono_region.TextToAltoMonoRegion`
+(310 LOC) — baseline TEXT → ALTO.
+
+**Cible** : `picarones.formats.alto.baseline_reconstruction` ou
+`picarones.evaluation.projectors.text_to_alto` (selon où la
+sémantique colle le mieux).
+
+**Effort** : 1 jour.
+
+### Phase 8 — Importers (`extras/importers/`)
+
+**Modules** : `iiif.py`, `gallica.py`, `escriptorium.py`, `_http.py`,
+`_fallback_log.py`.
+
+**Cible** : `picarones/adapters/corpus/{iiif,gallica,escriptorium}.py`
++ helpers partagés dans `adapters/corpus/_http.py`.
+
+**Effort** : 3-5 jours.
+
+### Phase 9 — Web UI riche (`web/`)
+
+**Modules** : 9 routers (`config`, `engines`, `history`, `home`,
+`importers`, `normalization`, `reports`, `synthesis`, `system`) +
+utilitaires (`benchmark_utils.py`, `engine_utils.py`,
+`corpus_utils.py`, `config_utils.py`, `state.py`, `security.py`,
+`models.py`, `jobs.py`, `maintenance.py`, `app.py`) + templates
+Jinja2.
+
+**Cible** : `picarones/interfaces/web/routers/<router>.py` + utils
+partagés dans `interfaces/web/_utils/` + templates dans
+`interfaces/web/templates/`.
+
+**Effort** : 8-12 jours.
+
+**Acceptance** : régression sur tous les `tests/web/test_sprint*.py`
+existants.  L'UI riche (sélecteur moteurs dynamique, gallery,
+stratification, narrative inline, browse corpus) doit produire les
+mêmes pages HTML.
+
+### Phase 10 — CLI complète (`cli/`)
+
+**Commandes** : 13 commandes legacy non couvertes (`metrics`,
+`engines`, `info`, `demo`, `diagnose`, `economics`, `edition`,
+`compare`, `import` group, `serve`, `history`, `robustness`,
+`pipeline` group avec sous-commandes `run` et `compare`).
+
+**Cible** : `picarones/interfaces/cli/<command>.py`.  L'entry point
+`console_scripts` du `pyproject.toml` doit pointer sur
+`picarones.interfaces.cli:cli` (à la place de `picarones.cli:cli`).
+
+**Effort** : 4-6 jours.
+
+### Phase 11 — Retrait final + release 2.0
+
+- Suppression des 10 packages legacy.
+- Suppression des shims `DeprecationWarning` introduits aux phases
+  précédentes.
+- Mise à jour du `pyproject.toml` (`console_scripts`,
+  `[project.urls]`).
+- Rédaction du CHANGELOG 2.0 final avec liste exhaustive des
+  breaking changes (les utilisateurs externes ont eu
+  `DeprecationWarning` à chaque phase).
+- Génération SBOM + signature SLSA Level 3 (cf.
+  `docs/operations/supply-chain.md`).
+- Bump `_version.py` et tag `v2.0.0`.
+
+**Effort** : 3-5 jours.
+
+## Estimation totale
+
+| Phase | Effort min | Effort max |
+|-------|------------|------------|
+| 0 | 2 j | 3 j |
+| 1 | 5 j | 8 j |
+| 2 | 5 j | 7 j |
+| 3 | 8 j | 12 j |
+| 4 | 23 j | 28 j |
+| 5 | 12 j | 18 j |
+| 6 | 3 j | 5 j |
+| 7 | 1 j | 1 j |
+| 8 | 3 j | 5 j |
+| 9 | 8 j | 12 j |
+| 10 | 4 j | 6 j |
+| 11 | 3 j | 5 j |
+| **Total** | **77 j** | **110 j** |
+
+Soit **3,5 à 5 mois** d'effort focalisé en mode développeur unique.
+Aucune contrainte de date — on livre quand c'est propre.
+
+## Stratégie de régression — invariant non négociable
+
+À chaque phase :
+
+1. **Avant** : exécuter le harness legacy sur 3 corpus de référence
+   (small / medium / large) → capture des outputs en JSON / HTML
+   bit-for-bit.
+2. **Pendant** : réécrire la fonctionnalité dans le rewrite.
+3. **Après** : exécuter le harness rewrite et **diff** vs. snapshot
+   legacy.
+4. **Tolérance** : explicite par métrique dans
+   `docs/migration/regression-tolerances.md`.  Tout écart non
+   tolerance = régression à corriger avant merge.
+
+Cela évite le piège classique du rewrite : *« ça compile, ça tourne,
+mais le CER a glissé de 0,002 par doc »*.
+
+## Anti-bricolage — règles
+
+1. **Pas de double API** : pendant la migration d'un module, on ne
+   garde **pas** le legacy en parallèle dans le code de production.
+   Soit on importe l'ancien, soit le nouveau.  Le harness de
+   régression suffit pour valider.
+2. **Pas de shim sans date de retrait** : tout `DeprecationWarning`
+   introduit doit être inscrit dans le CHANGELOG avec date de
+   retrait (la 2.0).
+3. **Pas de TODO dans le code mergé** : un TODO = une issue ouverte
+   référencée par numéro.
+4. **Pas de copié-collé** : si une logique apparaît dans deux
+   modules, extraire en helper partagé dès la deuxième occurrence.
+5. **Pas de god-module** : `tests/architecture/test_file_budgets.py`
+   reste l'autorité.
+
+## Statut
+
+| Phase | Statut |
+|-------|--------|
+| 0 | ✅ Terminée |
+| 1 | ✅ Partielle (3/9 modules ; les 6 autres → Phase 4-bis) |
+| 2 | ✅ Terminée (8/8 modules statistics migrés) |
+| 3 | ✅ Terminée (11 modules narrative + 2 templates + 18 détecteurs migrés) |
+| 4 | ✅ Partielle (9 modules autonomes/cascade ; 13 modules + 6 modules `core/` + 1 sous-package → Phase 4-bis) |
+| 4-bis | 🟡 Diagnostic posé, exécution reportée (couplage dicts-string plus complexe que prévu — voir détail Phase 4) |
+| 5-11 | ⚪ À démarrer |
+
+**Dernière mise à jour** : 2026-05 (Phase 4-bis tentative + revert + diagnostic).
+
+**Reste en place suite à la tentative Phase 4-bis** : aliases
+``TEXT``/``ALTO``/``PAGE`` dans ``domain.artifacts.ArtifactType``
+(inoffensif) + hook ``_missing_`` pour accepter les valeurs string
+legacy.  Préparation pour la session future qui complétera Phase
+4-bis.

docs/migration/pipeline-convergence-plan.md

@@ -0,0 +1,410 @@
+# Audit & sub-plan — Convergence ``PipelineRunner`` legacy ↔ ``PipelineExecutor`` canonique
+
+> **Note** : ce document est l'audit demandé en conclusion de Phase 5
+> du plan de retrait du legacy
+> (cf. ``docs/migration/legacy-retirement-plan.md``).  Il identifie
+> les différences entre les deux designs de pipeline, inventaire les
+> callers, propose 3 stratégies de convergence et recommande un
+> sub-plan d'exécution.
+
+---
+
+## 1. État des lieux
+
+Deux designs cohabitent :
+
+### 1.A Legacy — ``picarones.evaluation.pipeline`` (ex-``core/pipeline.py``)
+
+Sprint 63 (axe B), 607 lignes.  Relocalisé en Phase 5.C.batch7
+mais **non refactoré**.
+
+**Caractéristiques** :
+
+- ``PipelineRunner`` : classe statique avec ``.run(spec, document, initial_inputs) -> PipelineResult``.
+- ``PipelineSpec`` : dataclass mutable.
+- ``PipelineStep`` : dataclass avec ``module: BaseModule`` (instance Python).
+- ``StepResult`` : dataclass avec ``junction_metrics: dict[str, dict[str, Any]]``.
+- ``PipelineResult`` : dataclass avec ``steps: list[StepResult]``.
+- Modules : ``BaseModule`` ABC consommant des **payloads bruts**
+  (``{ArtifactType: str | dict | list | ...}``).
+- Évaluation : ``compute_at_junction`` automatique à chaque étape
+  contre la GT du document si ``GTLevel`` correspond.
+- Pas de cache d'artefacts.
+- Pas de ``ExecutionPlan`` séparé — résolution implicite des
+  inputs au runtime via un bag versionné.
+
+### 1.B Canonique — ``picarones.pipeline.executor`` + ``planner`` + ``protocols``
+
+Sprints S6-S7-S28, design rewrite ciblé.
+
+**Caractéristiques** :
+
+- ``PipelineExecutor`` : classe instanciable avec
+  ``adapter_resolver`` injecté + ``planner`` optionnel +
+  ``artifact_store`` optionnel.
+- Méthode ``run(spec, document, initial_inputs, context) ->
+  PipelineResult`` (compat S7) qui plan-then-execute.
+- Méthode canonique ``run_plan(plan, document, initial_inputs,
+  context)`` qui consomme un ``ExecutionPlan`` pré-calculé.
+- ``PipelineSpec`` : Pydantic immutable
+  (``picarones.domain.pipeline_spec``), sérialisable YAML.
+- ``PipelineStep`` : Pydantic immutable avec ``adapter_name: str``
+  (pas d'instance — résolution applicative).
+- ``ExecutionPlan`` : produit du ``PipelinePlanner`` — porte
+  ``StepInputBinding`` explicites + ``MetricJunction`` détectées.
+- ``StepResult`` : Pydantic immutable avec
+  ``produced_artifacts: dict[str, str]`` (map ArtifactType.value →
+  Artifact.id).
+- ``PipelineResult`` : Pydantic immutable avec
+  ``artifacts: tuple[Artifact, ...]``.
+- Adapters : ``StepExecutor`` Protocol (runtime-checkable)
+  consommant des **``Artifact`` typés**
+  (``{ArtifactType: Artifact(uri, content_hash, provenance)}``).
+- Cache d'artefacts via ``ArtifactCachePort`` (Sprint S29 + S47).
+- ``RunContext`` Pydantic injecté à chaque ``execute()`` —
+  document_id, code_version, pipeline_name, workspace_uri.
+
+---
+
+## 2. Différences API détaillées
+
+| Dimension                  | Legacy (``evaluation.pipeline``)         | Canonique (``pipeline.executor``)             |
+|----------------------------|------------------------------------------|-----------------------------------------------|
+| Construction               | classe statique                          | instance avec deps injectées                  |
+| Spec                       | dataclass mutable                        | Pydantic immutable, YAML-sérialisable         |
+| Step                       | porte ``module: BaseModule``             | porte ``adapter_name: str``                   |
+| Résolution adapters        | implicite (instance dans spec)           | explicite (``adapter_resolver`` callable)     |
+| Résolution inputs          | implicite (last-producer-wins)           | explicite (``StepInputBinding``)              |
+| Validation spec            | au runtime                               | au planning (``PipelinePlanner``)             |
+| Type passé aux modules     | payload brut (str, dict, list…)          | ``Artifact`` typé                             |
+| Provenance                 | absente                                  | ``ProvenanceRecord`` automatique              |
+| Hash de contenu            | absent                                   | ``Artifact.content_hash`` SHA-256             |
+| Cache inter-runs           | absent                                   | ``ArtifactCachePort``                         |
+| ``RunContext``             | absent                                   | injecté à chaque step                         |
+| Évaluation auto vs GT      | oui, à chaque step                       | non (sortie : artefacts seulement)            |
+| ``junction_metrics``       | dans ``StepResult``                      | absent du runtime, calculé à part             |
+| Représentation des étapes  | objets Python uniquement                 | YAML + Python                                 |
+
+---
+
+## 3. Inventaire des callers
+
+### 3.A Legacy (``evaluation.pipeline``)
+
+**Production** (4 fichiers) :
+
+- ``picarones/__init__.py`` — re-export de ``PipelineRunner``,
+  ``PipelineSpec``, ``PipelineStep``, ``StepResult``,
+  ``PipelineResult`` dans l'API publique.
+- ``picarones/evaluation/pipeline_benchmark.py`` — orchestre
+  l'exécution corpus-wide via ``PipelineRunner.run()``.
+- ``picarones/evaluation/pipeline_comparison.py`` — compare N
+  ``PipelineSpec`` via ``run_pipeline_benchmark``.
+- ``picarones/measurements/pipeline_spec_loader.py`` — charge des
+  YAML legacy en ``PipelineSpec`` + ``PipelineStep`` legacy
+  (avec instanciation des modules par ``adapter_name``).
+
+**Tests** : 7 fichiers de tests directs (``test_sprint63_*``,
+``test_sprint64_*``, ``test_sprint65_*``, ``test_sprint66_*``,
+``test_sprint67_*``, ``test_sprint68_*``, etc.).
+
+### 3.B Canonique (``pipeline.executor``)
+
+**Production** : 0 caller production (le rewrite n'a pas encore
+de service applicatif qui consomme l'executor canonique en
+mode mono-document).
+
+**Tests** : 9 fichiers de tests directs.  Tests-only à ce jour.
+
+**Conclusion sur les callers** : le legacy est en production,
+le canonique est test-only.  La convergence doit migrer le
+legacy **sans casser les 7+4 = 11 fichiers tests/prod
+existants**.
+
+---
+
+## 4. Stratégies de convergence
+
+### 4.A Wrapper legacy → canonique
+
+Le legacy ``PipelineRunner.run(spec, document, initial_inputs)``
+devient un **adaptateur** qui :
+
+1. Convertit la ``PipelineSpec`` legacy (dataclass + module
+   instance) en ``PipelineSpec`` canonique (Pydantic +
+   adapter_name).
+2. Wrappe chaque ``BaseModule`` en ``StepExecutor`` Protocol.
+3. Convertit les payloads bruts en ``Artifact`` (uri inline,
+   content_hash calculé).
+4. Injecte un ``adapter_resolver`` ad hoc qui retourne les
+   wrappers.
+5. Invoque ``PipelineExecutor.run(spec, document, initial_inputs,
+   context)``.
+6. Reconvertit le ``PipelineResult`` canonique en ``PipelineResult``
+   legacy avec ``junction_metrics`` calculées à partir des
+   artefacts produits.
+
+**Avantages** :
+- Préserve l'API legacy → 0 caller cassé en production.
+- Unifie le moteur d'exécution → 1 seul code path à maintenir.
+- Cohérent avec la philosophie "no breaking change for callers".
+
+**Inconvénients** :
+- 200-400 LOC de glue (conversion bidirectionnelle de types).
+- Coût de performance : double conversion à chaque step.
+- Le double modèle ``Artifact``/payload reste visible côté
+  modules (le wrapper masque mais le concept demeure).
+
+**Effort** : 2-3 sessions.
+
+### 4.B Migration complète
+
+Migrer chaque caller legacy vers l'API canonique :
+
+1. ``pipeline_benchmark`` : passe de ``PipelineRunner.run`` à
+   ``PipelineExecutor.run_plan``.  Les ``StepAggregate`` doivent
+   accepter la nouvelle structure ``StepResult`` (Pydantic).
+2. ``pipeline_comparison`` : idem.
+3. ``pipeline_spec_loader`` : produit des ``PipelineSpec`` Pydantic
+   au lieu de dataclass.  Plus de ``module`` instance — juste
+   ``adapter_name``.
+4. ``__init__.py`` : ré-exporte le canonique.
+5. Tests : 7 fichiers à refactorer (mock adapters → ``StepExecutor``
+   Protocol, payloads → ``Artifact``).
+
+**Avantages** :
+- 1 seul design.  Le legacy disparaît complètement.
+- Pas de glue ni de double conversion.
+- Conforme à la cible architecturale du rewrite.
+
+**Inconvénients** :
+- Massive : ~2500 LOC à toucher entre prod + tests.
+- Le contrat des modules tiers (``BaseModule`` → ``StepExecutor``)
+  change.  Un caller externe (BnF, HF Space) qui utilise
+  ``PipelineRunner.run`` casse silencieusement.
+- Risque de régression non détectée sur les ~7 tests sprints
+  axe B (les fixtures sont volumineuses).
+- Évaluation auto vs GT (legacy : à chaque step) doit être
+  ré-implémentée comme une post-étape canonique.
+
+**Effort** : 5-7 sessions.
+
+### 4.C Cohabitation documentée
+
+État actuel.  Document explicitement que les deux designs sont
+volontaires.  Convergence reportée à un sprint dédié quand un
+caller institutionnel l'exigera (BnF demande un YAML déclaratif
+non-instanciable, ou HF Space veut le cache d'artefacts).
+
+**Avantages** :
+- 0 risque de régression maintenant.
+- Permet de continuer le retrait du legacy sur les autres
+  paquets (Phases 6-11) sans buter sur ce sujet complexe.
+- Le canonique reste prêt pour le jour où il sera vraiment
+  nécessaire.
+
+**Inconvénients** :
+- 2 designs à maintenir.
+- L'objectif "core/ vide" du retrait du legacy n'est pas
+  totalement atteint : ``evaluation/pipeline.py`` reste un module
+  "legacy-style" en cercle 2.
+- Risque que le canonique reste mort-né si personne ne le
+  réclame.
+
+**Effort** : 0 (juste documentation).
+
+---
+
+## 5. Recommandation
+
+> **Mise à jour 2026-05** : l'utilisateur a précisé que le projet
+> est en stand-by jusqu'à la fin de la migration complète et que
+> la rétrocompat de l'API publique n'est pas une contrainte.  Cela
+> élimine l'avantage principal de la stratégie 4.A (wrapper) et
+> rend la stratégie 4.B (migration complète) recommandée :
+
+**Stratégie 4.B — Migration complète** est la voie cible.
+
+Bénéfices avec contrainte API levée :
+
+- 1 seul design final, plus de wrapper interne à maintenir.
+- Le contrat des modules tiers (``BaseModule`` → ``StepExecutor``)
+  peut changer sans gérer la rétrocompat.
+- Les ``Artifact`` typés (provenance, content_hash, uri) deviennent
+  natifs partout — pas de double conversion.
+
+Risques résiduels :
+
+- ~2500 LOC à toucher entre prod + tests.
+- L'évaluation auto vs GT (legacy : à chaque step) doit être
+  ré-implémentée comme une post-étape canonique.
+- Risque de régression sur les ~7 tests sprints axe B
+  (fixtures volumineuses).
+- Plusieurs sessions de travail nécessaires (5-7 sessions).
+
+---
+
+## 6. Découvertes additionnelles (audit complémentaire)
+
+L'audit initial parlait de 4 callers de production de
+``PipelineRunner``.  Une investigation plus poussée révèle un
+écosystème legacy plus large, qui doit être inclus dans le plan :
+
+### 6.A Legacy engines (`picarones/engines/`, ~1500 LOC)
+
+5 modules OCR legacy qui héritent de ``BaseOCREngine`` (lui-même
+extension de ``BaseModule``) :
+
+- ``engines/base.py:BaseOCREngine``
+- ``engines/tesseract.py:TesseractEngine`` (177 l)
+- ``engines/pero_ocr.py:PeroOCREngine`` (182 l)
+- ``engines/mistral_ocr.py:MistralOCREngine`` (231 l)
+- ``engines/google_vision.py:GoogleVisionEngine`` (256 l)
+- ``engines/azure_doc_intel.py:AzureDocIntelEngine``
+
+**Équivalents canoniques existent** dans
+``picarones/adapters/ocr/`` (TesseractAdapter, PeroOCRAdapter,
+etc.) et implémentent déjà ``StepExecutor``.  Mais les noms de
+classes et les APIs publiques **diffèrent** — pas un simple shim.
+
+Callers production des engines legacy :
+- ``picarones/web/benchmark_utils.py``
+- ``picarones/pipelines/base.py`` (lui-même legacy, Phase 6)
+
+### 6.B Legacy LLM (``picarones/llm/``, ~67 LOC)
+
+**Déjà migré** : tous les fichiers sont des shims qui
+ré-exportent depuis ``picarones/adapters/llm/``.  Rien à faire.
+
+### 6.C Legacy modules officiels (``picarones/modules/``)
+
+- ``modules/alto_text_to_mono_region.py:TextToAltoMonoRegion``
+  (310 LOC) — extension de ``BaseModule``.
+
+**Pas d'équivalent canonique** à ce jour.  Cible documentée :
+``picarones/formats/alto/baseline_reconstruction.py`` ou
+``picarones/evaluation/projectors/text_to_alto.py``
+(cf. Phase 7 du plan de retrait).
+
+### 6.D Sémantique des payloads vs Artifacts
+
+La conversion ``BaseModule.process`` ↔ ``StepExecutor.execute``
+n'est pas triviale parce que :
+
+- Le legacy passe des **payloads bruts** :
+  - ``ArtifactType.IMAGE`` → ``str`` (chemin du fichier image)
+  - ``ArtifactType.RAW_TEXT`` → ``str`` (contenu textuel inline)
+  - ``ArtifactType.ALTO_XML`` → ``str`` (contenu XML inline)
+  - ``ArtifactType.ENTITIES`` → ``list[dict]``
+- Le canonique passe des ``Artifact`` Pydantic immutables :
+  - ``uri`` (filesystem ou URI distant)
+  - ``content_hash`` (SHA-256)
+  - ``provenance`` (``ProvenanceRecord``)
+  - **pas de champ ``content`` direct** — le contenu se lit via
+    ``uri``.
+
+Pour les tests legacy qui injectent du contenu inline (mock
+modules retournant ``"hello"``), il faut **soit** :
+
+1. Persister le contenu dans un fichier temporaire et pointer
+   ``artifact.uri`` dessus.
+2. Ajouter une convention ``data:`` URI pour le contenu inline.
+3. Étendre ``Artifact`` avec un champ ``inline_payload: bytes |
+   None`` optionnel.
+
+Décision recommandée : **option 1** (fichier temporaire), parce
+qu'elle préserve la sémantique « un artefact a toujours un
+identifiant filesystem » et permet le cache/provenance proprement.
+
+---
+
+## 7. Sub-plan d'exécution révisé (stratégie 4.B)
+
+### Sub-phase 7.A — Migration des adapters concrets
+
+Bouclage de la migration des adapters legacy (engines/llm/modules)
+vers les canoniques avant de toucher aux pipeline runners.
+
+**Étapes** :
+
+1. ``engines/`` → shims pointant vers ``adapters/ocr/`` (avec
+   alias de classes : ``TesseractEngine = TesseractAdapter``,
+   etc.).
+2. Mise à jour des callers de ``engines/`` à utiliser
+   ``adapters/ocr/`` directement.
+3. ``modules/alto_text_to_mono_region.py`` → migré vers
+   ``picarones/evaluation/projectors/text_to_alto.py`` (canonique
+   en ``StepExecutor``).
+4. Suppression du shim ``engines/``.
+
+**Effort** : 2-3 sessions.
+
+### Sub-phase 7.B — Migration des callers ``PipelineRunner``
+
+Une fois les adapters unifiés sur ``StepExecutor`` :
+
+1. ``pipeline_spec_loader`` : produit des ``picarones.domain.pipeline_spec.PipelineSpec``
+   (Pydantic) avec ``adapter_name: str`` au lieu d'instances.
+2. ``pipeline_benchmark`` : consomme ``PipelineExecutor.run_plan``.
+   ``StepAggregate`` accepte ``StepResult`` Pydantic canonique.
+3. ``pipeline_comparison`` : idem.
+4. ``__init__.py`` : ré-exporte les canoniques.
+
+**Effort** : 2 sessions.
+
+### Sub-phase 7.C — Refactor des tests
+
+Les 7 fichiers de tests legacy axe B (sprints 63-68 + 95) :
+
+- Mocks ``BaseModule`` → mocks ``StepExecutor`` Protocol.
+- Payloads bruts → ``Artifact`` (avec helper
+  ``make_inline_artifact(content, type_)`` pour réduire le
+  boilerplate).
+- ``Document`` legacy → ``DocumentRef`` canonique.
+- Fixtures ``junction_metrics`` → ré-implémentation via
+  post-étape canonique.
+
+**Effort** : 1-2 sessions.
+
+### Sub-phase 7.D — Suppression du legacy
+
+1. Suppression de ``evaluation/pipeline.PipelineRunner``,
+   ``PipelineSpec``, ``PipelineStep``, ``StepResult``,
+   ``PipelineResult`` (le legacy).
+2. Suppression de ``domain/module_protocol.BaseModule``.
+3. Le module ``evaluation/pipeline.py`` réduit à
+   ``_artifact_type_to_gt_level`` ou supprimé totalement.
+4. ``core/pipeline.py`` (shim) supprimé.
+5. ``core/modules.py`` (shim) supprimé.
+
+**Effort** : 0.5 session (suppression mécanique).
+
+---
+
+## 8. Total effort révisé (stratégie 4.B)
+
+| Sub-phase | Description                                | Effort           |
+|-----------|--------------------------------------------|------------------|
+| 7.A       | Migration adapters concrets                | 2-3 sessions     |
+| 7.B       | Migration callers PipelineRunner           | 2 sessions       |
+| 7.C       | Refactor des tests                         | 1-2 sessions     |
+| 7.D       | Suppression du legacy                      | 0.5 session      |
+| **Total** | **Migration complète**                     | **5-8 sessions** |
+
+---
+
+## 9. Ordre d'exécution recommandé
+
+L'ordre **bottom-up** est plus sûr : à chaque étape, les tests
+restent verts.
+
+```
+Sub-phase 7.A (adapters) → Sub-phase 7.B (orchestration) →
+Sub-phase 7.C (tests) → Sub-phase 7.D (suppression)
+```
+
+L'ordre **top-down** (start by removing PipelineRunner, then
+fix everything that breaks) est plus risqué mais plus rapide
+si on accepte une période de tests rouges.
+
+Recommandation : **bottom-up**, par étapes verticales testables.

docs/migration/regression-tolerances.md

@@ -0,0 +1,178 @@
+# Tolérances de régression — legacy ↔ rewrite
+
+> **Audience** : développeur qui migre une fonctionnalité legacy
+> vers le rewrite, reviewer qui relit la PR.
+>
+> **Référence** : [`legacy-retirement-plan.md`](legacy-retirement-plan.md).
+>
+> **Contrat** : le harness `tests/regression/legacy_vs_rewrite/`
+> exécute legacy + rewrite sur les mêmes corpus de référence et
+> compare leurs sorties.  Toute divergence au-delà de la tolérance
+> ε définie ici est une **régression à corriger avant merge**.
+>
+> Une régression peut être :
+>
+> - **Intentionnelle** : la phase de migration corrige un bug
+>   historique → la tolérance est temporairement relâchée AVEC
+>   commentaire pointant vers l'issue.
+> - **Inattendue** : c'est ce que ce document est censé empêcher.
+
+## Principe général
+
+Pour une fonctionnalité donnée, la sortie du rewrite **doit être
+égale** à celle du legacy à la tolérance ε près.  L'égalité est :
+
+- **Bit-for-bit** quand l'output est déterministe (texte, hash, JSON).
+- **Sémantique** quand l'output structurel a des libertés (ordre des
+  éléments d'un set, indentation HTML, ordre des facts narratifs
+  équivalents).
+
+## Table des tolérances par type d'output
+
+### Métriques numériques
+
+| Métrique | ε | Justification |
+|----------|---|---------------|
+| `cer_raw`, `cer_nfc`, `cer_caseless`, `cer_diplomatic` | **0** (bit-for-bit) | jiwer est déterministe ; toute différence = changement de pré/post-processing |
+| `wer`, `mer`, `wil` | **0** | idem |
+| `bleu`, `chrf` | **1e-9** | flottants — réordonnancements internes acceptables |
+| `precision`, `recall`, `f1` (NER) | **1e-9** | flottants |
+| `mufi_coverage`, `abbreviation_expansion_score` | **0** | comptage entier sur ensembles fermés |
+| `roman_numerals_accuracy` | **0** | parsing déterministe |
+| `unicode_blocks_accuracy` | **0** | tables Unicode déterministes |
+| `reading_order_f1` (ICDAR 2015) | **1e-9** | algorithme déterministe, flottants |
+| `layout_f1` | **1e-9** | flottants |
+| `confusion_matrix.entries` | **0** | comptage entier |
+| `taxonomy.error_class_*` | **0** | classification déterministe sur règles |
+
+### Tests statistiques
+
+| Test | ε | Justification |
+|------|---|---------------|
+| Wilcoxon `p_value` | **1e-9** | scipy `wilcoxon` est déterministe à entrée constante |
+| Friedman `chi2`, `p_value` | **1e-9** | idem |
+| Nemenyi (matrice p-values) | **1e-9** | dérivé de Friedman |
+| Bootstrap CI 95 % | **1e-3** | random seed FIXÉ explicitement (cf. `bootstrap.py` du legacy : `seed=42`) ; la tolérance laisse une marge minuscule pour les ré-implémentations qui itéreraient dans un ordre différent à seed identique |
+| Pareto front (set d'engines dominants) | **0** (bit-for-bit en tant qu'ensemble) | dominance Pareto stable sur entrées identiques |
+| CDD (Critical Difference Diagram) coordonnées SVG | **1e-3** sur les positions (px) | rendu Matplotlib peut varier sur des sub-pixels selon backend |
+| Clustering (labels) | **0** sur l'**ensemble** des classes (l'étiquetage interne 0/1/2 peut différer mais la partition doit être identique) | un test custom compare les partitions, pas les labels |
+| Corrélation Spearman / Pearson | **1e-9** | flottants |
+
+### Calibration
+
+| Output | ε | Justification |
+|--------|---|---------------|
+| ECE, MCE | **1e-9** | flottants, pas d'aléatoire |
+| Reliability diagram (bins, freq, conf) | **0** sur les bins, **1e-9** sur les valeurs | binning déterministe |
+
+### Confidences sidecar (S50 sur Tesseract)
+
+| Output | ε |
+|--------|---|
+| `tokens[].text` | **0** (string identique) |
+| `tokens[].confidence` | **0** | Tesseract retourne un entier 0-100 ; division exacte par 100 → flottant binairement identique en IEEE-754 |
+| `extractor`, `model_version` | **0** |
+
+### HTML (rapport `reports_v2/html/render.py`)
+
+Le diff HTML est **structurel**, pas lexical :
+
+- Mêmes éléments DOM avec mêmes attributs sémantiques (`data-*`,
+  `aria-*`, `id`, `class`).
+- Mêmes valeurs textuelles dans les nœuds de texte.
+- L'**ordre** des sections doit être identique.
+- L'indentation et le whitespace inter-éléments sont **ignorés**.
+- Le contenu d'un `<script>` est comparé après normalisation
+  d'espace blanc.
+
+Implémenté via une fonction `assert_html_semantically_equal(a, b)`
+qui parse les deux HTML avec `lxml` (ou `html.parser` fallback) et
+compare l'arbre.
+
+### CSV (`reports_v2/csv/render.py`)
+
+| Output | ε |
+|--------|---|
+| Header row | **0** (identique exact) |
+| Data rows (set non ordonné) | **0** sur l'ensemble |
+| Ordre des lignes | autorisé à différer | les renderers triaient parfois différemment ; seule l'égalité ensembliste est exigée |
+| Format des nombres | **0** (le rewrite formate à 6 décimales `f"{v:.6f}"`) | déterministe |
+
+### JSON (`reports_v2/json/render.py`)
+
+| Output | ε |
+|--------|---|
+| Bit-for-bit identique | **0** | le rewrite utilise `model_dump(mode="json")` Pydantic + `json.dumps(sort_keys=True, indent=2, ensure_ascii=False)` ; le legacy doit être amené au même contrat dans la phase concernée |
+
+### Narrative facts (Phase 3)
+
+| Aspect | ε |
+|--------|---|
+| Ensemble des `Fact` produits (par `FactType`) | **0** sur l'ensemble | l'arbitre peut réordonner mais pas inventer ni rater un fact |
+| Payload de chaque fact (les valeurs numériques citées) | **0** (bit-for-bit) | garde-fou anti-hallucination |
+| Templates rendus FR + EN | **0** sur le texte | déterministe par `str.format_map` |
+| Ordre final des facts dans la synthèse | **autorisé à différer** | l'arbitre du rewrite peut choisir un ordre différent si la priorité est respectée — un test custom valide « les facts HIGH apparaissent avant les MEDIUM » plutôt que l'ordre exact |
+
+### Rapport HTML — sections legacy spécifiques (Phase 5)
+
+Pour chaque renderer migré (calibration, NER, Pareto, narrative,
+philological, etc.), un cas-test de régression dédié vit dans
+`tests/regression/legacy_vs_rewrite/test_phase5_<renderer>.py`.
+Le snapshot legacy est figé en début de phase.
+
+## Aléatoire — politique
+
+Tout module qui utilise `random` doit :
+
+1. Accepter un argument `seed: int` ou utiliser une seed fixée
+   explicitement.
+2. Documenter la seed dans son docstring.
+3. Le harness de régression utilise toujours **seed=42**.
+
+Modules concernés au legacy :
+
+- `measurements/statistics/bootstrap.py` (seed=42)
+- `measurements/runner/workers.py` (pas d'aléatoire — confirmé)
+- `core/results.py` (pas d'aléatoire — confirmé)
+
+## Adaptateurs cloud (Mistral, OpenAI, Anthropic, Google, Azure)
+
+Les appels réseau ne sont **pas** rejoués pendant la régression —
+le test serait non-déterministe et coûteux.  Stratégie :
+
+1. Le harness utilise des **fixtures de réponses figées** (JSON
+   capturé en local lors de la création du corpus de référence).
+2. Le legacy et le rewrite reçoivent **la même fixture** ; le test
+   vérifie que tous deux produisent le même output structurel.
+3. Si une dépendance SDK change la sérialisation (rare), le test
+   pète bruyamment et la PR doit re-frigorifier la fixture.
+
+Aucune tolérance non triviale n'est nécessaire — l'égalité
+bit-for-bit est tenable parce que l'aléatoire vient du cloud, pas
+du parser.
+
+## Procédure d'exception (régression intentionnelle)
+
+Quand une migration corrige un bug historique légitime :
+
+1. Ouvrir une issue GitHub avec le label `regression-intentional`.
+2. Référencer le numéro d'issue dans le commit qui modifie la
+   tolérance.
+3. Ajouter une entrée dans la section *« Régressions intentionnelles
+   acceptées »* ci-dessous, **avant** le merge.
+4. La tolérance peut être relâchée temporairement ; au merge, soit
+   le snapshot legacy est mis à jour pour refléter le nouveau
+   comportement (correct), soit la tolérance reste serrée pour les
+   prochaines migrations.
+
+## Régressions intentionnelles acceptées
+
+| Date | Issue | Phase | Module | Description |
+|------|-------|-------|--------|-------------|
+| (aucune à ce jour) |  |  |  |  |
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (Phase 0 du plan de retrait legacy) |

docs/operations/deployment-institutional.md

@@ -8,7 +8,7 @@
 > plutôt que sur HuggingFace Space public.
 >
 > Pour le déploiement HuggingFace Space ou un usage local rapide,
-> voir [`INSTALL.md`](../../INSTALL.md).
+> voir [`how-to/install.md`](../how-to/install.md).
 
 ## Pré-requis
 

docs/operations/observability.md

@@ -0,0 +1,208 @@
+# Observabilité — Picarones
+
+> **Audience** : opérateur (DSI institutionnelle, SRE).  Décrit
+> comment instrumenter Picarones pour qu'il soit observable depuis
+> Prometheus, Grafana, Loki, Datadog, etc.
+>
+> Pour la réponse aux incidents, voir [`runbook.md`](runbook.md).
+> Pour le déploiement, voir [`deployment-institutional.md`](deployment-institutional.md).
+
+## Principes
+
+Picarones expose trois types de signaux :
+
+1. **Logs structurés** (stdlib `logging`).  Tous les modules
+   utilisent `logger = logging.getLogger(__name__)`.  Niveaux
+   conventionnels : DEBUG, INFO, WARNING, ERROR.  Aucun `print` en
+   production.
+2. **Audit trail** spécifique : `[audit] <event> <key=value>`
+   (par convention).  Émis par les endpoints sensibles
+   (`POST/DELETE /api/jobs`).
+3. **Endpoints de santé** : `GET /health`, `GET /version`.
+
+L'export vers une plateforme observabilité (Prometheus, Datadog, ELK)
+est laissé au déploiement institutionnel — Picarones ne pousse rien
+de lui-même.
+
+## Logs structurés
+
+### Format recommandé
+
+Configurer le root logger en JSON pour l'ingestion automatique :
+
+```python
+# /etc/picarones/logging.yaml
+version: 1
+disable_existing_loggers: false
+formatters:
+  json:
+    format: '{"ts":"%(asctime)s","lvl":"%(levelname)s","logger":"%(name)s","msg":"%(message)s"}'
+handlers:
+  stdout:
+    class: logging.StreamHandler
+    stream: ext://sys.stdout
+    formatter: json
+loggers:
+  picarones:
+    level: INFO
+    handlers: [stdout]
+    propagate: false
+root:
+  level: WARNING
+  handlers: [stdout]
+```
+
+Activer au démarrage :
+
+```bash
+PICARONES_LOG_CONFIG=/etc/picarones/logging.yaml \
+  uvicorn picarones.interfaces.web:create_app --factory ...
+```
+
+### Niveaux par module
+
+| Module | Niveau prod recommandé |
+|--------|------------------------|
+| `picarones.adapters.*` | INFO |
+| `picarones.app.services.*` | INFO |
+| `picarones.interfaces.web.*` | INFO |
+| `picarones.pipeline.*` | INFO (DEBUG si chasse à un bug d'orchestration) |
+| `picarones.evaluation.*` | WARNING (très verbeux en INFO) |
+| `picarones.adapters._retry` | WARNING (déjà bavard sur les retries) |
+
+### Exemples de lignes utiles à monitorer
+
+| Pattern | Signification | Alerte |
+|---------|---------------|--------|
+| `[adapter] erreur retryable.*` | Cloud API instable | > 10/min sur 5 min → page |
+| `OCRAdapterError` | Échec définitif d'OCR | > 5/min → warning |
+| `[job_runner] job .* en échec` | Job s'est terminé en error | track per-IP |
+| `[audit] job_submitted` | Soumission de job | tracker pour audit RGPD |
+| `[audit] job_cancelled` | Annulation de job | tracker pour audit RGPD |
+| `WinError 87` | Filename Windows invalide | DEVRAIT être 0 (corrigé S59) — sinon régression |
+| `database is locked` | SQLite contention | > 1/min → page |
+
+## Audit trail
+
+Les opérations sensibles produisent un log INFO normalisé :
+
+```
+INFO [audit] job_submitted job_id=abc123 corpus=bnf_xviii from=10.0.0.42
+INFO [audit] job_cancelled job_id=abc123 from=10.0.0.42
+```
+
+Ces lignes sont **destinées à être conservées** selon la politique
+RGPD de l'institution (cf. [`data-retention-rgpd.md`](data-retention-rgpd.md)).
+Stockage minimum recommandé : 90 jours (audit interne) ; 5 ans si
+soumis aux Archives nationales.
+
+Pour ingestion SIEM :
+
+```
+filter '[audit] '
+extract job_id, corpus, from
+forward to siem.bnf.fr:514 (syslog)
+```
+
+## Endpoints de santé
+
+### `GET /health`
+
+Réponse `200 OK` si le process est en mesure de servir.  Vérifie :
+
+- `JobStore` accessible (lecture)
+- `WorkspaceManager` accessible (écriture sandbox)
+- Pas de check sur les API cloud (un cloud down ne doit pas planter
+  les health probes locales)
+
+```json
+{
+  "status": "ok",
+  "version": "1.3.0-dev",
+  "job_store": "ok",
+  "workspace": "ok"
+}
+```
+
+À utiliser comme **liveness probe** (Kubernetes) ou **healthcheck**
+(Docker).  Recommandation : every 30s, fail after 3 consecutive.
+
+### `GET /version`
+
+Réponse :
+
+```json
+{
+  "version": "1.3.0-dev",
+  "code_version": "git-sha-abc1234",
+  "python": "3.11.15"
+}
+```
+
+Utile pour déterminer la version déployée sans accès au filesystem.
+
+## Métriques (à venir)
+
+Picarones n'expose pas encore d'endpoint Prometheus `/metrics`.
+Recommandation immédiate : monitorer les logs.
+
+**Backlog** (cf. [`/docs/roadmap/backlog.md`](../roadmap/backlog.md)) :
+
+- Compteur `picarones_jobs_total{status="complete|error|cancelled"}`
+- Histogramme `picarones_job_duration_seconds`
+- Compteur `picarones_adapter_calls_total{adapter, status}`
+- Histogramme `picarones_adapter_latency_seconds{adapter}`
+- Gauge `picarones_jobs_running` (instantané)
+
+Implémentation visée : `prometheus_client` middleware FastAPI optionnel.
+
+## Tracing distribué
+
+Pour les institutions qui orchestrent Picarones avec d'autres services
+(ETL, cataloguing), le tracing OpenTelemetry est recommandé.
+
+État actuel : pas d'instrumentation native.  Une instrumentation
+opportuniste via `opentelemetry-instrumentation-fastapi` peut être
+activée par le déploiement sans modifier Picarones :
+
+```python
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from picarones.interfaces.web import create_app
+
+app = create_app(state=...)
+FastAPIInstrumentor.instrument_app(app)
+```
+
+## Dashboards Grafana — squelette
+
+Les panels recommandés pour un dashboard Picarones :
+
+1. **Jobs throughput** — courbes par status (complete/error/cancelled),
+   stack area, 24 h.
+2. **Adapter latency p50/p95/p99** par adapter (Tesseract, Pero,
+   Mistral OCR, Google Vision, Azure DI, OpenAI, Anthropic, Mistral
+   chat, Ollama).
+3. **Error rate par adapter** — % d'erreurs sur la dernière heure.
+4. **Concurrence** — `picarones_jobs_running` actuel, comparé à
+   `PICARONES_MAX_CONCURRENT_JOBS`.
+5. **Workspace size** — `du -sh /var/lib/picarones/workspaces` via
+   exporter node.
+6. **Heap RSS** du process Picarones (via node_exporter ou
+   process_exporter).
+
+## SLOs suggérés
+
+Pour un déploiement institutionnel ouvert aux chercheurs :
+
+| Métrique | SLO 30j | Action si dépassé |
+|----------|---------|-------------------|
+| Disponibilité `/health` | 99.5 % | Investiguer infra |
+| Job completion rate | > 95 % | Examiner taux d'erreurs adapter |
+| API p95 latency (CRUD jobs) | < 500 ms | Profiler le `JobStore` |
+| Cloud adapter retry rate | < 5 % | Demander quota plus haut |
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (S60) |

docs/operations/runbook.md

@@ -0,0 +1,374 @@
+# Runbook — réponse aux incidents Picarones
+
+> **Audience** : opérateur (DSI institutionnelle, SRE) en garde
+> active.  Ce document liste les incidents prévisibles et les
+> procédures de mitigation.  Pour le déploiement initial, voir
+> [`deployment-institutional.md`](deployment-institutional.md) ;
+> pour l'observabilité, voir [`observability.md`](observability.md).
+>
+> **Convention** : chaque scénario suit le format
+> `Symptôme → Diagnostic → Mitigation → Suivi`.
+
+## Index des scénarios
+
+| ID | Scénario | Sévérité | Page |
+|----|----------|----------|------|
+| INC-01 | Job stuck en `running` | MAJOR | [§INC-01](#inc-01--job-stuck-en-running) |
+| INC-02 | Disk full sur le workspace | BLOCKER | [§INC-02](#inc-02--disk-full-sur-le-workspace) |
+| INC-03 | Cloud API rate limit / quota dépassé | MAJOR | [§INC-03](#inc-03--cloud-api-rate-limit) |
+| INC-04 | SQLite `database is locked` | MAJOR | [§INC-04](#inc-04--sqlite-database-is-locked) |
+| INC-05 | Memory leak (RSS qui croît continûment) | MAJOR | [§INC-05](#inc-05--memory-leak) |
+| INC-06 | Compromission d'une clé API cloud | BLOCKER | [§INC-06](#inc-06--compromission-de-cl%C3%A9-api) |
+| INC-07 | Rapport HTML corrompu / non-déterministe | MEDIUM | [§INC-07](#inc-07--rapport-html-corrompu) |
+| INC-08 | CI bloquée > 30 min (déjà vu) | MEDIUM | [§INC-08](#inc-08--ci-bloqu%C3%A9e) |
+| INC-09 | Upgrade qui casse les jobs en cours | MAJOR | [§INC-09](#inc-09--upgrade-casse-jobs) |
+| INC-10 | Restauration depuis backup | MEDIUM | [§INC-10](#inc-10--restauration-backup) |
+
+---
+
+## INC-01 — Job stuck en `running`
+
+**Symptôme**.  `GET /api/jobs/{job_id}` retourne `status=running`
+depuis > 1 heure alors que le corpus tient en quelques minutes.
+
+**Diagnostic**.
+
+```bash
+# 1. Le thread daemon existe-t-il encore ?
+curl -s http://localhost:7860/api/jobs/{job_id} | jq '.status, .progress'
+
+# 2. Les logs montrent-ils une activité récente ?
+journalctl -u picarones -n 200 | grep "{job_id}"
+
+# 3. Y a-t-il un appel cloud bloqué ?
+ss -tnp | grep :443  # connexions TLS sortantes
+```
+
+Causes typiques :
+
+- Appel cloud qui hang sans timeout (anciens adapters).
+- Workspace en read-only (impossible d'écrire le résultat).
+- Process daemon mort sans avoir mis à jour le statut.
+
+**Mitigation**.
+
+```bash
+# Forcer l'annulation (dégrade en cancelled, pas en error).
+curl -X DELETE http://localhost:7860/api/jobs/{job_id}
+
+# Si le service ne répond plus :
+systemctl restart picarones
+# Au boot, le lifespan hook ``mark_orphaned_jobs_interrupted`` bascule
+# automatiquement les jobs ``running`` en ``interrupted``.
+```
+
+**Suivi**.  Vérifier que le `JobRunner` n'a pas d'autres threads
+zombies via `len(runner._threads)` (devrait redescendre).  Si
+récurrent, instrumenter avec un timeout de soft-cap par job.
+
+---
+
+## INC-02 — Disk full sur le workspace
+
+**Symptôme**.  Les jobs échouent en `error` avec
+`OSError: [Errno 28] No space left on device`.  L'API web peut
+elle-même planter au boot (`JobStore` ne peut plus persister).
+
+**Diagnostic**.
+
+```bash
+df -h /var/lib/picarones/workspaces  # ou le path configuré
+du -sh /var/lib/picarones/workspaces/*
+```
+
+Coupable typique : caches d'artefacts non purgés (`InMemoryArtifactStore`
+n'a pas de TTL ; `FilesystemArtifactStore` non plus).
+
+**Mitigation**.
+
+```bash
+# 1. Identifier les workspaces les plus gros.
+du -sh /var/lib/picarones/workspaces/* | sort -rh | head -10
+
+# 2. Purger les workspaces dont aucun job actif ne dépend (lookup
+#    via JobStore).
+sqlite3 /var/lib/picarones/jobs.db \
+  "SELECT job_id, status, payload FROM jobs WHERE status NOT IN ('pending', 'running');" \
+  | jq -r '.payload | fromjson | .output_dir'
+
+# 3. Pour chaque output_dir terminé, archiver puis supprimer.
+tar czf /backup/picarones-archive-$(date +%F).tar.gz <output_dirs>
+rm -rf <output_dirs>
+```
+
+**Suivi**.  Établir une politique de rétention dans
+[`data-retention-rgpd.md`](data-retention-rgpd.md).  Recommandation :
+purger les workspaces > 30 jours sans accès.
+
+---
+
+## INC-03 — Cloud API rate limit
+
+**Symptôme**.  Logs WARN : `[adapter] erreur retryable (tentative 3/4,
+attente 8s) : 429 Too Many Requests`.  Job se termine en error après
+épuisement des retries.
+
+**Diagnostic**.
+
+```bash
+# Compter les 429 dans la dernière heure.
+journalctl -u picarones --since "1 hour ago" \
+  | grep "429" | wc -l
+
+# Identifier les jobs concernés.
+journalctl -u picarones --since "1 hour ago" \
+  | grep -B2 "429" | grep "job_runner"
+```
+
+Causes typiques : un benchmark de 5000 documents lance 5000 appels
+en parallèle, dépasse la quota de l'organisation cloud.
+
+**Mitigation immédiate**.
+
+```bash
+# 1. Réduire le parallélisme du runner (env var).
+sed -i 's/PICARONES_RUNNER_MAX_WORKERS=8/PICARONES_RUNNER_MAX_WORKERS=2/' /etc/picarones/.env
+systemctl restart picarones
+
+# 2. Re-soumettre les jobs en error qui se sont arrêtés au milieu.
+# (Picarones ne fait pas de resume automatique sur erreur cloud — le
+# cache d'artefacts du PipelineExecutor évite de re-exécuter les
+# steps déjà terminés au prochain run.)
+```
+
+**Mitigation long terme**.  Demander une quota plus haute au
+fournisseur cloud, ou ajouter un throttle au niveau adapter (token
+bucket par adapter).
+
+---
+
+## INC-04 — SQLite `database is locked`
+
+**Symptôme**.  Logs ERROR : `sqlite3.OperationalError: database is
+locked`.  Touche typiquement le `JobStore`.
+
+**Diagnostic**.
+
+```bash
+# 1. Compter les processes qui ont la DB ouverte.
+lsof /var/lib/picarones/jobs.db
+
+# 2. Vérifier le mode WAL.
+sqlite3 /var/lib/picarones/jobs.db "PRAGMA journal_mode;"
+# Devrait répondre "wal".  Si "delete" ou "rollback", le WAL n'a pas
+# pris.
+```
+
+Causes : un process autre que Picarones a ouvert la DB (backup
+maladroit), ou le filesystem ne supporte pas WAL (FAT32, NFS sans
+verrous).
+
+**Mitigation**.
+
+```bash
+# 1. Stopper l'autre process si identifié.
+# 2. Si NFS : remonter avec ``-o nolock`` côté serveur ne marche PAS
+#    (WAL exige des verrous).  Solution : déplacer ``jobs.db`` sur un
+#    filesystem local et exporter le résultat via NFS read-only.
+# 3. Si filesystem ne supporte vraiment pas WAL, le code retombe sur
+#    ``rollback journal`` (cf. job_store.py:185-189) — fonctionnel
+#    mais bloquant en lecture pendant les écritures.
+
+# Test de santé.
+sqlite3 /var/lib/picarones/jobs.db "PRAGMA integrity_check;"
+```
+
+**Suivi**.  Configurer un monitoring du `journal_mode` au boot.
+
+---
+
+## INC-05 — Memory leak
+
+**Symptôme**.  RSS du process Picarones croît continûment au-delà
+de 2 GB après plusieurs heures.
+
+**Diagnostic**.
+
+```bash
+# Profiling minimal sans installer d'outil.
+ps -o pid,rss,cmd -p $(pgrep picarones) | tail -1
+
+# Si py-spy disponible :
+py-spy dump --pid $(pgrep picarones)
+```
+
+Causes connues :
+
+- `JobRunner._threads` non nettoyé (FIXÉ en S58).
+- `RateLimitMiddleware._buckets` non borné (FIXÉ en S58 — eviction LRU).
+- Caches d'artefacts in-memory accumulés (cf. INC-02).
+
+**Mitigation**.
+
+```bash
+systemctl restart picarones
+# Le lifespan hook nettoie les jobs orphelins ; les caches in-memory
+# sont vidés par redémarrage.
+```
+
+**Suivi**.  Si récurrent, exporter `picarones._mem_audit` (à
+implémenter — backlog) et corréler avec les jobs actifs.
+
+---
+
+## INC-06 — Compromission de clé API
+
+**Symptôme**.  Facturation cloud anormale, ou notification du
+fournisseur (« nous avons détecté une utilisation suspecte de votre
+clé »).
+
+**Mitigation immédiate** (dans l'ordre).
+
+```bash
+# 1. Révoquer la clé chez le fournisseur (console cloud).
+# 2. Stopper Picarones pour éviter qu'il ne tente de relancer avec
+#    la clé invalidée.
+systemctl stop picarones
+# 3. Rotater la clé dans le secret store.
+vault kv put secret/picarones OPENAI_API_KEY=sk-NEW...
+# 4. Reload + redémarrage.
+systemctl start picarones
+# 5. Audit des jobs récents pour identifier les exfiltrations.
+sqlite3 /var/lib/picarones/jobs.db \
+  "SELECT job_id, payload, created_at FROM jobs ORDER BY created_at DESC LIMIT 100;"
+```
+
+**Suivi**.  Notifier le DPO institutionnel sous 24 h si des
+documents avec PII (registres, état civil) ont été envoyés à l'API
+compromise.  Voir [`data-retention-rgpd.md`](data-retention-rgpd.md).
+
+---
+
+## INC-07 — Rapport HTML corrompu
+
+**Symptôme**.  Deux runs identiques produisent des rapports HTML
+différents byte-for-byte.
+
+**Diagnostic**.
+
+```bash
+# Comparer les hashes de manifests.
+sha256sum run-A/run_manifest.json run-B/run_manifest.json
+
+# Si différents : un des paramètres canoniques a divergé.
+diff <(jq -S . run-A/run_manifest.json) <(jq -S . run-B/run_manifest.json)
+```
+
+Causes typiques : un adapter cloud (gpt-4o, claude) qui a une
+température > 0 → non-déterminisme natif.  Vérifier les
+`adapter_kwargs` dans le manifest.
+
+**Mitigation**.  Forcer `temperature: 0.0` dans la `RunSpec` YAML.
+Pour les benchmarks de reproductibilité, exclure les adapters
+non-déterministes.
+
+---
+
+## INC-08 — CI bloquée
+
+**Symptôme**.  Un job GitHub Actions reste en `queued` ou
+`in_progress` > 30 minutes pour ce qui devrait être un test < 5 min.
+
+**Diagnostic**.  Vérifier dans cet ordre :
+
+1. **Codecov upload hang** (déjà vu — 50+ min) → couvert par
+   `timeout-minutes: 5` sur l'étape Codecov + `fail_ci_if_error: false`
+   depuis le S59.
+2. **Live tests qui s'exécutent** au lieu d'être deselected → le
+   marker `live` doit être dans `addopts` de `pyproject.toml`
+   (vérifié par les tests dual-lang).
+3. **Codespaces / runner épuisé** → annuler manuellement le job,
+   relancer.
+
+**Mitigation**.  Annuler le workflow run (UI GitHub Actions),
+relancer.  Si récurrent, élever un incident infra GitHub.
+
+---
+
+## INC-09 — Upgrade casse jobs
+
+**Symptôme**.  Après `git pull && pip install -e .`, les jobs
+soumis avant l'upgrade échouent en `error`.
+
+**Diagnostic**.  Le `JobStore` utilise une table `schema_version` ;
+une bump de SCHEMA_VERSION sans migration livre `JobStoreError` au
+boot.
+
+**Mitigation**.
+
+```bash
+# 1. Stopper le service AVANT l'upgrade.
+systemctl stop picarones
+
+# 2. Backup du JobStore.
+cp /var/lib/picarones/jobs.db /var/lib/picarones/jobs.db.bak
+
+# 3. Upgrade.
+git pull && pip install -e ".[dev,web]"
+
+# 4. Vérifier le schéma.
+sqlite3 /var/lib/picarones/jobs.db "SELECT version FROM schema_version;"
+
+# 5. Démarrer.  Le dispatcher applique automatiquement les
+#    migrations enregistrées dans ``_MIGRATIONS``.
+systemctl start picarones
+```
+
+**Suivi**.  Tester chaque upgrade en staging avant prod.
+
+---
+
+## INC-10 — Restauration depuis backup
+
+**Symptôme**.  Corruption ou perte du workspace ou de la DB jobs.
+
+**Pré-requis**.  Backup récent (recommandé : snapshot quotidien du
+volume `/var/lib/picarones/`).
+
+**Mitigation**.
+
+```bash
+# 1. Stopper le service.
+systemctl stop picarones
+
+# 2. Restaurer.
+rsync -av /backup/picarones-2026-05-XX/ /var/lib/picarones/
+
+# 3. Vérifier l'intégrité SQLite.
+sqlite3 /var/lib/picarones/jobs.db "PRAGMA integrity_check;"
+
+# 4. Démarrer.  Les jobs ``running`` au moment du backup seront
+#    automatiquement marqués ``interrupted`` par le lifespan hook.
+systemctl start picarones
+```
+
+**Suivi**.  Communiquer aux utilisateurs que les jobs en cours au
+moment du backup sont à relancer.
+
+---
+
+## Escalade
+
+Si un incident dépasse les procédures ci-dessus :
+
+1. Documenter l'observation dans un fichier `incidents/<date>.md`
+   (snapshot du symptôme + commandes lancées + résultat).
+2. Ouvrir une issue GitHub avec le label `incident`.
+3. Pour une vulnérabilité de sécurité, suivre la procédure de
+   [`/SECURITY.md`](../../SECURITY.md) (canal privé).
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (S60), 10 scénarios |

docs/operations/supply-chain.md

@@ -0,0 +1,125 @@
+# Supply chain — SBOM, SLSA, signatures
+
+> **Audience** : DSI institutionnelle et conformité réglementaire
+> (EU CRA — Cyber Resilience Act, exigible à partir de 2027 pour les
+> livraisons à des organismes publics européens).
+>
+> Décrit comment Picarones documente sa chaîne d'approvisionnement
+> logicielle et permet à une institution de vérifier l'intégrité
+> d'un wheel ou d'une image Docker avant déploiement.
+
+## SBOM (Software Bill of Materials)
+
+### Format CycloneDX
+
+Picarones produit un SBOM au format **CycloneDX 1.5 JSON** à chaque
+release.  Le SBOM liste l'intégralité des paquets Python installés
+dans l'environnement de build avec :
+
+- `name`, `version`, `purl` (package URL canonique).
+- `licenses` (SPDX expression).
+- `hashes` (SHA-256 du wheel).
+- `dependencies` (graphe de dépendance complet).
+
+Génération locale :
+
+```bash
+pip install cyclonedx-bom
+python scripts/gen_sbom.py --output sbom.json
+```
+
+Génération automatique dans la CI : voir
+[`.github/workflows/release.yml`](../../.github/workflows/release.yml)
+qui attache `sbom.json` à chaque GitHub Release.
+
+### Image Docker
+
+L'image Docker `ghcr.io/maribakulj/picarones:<version>` embarque son
+propre SBOM (couche métadonnées BuildKit) :
+
+```bash
+docker buildx imagetools inspect \
+  ghcr.io/maribakulj/picarones:<version> \
+  --format '{{ json .SBOM }}'
+```
+
+## SLSA Provenance
+
+[SLSA](https://slsa.dev/) (Supply-chain Levels for Software Artifacts)
+formalise le niveau de confiance qu'on peut accorder à un artefact
+livré.
+
+### État actuel : SLSA Level 2
+
+- **Build** isolé sur GitHub-hosted runners, traçable au commit SHA.
+- **Provenance** générée automatiquement par
+  [`docker/build-push-action@v5`](https://github.com/docker/build-push-action)
+  avec `provenance: true`.
+
+Inspection :
+
+```bash
+docker buildx imagetools inspect \
+  ghcr.io/maribakulj/picarones:<version> \
+  --format '{{ json .Provenance }}'
+```
+
+### Trajectoire vers SLSA Level 3
+
+Pour atteindre le niveau 3 (signature non-falsifiable), prochaines
+étapes (cf. [`/docs/roadmap/backlog.md`](../roadmap/backlog.md)) :
+
+1. Signer chaque wheel PyPI avec [Sigstore](https://www.sigstore.dev/)
+   via `pypi-attestations` (PEP 740).
+2. Signer le SBOM avec `cosign sign-blob` lors de la release.
+3. Publier les attestations sur Rekor (transparency log).
+
+## Vérification côté institution
+
+Avant déploiement, l'institution peut vérifier qu'un wheel n'a pas
+été altéré entre le build CI et le download :
+
+```bash
+# 1. Téléchargement.
+pip download picarones==<version> --no-deps -d /tmp/audit/
+
+# 2. Vérification du hash contre le SBOM.
+sha256sum /tmp/audit/picarones-*.whl
+jq -r '.components[] | select(.name == "picarones") | .hashes[0].content' sbom.json
+# Les deux valeurs doivent matcher.
+
+# 3. (Future, SLSA L3) Vérification de la signature Sigstore.
+# cosign verify-blob --bundle picarones-<version>.whl.sigstore picarones-<version>.whl
+```
+
+## Politique de mise à jour des dépendances
+
+- **CVE critique** (CVSS ≥ 9.0) : patch release sous 7 jours.
+- **CVE élevée** (7.0 ≤ CVSS < 9.0) : minor release sous 30 jours.
+- **CVE moyenne** : prise en compte au prochain cycle de release.
+
+Surveillance :
+
+- `pip-audit` exécuté en CI sur chaque push (cf.
+  [`/.github/workflows/precommit.yml`](../../.github/workflows/precommit.yml)).
+- Dependabot / Renovate sur `pyproject.toml` pour les minor / patch.
+
+## Conformité EU CRA (anticipation)
+
+L'EU Cyber Resilience Act, applicable à partir de 2027 pour les
+produits livrés à des entités publiques de l'UE, exigera :
+
+| Exigence CRA | Statut Picarones |
+|--------------|------------------|
+| SBOM machine-readable | ✅ CycloneDX 1.5 |
+| Vulnerability disclosure policy | ✅ [`/SECURITY.md`](../../SECURITY.md) + RFC 9116 [`/.well-known/security.txt`](../../.well-known/security.txt) |
+| Coordinated vulnerability disclosure | ✅ GitHub Security Advisories |
+| Cryptographic signing of releases | 🔧 SLSA L2 actuel, L3 prévu |
+| Vulnerability handling within reasonable timeframes | ✅ Politique documentée ci-dessus |
+| Security updates for at least 5 years | 🔧 Politique LTS à définir avant 1.0 GA |
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (S60) |

docs/{api-stable.md → reference/api-stable.md}

@@ -1,26 +1,34 @@
-# API publique stable de Picarones (Cercle 1)
-
-Phase D du chantier de refonte en 3 cercles — engagement contractuel
-de stabilité de l'API publique du Cercle 1.
+# API publique stable de Picarones
+
+> **Statut** : ce document décrivait l'API publique du Cercle 1
+> historique (`picarones.core/`).  Le projet est en cours de
+> retrait du legacy vers une **architecture 8 couches**
+> (`domain → formats → evaluation → pipeline → adapters → app
+> → reports_v2 → interfaces`, cf.
+> [`docs/explanation/architecture.md`](../explanation/architecture.md)).
+>
+> **Pendant la migration** (jusqu'à la version 2.0), l'API
+> publique est en cours de refonte.  Tous les chemins legacy
+> (`picarones.core.X`, `picarones.measurements.X`, etc.) sont
+> des shims `DeprecationWarning` qui ré-exportent depuis le
+> canonique.  Les nouveaux imports doivent utiliser les chemins
+> canoniques (`picarones.domain.*`, `picarones.evaluation.*`).
+>
+> Le tableau de parité legacy ↔ canonique vit dans
+> [`tests/architecture/test_legacy_canonical_parity.py`](../../tests/architecture/test_legacy_canonical_parity.py).
 
 ## Définition
 
-L'API publique de Picarones est constituée des classes, fonctions,
-constantes et types listés ci-dessous, exportés depuis le sous-package
-`picarones.core/`. Ce qui est dans cette liste constitue **un contrat
-de stabilité** : nous nous engageons à ne pas le casser entre versions
-mineures (semver `1.x.0`).
+L'API publique stable de Picarones est constituée des classes,
+fonctions, constantes et types listés ci-dessous, désormais
+exportés depuis l'arborescence canonique.
 
-Ce qui n'est pas dans cette liste — y compris les modules historiques
-qui ont été déplacés vers `picarones.measurements/`, `picarones.extras/`
-et accessibles via shims rétrocompat — peut évoluer à tout moment
+Ce qui n'est pas dans cette liste peut évoluer à tout moment
 sans bump majeur.
 
-Les imports historiques (`from picarones.core.confusion import ...`,
-`from picarones.core.narrative.facts import ...`, etc.) restent
-fonctionnels mais ne font **pas** partie de l'API publique stable :
-ce sont des aliases rétrocompat. Pour de la nouveauté, préférer
-`from picarones.measurements.confusion import ...`.
+Les imports historiques restent fonctionnels via shims pendant
+la migration ; ils ne font **pas** partie de l'API publique
+stable et émettent un `DeprecationWarning`.
 
 ## Test automatique
 
@@ -30,7 +38,7 @@ ou change de forme.
 
 ## Liste exhaustive
 
-### `picarones.core.corpus`
+### `picarones.evaluation.corpus`
 
 ```python
 class GTLevel(str, Enum):
@@ -51,12 +59,18 @@ GT_SUFFIXES: dict[GTLevel, str]   # mapping niveau → suffixe fichier
 def load_corpus_from_directory(path) -> Corpus
 ```
 
-### `picarones.core.modules`
+### `picarones.domain.artifacts`
 
 ```python
 class ArtifactType(str, Enum):
-    IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER
+    IMAGE, RAW_TEXT, CORRECTED_TEXT, ALTO_XML, PAGE_XML,
+    CANONICAL_DOCUMENT, ENTITIES, READING_ORDER, ALIGNMENT, CONFIDENCES
+    # Aliases legacy pour rétrocompat : TEXT, ALTO, PAGE
+```
 
+### `picarones.domain.module_protocol`
+
+```python
 class BaseModule(ABC):
     input_types: tuple[ArtifactType, ...]
     output_types: tuple[ArtifactType, ...]
@@ -71,7 +85,7 @@ class BaseModule(ABC):
 ExecutionMode = Literal["io", "cpu"]
 ```
 
-### `picarones.core.results`
+### `picarones.evaluation.benchmark_result`
 
 ```python
 class DocumentResult:    # résultat moteur sur un doc (CER, métriques, taxonomy…)
@@ -105,7 +119,7 @@ def run_benchmark(
 ) -> BenchmarkResult
 ```
 
-### `picarones.core.pipeline`
+### `picarones.evaluation.pipeline`
 
 ```python
 class PipelineStep:
@@ -144,7 +158,7 @@ def load_comparison_specs_from_yaml(path) -> tuple[list[PipelineSpec], dict]
 def load_comparison_specs_from_dict(data: dict) -> tuple[list[PipelineSpec], dict]
 ```
 
-### `picarones.core.metric_registry`
+### `picarones.evaluation.metric_registry`
 
 ```python
 class MetricSpec:    # frozen dataclass : name, func, input_types, ...
@@ -156,7 +170,7 @@ def select_metrics(input_types) -> list[MetricSpec]
 def compute_at_junction(reference, hypothesis, input_types, *, skip_on_error=True) -> dict
 ```
 
-### `picarones.core.metric_hooks`
+### `picarones.evaluation.metric_hooks`
 
 ```python
 # Profils — constantes
@@ -241,11 +255,11 @@ def reset_default_store(...)
   reflètent ces changements.
 - **Modules `picarones.extras/`** : statut variable selon le
   sous-package (academic / governance / historical / importers).
-  Voir `docs/architecture.md`.
+  Voir `docs/explanation/architecture.md`.
 - **Comportement des renderers HTML** : la structure des fichiers HTML
   peut évoluer entre versions mineures. Nous gardons les noms des
   vues principales.
-- **Internes des modules Cercle 1** : les noms commençant par `_`
+- **Internes des modules canoniques** : les noms commençant par `_`
   ne font pas partie de l'API publique. Les tests Sprints
   historiques qui les importent (Sprint 13/42) sont préservés mais
   par effort, pas par contrat.
@@ -258,9 +272,9 @@ Un bump majeur sera nécessaire pour :
 - Changer la signature d'une fonction publique de manière non
   rétrocompatible.
 - Casser le format de sérialisation du `BenchmarkResult.to_json()`.
-- Renommer un module Cercle 1.
+- Renommer un module de l'arborescence canonique.
 
-## Modules historiques rétrocompat (non Cercle 1)
+## Modules historiques rétrocompat (non canoniques)
 
 Les imports suivants continuent à fonctionner mais ne font pas partie
 de l'API publique stable. Ils peuvent évoluer ou être retirés en
@@ -275,7 +289,7 @@ from picarones.measurements.calibration import compute_calibration_metrics
 
 # Moteur narratif (déplacé vers picarones.measurements.narrative/)
 from picarones.measurements.narrative import build_synthesis
-from picarones.core.facts import Fact, FactType, FactImportance
+from picarones.domain.facts import Fact, FactType, FactImportance
 from picarones.measurements.narrative.detectors import detect_global_leader_cer
 
 # Plugins (déplacés vers picarones.extras/)
@@ -296,8 +310,8 @@ Pour les **nouvelles** intégrations, préférer les chemins canoniques :
 
 ## Voir aussi
 
-- [`docs/architecture.md`](architecture.md) — cartographie
+- [`docs/explanation/architecture.md`](architecture.md) — cartographie
   des 3 cercles + critères d'assignation.
-- [`docs/architecture.md`](architecture.md) — vue d'ensemble post-chantiers.
+- [`docs/explanation/architecture.md`](architecture.md) — vue d'ensemble post-chantiers.
 - [`tests/test_public_api.py`](../tests/test_public_api.py) — test
   automatique qui échoue si un nom listé ici disparaît.

docs/{profiles.md → reference/normalization-profiles.md}

@@ -4,7 +4,7 @@ Picarones expose **7 profils de calcul** qui modulent les métriques
 calculées par le runner selon le use case. Chaque profil active un
 sous-ensemble des **12 hooks document-level** et **12 agrégateurs
 corpus-level** du registre central
-([`picarones/core/metric_hooks.py`](../picarones/core/metric_hooks.py)).
+([`picarones/evaluation/metric_hooks.py`](../picarones/evaluation/metric_hooks.py)).
 
 ## Synoptique
 
@@ -21,7 +21,7 @@ corpus-level** du registre central
 > **Note rétrocompat** : aujourd'hui les profils `philological`, `diagnostics`,
 > `economics`, `pipeline` et `full` activent **le même ensemble** que `standard`
 > côté hooks calculés. Ce qui change, c'est la **vue HTML rendue** : chaque
-> profil active des sous-sections différentes du rapport (cf. `docs/views.md`).
+> profil active des sous-sections différentes du rapport (cf. `docs/reference/views.md`).
 > Les profils sont volontairement génériques pour permettre aux contributeurs
 > futurs d'ajouter des hooks spécifiques sans casser l'API.
 
@@ -127,11 +127,11 @@ reproductibilité scientifique maximale.
 
 ## Comment ajouter un hook personnalisé
 
-Voir [`docs/developer/narrative-engine.md`](developer/narrative-engine.md)
+Voir [`docs/explanation/narrative-engine.md`](developer/narrative-engine.md)
 pour le détail. Pattern de base :
 
 ```python
-from picarones.core.metric_hooks import (
+from picarones.evaluation.metric_hooks import (
     register_document_metric, PROFILE_DIAGNOSTICS, PROFILE_FULL,
 )
 
@@ -148,7 +148,7 @@ def my_hook(*, ground_truth, hypothesis, image_path, corpus_lang, ocr_result):
 
 ## Code source
 
-- [`picarones/core/metric_hooks.py`](../picarones/core/metric_hooks.py)
+- [`picarones/evaluation/metric_hooks.py`](../picarones/evaluation/metric_hooks.py)
   — registre, profils, `run_document_hooks()`, `run_corpus_aggregators()`.
 - [`picarones/measurements/builtin_hooks.py`](../picarones/measurements/builtin_hooks.py)
   — les 12 hooks doc + 12 agrégateurs natifs Picarones.

docs/{views.md → reference/views.md}

@@ -62,7 +62,7 @@ orphelins** identifiés dans l'audit initial :
 
 #### Vue « Coût et performance » (`build_economics_view_html`)
 
-Module : [`picarones/report/views/economics.py`](../picarones/report/views/economics.py).
+Module : [`picarones/reports_v2/html/views/economics.py`](../picarones/reports_v2/html/views/economics.py).
 Activée si :
 - `engine_reports` fournis avec durations non nulles.
 - (Optionnel) `extra_html_blocks` pour cost projection / marginal cost.
@@ -73,7 +73,7 @@ Sous-sections :
 
 #### Vue « Taxonomie avancée » (`build_advanced_taxonomy_view_html`)
 
-Module : [`picarones/report/views/advanced_taxonomy.py`](../picarones/report/views/advanced_taxonomy.py).
+Module : [`picarones/reports_v2/html/views/advanced_taxonomy.py`](../picarones/reports_v2/html/views/advanced_taxonomy.py).
 Activée si ≥ 2 moteurs ont une `aggregated_taxonomy`.
 
 Sous-sections :
@@ -85,7 +85,7 @@ Sous-sections :
 
 #### Vue « Diagnostic approfondi » (`build_diagnostics_view_html`)
 
-Module : [`picarones/report/views/diagnostics.py`](../picarones/report/views/diagnostics.py).
+Module : [`picarones/reports_v2/html/views/diagnostics.py`](../picarones/reports_v2/html/views/diagnostics.py).
 Activée si `detect_levers()` produit au moins un levier (typique sur
 un bench standard) ou si données opt-in fournies.
 
@@ -106,7 +106,7 @@ servent à composer des **rapports autonomes** :
 
 ### Vue « Pipeline composée » (`build_pipeline_view_html`)
 
-Module : [`picarones/report/views/pipeline.py`](../picarones/report/views/pipeline.py).
+Module : [`picarones/reports_v2/html/views/pipeline.py`](../picarones/reports_v2/html/views/pipeline.py).
 
 Utilisée par `picarones pipeline run` (ou par tout outil qui consomme un
 `PipelineBenchmarkResult`). Sous-sections :
@@ -122,7 +122,7 @@ Utilisée par `picarones pipeline run` (ou par tout outil qui consomme un
 
 ### Vue « Robustesse projetée » (`build_robustness_view_html`)
 
-Module : [`picarones/report/views/robustness.py`](../picarones/report/views/robustness.py).
+Module : [`picarones/reports_v2/html/views/robustness.py`](../picarones/reports_v2/html/views/robustness.py).
 
 Utilisée par le workflow `picarones robustness`. Sous-sections :
 
@@ -141,14 +141,14 @@ défini dans `economics.py` :
 
 ## Code source
 
-- [`picarones/report/generator.py`](../picarones/report/generator.py)
+- [`picarones/reports_v2/html/generator.py`](../picarones/reports_v2/html/generator.py)
   — orchestrateur Jinja2 qui appelle les renderers et passe leurs sorties
   au template.
-- [`picarones/report/views/`](../picarones/report/views/) — 5 modules de
+- [`picarones/reports_v2/html/views/`](../picarones/reports_v2/html/views/) — 5 modules de
   composition (chantier 3).
-- [`picarones/report/*_render.py`](../picarones/report/) — 26 renderers
+- [`picarones/reports_v2/html/renderers/`](../picarones/reports_v2/html/renderers/) — 26 renderers
   atomiques.
-- [`picarones/report/templates/view_analyses.html`](../picarones/report/templates/view_analyses.html)
+- [`picarones/reports_v2/html/templates/view_analyses.html`](../picarones/reports_v2/html/templates/view_analyses.html)
   — template Jinja2 qui inclut les blocs.
 - [`tests/test_views.py`](../tests/test_views.py) — tests d'intégration
   des 5 vues du chantier 3.

docs/roadmap/rewrite-2026.md

@@ -43,37 +43,38 @@ Le rewrite ciblé attaque ces trois problèmes ensemble.
 
 ```
 picarones/
-  domain/            # Cercle 1 — types purs (Artifact, PipelineSpec,
+  domain/            # Couche 1 — types purs (Artifact, PipelineSpec,
                      #   EvaluationSpec, DocumentRef, Provenance)
-  evaluation/        # Cercle 2 — vues, projecteurs, métriques
+  formats/           # Couche 2 — ALTO, PAGE, normalisation texte
+    alto/
+    pagexml/
+    text/
+  evaluation/        # Couche 3 — vues, projecteurs, métriques
     views/
     projectors/
     metrics/
     registry.py
-  pipeline/          # Cercle 2 — exécution
+  pipeline/          # Couche 4 — exécution canonique
     executor.py
     cache.py
     spec.py
-  formats/           # Cercle 2 — ALTO, PAGE, normalisation texte
-    alto/
-    pagexml/
-    text/
-  adapters/          # Cercle 3 — moteurs OCR/LLM/VLM, importers, storage
+  adapters/          # Couche 5 — moteurs OCR/LLM/VLM, importers, storage
     ocr/
     llm/
     vlm/
     corpus/
     storage/
-  app/               # Cercle 4 — services applicatifs
+  app/               # Couche 6 — services applicatifs
     services/
     schemas/
-  interfaces/        # Cercle 5 — CLI, web, reports
-    cli/
-    web/
-  reports/
+  reports_v2/        # Couche 7 — rendu HTML / JSON / CSV
     html/
     json/
     csv/
+    narrative/
+  interfaces/        # Couche 8 — CLI, web
+    json/
+    csv/
 ```
 
 Pivot mental : l'objet central n'est plus `Engine + BenchmarkResult`,

docs/security/threat-model.md

@@ -0,0 +1,148 @@
+# Threat model — Picarones
+
+> **Audience** : DSI institutionnelle (BnF, LoC, BL), auditeur
+> sécurité, mainteneur.  Ce document complète
+> [`/SECURITY.md`](../../SECURITY.md) en formalisant le modèle de
+> menace.  Méthodologie : **STRIDE** (Microsoft) + adaptation
+> patrimoine numérique.
+>
+> **Périmètre** : déploiement institutionnel — Picarones tourne sur
+> une infrastructure interne (NAS, cluster Kubernetes), un workspace
+> partagé entre chercheurs, des clés API cloud côté serveur.
+>
+> **Hors périmètre** : déploiement public HuggingFace Space (mode
+> ouvert anonymisé, sans secrets), CLI mono-utilisateur en local
+> (modèle de menace = celui de la machine de l'utilisateur).
+>
+> **Statut** : v1, 2026-05.  À réviser à chaque release majeure ou
+> incident sécurité.
+
+## Acteurs
+
+| Acteur | Confiance | Capacités |
+|--------|-----------|-----------|
+| **Utilisateur authentifié** (chercheur, archiviste BnF) | Modéré | Upload corpus, lance benchmark, lit rapport, télécharge artefacts |
+| **Utilisateur invité** (lecteur d'un rapport publié) | Bas | Lit un rapport HTML produit |
+| **Opérateur** (DSI institutionnelle) | Élevé | Déploie, configure, accède aux logs, gère les clés API |
+| **Mainteneur** (équipe Picarones) | Élevé sur le code | Push code, release, accès limité aux instances de production |
+| **Attaquant externe** | Aucune | Internet public ou utilisateur malveillant |
+
+## Actifs à protéger
+
+| Actif | Sensibilité | Pourquoi |
+|-------|-------------|----------|
+| **Corpus uploadés** | RGPD (peut contenir PII : registres d'état civil) | Article 4 RGPD — données personnelles si nominatives |
+| **Vérités terrain (GT)** | Propriété intellectuelle de l'institution | Investissement humain coûteux ; secret de fait |
+| **Clés API cloud** (`OPENAI_API_KEY`, etc.) | Secret crédential | Compromission = facturation arbitraire + exfiltration de données |
+| **Résultats de benchmark** | Faible (résultats agrégés) | Sauf si attribués nominativement à un transcripteur |
+| **Logs applicatifs** | Modéré (PII collatéral, métadonnées corpus) | Audit trail = preuve juridique mais aussi cible |
+| **Code source** | Public (OSS) | Intégrité supply-chain (signed releases, SBOM, SLSA) |
+| **Base SQLite des jobs** | Modéré (historique des runs, paramètres) | Permet de reconstituer l'activité d'un utilisateur |
+
+## Surfaces d'attaque
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Internet / Intranet                                     │
+└─────────────────────┬────────────────────────────────────┘
+                      │
+                      ▼
+   ┌───────────────────────────────────────┐
+   │  FastAPI (interfaces/web)             │  ← S1 (HTTP), S2 (auth)
+   │  - SecurityHeadersMiddleware          │
+   │  - BodySizeLimitMiddleware            │
+   │  - RateLimitMiddleware                │
+   │  - AuthenticationMiddleware (opt-in)  │
+   └────────────────────┬──────────────────┘
+                        │
+                        ▼
+   ┌───────────────────────────────────────┐
+   │  RunOrchestrator + JobRunner          │  ← S3 (job exec)
+   │  - WorkspaceManager (sandbox)         │
+   │  - ZIP extraction (zip-slip safe)     │
+   └────────────────────┬──────────────────┘
+                        │
+        ┌───────────────┼─────────────────┐
+        ▼               ▼                 ▼
+   ┌──────────┐   ┌───────────┐    ┌─────────────┐
+   │ Adapters │   │ Adapters  │    │ Storage     │  ← S4 (cloud)
+   │ OCR cloud│   │ LLM cloud │    │ filesystem  │  ← S5 (FS)
+   │ (HTTPS)  │   │ (HTTPS)   │    │ + SQLite    │  ← S6 (DB)
+   └──────────┘   └───────────┘    └─────────────┘
+```
+
+## Menaces — analyse STRIDE
+
+### S — Spoofing (usurpation d'identité)
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| S1 | Un attaquant se fait passer pour un utilisateur authentifié | `AuthenticationMiddleware` opt-in avec `AuthenticationBackend` Protocol — l'institution branche son SSO/LDAP/JWT.  Les endpoints `/health` et `/version` restent publics pour les sondes. |
+| S2 | Un client forge `X-Forwarded-For` pour spoofer son IP dans le rate limit | `RateLimitMiddleware.trust_proxy_count: int` (défaut 0 = XFF ignoré).  Lecture du Nème IP en partant de la fin de la chaîne XFF.  Test `tests/interfaces/web/test_rate_limit_xff.py` (7 cas). |
+| S3 | Un attaquant publie un faux package `picarones` sur PyPI | Le projet n'est pas encore sur PyPI public.  À la publication : signer les wheels avec Sigstore et publier le SLSA provenance level 3 (cf. backlog). |
+
+### T — Tampering (altération)
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| T1 | Un utilisateur uploade un ZIP avec des chemins zip-slip pour écrire hors workspace | `WorkspaceManager` sandboxe par session, extraction ZIP filtre les chemins absolus et `..`. |
+| T2 | Un caller construit `DocumentRef(id="../../etc/passwd")` programmatiquement | `_DOC_ID_RE` regex `^[A-Za-z0-9_.\-/]+$` + validateur Pydantic explicite qui rejette tout segment `..` (S59 #M3). |
+| T3 | Un attaquant altère le schéma SQLite `jobs.db` entre deux démarrages | `JobStore.SCHEMA_VERSION` + dispatcher `_MIGRATIONS` qui rejette dur les schémas downgrade.  Pas de mitigation contre une altération en place — c'est au filesystem. |
+| T4 | Un cache d'artefact corrompu ferait diverger un run | `ArtifactKey.hash_hex()` multi-paramètres (inputs hash + step + code_version + params + projection_spec) — un cache pollué est rejeté à la lecture parce que la clé ne match plus. |
+| T5 | Une fonte / modèle local est remplacé par un fichier malveillant | Picarones ne charge aucun modèle automatiquement.  Les modèles Tesseract et Pero sont pointés explicitement par l'utilisateur ; à charge à lui de vérifier les hashes. |
+
+### R — Repudiation (non-répudiation)
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| R1 | Un utilisateur lance un job coûteux puis nie l'avoir fait | `[audit]` log INFO sur `POST /api/jobs` et `DELETE /api/jobs/{id}` avec IP source (S59 #M2).  Logs structurés à conserver côté ops selon la politique RGPD. |
+| R2 | Un attaquant modifie un rapport persisté pour falsifier les chiffres | Le `RunManifest` est byte-déterministe (`model_dump_json` Pydantic ordered).  Le hash SHA-256 du manifest peut être cité dans une publication pour ancrer la version.  Signature cryptographique : non implémentée, à arbitrer (cf. backlog). |
+| R3 | Un mainteneur publie une release sans laisser de trace | GitHub Actions `release.yml` enregistre l'identité GitHub du déclencheur ; SLSA provenance (à venir) attestera la chaîne build → wheel. |
+
+### I — Information disclosure
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| I1 | Une clé API cloud (`OPENAI_API_KEY`, etc.) fuit dans un log applicatif | Les adapters ne logent jamais la clé — vérifié par revue de code.  Les exceptions cloud sont catchées et le message reformulé sans inclure de header.  À durcir : un test `bandit` dans la CI sur les patterns `api_key` en variable de log. |
+| I2 | Un rapport HTML embarque un CSP permissif et leak via XSS | `CSP: default-src 'self'`, pas de `unsafe-inline`, vérifié par `tests/interfaces/web/test_sprint_a14_s49_security.py`.  Le moteur narratif rend les chiffres via templates YAML (pas de injection HTML). |
+| I3 | Le workspace partagé fait fuiter le corpus d'un chercheur à un autre | `WorkspaceManager` sandboxe par `session_id` ; aucun caller ne peut sortir de son workspace via `resolve_output_path`. |
+| I4 | Un endpoint `GET /api/jobs/{job_id}` divulgue les paramètres d'un autre utilisateur | Pas d'isolation multi-tenants à ce jour — défaut documenté.  Le déploiement institutionnel doit ajouter une couche d'autorisation par utilisateur (cf. `AuthenticationMiddleware`). |
+| I5 | Un attaquant lit `dependencies_lock` du `RunManifest` pour cibler une CVE | Acceptable — `dependencies_lock` est public par design (reproductibilité).  La défense est de patcher rapidement les CVE via `pip-audit` en CI. |
+
+### D — Denial of Service
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| D1 | Upload ZIP géant qui sature le disque | `BodySizeLimitMiddleware` (défaut 100 MiB).  **Limite connue** : ne couvre pas `Transfer-Encoding: chunked` — recommandation = nginx `client_max_body_size` en amont (cf. [`operations/runbook.md`](../operations/runbook.md)). |
+| D2 | Flood de requêtes saturant le rate limit en mémoire | `RateLimitMiddleware` avec eviction LRU `max_clients=10000` (S58).  Pas atomique sous très haute concurrence — best-effort assumé. |
+| D3 | Job qui hang sur appel cloud (timeout réseau) | `pytest-timeout 5 min` par test ; `urllib.request.urlopen(timeout=)` configurable par adapter ; `call_with_retry` partagé (3 retries 2/4/8s) qui FAIL fast si non-retryable. |
+| D4 | DAG cyclique ou infini dans une `PipelineSpec` | Validation statique avec détection de cycle dans `pipeline/validation.py` ; rejet `PipelineSpecError` au load. |
+| D5 | XML billion-laughs / XXE sur upload ALTO/PAGE | `defusedxml` exclusif dans `formats/alto/parser.py` et `formats/pagexml/parser.py`. |
+
+### E — Elevation of privilege
+
+| ID | Menace | Mitigation |
+|----|--------|------------|
+| E1 | Un module contribué tiers s'exécute avec des privilèges qu'il ne devrait pas | `BaseModule` interface stricte ; `module_policy.audit_module` valide qu'un module externe ne dérive que de `BaseModule` et déclare ses `input_types`/`output_types` proprement.  Pas de sandboxing process — un module malicieux peut faire `os.system`. |
+| E2 | Un utilisateur web arrive à exécuter du code arbitraire via l'API | `RunSpec` est validé par Pydantic ; `adapter_class` est un dotted-path résolu via `importlib.import_module` mais filtré contre une liste explicite via `RegistryService.bootstrap_defaults()`.  Une release institutionnelle doit verrouiller cette liste. |
+
+## Risques résiduels acceptés
+
+| ID | Risque | Pourquoi accepté |
+|----|--------|------------------|
+| RR1 | Le rate limit n'est pas atomique sous très haute concurrence | Best-effort suffit pour usage institutionnel ; un Redis-backed rate limiter est l'évolution si besoin |
+| RR2 | Un module Python contribué peut faire des `os.system` arbitraires | Le modèle de confiance est *« le mainteneur a revu le code »* — pas de sandbox process.  Pour un usage institutionnel multi-tenant, déployer dans un conteneur isolé par tenant. |
+| RR3 | Les clés API cloud sont en variables d'environnement, pas en HSM | Standard de l'industrie ; un Vault-backed secret store est l'évolution si la DSI l'exige. |
+| RR4 | Pas d'isolation multi-tenants par user dans le workspace web | Documentée explicitement ; déploiement multi-tenants doit ajouter sa propre couche d'autorisation. |
+
+## Procédure de signalement
+
+Voir [`/SECURITY.md`](../../SECURITY.md) pour le canal de
+divulgation responsable.  La version anglaise est dans
+[`/SECURITY.en.md`](../../SECURITY.en.md).
+
+## Révisions
+
+| Version | Date | Changements |
+|---------|------|-------------|
+| 1.0 | 2026-05 | Création initiale (S60), méthodologie STRIDE |

docs/{user → tutorials}/reading-a-report.en.md

@@ -1,5 +1,5 @@
 <!-- translation: machine + human review pending -->
-<!-- canonical: docs/user/reading-a-report.md (FR) -->
+<!-- canonical: docs/tutorials/reading-a-report.md (FR) -->
 
 # Reading a Picarones report
 
@@ -98,6 +98,6 @@ relative path and loaded by the browser on-demand
 ## Further reading
 
 - [Glossary] (embedded in report, accessible via `?` icons)
-- [docs/developer/narrative-engine.en.md](../developer/narrative-engine.en.md) — adding a detector
+- [docs/explanation/narrative-engine.en.md](../developer/narrative-engine.en.md) — adding a detector
 - [docs/developer/extending-glossary.en.md](../developer/extending-glossary.en.md) — enriching the glossary
 - [SPECS.md](../../SPECS.md) — full project specifications

docs/{user → tutorials}/reading-a-report.md

@@ -24,7 +24,7 @@ Visible dès l'ouverture, sans navigation. Contient :
 1. **Synthèse factuelle** — 3 à 5 phrases générées mécaniquement à
    partir des résultats. Aucun LLM dans la chaîne, donc le texte est
    reproductible bit-à-bit. Chaque nombre cité est traçable au JSON
-   de résultats. Voir [docs/developer/narrative-engine.md] pour la liste
+   de résultats. Voir [docs/explanation/narrative-engine.md] pour la liste
    complète des faits que le moteur peut détecter.
 2. **Critical Difference Diagram** (Friedman-Nemenyi) — un graphique
    horizontal qui place chaque moteur sur un axe de rang moyen. Les
@@ -133,7 +133,7 @@ LibreOffice.
 ## Pour aller plus loin
 
 - [Glossaire complet] (intégré dans le rapport, accessible via les `?`)
-- [docs/developer/narrative-engine.md] — comment ajouter un détecteur
+- [docs/explanation/narrative-engine.md] — comment ajouter un détecteur
 - [docs/developer/extending-glossary.md] — comment enrichir le glossaire
 - [SPECS.md] — spécifications complètes du projet
 

docs/{user → tutorials}/writing-a-pipeline-module.md

@@ -17,8 +17,9 @@
 ## TL;DR
 
 ```python
-from picarones.core.modules import BaseModule, ArtifactType
-from picarones.core.pipeline import (
+from picarones.domain.artifacts import ArtifactType
+from picarones.domain.module_protocol import BaseModule
+from picarones.evaluation.pipeline import (
     PipelineRunner, PipelineSpec, PipelineStep,
 )
 
@@ -150,7 +151,7 @@ class NERExtractor(BaseModule):
 ### 3.a Mono-document (Sprint 63)
 
 ```python
-from picarones.core.pipeline import (
+from picarones.evaluation.pipeline import (
     PipelineRunner, PipelineSpec, PipelineStep,
 )
 
@@ -178,7 +179,7 @@ que `Document.ground_truths` porte une `TextGT` (ou `AltoGT`,
 ### 3.b Corpus complet (Sprint 64)
 
 ```python
-from picarones.measurements.pipeline_benchmark import run_pipeline_benchmark
+from picarones.evaluation.pipeline_benchmark import run_pipeline_benchmark
 
 bench = run_pipeline_benchmark(spec, my_corpus)
 print(bench.n_pipelines_succeeded, "/", bench.n_docs)
@@ -203,7 +204,7 @@ bench = run_pipeline_benchmark(spec, corpus, initial_inputs_factory=my_factory)
 ### 3.c Comparer N pipelines (Sprint 65)
 
 ```python
-from picarones.measurements.pipeline_comparison import compare_pipelines
+from picarones.evaluation.pipeline_comparison import compare_pipelines
 
 comparison = compare_pipelines(
     [spec_baseline, spec_with_correcteur_a, spec_with_correcteur_b],
@@ -259,7 +260,7 @@ Sans `inputs_from`, `correct_b` aurait reçu la sortie de
 
 ```python
 from pathlib import Path
-from picarones.report.pipeline_render import build_pipeline_report_html
+from picarones.reports_v2.html.renderers.pipeline import build_pipeline_report_html
 
 bench = run_pipeline_benchmark(spec, corpus)
 Path("rapport_pipeline.html").write_text(
@@ -270,8 +271,8 @@ Path("rapport_pipeline.html").write_text(
 ### 4.b Comparaison de N pipelines (Sprint 68)
 
 ```python
-from picarones.core.modules import ArtifactType
-from picarones.report.pipeline_render import (
+from picarones.domain.artifacts import ArtifactType
+from picarones.reports_v2.html.renderers.pipeline import (
     RankingSpec, build_pipeline_comparison_report_html,
 )