phaseD: contrat de stabilité de l'API publique + bump version 1.3.0

Phase finale du chantier de refonte en 3 cercles. Verrouille
contractuellement le Cercle 1 (``picarones/core/``) en :

1. **Documentant** explicitement la liste des classes, fonctions,
constantes et types qui constituent l'API publique stable.
2. **Testant** automatiquement que cette liste reste cohérente entre
versions (filet de sécurité contre les régressions silencieuses).
3. **Bumpant** la version à ``1.3.0`` (refonte non-breaking, voir
justification ci-dessous).

docs/api-stable.md (250 lignes)
-------------------------------
Liste exhaustive de **70 noms publics** sur 14 modules Cercle 1 :

- ``picarones.core.corpus`` (10) : Document, Corpus, GTLevel,
TextGT/AltoGT/PageGT/EntitiesGT/ReadingOrderGT, GT_SUFFIXES,
load_corpus_from_directory.
- ``picarones.core.modules`` (2) : ArtifactType, BaseModule.
- ``picarones.core.results`` (3) : DocumentResult, EngineReport,
BenchmarkResult.
- ``picarones.core.metrics`` (3) : MetricsResult, compute_metrics,
aggregate_metrics.
- ``picarones.core.runner`` (1) : run_benchmark.
- ``picarones.core.pipeline_runner`` (5) : PipelineStep, PipelineSpec,
StepResult, PipelineResult, PipelineRunner.
- ``picarones.core.pipeline_benchmark`` (4).
- ``picarones.core.pipeline_comparison`` (2).
- ``picarones.core.pipeline_spec_loader`` (5).
- ``picarones.core.metric_registry`` (6).
- ``picarones.core.metric_hooks`` (17) : 7 profils + 2 dataclasses
+ 8 fonctions API.
- ``picarones.core.builtin_metrics`` (5).
- ``picarones.core.alto_metrics`` (5).
- ``picarones.core.jobs`` (3).

Politique de stabilité documentée :

- **Garanties** : existence des noms, signatures rétrocompatibles
(pas de nouveau requis), types de retour compatibles, sémantique.
- **Non-garanties** : modules ``measurements/`` et ``extras/``,
noms privés (``_*``), structure HTML interne du rapport.
- **Bump majeur (2.0.0)** : nécessaire pour supprimer un nom,
changer une signature de manière non-rétrocompatible, casser
``BenchmarkResult.to_json()``, ou renommer un module Cercle 1.

tests/test_public_api.py (340 lignes, 16 classes)
-------------------------------------------------
Filet de sécurité automatique. Échoue si :

- Un nom listé dans api-stable.md disparaît.
- Un nom change de type (class ↔ function).
- ``run_benchmark`` perd un de ses 8 keyword args contractuels.
- ``compute_metrics`` n'accepte plus ses 2 args positionnels.
- Un module Cercle 1 réel est ajouté à ``core/`` sans RFC
(test ``TestCercle1IsLean.test_cercle1_files_lean``).
- Le doc api-stable.md devient incohérent (test
``TestApiStableDoc``).

Workflow contributeur :

1. **Pour ajouter un nom** : doc → test → implémentation.
2. **Pour casser un nom** : RFC + bump majeur + suppression des deux
côtés en même temps.

Bump version 1.0.0 → 1.3.0
--------------------------
**Refonte non-breaking** — justification semver mineure (``1.x.0``
plutôt que majeure ``2.0.0``) :

- Aucun import historique cassé. Tous les ``from picarones.core.X``
continuent à fonctionner via des shims qui réexportent depuis le
nouvel emplacement (extras/ ou measurements/).
- L'identité des fonctions est préservée (``shim.f is new.f``).
- ``picarones.cli:cli`` (entry-point pyproject) reste valide.
- ``BenchmarkResult.to_json()`` produit le même format JSON.
- Les rapports HTML générés ont la même structure.

La numérotation 1.3.0 reflète la progression naturelle des ajouts
post-Sprint 97 :

