docs(s2): Sprint A14-S2 — recadrer le discours, garde-fou install minimal

Sprint S2 du plan rewrite ciblé (rewrite-2026, étape 0 :
stabilisation de l'existant avant la migration de structure).

S2 livre trois choses : (1) un README qui dit la vérité sur l'état
du projet, (2) un BACKLOG_POST_LIVRAISON.md qui sert de garde-fou
contre la dérive de scope pendant les 24 sprints à venir, (3) un
test ``test_minimal_install.py`` qui empêche un nouvel ``import
foo`` au top-level d'introduire silencieusement une dépendance
non déclarée.

README — alignement avec la réalité
-----------------------------------
- Tagline : "benchmarking platform" → "comparison tool". Le
premier mot promettait une infrastructure que le code ne livre
pas encore (pas de couche service, web non confinée, runner
encore couplé au rapport).
- Section "Honest status (May 2026)" qui liste explicitement les
promesses non tenues : RGPD draft, gouvernance/COI documentés
mais non exercés, CITATION/JOSS/DOI planifiés non livrés,
WCAG/pentest scopés non audités. Le bloc précédent affirmait
ces items "complete as of May 2026".
- Section Roadmap pointe désormais vers
``docs/roadmap/rewrite-2026.md`` qui décrit le plan S1–S26 avec
le calendrier.
- Citation : retire la mention "Sprint A12" et pointe vers
BACKLOG_POST_LIVRAISON.md.
- Test count baseline : 3871 → ~3900 (couvre les 51 nouveaux
tests S1).

BACKLOG_POST_LIVRAISON.md — discipline du rewrite
------------------------------------------------
Document de référence pour matérialiser la règle "à chaque doute
pendant le sprint en cours, l'item va ici et le sprint continue".
Catégories :
1. Promesses retirées du README (JOSS/DOI, RGPD, gouvernance,
accessibilité, pentest).
2. Features attendues mais reportées (reprise hashée,
backpressure, cancellation propre, ZIP arborescence, GT
detection patterns, Views, app/services/, suppression imports
magiques, nettoyage Sprint X).
3. Idées spéculatives à valider après livraison.
4. Convention d'usage.

docs/roadmap/rewrite-2026.md — plan S1–S26
------------------------------------------
Synthèse du plan complet livré dans la session de cadrage : les 4
phases, les 26 sprints, les critères go/no-go entre phases, les
4 invariants permanents (main reste livrable, pas de feature
nouvelle, fin de sprint = suite verte, livrable démontrable en 5
min). Référencé depuis le README.

tests/test_minimal_install.py — garde-fou install
-------------------------------------------------
6 tests qui verrouillent deux invariants :
- Tous les noms de l'API publique (28 symboles) sont importables
via ``from picarones import X``.
- Tout package externe chargé à ``import picarones`` doit être
déclaré dans ``[project.dependencies]`` du pyproject.toml. En
cas de désynchronisation (ex : on ajoute ``import foo`` quelque
part mais on oublie ``foo`` dans pyproject), le test échoue.
- Réciproquement, toute dep déclarée comme obligatoire doit être
installable.
- Les modules engines optionnels doivent s'importer en mode
dégradé (warning + fallback) plutôt que de lever ImportError au
top-level.

État de la suite
----------------
``pytest tests/ -q`` → 3920 passed, 3 skipped, 2 failed.
Les 2 fails restants sont purement environnementaux (sous-process
pytest sans ``pip install -e .``) et seront couverts par la CI :
* test_readme_test_count_matches_baseline
* test_readme_tables_consistent_with_code
Aucune régression S2.

À noter : l'inventaire des deps a montré que ``defusedxml`` était
déjà déclaré dans ``[project.dependencies]`` depuis A1. Le crash
``ModuleNotFoundError: defusedxml`` observé dans l'audit initial
était dû à un venv de dev incomplet, pas à pyproject.toml. Le
nouveau ``test_top_level_externals_are_declared`` empêche la
régression dans l'autre sens.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

BACKLOG_POST_LIVRAISON.md

@@ -0,0 +1,169 @@
+# Backlog post-livraison
+
+> **Garde-fou de discipline du rewrite ciblé** (cf. `docs/roadmap/rewrite-2026.md`).
+>
+> Tout ce qui apparaît ici est **explicitement hors scope** des sprints
+> S1–S26. Ces items pourront revenir dans le scope après la livraison à
+> la BnF, pas avant.
+>
+> La règle d'or : "à chaque doute pendant le sprint en cours, l'item va
+> ici et le sprint continue."
+
+---
+
+## 1. Promesses retirées du README
+
+Items historiquement présentés comme acquis et qui ne sont en réalité
+pas tenus au niveau qui justifierait leur affirmation publique.
+
+### 1.1 Scientific publication track
+
+- `CITATION.cff` au format Citation File Format 1.2.
+- DOI Zenodo (snapshot release).
+- Soumission JOSS (Journal of Open Source Software) avec article
+  technique.
+- BibTeX généré automatiquement par release.
+
+**Pourquoi retiré du README pour l'instant** : la posture éditoriale
+sera difficile à tenir tant que le rewrite ciblé n'est pas livré et
+qu'on ne peut pas pointer vers une version 2.0 stable.
+
+**Quand revoir** : après S26.
+
+### 1.2 Conformité RGPD opérationnelle
+
+- Audit DPO interne ou externe.
+- Registre des traitements documenté.
+- Politique de rétention enforced (pas seulement documentée).
+- Mécanisme d'exercice des droits (export, suppression).
+
+**État actuel** : `docs/operations/data-retention-rgpd.md` existe mais
+n'a jamais été validé par un DPO ni testé sur un workflow réel BnF.
+
+### 1.3 Gouvernance et COI policies
+
+- Constitution explicite du comité de pilotage.
+- Politique de gestion des conflits d'intérêts exercée sur ≥ 1 PR
+  externe.
+- Processus de release reviews documenté et appliqué.
+
+**État actuel** : `GOVERNANCE.md` et `CONTRIBUTING.md` sont en place
+comme documents de référentiel mais aucun de ces processus n'a été
+exercé en pratique.
+
+### 1.4 Accessibilité WCAG 2.1 AA
+
+- Audit RGAA externe.
+- Tests automatisés axe-core sur la SPA.
+- Navigation complète clavier validée par utilisateur empêché.
+
+**État actuel** : `ACCESSIBILITY.md` documente l'intention. Les
+améliorations Sprint 25 (extraction du JS inline vers
+`web-app.js`) sont un pas dans la bonne direction mais ne suffisent
+pas à revendiquer la conformité.
+
+### 1.5 Sécurité — pentest externe
+
+- Pentest opérationnel sur un déploiement institutionnel (pas un
+  Space HF public).
+- Validation de la CSP sans `'unsafe-inline'`.
+- Validation de la sandbox `validated_path` / `compute_workspace_roots`
+  par un attaquant compétent.
+
+**État actuel** : Sprint A14-S1 a comblé les 6 P0 connus mais
+l'absence d'audit externe nous interdit d'affirmer l'absence d'autres
+vecteurs.
+
+---
+
+## 2. Features attendues mais reportées
+
+### 2.1 Features fonctionnelles
+
+- Reprise de benchmark hashée par contenu+config (pas seulement par
+  `corpus_name + engine_name`).
+- Backpressure réelle dans le runner (limite de futures en vol,
+  timeout depuis le début d'exécution réelle).
+- Annulation propre qui tue les workers OCR/LLM en cours
+  (actuellement `cancel_futures` ne ferme pas un Tesseract en train
+  de tourner).
+- ZIP upload qui préserve l'arborescence (sans flatten qui écrase).
+- Détection des paires `(image, GT)` qui supporte tous les patterns
+  réels (`.gt.alto.xml`, `.alto.xml`, `.page.xml`, etc.).
+
+→ Couverts par les Sprints S8, S9, S20 du rewrite ciblé.
+
+### 2.2 Vues d'évaluation explicites
+
+- `TextView` — la vue qui projette toute sortie textuelle vers du
+  texte brut comparable.
+- `AltoView` — fidélité documentaire ALTO/PAGE.
+- `SearchView` — recherchabilité fuzzy plein-texte.
+- `LayoutView` — coordonnées et ordre de lecture.
+- `HallucinationView` — contrôle d'invention par le modèle.
+- `CostView` — coût/temps/CO₂.
+
+→ Sprints S13–S18 du rewrite. Au minimum les 3 premières doivent
+exister à la livraison BnF.
+
+### 2.3 Couche service applicative
+
+- `app/services/benchmark_service.py` — orchestration séparée des
+  routers FastAPI.
+- `app/services/path_security.py` — `WorkspaceManager` qui crée un
+  dossier isolé par session/run.
+- Schemas DTO (Pydantic) séparés des modèles de domaine.
+
+→ Sprint S19 du rewrite.
+
+### 2.4 Suppression de la dette d'imports magiques
+
+- Plus de `import picarones.measurements as _trigger_metric_registration`
+  dans `picarones/__init__.py`.
+- Registres construits explicitement par un service au démarrage.
+- Entry points Python pour les modules tiers (`picarones.metrics`,
+  `picarones.adapters`).
+
+→ Sprint S5 + S20 du rewrite.
+
+### 2.5 Suppression des références "Sprint X" dans le code
+
+Le repo contient ~679 références à "Sprint N" dans les fichiers
+Python (commentaires, docstrings, justifications de seuils
+éditoriaux). C'est de la stratigraphie archéologique qui rend le
+code illisible pour un nouveau contributeur.
+
+→ Nettoyage progressif au fil des Sprints S10–S22 du rewrite (à
+chaque déplacement de fichier, on supprime les commentaires de
+sprint qui n'apportent plus rien �� un lecteur de la version
+courante). Pas un sprint dédié.
+
+---
+
+## 3. Idées qui ressortent mais qu'on ne traite pas
+
+À valider après la livraison.
+
+- Cache d'artefacts intermédiaires côté pipeline executor.
+- Parallélisation inter-étapes au sein d'une même pipeline.
+- Vue HTML drag-and-drop pour composer un pipeline (le DAG render
+  Sprint 95 est de l'inspection, pas de la construction).
+- Score composite personnel persisté côté serveur (pour l'instant
+  uniquement URL state côté client).
+- Plugin system PyPI pour modules contribués (`picarones-module-X`).
+- Extension corpus levels au-delà de TEXT/ALTO/PAGE/ENTITIES/READING_ORDER
+  (par exemple : tableaux, mathématiques, partitions).
+
+---
+
+## 4. Convention d'usage de ce document
+
+- **Ajouter** un item dès qu'on identifie une promesse / feature qui
+  doit attendre.
+- **Ne pas retirer** un item juste parce qu'on a envie de le faire ;
+  attendre que le rewrite l'absorbe officiellement (auquel cas il
+  apparaîtra dans `docs/roadmap/rewrite-2026.md`).
+- **Référencer** ce fichier dans les PRs qui retirent du scope du
+  README ou de la documentation utilisateur.
+
+Dernière revue : Sprint A14-S2 (rewrite ciblé, étape 0).

README.md

@@ -9,9 +9,17 @@ pinned: false
 
 # Picarones
 
-> **Heritage OCR / HTR / VLM and post-correction benchmarking platform**
+> **Heritage OCR / HTR / VLM and post-correction benchmarking tool**
 >
-> **Banc d'essai d'OCR / HTR / VLM et de post-correction pour documents patrimoniaux**
+> **Outil de comparaison d'OCR / HTR / VLM et de post-correction pour documents patrimoniaux**
+
+**Status (May 2026)** — version 1.x, scientific prototype under
+consolidation.  The core (corpus, runner, metrics, HTML report) is
+usable to compare transcription pipelines on a ground-truth corpus.
+A targeted rewrite (see
+[`docs/roadmap/rewrite-2026.md`](docs/roadmap/rewrite-2026.md))
+rebuilds the orchestration layer and evaluation views for a stable
+2.0 release by the end of 2026.
 
 [![CI](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml/badge.svg)](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
@@ -23,22 +31,25 @@ pinned: false
 
 ## What is Picarones?
 
-**Picarones** is an open-source benchmarking platform for OCR, HTR, VLM
-and post-correction pipelines on **heritage documents** (manuscripts,
+**Picarones** is an open-source comparison tool for OCR, HTR, VLM and
+post-correction pipelines on **heritage documents** (manuscripts,
 early printed books, archives).
 
 The input is a folder of `(image, ground truth)` pairs — ground truth
 in plain text, ALTO XML, or PAGE XML. Picarones runs the AIs you plug
 in (OCR engines, VLMs, OCR+LLM pipelines, ALTO mappers, ensembles…) on
-every page, compares each output to the ground truth at every relevant
-level (text, ALTO, PAGE, entities, reading order), and produces a
-**self-contained HTML report** with factual numbers, statistical tests
-and a reproducibility snapshot.
+every page, compares each output to the ground truth, and produces an
+HTML report with the numerical results.
 
 **Without ground truth, no benchmark** — Picarones measures how well
 an AI matches a known reference, not how it transcribes an arbitrary
 document.
 
+> **Limits to keep in mind.** Picarones is a tool, not a verdict
+> machine. CER/WER and the philological metrics measure agreement with
+> a single reference; the choice of reference, normalization profile
+> and metric is an editorial decision the user must own.
+
 > *Version française ci-dessous.*
 
 ### Use case
@@ -385,9 +396,12 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~3871 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~3900 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
-requiring live HTTP.
+requiring live HTTP. A handful of tests depend on optional engines
+(`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when
+those binaries are not installed in the local environment — the CI
+matrix runs them in a fully provisioned image.
 
 For end-to-end developer guides, see
 [`docs/developer/index.md`](docs/developer/index.md) (FR) /
@@ -415,19 +429,26 @@ Detailed history and current direction live in:
   one entry per sprint up to the latest release.
 - [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md) —
   technical evolution roadmap (axes A and B for 2026+).
-- [`docs/audits/`](docs/audits/) — institutional readiness audit
-  and remediation plan (sprints A1–A15).
-
-The **Phase 1 of the institutional readiness plan** (sprints A1–A11)
-is complete as of May 2026: CI hardening, doc consistency gates,
-3-circle refactor, web hardening, perf+concurrency tests, WCAG 2.1
-AA accessibility, reproducibility ops (lock files, Docker pinning),
-PyPI/ghcr.io release pipeline, governance & COI policies,
-institutional deployment guide & RGPD documentation.
-
-Remaining: scientific publication track (CITATION + JOSS, sprint
-A12), README/SPECS final polish (this sprint and A14), external
-audits (RGAA + security pentest, A15).
+- [`docs/roadmap/rewrite-2026.md`](docs/roadmap/rewrite-2026.md) —
+  targeted rewrite plan (S1–S26) restructuring orchestration around
+  `Pipeline → Artifacts → Projection → EvaluationView`. Target: end of 2026.
+- [`docs/audits/`](docs/audits/) — internal audit notes ; [`BACKLOG_POST_LIVRAISON.md`](BACKLOG_POST_LIVRAISON.md) — promises **not** in scope.
+
+**Honest status (May 2026).** Several items historically presented as
+"institutional readiness complete" are not at the level the README
+previously claimed and remain on the post-delivery backlog:
+
+- RGPD documentation is a draft, not a validated policy.
+- Governance / COI policies are documented but not exercised by an
+  external review.
+- `CITATION.cff` + Zenodo DOI + JOSS submission are planned, not done.
+- Accessibility (WCAG 2.1 AA) and security pentest are scoped but
+  not externally audited.
+
+The **rewrite-2026** plan (S1–S26) prioritises stabilising the
+benchmark core and the security boundary of the web layer over
+adding new features. Until S26 ships, treat the web app as an
+experimental demonstrator and the CLI as the supported interface.
 
 ---
 
@@ -451,11 +472,13 @@ The complete functional specification is in
 
 ## Citation
 
-A `CITATION.cff` file and a Zenodo DOI will land in Sprint A12
-(scientific publication track). Until then, cite the GitHub repo
-with the commit SHA used in your benchmark — every Picarones report
-embeds the commit and full snapshot for reproducibility (cf.
-[`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md)).
+A `CITATION.cff` file and a Zenodo DOI are **planned**, not yet
+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))
+so the cited commit is sufficient to attribute the result.
 
 ---
 

docs/roadmap/rewrite-2026.md

@@ -0,0 +1,185 @@
+# Rewrite ciblé — plan S1 → S26
+
+> **Statut** — démarré au Sprint A14-S1 (mai 2026), livraison cible
+> **fin 2026** sur la branche `claude/repo-analysis-cukvm` puis fusion
+> sur `main` pour livraison BnF.
+>
+> **Doctrine** : pas de Big Rewrite. Pas non plus de migration douce
+> qui laisserait la dette en place. **Rewrite ciblé** : on réécrit
+> from scratch les zones cassées (~5–8 k lignes : runner d'orchestration,
+> couche web sécurité, gestion d'artefacts) et on **déplace** les zones
+> saines (~30–40 k lignes : calculs purs MUFI / philological /
+> statistics / etc.) sans toucher à leur logique.
+
+---
+
+## Pourquoi un rewrite ciblé ?
+
+Trois constats issus de l'audit (`docs/audits/`) et de la conversation
+de cadrage de mai 2026 :
+
+1. **Les promesses du README dépassaient la réalité du code.** Six bugs
+   P0 vérifiés dans l'audit invalidaient la promesse scientifique
+   (notamment : `normalization_profile` côté web silencieusement
+   ignoré, `compact()` qui amputait le JSON exporté, `compute_metrics`
+   qui retournait `0.0` indistinguable d'un score parfait en cas
+   d'erreur).
+2. **L'architecture à imports magiques.** `import picarones`
+   déclenche une chaîne d'imports par effet de bord qui charge le
+   registre de métriques. Une dépendance optionnelle manquante au fond
+   de la chaîne fait crasher l'import du package entier.
+3. **La dette narrative est trop lourde.** ~679 références à
+   "Sprint N" dans les fichiers Python, qui parasitent la lecture du
+   code par un nouveau contributeur et empêchent toute prise en main
+   par un mainteneur extérieur.
+
+Le rewrite ciblé attaque ces trois problèmes ensemble.
+
+---
+
+## Architecture cible
+
+À la fin du rewrite, l'arborescence Python sera :
+
+```
+picarones/
+  domain/            # Cercle 1 — types purs (Artifact, PipelineSpec,
+                     #   EvaluationSpec, DocumentRef, Provenance)
+  evaluation/        # Cercle 2 — vues, projecteurs, métriques
+    views/
+    projectors/
+    metrics/
+    registry.py
+  pipeline/          # Cercle 2 — exécution
+    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
+    ocr/
+    llm/
+    vlm/
+    corpus/
+    storage/
+  app/               # Cercle 4 — services applicatifs
+    services/
+    schemas/
+  interfaces/        # Cercle 5 — CLI, web, reports
+    cli/
+    web/
+  reports/
+    html/
+    json/
+    csv/
+```
+
+Pivot mental : l'objet central n'est plus `Engine + BenchmarkResult`,
+c'est `Pipeline → Artifacts → Projection → EvaluationView → Metrics`.
+
+---
+
+## Calendrier (26 semaines)
+
+### Phase 0 — Stabilisation de l'existant (S1 → S2)
+
+| Sprint | Objectif | État |
+|---|---|---|
+| **S1** | Boucher les 6 P0 sur `main` | ✅ Livré (commit `a2bea75`) |
+| **S2** | Recadrer le README, env propre, BACKLOG_POST_LIVRAISON | ⏳ En cours |
+
+À la fin de S2, l'outil actuel reste utilisable pour les tests BnF
+pendant que le rewrite avance sur `rewrite-2026`.
+
+### Phase 1 — Squelette et règles d'architecture (S3 → S6)
+
+| Sprint | Objectif |
+|---|---|
+| S3 | Créer les répertoires cibles + tests d'architecture qui interdisent le retour en arrière |
+| S4 | Modèle `Artifact` et types fondamentaux dans `domain/` |
+| S5 | `EvaluationView`, `EvaluationSpec`, `MetricSpec` typés |
+| S6 | `PipelineSpec`, `PipelineStep`, contrats d'exécution |
+
+Critère go/no-go fin de Phase 1 : les tests d'architecture passent,
+la BnF continue à utiliser `main`.
+
+### Phase 2 — Pipeline executor et migration des calculs (S7 → S12)
+
+| Sprint | Objectif |
+|---|---|
+| S7 | Pipeline executor v1 (séquentiel mono-document) |
+| S8 | Backpressure + timeout réel + annulation propre |
+| S9 | `formats/alto/` et `formats/pagexml/` |
+| S10 | Migration des calculs purs vers `evaluation/metrics/` (gros sprint) |
+| S11 | Migration des adapters dans `adapters/` |
+| S12 | Le nouvel executor reproduit l'ancien runner numériquement |
+
+Critère go/no-go fin de Phase 2 : équivalence CER/WER vérifiée à
+1e-9 près sur 5 fixtures + 1 corpus BnF réel.
+
+### Phase 3 — Vues d'évaluation (S13 → S18) — cœur de la valeur ajoutée
+
+| Sprint | Objectif |
+|---|---|
+| S13 | `EvaluationViewExecutor` et le moteur de vues |
+| S14 | `TextView` (vue canonique 1) |
+| S15 | `AltoView` (vue canonique 2) |
+| S16 | `SearchView` (vue canonique 3) + cohérence inter-vues |
+| S17 | Intégration runner + vues + nouveau format de résultat |
+| S18 | E2E sur le cas BnF central + recettage interne |
+
+Critère go/no-go fin de Phase 3 : ton cas d'usage central
+(Tesseract texte brut vs OCR+LLM+ALTO remappé vs VLM+ALTO reconstruit)
+fonctionne bout-en-bout, lisible, avec rapports de projection
+explicites.
+
+### Phase 4 — Web sandboxée + recettage (S19 → S24)
+
+| Sprint | Objectif |
+|---|---|
+| S19 | Couche `app/services/` |
+| S20 | Réécriture corpus upload + sandbox ZIP |
+| S21 | Nouveau `interfaces/web/` (CSRF on, CSP sans inline) |
+| S22 | `interfaces/cli/` + `reports/html/` migration |
+| S23 | Recettage BnF complet |
+| S24 | Corrections de recettage + documentation finale |
+
+### Buffer (S25 → S26)
+
+Imprévus + livraison. Ces deux semaines sont **non négociables**.
+
+---
+
+## Discipline du rewrite
+
+Quatre invariants permanents, valables pendant les 26 semaines :
+
+1. **`main` reste livrable.** Le rewrite vit sur `rewrite-2026` /
+   `claude/repo-analysis-cukvm`. Les P0 vont sur `main`.
+2. **Pas de feature nouvelle.** Si l'envie vient, écrire dans
+   [`BACKLOG_POST_LIVRAISON.md`](../../BACKLOG_POST_LIVRAISON.md) et
+   passer.
+3. **Fin de chaque sprint = un commit qui passe `pytest tests/ -q`.**
+4. **Chaque sprint a un livrable démontrable** en 5 minutes.
+
+Pour le détail à la semaine de chaque sprint (livrables, tests,
+définition de "done", risque principal), voir le plan complet livré
+en réponse à la question de cadrage du 2026-05-03 dans la session
+[`session_011XQZNitg1rCgia8ZD1a2hP`](https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP).
+
+---
+
+## Ce qui n'est *pas* dans le rewrite
+
+Cf. [`BACKLOG_POST_LIVRAISON.md`](../../BACKLOG_POST_LIVRAISON.md) pour
+la liste complète. En résumé :
+
+- Pas de feature nouvelle (NER cloud, VLM extras, etc.).
+- Pas de promesses institutionnelles (RGPD opérationnel, JOSS, COI
+  exercés).
+- Pas de réécriture des calculs purs (MUFI, philological, statistics)
+  — on les déplace, point.
+- Pas de refonte du rapport HTML au-delà de l'intégration des vues
+  (le rendu visuel reste celui d'aujourd'hui pour ne pas allonger).

tests/test_minimal_install.py

@@ -0,0 +1,295 @@
+"""Sprint A14-S2 — A.I.0 P0 : ``import picarones`` doit marcher avec
+seulement les dépendances obligatoires.
+
+Avant ce sprint, l'import du package au top-level chaînait des
+``import`` par effet de bord (cf. ``picarones/__init__.py:91`` :
+``import picarones.measurements as _trigger_metric_registration``)
+qui exigeaient au moment du chargement initial des modules
+théoriquement optionnels.  Conséquence : un ``pip install picarones``
+sur un environnement où, par exemple, ``defusedxml`` n'était pas
+résolu (Python 3.13 alpha, mirrors PyPI partiels, etc.) faisait
+crasher tout import du package — y compris ``from picarones import
+Document`` qui n'a logiquement pas besoin d'XML.
+
+Ce module vérifie deux invariants critiques :
+
+1. **Import OK avec seulement les deps obligatoires** —
+   l'API publique du Cercle 1 doit s'importer sans nécessiter
+   ``[web]``, ``[ner]``, ``[stats]``, ``[pero]``, ``[hf]``, ``[llm]``,
+   ``[ocr-cloud]``, ``[kraken]``.
+
+2. **Les deps obligatoires sont effectivement déclarées** dans
+   ``pyproject.toml`` (cohérence entre le code et la spec
+   d'installation).
+
+Note d'environnement : ce test ne crée pas un venv vierge en
+sous-processus (trop coûteux pour la CI à chaque commit).  Il
+vérifie ce qu'on peut vérifier dans le venv courant — la vraie
+validation "venv neuf" est faite par la matrice CI (cf.
+``.github/workflows/ci.yml``).
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+
+# ──────────────────────────────────────────────────────────────────────
+# 1. Smoke test de l'API publique
+# ──────────────────────────────────────────────────────────────────────
+
+
+PUBLIC_API_NAMES = (
+    "Corpus",
+    "Document",
+    "GTLevel",
+    "TextGT",
+    "AltoGT",
+    "PageGT",
+    "EntitiesGT",
+    "ReadingOrderGT",
+    "load_corpus_from_directory",
+    "ArtifactType",
+    "BaseModule",
+    "BenchmarkResult",
+    "DocumentResult",
+    "EngineReport",
+    "MetricsResult",
+    "aggregate_metrics",
+    "DetectorRegistry",
+    "Fact",
+    "FactImportance",
+    "FactType",
+    "PipelineResult",
+    "PipelineRunner",
+    "PipelineSpec",
+    "PipelineStep",
+    "StepResult",
+    "MetricSpec",
+    "compute_at_junction",
+    "register_metric",
+    "select_metrics",
+)
+
+
+def test_import_picarones_exposes_public_api() -> None:
+    """Tous les noms documentés dans le ``__all__`` du package
+    racine doivent être effectivement importables."""
+    import picarones
+
+    for name in PUBLIC_API_NAMES:
+        assert hasattr(picarones, name), (
+            f"``picarones.{name}`` annoncé dans ``__all__`` mais absent "
+            "du namespace au moment de l'import."
+        )
+
+
+def test_picarones_all_matches_imports() -> None:
+    """``__all__`` ne doit pas mentir."""
+    import picarones
+
+    declared = set(picarones.__all__)
+    expected = set(PUBLIC_API_NAMES) | {"__version__", "__author__"}
+    missing = expected - declared
+    assert not missing, (
+        f"``__all__`` n'expose pas tous les noms attendus : {missing}"
+    )
+
+
+def test_version_is_set() -> None:
+    """``picarones.__version__`` doit être une string non vide."""
+    import picarones
+
+    assert isinstance(picarones.__version__, str)
+    assert picarones.__version__.strip() != ""
+
+
+# ──────────────────────────────────────────────────────────────────────
+# 2. Cohérence entre les imports top-level et pyproject.toml
+# ──────────────────────────────────────────────────────────────────────
+
+
+def _project_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _read_pyproject_dependencies() -> list[str]:
+    """Liste des noms de package des deps obligatoires.
+
+    Volontairement permissif : on garde uniquement le nom (avant
+    ``>=``, ``==``, ``[``, etc.) puisque c'est ce qui permet
+    ``importlib.util.find_spec``.  Les noms PyPI utilisent ``-``
+    mais les modules importés utilisent ``_`` (et ce n'est pas
+    toujours symétrique : ``Pillow`` → ``PIL``, ``pyyaml`` →
+    ``yaml``).  On gère explicitement le mapping ci-dessous.
+    """
+    pyproject = _project_root() / "pyproject.toml"
+    text = pyproject.read_text(encoding="utf-8")
+    # Parser TOML léger : on cible juste le bloc ``dependencies = [...]``
+    # de [project].  Pour rester sans dépendance externe, on parse à la
+    # main une fois la section trouvée.
+    in_deps = False
+    out: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("dependencies"):
+            in_deps = True
+            continue
+        if in_deps:
+            if stripped.startswith("]"):
+                break
+            if stripped.startswith("#") or not stripped:
+                continue
+            # ``    "click>=8.1.0",``  →  ``click``
+            raw = stripped.strip(",").strip().strip('"').strip("'")
+            # Coupe à la première occurrence d'un opérateur de version
+            # ou d'un crochet d'extra.
+            for sep in (">=", "==", "<=", ">", "<", "~=", "[", ";"):
+                idx = raw.find(sep)
+                if idx >= 0:
+                    raw = raw[:idx]
+                    break
+            raw = raw.strip()
+            if raw:
+                out.append(raw)
+    return out
+
+
+# Mapping nom PyPI → nom du module Python à importer.
+# Source : https://packaging.python.org/en/latest/discussions/...
+# Ne lister que les paires asymétriques.
+_NAME_OVERRIDES: dict[str, str] = {
+    "Pillow": "PIL",
+    "pyyaml": "yaml",
+    "PyYAML": "yaml",
+    "python-multipart": "multipart",
+    "pyaml": "yaml",
+}
+
+
+def _import_name(pypi_name: str) -> str:
+    return _NAME_OVERRIDES.get(pypi_name, pypi_name.replace("-", "_"))
+
+
+def test_required_deps_are_importable() -> None:
+    """Toutes les deps déclarées dans ``[project.dependencies]`` doivent
+    être effectivement installables/importables.  Garde-fou contre une
+    typo ou un nom de package PyPI mal copié."""
+    declared = _read_pyproject_dependencies()
+    assert declared, (
+        "Aucune dépendance obligatoire trouvée dans pyproject.toml — "
+        "le parser maison s'est cassé sur le format actuel."
+    )
+    missing: list[tuple[str, str]] = []
+    for pypi in declared:
+        mod = _import_name(pypi)
+        if importlib.util.find_spec(mod) is None:
+            missing.append((pypi, mod))
+    assert not missing, (
+        "Deps obligatoires déclarées mais introuvables dans le venv "
+        "courant.  En CI institutionnelle, c'est un échec dur — un "
+        "``pip install picarones`` produit un package qui crashera à "
+        f"l'import sur ces noms : {missing}.  Vérifier le mapping "
+        "PyPI → module dans ``_NAME_OVERRIDES``."
+    )
+
+
+def test_top_level_externals_are_declared() -> None:
+    """Tout package externe chargé par ``import picarones`` doit être
+    listé dans ``[project.dependencies]``.
+
+    Garde-fou contre le scénario opposé : on ajoute un ``import foo``
+    quelque part dans ``picarones/__init__.py`` (ou dans un module
+    chargé par effet de bord depuis ``__init__.py``) sans déclarer
+    ``foo`` dans ``pyproject.toml``.  Sur un install propre, le
+    package crash.
+    """
+    # Capture des modules chargés avant et après ``import picarones``.
+    before = set(sys.modules)
+    importlib.import_module("picarones")
+    after = set(sys.modules)
+
+    # On ne garde que les top-level (pas de ``foo.bar``) qui ne sont
+    # pas des modules picarones et qui ne sont pas stdlib.
+    stdlib_names = set(getattr(sys, "stdlib_module_names", ()))
+    candidates = {
+        m.split(".")[0] for m in (after - before)
+        if "." not in m
+    }
+    candidates -= {m for m in candidates if m.startswith("_")}
+    candidates -= stdlib_names
+    candidates -= {"picarones"}
+    # Modules implicitement amenés par d'autres déjà déclarés (ex :
+    # rapidfuzz vient avec jiwer ; pydantic_core vient avec pydantic ;
+    # cython_runtime vient avec rapidfuzz ; pyexpat est en stdlib mais
+    # pas toujours dans stdlib_module_names selon la version).
+    transitive_allowed = {
+        "rapidfuzz",
+        "cython_runtime",
+        "pyexpat",
+        "annotated_types",
+        "pydantic",
+        "pydantic_core",
+        "typing_extensions",
+        "typing_inspection",
+        "annotated_doc",
+        "tomli",  # TOML stdlib uniquement à partir de 3.11 (tomllib)
+        "tomllib",
+    }
+    candidates -= transitive_allowed
+
+    declared = {_import_name(d) for d in _read_pyproject_dependencies()}
+
+    undeclared = candidates - declared
+    assert not undeclared, (
+        f"Modules externes chargés à ``import picarones`` mais non "
+        f"déclarés dans ``[project.dependencies]`` : {sorted(undeclared)}.\n"
+        "Soit ajouter ces deps à pyproject.toml, soit déplacer leur "
+        "import en lazy load (à l'intérieur d'une fonction qui n'est "
+        "pas appelée au top-level)."
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# 3. Garde-fou : pas de crash silencieux sur deps optionnelles absentes
+# ─────────────────────────────────────────────────────────���────────────
+
+
+def test_optional_deps_not_required_at_top_level() -> None:
+    """Les modules dépendant de deps optionnelles doivent s'importer
+    en mode dégradé silencieux quand ces deps manquent.
+
+    Exemple : ``picarones.engines.tesseract`` ne doit pas crasher
+    l'import si ``pytesseract`` n'est pas installé — il doit échouer
+    plus tard, au moment du ``run()``.  Idem pour Pero, Mistral OCR,
+    Google Vision, Azure DI.
+
+    On vérifie ici que les modules existent et s'importent même
+    quand on n'a pas les engines installés.
+    """
+    # Liste des modules engines qu'on doit pouvoir au moins charger
+    # (pas exécuter) sans planter.
+    optional_engine_modules = (
+        "picarones.engines.tesseract",
+        "picarones.engines.pero_ocr",
+        "picarones.engines.mistral_ocr",
+        "picarones.engines.google_vision",
+        "picarones.engines.azure_doc_intel",
+    )
+    failed: list[tuple[str, str]] = []
+    for mod_name in optional_engine_modules:
+        try:
+            importlib.import_module(mod_name)
+        except ImportError as exc:
+            failed.append((mod_name, str(exc)))
+    assert not failed, (
+        "Modules engines qui plantent à l'import simple — ils doivent "
+        "tomber en mode dégradé (warning + fallback) plutôt que de "
+        "lever ImportError au top-level.  C'est ce qui permet à un "
+        f"installeur minimal d'utiliser le CLI : {failed}"
+    )