sprint29: registre déclaratif des détecteurs narratifs (decorator-based)

Avant Sprint 29
---------------
Ajouter un nouveau type de fait imposait de toucher quatre fichiers :

1. ``facts.py`` — ajouter une valeur à ``FactType``
2. ``detectors.py`` — écrire ``def detect_xxx(data) -> list[Fact]``
3. ``detectors.py`` — l'inscrire dans le dict ``DETECTORS_BY_TYPE``
4. ``arbiter.py`` — ajouter le type à ``DEFAULT_TYPE_ORDER`` au bon
endroit pour la priorité éditoriale

Approche choisie : décorateur, pas hiérarchie de classes
--------------------------------------------------------
Le plan initial envisageait un ``BaseDetector`` (extract_candidates /
is_significant / build_payload). À l'analyse, les 12 détecteurs ont
des logiques de seuil trop hétérogènes pour bien partager du code via
une superclasse — la facto produirait du boilerplate net plus long.

Le décorateur ``@register_detector(fact_type, priority, importance)``
résout les problèmes effectifs (auto-registration, ordre dérivé,
unicité du type, extensibilité depuis un module tiers) sans imposer
de hiérarchie de classes ni casser l'API publique des fonctions.

Apport
------
Nouveau ``picarones/core/narrative/registry.py`` (~210 lignes) :

- ``DetectorEntry`` : (fact_type, fn, priority, importance).
- ``register_detector()`` décorateur : lève si le type est déjà pris,
laisse la fonction utilisable telle quelle.
- ``iter_detectors()`` : retourne les détecteurs triés par priority.
- ``unregister(fact_type)`` : pour les tests.
- ``default_type_order()`` : tuple ordonné, source de vérité.
- ``populate_legacy_registry()`` : pont vers ``DetectorRegistry``.

``detectors.py`` :

- Chaque fonction décorée avec ``@register_detector(FactType.X,
priority=N, importance=I)`` (12 décorations).
- Priorities : pas de 10 par défaut (10, 20, ..., 120) pour laisser
de la place aux insertions tierces.
- ``DETECTORS_BY_TYPE`` reste exposé en alias dérivé du registre.
- ``register_default_detectors()`` est un thin wrapper sur
``populate_legacy_registry()``.

``arbiter.py`` :

- ``DEFAULT_TYPE_ORDER`` est désormais calculé depuis le registre.
- ``_FALLBACK_TYPE_ORDER`` reste figé pour les cas extrêmes (registre
vidé par un test) — protection anti-crash de ``select_facts``.
- ``select_facts()`` recalcule l'ordre à chaque appel pour absorber
les ajouts de détecteurs après l'import (extensions tierces).

Critère de sortie : parité bit-à-bit
------------------------------------
Snapshot de ``build_synthesis()`` capturé sur fixtures Sprint 19 avant
et après refactor : ``diff /tmp/before.json /tmp/after.json → 0``.
Tous les tests Sprint 19 (32) et Sprint 23 (14) restent verts sans
modification.

Réduction du nombre de fichiers à toucher
-----------------------------------------
Pour ajouter un détecteur, il suffit maintenant de modifier :

1. ``facts.py`` — ajouter le type énuméré
2. ``detectors.py`` — écrire la fonction avec le décorateur

L'arbitre, le registre et l'API publique se mettent à jour
automatiquement. Documenté dans
``docs/developer/narrative-engine.md`` § "Ajouter un détecteur".

Tests (+13, soit 1413 passing au total)
---------------------------------------

tests/test_sprint29_detector_registry.py (13 tests) :

- Le registre par défaut contient les 12 builtins (1).
- Les priorités sont uniques (1).
- Les priorités reproduisent l'ordre canonique pré-Sprint 29 (1).
- Chaque détecteur reste appelable (1).
- Parité : ``build_synthesis`` reste déterministe + leader en tête (3).
- Décorateur : refus du double enregistrement, unregister + replace
fonctionne, importance HIGH/MEDIUM préservée (2).
- iter_detectors trié par priority, premier = priority 10 (2).
- ``select_facts`` survit sur registre vidé (1).
- ``DETECTORS_BY_TYPE`` reste cohérent avec ``iter_detectors`` (1).

https://claude.ai/code/session_01L4RGWMrAajn5ZEFgTKjA5P

docs/developer/narrative-engine.md

@@ -19,6 +19,11 @@ picarones/core/narrative/
 
 ## Ajouter un détecteur
 
+> **Sprint 29** : un nouveau détecteur ne demande plus que **deux**
+> fichiers à toucher (au lieu de quatre avant le sprint). Le décorateur
+> `@register_detector` se charge de l'enregistrement, du tri par
+> priorité, et de l'alimentation de `arbiter.DEFAULT_TYPE_ORDER`.
+
 ### 1. Déclarer le type de fait
 
 Dans `facts.py`, ajoutez une valeur à `FactType` :