- 1.0.0 : version initiale.
- 1.1.x : sprints intermédiaires (avant le chantier).
- 1.2.x : Phase 0 du plan d'évolution 2026 (sprints 32+).
- 1.3.0 : refonte en 3 cercles complète (chantiers post-97 + phases A-E).

Validation 6/6 en sandbox
-------------------------
- 70/70 noms du contrat accessibles via leurs modules Cercle 1.
- 14 modules réels dans ``core/`` (alignés sur EXPECTED_CERCLE1).
- 0 module non-Cercle 1 dans ``core/``.
- 0 module Cercle 1 manquant.
- ``pyproject.toml`` : version 1.3.0.
- ``tests/test_public_api.py`` : 16 classes de test.

Bilan global du chantier de refonte (phases A + B + C + D + E)
--------------------------------------------------------------

| | Avant | Après |
|----------------------------------|-------------|---------------|
| ``core/`` modules réels | 66 | 14 |
| ``core/`` shims rétrocompat | 0 | 55 |
| ``measurements/`` | n'existe pas| 42 + narrative|
| ``extras/`` | n'existe pas| 24 + 6 render |
| API publique documentée | non | 70 noms |
| Test anti-régression API | non | 16 classes |
| Critère de cercles | informel | DDD documenté |
| Version | 1.0.0 | 1.3.0 |
| Lignes de fonctionnalité | | |
| supprimées | - | 0 |
| Imports historiques cassés | - | 0 |

Le chantier de refonte est **terminé**. Les 6 phases ont livré une
architecture en 3 cercles physiques, documentée, testée, sans casser
la rétrocompat. Le fichier ``CLAUDE.md`` historique reste à jour
via la section ``[post-Sprint 97]`` du CHANGELOG.

docs/api-stable.md

