docs(architecture): manifeste 3 cercles avec règle de dépendance stricte

Réécriture du manifeste pour clarifier la frontière entre cercles :

- Cercle 1 (`core/`) : abstractions pures, pas de logique métier.
Liste exhaustive : modules, corpus, results, metric_registry,
metric_hooks, pipeline, facts.
- Cercle 2 (`measurements/`, `engines/`, `llm/`, `pipelines/`,
`modules/`) : implémentations officielles distribuées.
- Cercle 3 (`extras/`, `report/`, `cli/`, `web/`) : extensions et
présentation.

Règle de dépendance : les flèches d'import vont uniquement de
l'extérieur vers l'intérieur. Pas de shim — un module a un seul
emplacement physique.

https://claude.ai/code/session_01Hsd7kL8yeCbXn1mA7GQK9L

docs/architecture.md

@@ -1,181 +1,143 @@
-# Architecture Picarones — vue d'ensemble post-chantiers
-
-Ce document décrit l'architecture du projet **après les chantiers 1-5**
-du plan d'évolution post-Sprint 97. Il complète le `CLAUDE.md`
-historique (qui reste l'historique chronologique des sprints) en
-donnant une **vue thématique** de l'organisation actuelle du code.
-
-## Vue d'ensemble
+# Architecture Picarones — manifeste
 
 Picarones est un **banc d'essai** pour pipelines OCR/HTR sur documents
-patrimoniaux. Le projet livre :
-
-1. **Engines OCR** (5 adapters : Tesseract, Pero OCR, Mistral OCR,
-   Google Vision, Azure Document Intelligence).
-2. **Adapters LLM** (4 providers : OpenAI, Anthropic, Mistral, Ollama)
-   pour les pipelines OCR+LLM (zero-shot, post-correction…).
-3. **Modules de référence** (chantier 1) : `TextToAltoMonoRegion`
-   pour démonstrer l'extension `BaseModule` (image+texte → ALTO).
-4. **Runner** orchestrateur multi-moteurs avec parallélisation
-   ProcessPool (CPU-bound) ou ThreadPool (IO-bound).
-5. **Rapport HTML** auto-suffisant (Chart.js embarqué) avec 5+ vues
-   thématiques composables.
-6. **Interface web FastAPI** + **CLI Click** (15 sous-commandes).
-
-## Structure des packages
+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.
 
 ```
-picarones/
-├── cli/                     (chantier 5) Package CLI Click
-│   ├── __init__.py          Groupe `cli` + helpers + commandes simples
-│   ├── _workflows.py        run, diagnose, economics, edition, compare
-│   ├── _pipeline.py         pipeline run, pipeline compare
-│   ├── _imports.py          import iiif (+ futurs)
-│   ├── _serve.py            serve (FastAPI launcher)
-│   ├── _history.py          history (consultation SQLite)
-│   └── _robustness.py       analyse robustesse
-│
-├── core/
-│   ├── corpus.py            Document, Corpus, GTLevel multi-niveaux
-│   ├── modules.py           BaseModule + ArtifactType (Sprint 33)
-│   ├── metric_registry.py   Registre typé (Sprint 34)
-│   ├── builtin_metrics.py   Métriques scalaires natives
-│   ├── alto_metrics.py      (chantier 1) Métriques (ALTO, ALTO)
-│   ├── metric_hooks.py      (chantier 2) Profils + registre de hooks
-│   ├── builtin_hooks.py     (chantier 2) 12 hooks doc + 12 agrégateurs
-│   ├── runner.py            Orchestrateur multi-moteurs
-│   ├── pipeline_runner.py   Banc d'essai de pipelines composées
-│   ├── narrative/
-│   │   ├── facts.py         Modèle Fact + 18+ FactType
-│   │   ├── registry.py      Registre déclaratif
-│   │   ├── arbiter.py       Arbitrage des Facts (anti-redondance)
-│   │   ├── renderer.py      Rendu i18n YAML → str.format_map
-│   │   └── detectors/       (chantier 5) 6 sous-modules thématiques
-│   │       ├── ranking.py
-│   │       ├── pareto.py
-│   │       ├── stratum.py
-│   │       ├── quality.py
-│   │       ├── history.py
-│   │       └── ensemble.py
-│   └── ... (~60 modules métriques philologiques, statistiques, etc.)
-│
-├── engines/
-│   ├── base.py              (chantier 1) BaseOCREngine factorisée
-│   │                        avec hooks _run_with_native +
-│   │                        _extract_raw_confidences
-│   ├── tesseract.py
-│   ├── pero_ocr.py
-│   ├── mistral_ocr.py
-│   ├── google_vision.py
-│   └── azure_doc_intel.py
-│
-├── llm/
-│   ├── base.py              (chantier 4) Helpers normalize_llm_content +
-│   │                        log_http_error factorisés
-│   ├── mistral_adapter.py
-│   ├── openai_adapter.py
-│   ├── anthropic_adapter.py
-│   └── ollama_adapter.py
-│
-├── modules/                 (chantier 1) Modules BaseModule de référence
-│   └── alto_text_to_mono_region.py
-│
-├── importers/
-│   ├── _http.py             (chantier 4) Helpers HTTP factorisés
-│   ├── iiif.py
-│   ├── htr_united.py
-│   ├── gallica.py           (chantier 4) Délègue à _http
-│   ├── huggingface.py
-│   └── escriptorium.py
-│
-├── pipelines/               Pipelines OCR+LLM (zero_shot, post_correction)
-│
-├── prompts/                 8 templates .txt FR+EN
-│
-├── report/                  Rapport HTML
-│   ├── generator.py         Orchestrateur Jinja2
-│   ├── views/               (chantier 3) 5 vues thématiques composables
-│   │   ├── economics.py     throughput + cost projection
-│   │   ├── advanced_taxonomy.py  taxonomy comparison + lexical_modernization
-│   │   ├── diagnostics.py   levers + image_predictive + baseline + worst_lines
-│   │   ├── pipeline.py      DAG + error_absorption + incremental + audit
-│   │   └── robustness.py    robustness projection
-│   ├── *_render.py          26 renderers atomiques
-│   ├── templates/           Jinja2 (10 vues HTML + partials)
-│   ├── i18n/{fr,en}.json    410 clés
-│   ├── glossary/            25 entrées YAML bilingues
-│   └── vendor/              Chart.js embarqué
-│
-└── web/
-    ├── app.py               FastAPI (2065 lignes — découpage reporté)
-    ├── security.py
-    ├── templates/, static/
-    └── ...
+   Cercle 3 (extras, report, cli, web)
+   │
+   ▼
+   Cercle 2 (measurements, engines, llm, pipelines, modules)
+   │
+   ▼
+   Cercle 1 (core)
 ```
 
-## Fluxes principaux
+## Cercle 1 — `picarones/core/` : abstractions de domaine
 
-### Bench OCR classique
+Pas de logique métier, pas d'I/O. Uniquement des **contrats** que les
+cercles supérieurs implémentent.
 
-```
-CLI: picarones run --corpus DIR --engines tess,pero --profile standard
-  ↓
-load_corpus_from_directory(DIR)  → Corpus
-_engine_from_name("tess")        → TesseractEngine (BaseOCREngine)
-                                   (chantier 1 : refondu sur _run_with_native
-                                    + _extract_raw_confidences)
-  ↓
-run_benchmark(corpus, engines, profile="standard")
-  ↓ (profil active 12 hooks doc + 12 agrégateurs via builtin_hooks)
-ProcessPoolExecutor / ThreadPoolExecutor
-  ↓
-_compute_document_result(doc, profile)
-  ↓ (run_document_hooks itère sur les hooks actifs du profil)
-DocumentResult (avec confusion, taxonomy, calibration, …)
-  ↓ (run_corpus_aggregators)
-EngineReport (avec aggregated_*)
-  ↓
-BenchmarkResult
-  ↓
-ReportGenerator.generate()
-  ↓ (build_economics_view_html + build_advanced_taxonomy_view_html
-     + build_diagnostics_view_html selon profil)
-report.html (autonome, ~450 Ko)
-```
+| 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` |
 
-### Bench pipeline composée (axe B, chantier 1 livré bout-en-bout)
+**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.
 
-```
-CLI: picarones pipeline run examples/pipelines/ocr_to_alto.yaml --corpus DIR
-  ↓
-load_pipeline_spec_from_yaml()
-  ↓
-PipelineSpec :
-  step "ocr"  : TesseractEngine          (IMAGE → TEXT)
-  step "alto" : TextToAltoMonoRegion     (IMAGE+TEXT → ALTO)
-  ↓
-PipelineRunner.run(spec, document)
-  ↓ (compute_at_junction((TEXT,TEXT)) → cer/wer/mer/wil)
-  ↓ (compute_at_junction((ALTO,ALTO)) → alto_text_cer/wer/...)
-PipelineResult avec junction_metrics par étape
-  ↓
-build_pipeline_report_html()  (rapport pipeline composée autonome)
-```
+## 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.py`, `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).
 
-## Documents complémentaires
-
-- [`docs/profiles.md`](profiles.md) — les 7 profils de calcul du chantier 2.
-- [`docs/cli-workflows.md`](cli-workflows.md) — les 15 commandes CLI.
-- [`docs/views.md`](views.md) — les vues HTML disponibles dans le rapport.
-- [`docs/user/reading-a-report.md`](user/reading-a-report.md) — guide
-  utilisateur pour lire un rapport.
-- [`docs/user/writing-a-pipeline-module.md`](user/writing-a-pipeline-module.md)
-  — guide pour brancher un module tiers (`BaseModule`).
-- [`docs/developer/narrative-engine.md`](developer/narrative-engine.md)
-  — détecteurs narratifs : architecture, comment en ajouter.
-- [`docs/developer/module-policy.md`](developer/module-policy.md) — manifest
-  + audit pour modules contribués (Sprint 97).
-- [`docs/case-studies/`](case-studies/) — 2 cas d'école (registres
-  paroissiaux, édition critique).
-- [`docs/roadmap/evolution-2026.md`](roadmap/evolution-2026.md) — plan
-  d'évolution (axe A métrique + axe B pipelines composées).
+Un test du cercle N **n'importe pas** les implémentations des
+cercles > N (sauf `tests/integration/`).