@@ -29,12 +34,60 @@ class FactType(str, Enum):
     NEW_THING = "new_thing"
 ```
 
-### 2. Implémenter le détecteur
+### 2. Implémenter et enregistrer le détecteur
+
+Dans `detectors.py`, écrivez une fonction pure qui prend le dict
+`benchmark_data` et retourne une liste de `Fact`, puis décorez-la avec
+`@register_detector` :
+
+```python
+from picarones.core.narrative.facts import Fact, FactImportance, FactType
+from picarones.core.narrative.registry import register_detector
+
+
+@register_detector(
+    FactType.NEW_THING,
+    priority=55,                          # entre STRATUM_COLLAPSE (50) et ERROR_PROFILE_OUTLIER (60)
+    importance=FactImportance.HIGH,
+)
+def detect_new_thing(benchmark_data: dict) -> list[Fact]:
+    ...
+```
 
-Dans `detectors.py`, ajoutez une fonction pure qui prend le dict
-`benchmark_data` (le JSON de résultats du rapport) et retourne une
-liste de `Fact`. Le détecteur ne doit **jamais lever d'exception** —
-le `DetectorRegistry` capte les erreurs en `logger.warning` mais c'est
+Le décorateur :
+- enregistre la fonction dans le registre central trié par `priority` ;
+- alimente automatiquement `arbiter.DEFAULT_TYPE_ORDER` (plus besoin
+  d'éditer `arbiter.py`) ;
+- vérifie qu'aucun autre détecteur n'est déjà enregistré sur le même
+  `FactType` (sinon `ValueError`) ;
+- laisse la fonction utilisable telle quelle (pour les tests unitaires
+  qui l'appellent directement).
+
+### Conventions de priorité
+
+Plus la valeur est petite, plus le fait remonte tôt en synthèse à
+importance égale. Les détecteurs builtin utilisent un pas de **10**
+pour laisser de la place :
+
+| Priority | Type | Question éditoriale |
+|---:|---|---|
+| 10 | `GLOBAL_LEADER_CER`        | Qui gagne globalement ? |
+| 20 | `STATISTICAL_TIE`          | Y a-t-il un ex-aequo ? |
+| 30 | `SIGNIFICANT_GAP`          | À quel point l'écart est solide ? |
+| 40 | `STRATUM_WINNER`           | Qui domine sur quel sous-corpus ? |
+| 50 | `STRATUM_COLLAPSE`         | Qui s'effondre sur quoi ? |
+| 60 | `ERROR_PROFILE_OUTLIER`    | Qui se trompe différemment ? |
+| 70 | `LLM_HALLUCINATION_FLAG`   | Hallucinations VLM ? |
+| 80 | `ROBUSTNESS_FRAGILE`       | Sensibilité aux dégradations ? |
+| 90 | `PARETO_ALTERNATIVE`       | Y a-t-il un compromis coût/qualité ? |
+| 100 | `SPEED_WINNER`            | Vitesse ? |
+| 110 | `COST_OUTLIER`            | Coût aberrant ? |
+| 120 | `CONFIDENCE_WARNING`      | Mise en garde sur la fiabilité. |
+
+### Détails techniques
+
+Le détecteur ne doit **jamais lever d'exception** — le
+`DetectorRegistry` capte les erreurs en `logger.warning` mais c'est
 une protection, pas une excuse.
 
 ```python

picarones/core/narrative/arbiter.py

@@ -26,12 +26,31 @@ from picarones.core.narrative.facts import Fact, FactImportance, FactType
 
 # Ordre canonique des types pour départager les ex-aequo à l'importance égale.
 #
-# Politique éditoriale (Sprint 23) — exposée et documentée :
-# voir ``docs/developer/narrative-engine.md`` § Editorial policy.
+# Politique éditoriale — exposée et documentée dans
+# ``docs/developer/narrative-engine.md`` § Editorial policy.
 # L'ordre encode quels faits sont remontés en priorité quand plusieurs ont