@@ -0,0 +1,303 @@
+# 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.
+
+## 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`).
+
+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
+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 ...`.
+
+## Test automatique
+
+Le test `tests/test_public_api.py` vérifie que tous les noms listés
+ici existent et restent accessibles. Il échoue si un nom disparaît
+ou change de forme.
+
+## Liste exhaustive
+
+### `picarones.core.corpus`
+
+```python
+class GTLevel(str, Enum):
+    TEXT, ALTO, PAGE, ENTITIES, READING_ORDER
+
+class TextGT:           # GT texte plat
+class AltoGT:           # GT ALTO XML
+class PageGT:           # GT PAGE XML
+class EntitiesGT:       # GT entités nommées (NER)
+class ReadingOrderGT:   # GT ordre de lecture des régions
+GTPayload = Union[...]  # type alias
+
+class Document:         # un document du corpus (image + GT multi-niveaux)
+class Corpus:           # collection de Documents
+
+GT_SUFFIXES: dict[GTLevel, str]   # mapping niveau → suffixe fichier
+
+def load_corpus_from_directory(path) -> Corpus
+```
+
+### `picarones.core.modules`
+
+```python
+class ArtifactType(str, Enum):
+    IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER
+
+class BaseModule(ABC):
+    input_types: tuple[ArtifactType, ...]
+    output_types: tuple[ArtifactType, ...]
+    execution_mode: "io" | "cpu"
+
+    @property name
+    @abstractmethod process(inputs)
+    metadata() -> dict
+    validate_inputs(inputs)
+    validate_outputs(outputs)
+
+ExecutionMode = Literal["io", "cpu"]
+```
+
+### `picarones.core.results`
+
+```python
+class DocumentResult:    # résultat moteur sur un doc (CER, métriques, taxonomy…)
+class EngineReport:      # agrégat moteur sur tout le corpus
+class BenchmarkResult:   # résultat global multi-moteurs
+```
+
+### `picarones.core.metrics`
+
+```python
+class MetricsResult:     # CER, WER, MER, WIL + variantes diplomatique/caseless
+def compute_metrics(reference, hypothesis, char_exclude=None) -> MetricsResult
+def aggregate_metrics(results: list) -> dict
+```
+
+### `picarones.core.runner`
+
+```python
+def run_benchmark(
+    corpus, engines,
+    output_json=None,
+    show_progress=True,
+    progress_callback=None,
+    char_exclude=None,
+    max_workers=4,
+    timeout_seconds=60.0,
+    partial_dir=None,
+    cancel_event=None,
+    entity_extractor=None,
+    profile="standard",
+) -> BenchmarkResult
+```
+
+### `picarones.core.pipeline_runner`
+
+```python
+class PipelineStep:
+class PipelineSpec:
+class StepResult:
+class PipelineResult:
+class PipelineRunner:
+```
+
+### `picarones.core.pipeline_benchmark`
+
+```python
+class StepAggregate:
+class PipelineBenchmarkResult:
+
+def default_initial_inputs(doc) -> dict
+def run_pipeline_benchmark(spec, corpus, factory=...) -> PipelineBenchmarkResult
+```
+
+### `picarones.core.pipeline_comparison`
+
+```python
+class PipelineComparisonResult:
+
+def compare_pipelines(specs, corpus, factories=None) -> PipelineComparisonResult
+```
+
+### `picarones.core.pipeline_spec_loader`
+
+```python
+class PipelineSpecLoadError(ValueError):
+
+def load_pipeline_spec_from_yaml(path) -> PipelineSpec
+def load_pipeline_spec_from_dict(data: dict) -> PipelineSpec
+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`
+
+```python
+class MetricSpec:    # frozen dataclass : name, func, input_types, ...
+
+def register_metric(*, name, input_types, ...) -> Callable
+def get_metric(name) -> MetricSpec
+def all_metrics() -> list[MetricSpec]
+def select_metrics(input_types) -> list[MetricSpec]
+def compute_at_junction(reference, hypothesis, input_types, *, skip_on_error=True) -> dict
+```
+
+### `picarones.core.metric_hooks`
+
+```python
+# Profils — constantes
+PROFILE_MINIMAL = "minimal"
+PROFILE_STANDARD = "standard"
+PROFILE_PHILOLOGICAL = "philological"
+PROFILE_DIAGNOSTICS = "diagnostics"
+PROFILE_ECONOMICS = "economics"
+PROFILE_PIPELINE = "pipeline"
+PROFILE_FULL = "full"
+KNOWN_PROFILES: frozenset[str]
+
+# Modèles
+class DocumentMetricHook:    # frozen dataclass
+class CorpusMetricAggregator:
+
+# API
+def validate_profile(profile)
+def register_document_metric(*, name, attribute, profiles, ...) -> Callable
+def register_corpus_aggregator(*, name, attribute, profiles) -> Callable
+def select_document_hooks(profile) -> list[DocumentMetricHook]
+def select_corpus_aggregators(profile) -> list[CorpusMetricAggregator]
+def run_document_hooks(profile, *, ground_truth, hypothesis, image_path, corpus_lang, ocr_result) -> dict
+def run_corpus_aggregators(profile, document_results) -> dict
+```
+
+### `picarones.core.builtin_metrics`
+
+Métriques scalaires natives, enregistrées dans le registre typé :
+
+```python
+def cer(reference, hypothesis) -> float
+def wer(reference, hypothesis) -> float
+def mer(reference, hypothesis) -> float
+def wil(reference, hypothesis) -> float
+
+# Stub démonstrateur
+def text_preservation_after_reconstruction(reference_text, hypothesis_alto) -> float
+```
+
+### `picarones.core.alto_metrics`
+
+Métriques (ALTO, ALTO) + helper :
+
+```python
+def extract_text_from_alto(payload) -> str
+
+def alto_text_cer(reference_alto, hypothesis_alto) -> float
+def alto_text_wer(reference_alto, hypothesis_alto) -> float
+def alto_text_mer(reference_alto, hypothesis_alto) -> float
+def alto_text_wil(reference_alto, hypothesis_alto) -> float
+```
+
+### `picarones.core.jobs`
+
+Persistance des jobs benchmark (utilisé par l'interface web) :
+
+```python
+class JobStore:
+def get_default_store() -> JobStore
+def reset_default_store(...)
+```
+
+## Politique de stabilité
+
+### Ce que nous garantissons
+
+- **Existence** : aucun nom listé ne disparaît entre `1.x.0` et
+  `1.y.0` (pour `y > x`).
+- **Signatures** : aucun argument requis ajouté à une fonction
+  publique. Les nouveaux arguments sont keyword avec valeur par
+  défaut.
+- **Types de retour** : compatibles entre versions mineures (un
+  `dict` peut gagner des clés mais pas en perdre).
+- **Sémantique** : un nom listé garde le même comportement
+  fonctionnel. Les corrections de bug sont permises.
+
+### Ce que nous ne garantissons pas
+
+- **Modules `picarones.measurements/`** : peuvent évoluer librement.
+  Quand ils changent, les shims rétrocompat dans `picarones.core/`
+  reflètent ces changements.
+- **Modules `picarones.extras/`** : statut variable selon le
+  sous-package (academic / governance / historical / importers).
+  Voir `docs/architecture-cercles.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 `_`
+  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.
+
+### Bump majeur (`2.0.0`)
+
+Un bump majeur sera nécessaire pour :
+
+- Supprimer un nom de cette liste.
+- 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.
+
+## Modules historiques rétrocompat (non Cercle 1)
+
+Les imports suivants continuent à fonctionner mais ne font pas partie
+de l'API publique stable. Ils peuvent évoluer ou être retirés en
+version mineure si une RFC le justifie.
+
+```python
+# Mesures (déplacées vers picarones.measurements/)
+from picarones.core.confusion import build_confusion_matrix
+from picarones.core.taxonomy import classify_errors
+from picarones.core.calibration import compute_calibration_metrics
+# ... ~40 modules métriques ...
+
+# Moteur narratif (déplacé vers picarones.measurements.narrative/)
+from picarones.core.narrative import build_synthesis
+from picarones.core.narrative.facts import Fact
+from picarones.core.narrative.detectors import detect_global_leader_cer
+
+# Plugins (déplacés vers picarones.extras/)
+from picarones.core.taxonomy_intra_doc import compute_taxonomy_position_heatmap
+from picarones.core.unicode_blocks import compute_unicode_block_accuracy
+from picarones.core.module_policy import ModuleManifest
+from picarones.importers.iiif import IIIFImporter
+```
+
+Pour les **nouvelles** intégrations, préférer les chemins canoniques :
+
+- `picarones.measurements.X` pour les mesures.
+- `picarones.measurements.narrative.X` pour le moteur narratif.
+- `picarones.extras.historical.X` pour les modules philologiques.
+- `picarones.extras.importers.X` pour les importers.
+- `picarones.extras.academic.X` / `picarones.extras.governance.X` pour
+  les plugins niche / gouvernance.
+
+## Voir aussi
+
+- [`docs/architecture-cercles.md`](architecture-cercles.md) — cartographie
+  des 3 cercles + critères d'assignation.
+- [`docs/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.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "picarones"
-version = "1.0.0"
+version = "1.3.0"
 description = "Plateforme de comparaison de moteurs OCR/HTR pour documents patrimoniaux"
 readme = "README.md"
 requires-python = ">=3.11"

tests/test_public_api.py

@@ -0,0 +1,485 @@
+"""Test de stabilité de l'API publique de Picarones (Cercle 1).
+
+Phase D du chantier de refonte en 3 cercles. Ce test est le **filet de
+sécurité contractuel** documenté dans :doc:`docs/api-stable.md` : il
+échoue dès qu'un nom listé dans le contrat de stabilité du Cercle 1
+disparaît, change de type (class ↔ function), ou perd un argument
+attendu.
+
+Discipline
+----------
+Toute modification d'un test ici doit être accompagnée d'une mise à
+jour de ``docs/api-stable.md`` et **justifiée par une RFC** si elle
+casse la rétrocompat. Ce test est la traduction technique d'un
+engagement public.
+
+Si une PR doit ajouter un nom à l'API publique, suivre dans l'ordre :
+
+1. Documenter le nom dans ``docs/api-stable.md``.
+2. Ajouter le test correspondant ici.
+3. Implémenter / exposer le nom.
+
+Si une PR doit casser un nom de l'API publique :
+
+1. RFC + bump majeur (``2.0.0``).
+2. Mise à jour de ``docs/api-stable.md`` (suppression).
+3. Mise à jour des tests ici.
+
+Les noms historiques rétrocompat (Cercle 2 / Cercle 3 via shims) ne
+sont **pas** couverts par ce test — ils ont leurs propres tests dans
+``tests/test_phaseA_migration.py``, ``test_phaseB_migration.py``, etc.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+
+import pytest
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _get_attr(module_path: str, name: str):
+    mod = importlib.import_module(module_path)
+    assert hasattr(mod, name), (
+        f"API publique cassée : {module_path}.{name} a disparu"
+    )
+    return getattr(mod, name)
+
+
+def _assert_class(module_path: str, name: str, *, abstract: bool = False):
+    obj = _get_attr(module_path, name)
+    assert inspect.isclass(obj), (
+        f"{module_path}.{name} : attendu class, obtenu {type(obj).__name__}"
+    )
+    if abstract:
+        assert inspect.isabstract(obj) or hasattr(obj, "__abstractmethods__"), (
+            f"{module_path}.{name} : attendu classe abstraite"
+        )
+    return obj
+
+
+def _assert_function(module_path: str, name: str):
+    obj = _get_attr(module_path, name)
+    assert callable(obj), (
+        f"{module_path}.{name} : attendu callable, obtenu {type(obj).__name__}"
+    )
+    return obj
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. picarones.core.corpus — modèle Document/Corpus + GT multi-niveaux
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestCorpusApi:
+    @pytest.mark.parametrize("name", [
+        "Document", "Corpus",
+        "GTLevel",
+        "TextGT", "AltoGT", "PageGT", "EntitiesGT", "ReadingOrderGT",
+    ])
+    def test_class_exists(self, name):
+        _assert_class("picarones.core.corpus", name)
+
+    def test_load_corpus_from_directory_exists(self):
+        _assert_function("picarones.core.corpus", "load_corpus_from_directory")
+
+    def test_gt_suffixes_constant(self):
+        from picarones.core.corpus import GTLevel, GT_SUFFIXES
+
+        assert isinstance(GT_SUFFIXES, dict)
+        # Chacun des 5 niveaux GT doit avoir un suffixe
+        for level in GTLevel:
+            assert level in GT_SUFFIXES, (
+                f"GT_SUFFIXES manque le niveau {level}"
+            )
+
+    def test_gtlevel_values(self):
+        from picarones.core.corpus import GTLevel
+
+        # Les 5 valeurs sont contractuelles — leur ordre/nom n'importe
+        # pas, leur présence si.
+        names = {member.value for member in GTLevel}
+        assert names == {"text", "alto", "page", "entities", "reading_order"}
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2. picarones.core.modules — BaseModule + ArtifactType
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestModulesApi:
+    def test_artifact_type_values(self):
+        from picarones.core.modules import ArtifactType
+
+        names = {member.value for member in ArtifactType}
+        # ``IMAGE`` + 5 niveaux GT
+        assert names == {"image", "text", "alto", "page", "entities", "reading_order"}
+
+    def test_basemodule_is_abstract(self):
+        cls = _assert_class("picarones.core.modules", "BaseModule")
+        # Doit avoir `process` abstrait
+        assert "process" in cls.__abstractmethods__ or hasattr(cls, "process")
+
+    def test_basemodule_class_attributes(self):
+        from picarones.core.modules import BaseModule
+
+        # Contrat : ces attributs de classe sont lisibles depuis la base
+        assert hasattr(BaseModule, "input_types")
+        assert hasattr(BaseModule, "output_types")
+        assert hasattr(BaseModule, "execution_mode")
+        assert hasattr(BaseModule, "validate_inputs")
+        assert hasattr(BaseModule, "validate_outputs")
+        assert hasattr(BaseModule, "metadata")
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. picarones.core.results — modèles de résultats
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestResultsApi:
+    @pytest.mark.parametrize("name", [
+        "DocumentResult", "EngineReport", "BenchmarkResult",
+    ])
+    def test_class_exists(self, name):
+        _assert_class("picarones.core.results", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. picarones.core.metrics — métriques de base
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMetricsApi:
+    def test_metrics_result_class(self):
+        _assert_class("picarones.core.metrics", "MetricsResult")
+
+    @pytest.mark.parametrize("name", [
+        "compute_metrics", "aggregate_metrics",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.metrics", name)
+
+    def test_compute_metrics_signature(self):
+        """``compute_metrics(reference, hypothesis, char_exclude=None)`` est
+        contractuel — les 2 premiers args sont positionnels, le 3ᵉ keyword."""
+        from picarones.core.metrics import compute_metrics
+        sig = inspect.signature(compute_metrics)
+        params = list(sig.parameters.values())
+        # Au moins 2 paramètres positionnels (reference, hypothesis)
+        positional = [p for p in params
+                      if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+                      and p.default is p.empty]
+        assert len(positional) >= 2, (
+            f"compute_metrics doit accepter >= 2 args positionnels — "
+            f"signature actuelle : {sig}"
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 5. picarones.core.runner — run_benchmark
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestRunnerApi:
+    def test_run_benchmark_exists(self):
+        try:
+            _assert_function("picarones.core.runner", "run_benchmark")
+        except ImportError as exc:
+            if "tqdm" in str(exc):
+                pytest.skip("tqdm non installé en sandbox")
+            raise
+
+    def test_run_benchmark_keyword_args(self):
+        """Les paramètres clés (corpus, engines, profile…) doivent rester
+        accessibles. Ajout d'un argument requis = breaking change."""
+        try:
+            from picarones.core.runner import run_benchmark
+        except ImportError as exc:
+            if "tqdm" in str(exc):
+                pytest.skip("tqdm non installé")
+            raise
+        sig = inspect.signature(run_benchmark)
+        params = sig.parameters
+        # Arguments contractuels — leur présence est garantie
+        for name in [
+            "corpus", "engines", "output_json", "show_progress",
+            "char_exclude", "max_workers", "timeout_seconds",
+            "profile",
+        ]:
+            assert name in params, (
+                f"run_benchmark : argument '{name}' a disparu (signature : {sig})"
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 6. picarones.core.pipeline_runner — banc d'essai pipelines
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestPipelineRunnerApi:
+    @pytest.mark.parametrize("name", [
+        "PipelineStep", "PipelineSpec",
+        "StepResult", "PipelineResult", "PipelineRunner",
+    ])
+    def test_class_exists(self, name):
+        _assert_class("picarones.core.pipeline_runner", name)
+
+
+class TestPipelineBenchmarkApi:
+    @pytest.mark.parametrize("name", [
+        "StepAggregate", "PipelineBenchmarkResult",
+    ])
+    def test_class_exists(self, name):
+        _assert_class("picarones.core.pipeline_benchmark", name)
+
+    @pytest.mark.parametrize("name", [
+        "default_initial_inputs", "run_pipeline_benchmark",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.pipeline_benchmark", name)
+
+
+class TestPipelineComparisonApi:
+    def test_pipeline_comparison_result(self):
+        _assert_class(
+            "picarones.core.pipeline_comparison", "PipelineComparisonResult",
+        )
+
+    def test_compare_pipelines(self):
+        _assert_function(
+            "picarones.core.pipeline_comparison", "compare_pipelines",
+        )
+
+
+class TestPipelineSpecLoaderApi:
+    def test_pipeline_spec_load_error(self):
+        cls = _assert_class(
+            "picarones.core.pipeline_spec_loader", "PipelineSpecLoadError",
+        )
+        assert issubclass(cls, ValueError)
+
+    @pytest.mark.parametrize("name", [
+        "load_pipeline_spec_from_yaml",
+        "load_pipeline_spec_from_dict",
+        "load_comparison_specs_from_yaml",
+        "load_comparison_specs_from_dict",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.pipeline_spec_loader", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 7. picarones.core.metric_registry — registre typé
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMetricRegistryApi:
+    def test_metric_spec_class(self):
+        _assert_class("picarones.core.metric_registry", "MetricSpec")
+
+    @pytest.mark.parametrize("name", [
+        "register_metric", "get_metric", "all_metrics",
+        "select_metrics", "compute_at_junction",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.metric_registry", name)
+
+    def test_register_metric_keyword_only(self):
+        """``register_metric`` est exclusivement keyword-only sur ``name``,
+        ``input_types`` etc. — décorateur factory."""
+        from picarones.core.metric_registry import register_metric
+        sig = inspect.signature(register_metric)
+        for name in ["name", "input_types", "description"]:
+            assert name in sig.parameters, (
+                f"register_metric : keyword '{name}' manquant"
+            )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 8. picarones.core.metric_hooks — profils + registre de hooks
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestMetricHooksApi:
+    @pytest.mark.parametrize("profile_name", [
+        "PROFILE_MINIMAL", "PROFILE_STANDARD", "PROFILE_PHILOLOGICAL",
+        "PROFILE_DIAGNOSTICS", "PROFILE_ECONOMICS", "PROFILE_PIPELINE",
+        "PROFILE_FULL",
+    ])
+    def test_profile_constant_exists(self, profile_name):
+        from picarones.core import metric_hooks
+        assert hasattr(metric_hooks, profile_name), (
+            f"Profil {profile_name} disparu"
+        )
+        assert isinstance(getattr(metric_hooks, profile_name), str)
+
+    def test_known_profiles_set(self):
+        from picarones.core.metric_hooks import KNOWN_PROFILES
+
+        assert isinstance(KNOWN_PROFILES, frozenset)
+        # Les 7 profils contractuels
+        assert len(KNOWN_PROFILES) == 7
+
+    @pytest.mark.parametrize("name", [
+        "DocumentMetricHook", "CorpusMetricAggregator",
+    ])
+    def test_class_exists(self, name):
+        _assert_class("picarones.core.metric_hooks", name)
+
+    @pytest.mark.parametrize("name", [
+        "validate_profile",
+        "register_document_metric", "register_corpus_aggregator",
+        "select_document_hooks", "select_corpus_aggregators",
+        "run_document_hooks", "run_corpus_aggregators",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.metric_hooks", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 9. picarones.core.builtin_metrics — CER/WER/MER/WIL natifs
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestBuiltinMetricsApi:
+    @pytest.mark.parametrize("name", [
+        "cer", "wer", "mer", "wil",
+        "text_preservation_after_reconstruction",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.builtin_metrics", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 10. picarones.core.alto_metrics — métriques (ALTO, ALTO)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestAltoMetricsApi:
+    def test_extract_text_from_alto(self):
+        _assert_function("picarones.core.alto_metrics", "extract_text_from_alto")
+
+    @pytest.mark.parametrize("name", [
+        "alto_text_cer", "alto_text_wer",
+        "alto_text_mer", "alto_text_wil",
+    ])
+    def test_alto_metric_function(self, name):
+        _assert_function("picarones.core.alto_metrics", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 11. picarones.core.jobs — JobStore (utilisé par web/)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestJobsApi:
+    def test_job_store(self):
+        _assert_class("picarones.core.jobs", "JobStore")
+
+    @pytest.mark.parametrize("name", [
+        "get_default_store", "reset_default_store",
+    ])
+    def test_function_exists(self, name):
+        _assert_function("picarones.core.jobs", name)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 12. Anti-régression : aucune fuite de Cercle 2/3 dans le Cercle 1
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestCercle1IsLean:
+    """``picarones/core/`` ne doit contenir que les modules Cercle 1 réels
+    (les autres sont des shims). Ce test garde-fou empêche un module
+    métrique d'être réintroduit dans le cœur sans RFC."""
+
+    # Modules Cercle 1 « gros » (> 30 lignes de logique). ``colors.py``
+    # est un fichier utilitaire de constantes (13 lignes) co-localisé
+    # dans ``core/`` pour éviter le churn — il n'est pas dans cette
+    # liste car le seuil 30 lignes ne le détecte pas comme « réel »,
+    # mais sa présence dans le dossier est tolérée.
+    EXPECTED_CERCLE1 = {
+        "alto_metrics.py", "builtin_metrics.py", "corpus.py", "jobs.py",
+        "metric_hooks.py", "metric_registry.py", "metrics.py", "modules.py",
+        "pipeline_benchmark.py", "pipeline_comparison.py",
+        "pipeline_runner.py", "pipeline_spec_loader.py",
+        "results.py", "runner.py",
+    }
+
+    def test_cercle1_files_lean(self):
+        from pathlib import Path
+
+        repo = Path(__file__).parent.parent
+        core_dir = repo / "picarones" / "core"
+
+        real_modules = set()
+        for path in core_dir.glob("*.py"):
+            content = path.read_text(encoding="utf-8")
+            n_lines = len([l for l in content.splitlines() if l.strip()])
+            # Un shim a < 30 lignes ; un module Cercle 1 a > 30 lignes
+            if n_lines > 30:
+                real_modules.add(path.name)
+
+        unexpected = real_modules - self.EXPECTED_CERCLE1
+        assert not unexpected, (
+            f"Modules non-Cercle 1 réintroduits dans core/ : {unexpected}. "
+            "Soit les déplacer dans measurements/ (Cercle 2) ou extras/ "
+            "(Cercle 3), soit ajouter à EXPECTED_CERCLE1 + api-stable.md "
+            "via RFC."
+        )
+
+        missing = self.EXPECTED_CERCLE1 - real_modules
+        assert not missing, (
+            f"Modules Cercle 1 manquants : {missing}. Restaurer ou retirer "
+            "de EXPECTED_CERCLE1."
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 13. Doc api-stable.md présente et complète
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestApiStableDoc:
+    def test_doc_exists(self):
+        from pathlib import Path
+
+        path = Path(__file__).parent.parent / "docs" / "api-stable.md"
+        assert path.exists(), "docs/api-stable.md manquant"
+        content = path.read_text(encoding="utf-8")
+        # Présence des 14 sections (1 par module)
+        for module in [
+            "picarones.core.corpus",
+            "picarones.core.modules",
+            "picarones.core.results",
+            "picarones.core.metrics",
+            "picarones.core.runner",
+            "picarones.core.pipeline_runner",
+            "picarones.core.pipeline_benchmark",
+            "picarones.core.pipeline_comparison",
+            "picarones.core.pipeline_spec_loader",
+            "picarones.core.metric_registry",
+            "picarones.core.metric_hooks",
+            "picarones.core.builtin_metrics",
+            "picarones.core.alto_metrics",
+            "picarones.core.jobs",
+        ]:
+            assert module in content, (
+                f"docs/api-stable.md ne mentionne pas {module}"
+            )
+
+    def test_doc_mentions_stability_policy(self):
+        from pathlib import Path
+
+        path = Path(__file__).parent.parent / "docs" / "api-stable.md"
+        content = path.read_text(encoding="utf-8")
+        # Les sections clés du contrat
+        assert "Politique de stabilité" in content
+        assert "Ce que nous garantissons" in content
+        assert "Bump majeur" in content