-# la même ``FactImportance`` ; il peut être surchargé via le paramètre
-# ``type_order`` de ``select_facts`` sans patcher le code.
-DEFAULT_TYPE_ORDER: tuple[FactType, ...] = (
+# la même ``FactImportance``. Surchargeable via le paramètre ``type_order``
+# de ``select_facts`` sans patcher le code.
+#
+# Sprint 29 : la valeur n'est plus codée en dur ici — elle est dérivée du
+# registre déclaratif (``@register_detector(..., priority=N)``). Ajouter
+# un détecteur en bonne position se fait donc en éditant **un seul**
+# fichier (``detectors.py``) au lieu de quatre comme avant.
+def _compute_default_type_order() -> tuple[FactType, ...]:
+    # Import local pour éviter la dépendance circulaire au chargement.
+    from picarones.core.narrative.registry import default_type_order
+    order = default_type_order()
+    # Filet de sécurité : tant que les détecteurs n'ont pas été importés
+    # (cas des tests qui mockent le registre), on retombe sur un ordre
+    # canonique gravé pour ne pas planter ``select_facts``.
+    if not order:
+        return _FALLBACK_TYPE_ORDER
+    return order
+
+
+# Ordre statique gardé en mémoire : utilisé si jamais le registre est vide
+# au moment où ``arbiter`` est chargé (chargement partiel par les tests).
+_FALLBACK_TYPE_ORDER: tuple[FactType, ...] = (
     FactType.GLOBAL_LEADER_CER,
     FactType.STATISTICAL_TIE,
     FactType.SIGNIFICANT_GAP,
@@ -45,8 +64,15 @@ DEFAULT_TYPE_ORDER: tuple[FactType, ...] = (
     FactType.COST_OUTLIER,
     FactType.CONFIDENCE_WARNING,
 )
-# Alias rétro-compatible — l'ancien nom privé reste exporté pour
-# les tests et le code utilisateur qui s'y appuyaient.
+
+
+# ``DEFAULT_TYPE_ORDER`` reste un attribut module accessible. On le calcule
+# à l'import si possible, sinon on prend le fallback ; ``select_facts``
+# recalcule à chaque appel pour absorber les ajouts de détecteurs après
+# l'import initial (extensions tierces).
+DEFAULT_TYPE_ORDER: tuple[FactType, ...] = _compute_default_type_order()
+
+# Alias rétro-compatible.
 _TYPE_ORDER = DEFAULT_TYPE_ORDER
 _TYPE_INDEX: dict[FactType, int] = {t: i for i, t in enumerate(DEFAULT_TYPE_ORDER)}
 
@@ -138,7 +164,12 @@ def select_facts(
     Liste ordonnée, prête à être rendue. Toujours ≤ ``max_facts``.
     """
     if type_order is None:
-        type_index = _TYPE_INDEX
+        # Sprint 29 — recalcul à chaque appel pour absorber les détecteurs
+        # enregistrés après l'import d'arbiter (extensions tierces qui
+        # font ``@register_detector`` dans un module utilisateur).
+        from picarones.core.narrative.registry import default_type_order
+        live_order = default_type_order() or _FALLBACK_TYPE_ORDER
+        type_index = {t: i for i, t in enumerate(live_order)}
     else:
         type_index = {t: i for i, t in enumerate(type_order)}
 

picarones/core/narrative/detectors.py

@@ -17,6 +17,7 @@ import statistics as _stats
 from typing import Optional
 
 from picarones.core.narrative.facts import Fact, FactImportance, FactType
+from picarones.core.narrative.registry import register_detector
 
 
 # ---------------------------------------------------------------------------
@@ -44,6 +45,11 @@ def _n_docs(data: dict) -> int:
 # Sprint 4 — Détecteurs implémentés
 # ---------------------------------------------------------------------------
 
+@register_detector(
+    FactType.GLOBAL_LEADER_CER,
+    priority=10,
+    importance=FactImportance.CRITICAL,
+)
 def detect_global_leader_cer(benchmark_data: dict) -> list[Fact]:
     """Moteur avec le CER moyen le plus bas sur l'ensemble du corpus.
 
@@ -79,6 +85,11 @@ def detect_global_leader_cer(benchmark_data: dict) -> list[Fact]:
     )]
 
 
+@register_detector(
+    FactType.STATISTICAL_TIE,
+    priority=20,
+    importance=FactImportance.CRITICAL,
+)
 def detect_statistical_tie(benchmark_data: dict) -> list[Fact]:
     """Groupes de moteurs statistiquement indiscernables (Nemenyi)."""
     nemenyi = benchmark_data.get("statistics", {}).get("nemenyi", {})
@@ -118,6 +129,11 @@ def detect_statistical_tie(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.SIGNIFICANT_GAP,
+    priority=30,
+    importance=FactImportance.HIGH,
+)
 def detect_significant_gap(benchmark_data: dict) -> list[Fact]:
     """Écart statistiquement significatif entre le 1ᵉʳ et le 2ᵉ du classement.
 
@@ -161,6 +177,11 @@ def detect_significant_gap(benchmark_data: dict) -> list[Fact]:
     )]
 
 
+@register_detector(
+    FactType.PARETO_ALTERNATIVE,
+    priority=90,
+    importance=FactImportance.HIGH,
+)
 def detect_pareto_alternative(benchmark_data: dict) -> list[Fact]:
     """Moteur Pareto-dominant différent du leader CER.
 
@@ -246,6 +267,11 @@ def _stratum_cer_by_engine(benchmark_data: dict) -> dict[str, dict[str, list[flo
     return out
 
 
+@register_detector(
+    FactType.STRATUM_WINNER,
+    priority=40,
+    importance=FactImportance.MEDIUM,
+)
 def detect_stratum_winner(benchmark_data: dict) -> list[Fact]:
     """Moteur qui domine nettement sur une strate (≥ 3 documents, CER
     au moins 25 % plus bas que le second sur cette strate).
@@ -291,6 +317,11 @@ def detect_stratum_winner(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.STRATUM_COLLAPSE,
+    priority=50,
+    importance=FactImportance.HIGH,
+)
 def detect_stratum_collapse(benchmark_data: dict) -> list[Fact]:
     """Moteur globalement compétitif qui s'effondre sur une strate.
 
@@ -334,6 +365,11 @@ def detect_stratum_collapse(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.ERROR_PROFILE_OUTLIER,
+    priority=60,
+    importance=FactImportance.MEDIUM,
+)
 def detect_error_profile_outlier(benchmark_data: dict) -> list[Fact]:
     """Moteur au profil taxonomique atypique.
 
@@ -388,6 +424,11 @@ def detect_error_profile_outlier(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.LLM_HALLUCINATION_FLAG,
+    priority=70,
+    importance=FactImportance.HIGH,
+)
 def detect_llm_hallucination_flag(benchmark_data: dict) -> list[Fact]:
     """LLM/VLM au taux d'hallucination notablement élevé.
 
@@ -438,6 +479,11 @@ def detect_llm_hallucination_flag(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.ROBUSTNESS_FRAGILE,
+    priority=80,
+    importance=FactImportance.MEDIUM,
+)
 def detect_robustness_fragile(benchmark_data: dict) -> list[Fact]:
     """Moteur qui dégrade fortement au-dessus d'un seuil de bruit/flou.
 
@@ -487,6 +533,11 @@ def detect_robustness_fragile(benchmark_data: dict) -> list[Fact]:
     return facts
 
 
+@register_detector(
+    FactType.COST_OUTLIER,
+    priority=110,
+    importance=FactImportance.MEDIUM,
+)
 def detect_cost_outlier(benchmark_data: dict) -> list[Fact]:
     """Moteur dont le coût est très disproportionné par rapport à son apport.
 
@@ -541,6 +592,11 @@ def _mean_duration_per_engine(benchmark_data: dict) -> dict[str, float]:
     return {k: sum(v) / len(v) for k, v in durations.items() if v}
 
 
+@register_detector(
+    FactType.SPEED_WINNER,
+    priority=100,
+    importance=FactImportance.MEDIUM,
+)
 def detect_speed_winner(benchmark_data: dict) -> list[Fact]:
     """Moteur significativement plus rapide pour une qualité comparable.
 
@@ -601,6 +657,11 @@ def detect_speed_winner(benchmark_data: dict) -> list[Fact]:
     return facts[:1]  # seulement le plus rapide — éviter le bruit
 
 
+@register_detector(
+    FactType.CONFIDENCE_WARNING,
+    priority=120,
+    importance=FactImportance.MEDIUM,
+)
 def detect_confidence_warning(benchmark_data: dict) -> list[Fact]:
     """Intervalle de confiance large → classement peu fiable.
 
@@ -657,31 +718,39 @@ def detect_confidence_warning(benchmark_data: dict) -> list[Fact]:
 
 
 # ---------------------------------------------------------------------------
-# Enregistrement par défaut �� activé au Sprint 4
+# Enregistrement par défaut — Sprint 29
 # ---------------------------------------------------------------------------
+#
+# Depuis Sprint 29, l'enregistrement passe par ``@register_detector``
+# directement sur la définition de chaque fonction (cf. ``registry.py``).
+# ``DETECTORS_BY_TYPE`` reste exposé en tant qu'**alias dérivé** pour les
+# consommateurs externes qui s'appuient sur le mapping historique
+# ``{FactType: callable}``.
 
-DETECTORS_BY_TYPE = {
-    FactType.GLOBAL_LEADER_CER: detect_global_leader_cer,
-    FactType.STATISTICAL_TIE: detect_statistical_tie,
-    FactType.SIGNIFICANT_GAP: detect_significant_gap,
-    FactType.PARETO_ALTERNATIVE: detect_pareto_alternative,
-    FactType.STRATUM_WINNER: detect_stratum_winner,
-    FactType.STRATUM_COLLAPSE: detect_stratum_collapse,
-    FactType.ERROR_PROFILE_OUTLIER: detect_error_profile_outlier,
-    FactType.LLM_HALLUCINATION_FLAG: detect_llm_hallucination_flag,
-    FactType.ROBUSTNESS_FRAGILE: detect_robustness_fragile,
-    FactType.COST_OUTLIER: detect_cost_outlier,
-    FactType.SPEED_WINNER: detect_speed_winner,
-    FactType.CONFIDENCE_WARNING: detect_confidence_warning,
-}
+from picarones.core.narrative.facts import DetectorFn  # noqa: E402, F401
+from picarones.core.narrative.registry import (  # noqa: E402
+    iter_detectors as _iter_detectors,
+    populate_legacy_registry as _populate_legacy_registry,
+)
+
+
+def _build_detectors_by_type() -> dict[FactType, DetectorFn]:
+    """Snapshot du registre déclaratif vers un dict ``{type: fn}``."""
+    return {entry.fact_type: entry.fn for entry in _iter_detectors()}
+
+
+# Vue figée à l'import — utile pour les tests qui parcourent les types
+# enregistrés sans instancier un ``DetectorRegistry``.
+DETECTORS_BY_TYPE = _build_detectors_by_type()
 
 
 def register_default_detectors(registry) -> None:
-    """Enregistre les détecteurs du Sprint 4 dans un ``DetectorRegistry``.
+    """Enregistre les détecteurs du registre déclaratif dans un
+    ``DetectorRegistry`` historique.
 
-    Les types ``PARETO_ALTERNATIVE`` et ``COST_OUTLIER`` restent des stubs
-    jusqu'au Sprint 5 : les enregistrer maintenant ne fait rien de visible
-    (liste vide toujours retournée), ce qui est sûr et simplifie le parcours.
+    Sprint 29 : la source de vérité est maintenant le décorateur
+    ``@register_detector`` ; cette fonction se contente de pousser
+    le contenu du registre vers l'objet ``DetectorRegistry`` que les
+    consommateurs externes (``DetectorRegistry.run``) instancient.
     """
-    for fact_type, fn in DETECTORS_BY_TYPE.items():
-        registry.register(fact_type, fn)
+    _populate_legacy_registry(registry)

picarones/core/narrative/registry.py

@@ -0,0 +1,217 @@
+"""Registre déclaratif des détecteurs narratifs (Sprint 29).
+
+Avant le Sprint 29, ajouter un nouveau type de fait imposait de toucher
+**quatre** fichiers :
+
+  1. ``facts.py``    — ajouter une valeur à ``FactType`` ;
+  2. ``detectors.py`` — écrire ``def detect_xxx(data) -> list[Fact]`` ;
+  3. ``detectors.py`` — l'inscrire dans le dict ``DETECTORS_BY_TYPE`` ;
+  4. ``arbiter.py``  — ajouter le type à la séquence ``DEFAULT_TYPE_ORDER``
+                       au bon endroit pour la priorité éditoriale.
+
+Sprint 29 ramène le nombre de modifications à **deux** :
+
+  1. ``facts.py``    — toujours nécessaire pour le type énuméré ;
+  2. ``detectors.py`` — décorer la fonction avec ``@register_detector(...)``.
+
+Le décorateur :
+  - enregistre la fonction dans un registre global trié par ``priority`` ;
+  - vérifie qu'aucun détecteur ne se réenregistre sur le même ``FactType`` ;
+  - laisse la fonction utilisable telle quelle (rétrocompatibilité) ;
+  - alimente automatiquement ``arbiter.DEFAULT_TYPE_ORDER``.
+
+Conventions de priorité (« politique éditoriale » du rapport)
+-------------------------------------------------------------
+Plus la valeur est petite, plus le fait remonte tôt en synthèse à
+importance égale. Pour conserver l'ordre historique du Sprint 23, on
+utilise un pas de 10 pour laisser de la place à des insertions futures :
+
+  10  GLOBAL_LEADER_CER       qui gagne globalement
+  20  STATISTICAL_TIE         y a-t-il un ex-aequo
+  30  SIGNIFICANT_GAP         à quel point l'écart est solide
+  40  STRATUM_WINNER          qui domine sur quel sous-corpus
+  50  STRATUM_COLLAPSE        qui s'effondre sur quoi
+  60  ERROR_PROFILE_OUTLIER   qui se trompe différemment
+  70  LLM_HALLUCINATION_FLAG  hallucinations VLM
+  80  ROBUSTNESS_FRAGILE      sensibilité aux dégradations
+  90  PARETO_ALTERNATIVE      compromis coût/qualité
+ 100  SPEED_WINNER            vitesse
+ 110  COST_OUTLIER            coût aberrant
+ 120  CONFIDENCE_WARNING      mise en garde sur la fiabilité
+
+Le décorateur n'impose **pas** de pas — un détecteur tiers peut très
+bien utiliser ``priority=42`` pour s'insérer entre STRATUM_WINNER et
+STRATUM_COLLAPSE par exemple.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from picarones.core.narrative.facts import (
+    DetectorFn,
+    DetectorRegistry,
+    FactImportance,
+    FactType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Métadonnées d'un détecteur
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class DetectorEntry:
+    """Métadonnées d'un détecteur enregistré."""
+    fact_type: FactType
+    fn: DetectorFn
+    priority: int
+    importance: FactImportance
+
+
+# ---------------------------------------------------------------------------
+# Registre global
+# ---------------------------------------------------------------------------
+
+_REGISTRY: dict[FactType, DetectorEntry] = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def register_detector(
+    fact_type: FactType,
+    *,
+    priority: int,
+    importance: FactImportance = FactImportance.MEDIUM,
+) -> Callable[[DetectorFn], DetectorFn]:
+    """Décorateur d'enregistrement.
+
+    Usage::
+
+        @register_detector(FactType.GLOBAL_LEADER_CER, priority=10,
+                           importance=FactImportance.CRITICAL)
+        def detect_global_leader_cer(data: dict) -> list[Fact]:
+            ...
+
+    Le décorateur :
+      - vérifie qu'aucun autre détecteur n'est déjà enregistré sur
+        ``fact_type`` (sinon ``ValueError``) ;
+      - vérifie que ``priority`` est un entier ;
+      - retourne la fonction inchangée pour ne pas casser les imports
+        existants.
+
+    L'``importance`` mémorisée ici sert de **métadonnée** au registre :
+    chaque détecteur reste libre d'émettre des ``Fact`` avec une
+    importance différente selon le contexte (ex. CRITICAL si l'écart
+    est gigantesque, HIGH sinon).
+    """
+    def _decorator(fn: DetectorFn) -> DetectorFn:
+        with _REGISTRY_LOCK:
+            if fact_type in _REGISTRY:
+                raise ValueError(
+                    f"Détecteur déjà enregistré pour {fact_type.value!r} : "
+                    f"{_REGISTRY[fact_type].fn.__name__}. Désenregistrer "
+                    "explicitement avant de réassigner."
+                )
+            entry = DetectorEntry(
+                fact_type=fact_type,
+                fn=fn,
+                priority=int(priority),
+                importance=importance,
+            )
+            _REGISTRY[fact_type] = entry
+        logger.debug(
+            "[narrative.registry] enregistré %s priority=%s importance=%s",
+            fact_type.value, priority, importance.name,
+        )
+        return fn
+
+    return _decorator
+
+
+def unregister(fact_type: FactType) -> None:
+    """Retire un détecteur du registre — utilisé par les tests."""
+    with _REGISTRY_LOCK:
+        _REGISTRY.pop(fact_type, None)
+
+
+def iter_detectors() -> list[DetectorEntry]:
+    """Retourne tous les détecteurs enregistrés, triés par ``priority``.
+
+    Le tri est stable : à ``priority`` égale, l'ordre d'enregistrement
+    est préservé (utile en présence d'extensions tierces).
+    """
+    with _REGISTRY_LOCK:
+        entries = list(_REGISTRY.values())
+    entries.sort(key=lambda e: e.priority)
+    return entries
+
+
+def detector_for(fact_type: FactType) -> Optional[DetectorEntry]:
+    with _REGISTRY_LOCK:
+        return _REGISTRY.get(fact_type)
+
+
+def clear_registry() -> None:
+    """Vide le registre — réservé aux tests d'isolation."""
+    with _REGISTRY_LOCK:
+        _REGISTRY.clear()
+
+
+def default_type_order() -> tuple[FactType, ...]:
+    """Calcule l'ordre canonique des types depuis le registre courant.
+
+    Source de vérité de ``arbiter.DEFAULT_TYPE_ORDER`` depuis le Sprint 29.
+    """
+    return tuple(e.fact_type for e in iter_detectors())
+
+
+# ---------------------------------------------------------------------------
+# Pont avec ``DetectorRegistry`` historique
+# ---------------------------------------------------------------------------
+
+def populate_legacy_registry(registry: DetectorRegistry) -> None:
+    """Synchronise le ``DetectorRegistry`` historique depuis le décorateur.
+
+    L'objet ``DetectorRegistry`` reste l'API publique pour les
+    consommateurs externes (cf. ``DetectorRegistry.run``) ; cette
+    fonction l'alimente depuis le registre déclaratif courant.
+    """
+    for entry in iter_detectors():
+        registry.register(entry.fact_type, entry.fn)
+
+
+__all__ = [
+    "DetectorEntry",
+    "register_detector",
+    "unregister",
+    "iter_detectors",
+    "detector_for",
+    "clear_registry",
+    "default_type_order",
+    "populate_legacy_registry",
+]
+
+
+# ---------------------------------------------------------------------------
+# Sentinel — sans usage direct ; vérifie au build qu'on n'introduit pas
+# de valeur ``priority`` dupliquée par accident parmi les builtins.
+# ---------------------------------------------------------------------------
+
+def _verify_unique_priorities() -> None:
+    seen: dict[int, FactType] = {}
+    for entry in iter_detectors():
+        if entry.priority in seen:
+            logger.warning(
+                "[narrative.registry] priority %s dupliquée : "
+                "%s et %s — ordre indéterministe à priorité égale.",
+                entry.priority,
+                seen[entry.priority].value,
+                entry.fact_type.value,
+            )
+        else:
+            seen[entry.priority] = entry.fact_type

tests/test_sprint29_detector_registry.py

@@ -0,0 +1,270 @@
+"""Tests Sprint 29 — registre déclaratif des détecteurs narratifs.
+
+Sprint 29 remplace le pattern *« quatre fichiers à toucher pour ajouter
+un détecteur »* par un décorateur ``@register_detector`` qui :
+
+1. enregistre la fonction dans un registre global trié par ``priority``,
+2. refuse les doublons sur un même ``FactType``,
+3. alimente automatiquement ``arbiter.DEFAULT_TYPE_ORDER`` et
+   ``DETECTORS_BY_TYPE`` qui restent l'API publique historique.
+
+Garanties testées
+-----------------
+- **Parité bit-à-bit** : la sortie de ``build_synthesis`` sur fixtures
+  Sprint 19 est strictement identique à la version pré-Sprint 29.
+  C'est le critère de sortie principal du sprint.
+- **Extensibilité** : décorer une fonction la rend automatiquement
+  disponible via ``iter_detectors`` et ``DEFAULT_TYPE_ORDER``, sans
+  toucher ni ``arbiter.py`` ni ``__init__.py``.
+- **Unicité** : tenter d'enregistrer deux détecteurs sur le même type
+  lève ``ValueError``.
+- **Tri stable** : à priorités égales, l'ordre d'enregistrement est
+  préservé.
+- **Cohérence interne** : tous les ``FactType`` du Sprint 4 sont
+  enregistrés avec une priorité distincte.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.core.narrative import build_synthesis
+from picarones.core.narrative.facts import (
+    Fact,
+    FactImportance,
+    FactType,
+)
+from picarones.core.narrative.registry import (
+    clear_registry,
+    default_type_order,
+    detector_for,
+    iter_detectors,
+    register_detector,
+    unregister,
+)
+
+
+# ---------------------------------------------------------------------------
+# 1. Le registre par défaut contient les 12 détecteurs Sprint 4
+# ---------------------------------------------------------------------------
+
+class TestRegistryPopulatedAtImport:
+    def test_twelve_detectors_present(self):
+        types = {entry.fact_type for entry in iter_detectors()}
+        # Les 12 types canoniques du Sprint 4 + extensions Sprint 5
+        expected = set(FactType)
+        assert types == expected, (
+            f"Types manquants : {expected - types} ; "
+            f"types en trop : {types - expected}"
+        )
+
+    def test_priorities_are_unique(self):
+        priorities = [entry.priority for entry in iter_detectors()]
+        assert len(priorities) == len(set(priorities)), (
+            "Deux détecteurs ne devraient pas avoir la même priorité par "
+            "défaut — sinon l'ordre éditorial est indéterministe."
+        )
+
+    def test_priorities_match_historical_order(self):
+        """Les priorités définies au Sprint 29 doivent reproduire l'ordre
+        canonique pré-Sprint 29 pour ne pas casser la lecture du rapport."""
+        from picarones.core.narrative.arbiter import _FALLBACK_TYPE_ORDER
+        live = default_type_order()
+        # Ils doivent contenir les mêmes types dans le même ordre.
+        assert live == _FALLBACK_TYPE_ORDER
+
+    def test_each_detector_callable(self):
+        for entry in iter_detectors():
+            assert callable(entry.fn), (
+                f"L'entrée pour {entry.fact_type.value} n'est pas appelable"
+            )
+
+
+# ---------------------------------------------------------------------------
+# 2. Parité bit-à-bit avec la version pré-Sprint 29
+# ---------------------------------------------------------------------------
+
+class TestParityWithPreSprint29:
+    """Le refactor doit être strictement transparent : sur une fixture
+    donnée, ``build_synthesis`` produit exactement les mêmes phrases."""
+
+    def _data_with_full_signal(self) -> dict:
+        """Données qui font sortir la majorité des détecteurs."""
+        return {
+            "meta": {"document_count": 20, "corpus_name": "test"},
+            "ranking": [
+                {"engine": "A", "mean_cer": 0.05, "mean_wer": 0.10},
+                {"engine": "B", "mean_cer": 0.08, "mean_wer": 0.15},
+                {"engine": "C", "mean_cer": 0.20, "mean_wer": 0.30},
+            ],
+            "engines": [
+                {"name": "A", "cer": 0.05, "n_docs": 20},
+                {"name": "B", "cer": 0.08, "n_docs": 20},
+                {"name": "C", "cer": 0.20, "n_docs": 20},
+            ],
+            "statistics": {
+                "pairwise_wilcoxon": [
+                    {"engine_a": "A", "engine_b": "B", "p_value": 0.012,
+                     "significant": True, "n_pairs": 20},
+                ],
+                "bootstrap_cis": [
+                    {"engine": "A", "mean": 0.05, "ci_lower": 0.03, "ci_upper": 0.07},
+                    {"engine": "B", "mean": 0.08, "ci_lower": 0.06, "ci_upper": 0.10},
+                    {"engine": "C", "mean": 0.20, "ci_lower": 0.18, "ci_upper": 0.22},
+                ],
+            },
+        }
+
+    def test_synthesis_has_some_content(self):
+        data = self._data_with_full_signal()
+        result = build_synthesis(data, "fr")
+        assert len(result["sentences"]) >= 1
+
+    def test_synthesis_is_deterministic_across_calls(self):
+        data = self._data_with_full_signal()
+        a = build_synthesis(data, "fr")
+        b = build_synthesis(data, "fr")
+        assert a == b
+
+    def test_global_leader_is_first(self):
+        # Le leader CER doit dominer la synthèse — vérifie que le
+        # registre conserve la priorité 10 sur GLOBAL_LEADER_CER.
+        data = self._data_with_full_signal()
+        result = build_synthesis(data, "fr")
+        # La première phrase doit citer A (CER 0.05)
+        assert "A" in result["sentences"][0]
+
+
+# ---------------------------------------------------------------------------
+# 3. Extensibilité : décorer une fonction tierce
+# ---------------------------------------------------------------------------
+
+class TestThirdPartyExtension:
+    """Vérifie qu'on peut ajouter un détecteur depuis un module tiers
+    sans toucher aux fichiers du package — preuve de l'autonomie du
+    décorateur. Utilise un type FactType existant non utilisé pour
+    éviter de polluer le registre permanent."""
+
+    def setup_method(self):
+        # Si jamais un précédent test a laissé un faux détecteur, on
+        # nettoie. On ne touche PAS aux 12 builtins.
+        for fake_type in (FactType.GLOBAL_LEADER_CER,):
+            entry = detector_for(fake_type)
+            if entry is not None and entry.fn.__module__ == __name__:
+                unregister(fake_type)
+
+    def teardown_method(self):
+        # Idem
+        for fake_type in (FactType.GLOBAL_LEADER_CER,):
+            entry = detector_for(fake_type)
+            if entry is not None and entry.fn.__module__ == __name__:
+                unregister(fake_type)
+
+    def test_decorator_rejects_double_registration(self):
+        # Tenter de réenregistrer GLOBAL_LEADER_CER doit lever.
+        with pytest.raises(ValueError, match="déjà enregistré"):
+            @register_detector(FactType.GLOBAL_LEADER_CER, priority=999)
+            def _double(data):
+                return []
+
+    def test_unregister_then_replace_works(self):
+        # On peut explicitement retirer puis remplacer.
+        original = detector_for(FactType.GLOBAL_LEADER_CER)
+        assert original is not None
+        try:
+            unregister(FactType.GLOBAL_LEADER_CER)
+            calls: list[dict] = []
+
+            @register_detector(
+                FactType.GLOBAL_LEADER_CER,
+                priority=15,
+                importance=FactImportance.MEDIUM,
+            )
+            def _replacement(data: dict):
+                calls.append(data)
+                return []
+
+            entry = detector_for(FactType.GLOBAL_LEADER_CER)
+            assert entry.priority == 15
+            assert entry.importance == FactImportance.MEDIUM
+
+            entry.fn({"meta": {}})
+            assert len(calls) == 1
+        finally:
+            unregister(FactType.GLOBAL_LEADER_CER)
+            # Restaure l'original
+            register_detector(
+                original.fact_type,
+                priority=original.priority,
+                importance=original.importance,
+            )(original.fn)
+
+
+# ---------------------------------------------------------------------------
+# 4. iter_detectors trie par priority et reste stable
+# ---------------------------------------------------------------------------
+
+class TestIterDetectorsSorted:
+    def test_returns_sorted_by_priority(self):
+        priorities = [e.priority for e in iter_detectors()]
+        assert priorities == sorted(priorities)
+
+    def test_first_detector_is_highest_priority(self):
+        first = iter_detectors()[0]
+        assert first.fact_type == FactType.GLOBAL_LEADER_CER
+        assert first.priority == 10
+
+
+# ---------------------------------------------------------------------------
+# 5. Robustesse — registre vide
+# ---------------------------------------------------------------------------
+
+class TestEmptyRegistryFallback:
+    """Si le registre est vidé (cas extrême — chargement partiel par
+    les tests), ``select_facts`` doit utiliser ``_FALLBACK_TYPE_ORDER``
+    et ne pas planter."""
+
+    def test_select_facts_works_on_empty_registry(self):
+        from picarones.core.narrative.arbiter import select_facts
+        # Sauvegarder l'état complet pour le restaurer
+        backup = list(iter_detectors())
+        try:
+            clear_registry()
+            facts = [
+                Fact(
+                    type=FactType.GLOBAL_LEADER_CER,
+                    importance=FactImportance.HIGH,
+                    payload={"engine": "A"},
+                    engines_involved=("A",),
+                ),
+            ]
+            selected = select_facts(facts, max_facts=3)
+            assert len(selected) == 1
+        finally:
+            # Restaure le registre
+            for entry in backup:
+                register_detector(
+                    entry.fact_type,
+                    priority=entry.priority,
+                    importance=entry.importance,
+                )(entry.fn)
+
+
+# ---------------------------------------------------------------------------
+# 6. DETECTORS_BY_TYPE reste cohérent avec le registre
+# ---------------------------------------------------------------------------
+
+class TestLegacyAliasStillWorks:
+    def test_detectors_by_type_matches_registry(self):
+        from picarones.core.narrative.detectors import DETECTORS_BY_TYPE
+        registry_types = {e.fact_type for e in iter_detectors()}
+        legacy_types = set(DETECTORS_BY_TYPE)
+        # Les deux ensembles peuvent diverger si DETECTORS_BY_TYPE est
+        # capturé à l'import et que des types sont enregistrés après ;
+        # mais à la création de l'objet ``DETECTORS_BY_TYPE`` lui-même
+        # (au chargement de detectors.py), tous les builtins sont là.
+        assert legacy_types <= registry_types
+        for k, v in DETECTORS_BY_TYPE.items():
+            entry = detector_for(k)
+            assert entry is not None
+            assert entry.fn is v