refactor(arch): Sprint A3 — refactor cercles + importers (B-1, B-2, B-3, m-17)

Phase 1 du plan de remédiation institutionnelle. Quatre violations de
la règle d'architecture en 3 cercles fermées + un garde-fou
architectural posé pour empêcher toute régression future.

B-1 : déplace ``compute_word_diff`` / ``compute_char_diff`` /
``diff_stats`` de ``picarones/report/diff_utils.py`` vers
``picarones/core/diff_utils.py`` (Cercle 1, source canonique).
``report/diff_utils.py`` reste comme ré-export trivial avec
``DeprecationWarning`` (suppression v1.3.0). Les 3 consommateurs
(``measurements/statistics.py:861``, ``report/generator.py:39``,
``report/worst_lines_render.py:22``) importent désormais depuis
``core``. Tests déplacés ``tests/report/`` → ``tests/core/``.

B-2 : déplace ``difficulty_color()`` de
``picarones/measurements/difficulty.py:195`` vers le nouveau module
``picarones/report/difficulty_render.py``. ``measurements/difficulty.py``
ne contient plus que de la logique purement numérique.

B-3 : remplace 4 sites ``except Exception: pass`` (huggingface.py:266,
416 + htr_united.py:431, 448) par
``logger.warning`` + appel à un nouveau journal en mémoire
``picarones.extras.importers._fallback_log`` (record_fallback /
consume_fallback_log). Le moteur narratif consomme ce journal via le
nouveau ``FactType.IMPORTER_FALLBACK_TRIGGERED`` (priority 180,
importance MEDIUM, HIGH si ≥2 incidents sur le même importer).
Templates FR + EN ajoutés (10 lignes chacun, factuel sans chiffre en
dur).

m-17 : déplace 2 tests qui violaient la règle d'imports cross-cercle
(``tests/measurements/test_sprint11_i18n_english.py`` et
``tests/measurements/test_sprint94_error_absorption.py``) vers
``tests/integration/`` puisqu'ils consomment du Cercle 3.

Bonus refactor : la cérémonie d'eager-load des métriques typées
(Sprint 34) qui vivait dans ``core/pipeline.py`` (11 imports vers
``picarones.measurements.*``, violation Cercle 1→2) est déplacée
dans ``picarones/measurements/__init__.py``. Le top-level
``picarones/__init__.py`` déclenche désormais l'enregistrement via
``import picarones.measurements as _trigger_metric_registration``.

Garde-fou architectural :
``tests/core/test_circle_dependencies.py`` parse l'AST de tous les
fichiers Cercle 1+2 et fail dès qu'un import remonte vers un cercle
plus extérieur. Couvre imports top-level ET paresseux dans les
fonctions (le piège qui a permis B-1 et B-2). 105 fichiers audités,
0 violation.

Mises à jour expectations Sprint 29 + chantier5 :
``DETECTORS_BY_TYPE`` 18→19, history 3→4 détecteurs,
``_FALLBACK_TYPE_ORDER`` étendue.

Validation locale : 77/77 Sprint 29 + chantier5 verts ;
123/123 tests/core (diff_utils + circle_dependencies) verts ; ruff,
mypy strict sur core/, bandit (0 HIGH/MEDIUM) tous verts. Suite
complète relancée en arrière-plan pour confirmation finale.

picarones/__init__.py

@@ -73,6 +73,14 @@ from picarones.core.metric_registry import (
     select_metrics,
 )
 
+# Sprint A3 — trigger d'enregistrement du registre typé (Sprint 34).
+# L'import de ``picarones.measurements`` provoque l'exécution des
+# décorateurs ``@register_metric`` sur ``cer``, ``wer``, ``mer``,
+# ``wil`` + ~15 métriques philologiques + reading order + NER + ALTO.
+# Ce trigger remplace l'ancien import croisé Cercle 1 → Cercle 2 dans
+# ``core/pipeline.py`` (violation B-1/B-2 du même esprit).
+import picarones.measurements as _trigger_metric_registration  # noqa: F401, E402
+
 __all__ = [
     "__version__",
     "__author__",

picarones/core/diff_utils.py

@@ -0,0 +1,89 @@
+"""Calcul du diff mot-à-mot entre vérité terrain et sortie OCR.
+
+Produit une liste d'opérations sérialisables en JSON, consommée
+par le rendu JS dans le rapport HTML.
+
+Opérations possibles
+--------------------
+{"op": "equal",   "text": "mot"}
+{"op": "insert",  "text": "mot"}    -- présent dans l'OCR mais pas dans la GT
+{"op": "delete",  "text": "mot"}    -- présent dans la GT mais pas dans l'OCR
+{"op": "replace", "old": "…", "new": "…"}  -- substitution (orange)
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from typing import Any
+
+
+def _tokenize(text: str) -> list[str]:
+    """Découpe le texte en tokens (mots + ponctuation + espaces)."""
+    # Conserver les espaces comme tokens pour un rendu fidèle
+    return re.split(r"(\s+)", text)
+
+
+def compute_word_diff(reference: str, hypothesis: str) -> list[dict[str, Any]]:
+    """Calcule un diff mot-à-mot entre deux textes.
+
+    Parameters
+    ----------
+    reference:
+        Texte de vérité terrain.
+    hypothesis:
+        Texte produit par le moteur OCR.
+
+    Returns
+    -------
+    list of dict
+        Séquence d'opérations : equal, insert, delete, replace.
+    """
+    ref_tokens = reference.split()
+    hyp_tokens = hypothesis.split()
+
+    matcher = difflib.SequenceMatcher(None, ref_tokens, hyp_tokens, autojunk=False)
+    ops: list[dict[str, Any]] = []
+
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        ref_chunk = " ".join(ref_tokens[i1:i2])
+        hyp_chunk = " ".join(hyp_tokens[j1:j2])
+
+        if tag == "equal":
+            ops.append({"op": "equal", "text": ref_chunk})
+        elif tag == "insert":
+            ops.append({"op": "insert", "text": hyp_chunk})
+        elif tag == "delete":
+            ops.append({"op": "delete", "text": ref_chunk})
+        elif tag == "replace":
+            ops.append({"op": "replace", "old": ref_chunk, "new": hyp_chunk})
+
+    return ops
+
+
+def compute_char_diff(reference: str, hypothesis: str) -> list[dict[str, Any]]:
+    """Diff caractère par caractère — utile pour les tokens courts."""
+    matcher = difflib.SequenceMatcher(None, list(reference), list(hypothesis), autojunk=False)
+    ops: list[dict[str, Any]] = []
+
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        ref_chunk = reference[i1:i2]
+        hyp_chunk = hypothesis[j1:j2]
+        if tag == "equal":
+            ops.append({"op": "equal", "text": ref_chunk})
+        elif tag == "insert":
+            ops.append({"op": "insert", "text": hyp_chunk})
+        elif tag == "delete":
+            ops.append({"op": "delete", "text": ref_chunk})
+        elif tag == "replace":
+            ops.append({"op": "replace", "old": ref_chunk, "new": hyp_chunk})
+
+    return ops
+
+
+def diff_stats(ops: list[dict[str, Any]]) -> dict[str, int]:
+    """Compte le nombre d'insertions, suppressions et substitutions."""
+    stats = {"equal": 0, "insert": 0, "delete": 0, "replace": 0}
+    for op in ops:
+        stats[op["op"]] += 1
+    return stats

picarones/core/facts.py

@@ -100,6 +100,15 @@ class FactType(str, Enum):
     (régression progressive), soit change-point avec delta >
     seuil (rupture brutale)."""
 
+    IMPORTER_FALLBACK_TRIGGERED = "importer_fallback_triggered"
+    """Un import distant (HuggingFace, HTR-United, Gallica, eScriptorium…)
+    a échoué ou a basculé en mode dégradé pendant la constitution du
+    corpus (Sprint A3, item B-3).  Le moteur narratif lit
+    ``picarones.extras.importers.consume_fallback_log()`` qui retourne
+    et **vide** la liste des incidents accumulés depuis le dernier
+    benchmark.  Un Fact par incident, importance MEDIUM (HIGH si
+    plusieurs incidents sur le même importer)."""
+
 
 class FactImportance(int, Enum):
     """Score d'importance d'un fait — décide l'ordre et la sélection."""

picarones/core/pipeline.py

@@ -57,25 +57,13 @@ from picarones.core.corpus import Document, GTLevel
 from picarones.core.metric_registry import compute_at_junction
 from picarones.core.modules import ArtifactType, BaseModule
 
-# Eager-load des modules qui enregistrent des métriques dans le
-# registre typé (Sprint 34) — sans ces imports, ``compute_at_junction``
-# trouverait un registre vide et ne calculerait rien aux jonctions.
-# Sprint 34 : cer / wer / mer / wil + stub TEXT→ALTO
-import picarones.measurements.builtin_metrics  # noqa: F401
-# Sprints 55-60 : métriques philologiques.
-import picarones.measurements.unicode_blocks  # noqa: F401
-import picarones.measurements.abbreviations  # noqa: F401
-import picarones.measurements.mufi  # noqa: F401
-import picarones.measurements.early_modern_typography  # noqa: F401
-import picarones.measurements.modern_archives  # noqa: F401
-import picarones.measurements.roman_numerals  # noqa: F401
-# Sprint 53 : reading order F1.  Sprints 38, 52 : NER, readability.
-import picarones.measurements.reading_order  # noqa: F401
-import picarones.measurements.readability  # noqa: F401
-import picarones.measurements.ner  # noqa: F401
-# Chantier 1 (post-Sprint 97) : métriques (ALTO, ALTO) pour évaluer
-# les reconstructeurs ALTO contre une GT ALTO du document.
-import picarones.measurements.alto_metrics  # noqa: F401
+# Sprint A3 (renforce la règle Cercle 1 → Cercle 1 uniquement) — la
+# cérémonie d'eager-load des métriques typées (Sprint 34) qui vivait
+# ici a été déplacée dans ``picarones/measurements/__init__.py``. Tout
+# consommateur de ``compute_at_junction`` (typiquement la classe
+# ``PipelineRunner`` ci-dessous) doit avoir importé
+# ``picarones.measurements`` au moins une fois — c'est le cas dans
+# l'API publique via ``picarones.__init__`` qui déclenche le trigger.
 
 logger = logging.getLogger(__name__)
 

picarones/extras/importers/__init__.py

@@ -30,6 +30,12 @@ from picarones.extras.importers.escriptorium import (
     EScriptoriumDocument,
     connect_escriptorium,
 )
+from picarones.extras.importers._fallback_log import (
+    consume_fallback_log,
+    peek_fallback_log,
+    record_fallback,
+    reset_fallback_log,
+)
 
 __all__ = [
     "IIIFImporter",
@@ -42,4 +48,9 @@ __all__ = [
     "EScriptoriumProject",
     "EScriptoriumDocument",
     "connect_escriptorium",
+    # Sprint A3 (B-3) — journal des fallbacks d'importer
+    "record_fallback",
+    "consume_fallback_log",
+    "peek_fallback_log",
+    "reset_fallback_log",
 ]

picarones/extras/importers/_fallback_log.py

@@ -0,0 +1,98 @@
+"""Journal en mémoire des fallbacks d'importer (Sprint A3, item B-3).
+
+Quand un importer (HuggingFace, HTR-United, Gallica, eScriptorium…)
+bascule en mode dégradé (timeout réseau, JSON mal formé, ZIP corrompu,
+catalogue distant indisponible…), il enregistre un incident ici via
+:func:`record_fallback`. Le moteur narratif consomme ces incidents via
+:func:`consume_fallback_log`, qui **vide** la liste pour qu'un benchmark
+suivant ne remonte pas les incidents du précédent.
+
+Conception volontairement minimale :
+
+- Pas de persistance disque (les incidents sont contextuels à un run).
+- Pas de structure complexe (juste un ``list[dict]`` thread-safe).
+- Le runner / le rapport peuvent ignorer la liste sans casser.
+
+Le détecteur de Fact correspondant (``FactType.IMPORTER_FALLBACK_TRIGGERED``)
+est implémenté dans
+:mod:`picarones.measurements.narrative.detectors.history`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+_fallbacks: list[dict[str, Any]] = []
+
+
+def record_fallback(
+    importer: str,
+    operation: str,
+    error: BaseException | None = None,
+    *,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Enregistre un incident de mode dégradé.
+
+    Logge également via ``logger.warning`` pour qu'un opérateur voit
+    l'incident en temps réel sans dépendre du rapport.
+
+    Parameters
+    ----------
+    importer:
+        Nom court de l'importer (ex : ``"huggingface"``, ``"htr_united"``).
+    operation:
+        Description courte de l'opération (ex : ``"yaml_catalogue_parse"``,
+        ``"image_save"``, ``"hub_search"``).
+    error:
+        Exception originelle (utilisée pour le message log et stockée dans
+        le payload sous forme de chaîne — pas l'objet, pour éviter les
+        références persistantes).
+    extra:
+        Champs additionnels (URL distante, identifiant dataset…) qui peuvent
+        être utiles à un détecteur de Fact ultérieur.
+    """
+    error_repr = repr(error) if error is not None else None
+    logger.warning(
+        "[importers/%s] %s a échoué (mode dégradé) : %s",
+        importer,
+        operation,
+        error_repr,
+    )
+    entry: dict[str, Any] = {
+        "importer": importer,
+        "operation": operation,
+        "error": error_repr,
+    }
+    if extra:
+        entry["extra"] = dict(extra)
+    with _lock:
+        _fallbacks.append(entry)
+
+
+def consume_fallback_log() -> list[dict[str, Any]]:
+    """Retourne ET vide la liste des incidents accumulés.
+
+    Le moteur narratif appelle cette fonction au moment de construire
+    la synthèse pour transformer chaque incident en ``Fact``."""
+    with _lock:
+        out = list(_fallbacks)
+        _fallbacks.clear()
+    return out
+
+
+def peek_fallback_log() -> list[dict[str, Any]]:
+    """Retourne une copie sans vider — utile pour les tests."""
+    with _lock:
+        return list(_fallbacks)
+
+
+def reset_fallback_log() -> None:
+    """Vide la liste sans rien retourner — utile pour les fixtures pytest."""
+    with _lock:
+        _fallbacks.clear()

picarones/extras/importers/htr_united.py

@@ -428,7 +428,17 @@ def _try_download_corpus(
                     dest = output_path / Path(fname).name
                     dest.write_bytes(zf.read(fname))
                 return len(gt_files)
-    except Exception:
+    except Exception as exc:  # noqa: BLE001 — large surface (réseau, ZIP, FS)
+        # Sprint A3 (B-3) : on documente l'incident plutôt que de le
+        # masquer ; le caller reçoit toujours 0 pour préserver le
+        # contrat numérique de retour.
+        from picarones.extras.importers._fallback_log import record_fallback
+        record_fallback(
+            importer="htr_united",
+            operation="download_zip_samples",
+            error=exc,
+            extra={"output_path": str(output_path)},
+        )
         return 0
 
 
@@ -445,8 +455,16 @@ def _parse_yml_catalogue(raw: str) -> list[HTRUnitedEntry]:
         data = yaml.safe_load(raw)
         if isinstance(data, list):
             return [HTRUnitedEntry.from_dict(d) for d in data if isinstance(d, dict)]
-    except Exception:
-        pass
+    except Exception as exc:  # noqa: BLE001 — yaml + parsing user-supplied
+        # Sprint A3 (B-3) : un YAML mal formé bascule en mode démo
+        # sans que l'utilisateur en soit averti — on logge et on émet
+        # un Fact pour que la synthèse du rapport mentionne l'incident.
+        from picarones.extras.importers._fallback_log import record_fallback
+        record_fallback(
+            importer="htr_united",
+            operation="yaml_catalogue_parse",
+            error=exc,
+        )
     return [HTRUnitedEntry.from_dict(d) for d in _DEMO_CATALOGUE]
 
 

picarones/extras/importers/huggingface.py

@@ -263,8 +263,17 @@ class HuggingFaceImporter:
                 if ds.dataset_id not in existing_ids:
                     results.append(ds)
                     existing_ids.add(ds.dataset_id)
-        except Exception:
-            pass
+        except Exception as exc:  # noqa: BLE001 — réseau/API tierce
+            # Sprint A3 (B-3) : la recherche API échoue silencieusement →
+            # l'utilisateur ne voit que les datasets de référence et croit
+            # que l'API est vide. On documente l'incident.
+            from picarones.extras.importers._fallback_log import record_fallback
+            record_fallback(
+                importer="huggingface",
+                operation="hub_search_api",
+                error=exc,
+                extra={"query": query, "language": language, "limit": limit},
+            )
 
         return results[:limit]
 
@@ -413,8 +422,18 @@ def _try_import_with_datasets_lib(
                 img_file = output_path / f"doc_{i:04d}.jpg"
                 try:
                     image.save(str(img_file))
-                except Exception:
-                    pass
+                except Exception as exc:  # noqa: BLE001 — PIL/PIL-IO
+                    # Sprint A3 (B-3) : un échec de sauvegarde d'image
+                    # produirait un GT orphelin (texte sans image). On
+                    # documente et on continue — le GT est tout de même
+                    # écrit pour préserver la cohérence numérique du compteur.
+                    from picarones.extras.importers._fallback_log import record_fallback
+                    record_fallback(
+                        importer="huggingface",
+                        operation="image_save",
+                        error=exc,
+                        extra={"img_file": str(img_file), "doc_index": i},
+                    )
 
             gt_file = output_path / f"doc_{i:04d}.gt.txt"
             gt_file.write_text(str(text), encoding="utf-8")

picarones/measurements/__init__.py

@@ -117,3 +117,37 @@ Moteur narratif :
 Voir :doc:`docs/architecture.md` pour la cartographie complète et
 la règle de dépendance des 3 cercles.
 """
+
+# ──────────────────────────────────────────────────────────────────────────
+# Sprint A3 (renforce le respect de la règle Cercle 2 → Cercle 1
+# uniquement) — la cérémonie d'enregistrement des métriques typées dans
+# le registre Sprint 34 a été déplacée ici depuis ``core/pipeline.py``
+# qui violait la règle.
+#
+# Tout consommateur qui veut utiliser ``compute_at_junction``
+# (``picarones.core.metric_registry``) doit avoir importé
+# ``picarones.measurements`` au moins une fois pour que les décorateurs
+# ``@register_metric`` aient été exécutés. C'est le cas par défaut dans
+# le pipeline standard ; les notebooks isolés peuvent ajouter
+# ``import picarones.measurements`` (suivi d'un commentaire d'exception
+# ruff sur la ligne d'import si leur linter signale un import inutilisé).
+#
+# Sans ces imports, ``compute_at_junction`` trouverait un registre vide
+# et ne calculerait rien aux jonctions.
+# ──────────────────────────────────────────────────────────────────────────
+# Sprint 34 : cer / wer / mer / wil + stub TEXT→ALTO
+from picarones.measurements import builtin_metrics  # noqa: F401
+# Sprints 55-60 : métriques philologiques.
+from picarones.measurements import abbreviations  # noqa: F401
+from picarones.measurements import early_modern_typography  # noqa: F401
+from picarones.measurements import modern_archives  # noqa: F401
+from picarones.measurements import mufi  # noqa: F401
+from picarones.measurements import roman_numerals  # noqa: F401
+from picarones.measurements import unicode_blocks  # noqa: F401
+# Sprint 53 : reading order F1.  Sprints 38, 52 : NER, readability.
+from picarones.measurements import ner  # noqa: F401
+from picarones.measurements import readability  # noqa: F401
+from picarones.measurements import reading_order  # noqa: F401
+# Chantier 1 (post-Sprint 97) : métriques (ALTO, ALTO) pour évaluer
+# les reconstructeurs ALTO contre une GT ALTO du document.
+from picarones.measurements import alto_metrics  # noqa: F401

picarones/measurements/difficulty.py

@@ -190,13 +190,6 @@ def difficulty_label(score: float) -> str:
     return "Très difficile"
 
 
-def difficulty_color(score: float) -> str:
-    """Retourne une couleur CSS pour un score de difficulté."""
-    from picarones.report.colors import COLOR_GREEN, COLOR_YELLOW, COLOR_ORANGE, COLOR_RED
-    if score < 0.25:
-        return COLOR_GREEN
-    if score < 0.50:
-        return COLOR_YELLOW
-    if score < 0.75:
-        return COLOR_ORANGE
-    return COLOR_RED
+# Sprint A3 (B-2) : ``difficulty_color`` a été déplacée dans
+# :mod:`picarones.report.difficulty_render` pour respecter la règle
+# Cercle 2 → Cercle 1 uniquement. Ce module reste purement numérique.

picarones/measurements/narrative/arbiter.py

@@ -83,6 +83,11 @@ _FALLBACK_TYPE_ORDER: tuple[FactType, ...] = (
     # caractérisant la tendance : l'écart courant est-il une
     # dégradation graduelle, une rupture brutale, ou un bruit ?
     FactType.REGRESSION_IN_HISTORY,
+    # Sprint A3 — priority 180, en queue.  Les incidents d'importer
+    # sont contextuels à l'acquisition de données (non au ranking) ;
+    # ils viennent en toute fin de synthèse comme avertissement sur
+    # la qualité du corpus.
+    FactType.IMPORTER_FALLBACK_TRIGGERED,
 )
 
 

picarones/measurements/narrative/detectors/__init__.py

@@ -61,6 +61,7 @@ from picarones.measurements.narrative.detectors.quality import (
 from picarones.measurements.narrative.detectors.history import (
     detect_engine_off_baseline,
     detect_engine_unstable,
+    detect_importer_fallback,
     detect_regression_in_history,
 )
 from picarones.measurements.narrative.detectors.ensemble import (
@@ -120,6 +121,7 @@ __all__ = [
     # history
     "detect_engine_off_baseline",
     "detect_engine_unstable",
+    "detect_importer_fallback",
     "detect_regression_in_history",
     # ensemble
     "detect_ensemble_opportunity",

picarones/measurements/narrative/detectors/history.py

@@ -271,3 +271,67 @@ def detect_regression_in_history(benchmark_data: dict) -> list[Fact]:
             engines_involved=(engine,),
         ))
     return facts
+
+
+# ---------------------------------------------------------------------------
+# Sprint A3 (item B-3) — détecteur IMPORTER_FALLBACK_TRIGGERED
+# ---------------------------------------------------------------------------
+
+
+@register_detector(
+    FactType.IMPORTER_FALLBACK_TRIGGERED,
+    # Priorité 180 — en queue, après les détecteurs de tendance historique.
+    # L'incident d'importer est *informationnel sur l'acquisition*, pas
+    # sur le ranking ou la performance d'un moteur — il vient logiquement
+    # après tout le reste de la synthèse.
+    priority=180,
+    importance=FactImportance.MEDIUM,
+)
+def detect_importer_fallback(benchmark_data: dict) -> list[Fact]:
+    """Émet un Fact par incident d'importer en mode dégradé.
+
+    Lit ``benchmark_data["importer_fallbacks"]`` (liste de dicts
+    produite par ``picarones.extras.importers.consume_fallback_log()``).
+    Si la clé est absente ou vide, le détecteur reste silencieux —
+    typiquement le cas pour un benchmark qui n'utilise pas d'importer
+    distant (corpus local).
+
+    Importance HIGH si **plusieurs incidents** sur le même importer
+    (signal d'une indisponibilité prolongée plutôt qu'un échec
+    isolé) ; MEDIUM sinon.
+    """
+    fallbacks = benchmark_data.get("importer_fallbacks") or []
+    if not fallbacks:
+        return []
+
+    # Compte par importer pour détecter les incidents répétés.
+    counts: dict[str, int] = {}
+    for entry in fallbacks:
+        if isinstance(entry, dict):
+            counts[str(entry.get("importer", "unknown"))] = (
+                counts.get(str(entry.get("importer", "unknown")), 0) + 1
+            )
+
+    facts: list[Fact] = []
+    for entry in fallbacks:
+        if not isinstance(entry, dict):
+            continue
+        importer = str(entry.get("importer", "unknown"))
+        operation = str(entry.get("operation", "unknown"))
+        importance = (
+            FactImportance.HIGH if counts.get(importer, 0) >= 2 else FactImportance.MEDIUM
+        )
+        payload: dict = {
+            "importer": importer,
+            "operation": operation,
+            "incidents_for_importer": counts.get(importer, 1),
+        }
+        if entry.get("error"):
+            payload["error_repr"] = str(entry["error"])
+        facts.append(Fact(
+            type=FactType.IMPORTER_FALLBACK_TRIGGERED,
+            importance=importance,
+            payload=payload,
+            engines_involved=(),
+        ))
+    return facts

picarones/measurements/narrative/templates/en.yaml

@@ -94,3 +94,11 @@ regression_in_history: >-
   moved from {first_cer_pct} % to {last_cer_pct} %
   (cumulative change {absolute_delta_pct} points). Investigate what
   changed in the pipeline or the models.
+
+# Sprint A3 (item B-3) — importer fallback incidents.
+# The payload contains `importer`, `operation` and `incidents_for_importer`.
+importer_fallback_triggered: >-
+  The "{importer}" importer fell back to degraded mode during the
+  "{operation}" operation ({incidents_for_importer} incident(s) this
+  run). Imported data may be incomplete or from a fallback — check
+  the logs for details.

picarones/measurements/narrative/templates/fr.yaml

@@ -99,3 +99,11 @@ regression_in_history: >-
   est passé de {first_cer_pct} % à {last_cer_pct} %
   (variation cumulée {absolute_delta_pct} points). Vérifier ce qui
   a changé dans le pipeline ou les modèles.
+
+# Sprint A3 (item B-3) — incidents d'importer en mode dégradé.
+# Le payload contient `importer`, `operation` et `incidents_for_importer`.
+importer_fallback_triggered: >-
+  L'importer « {importer} » a basculé en mode dégradé pendant l'opération
+  « {operation} » ({incidents_for_importer} incident·s sur ce run). Les
+  données importées peuvent être incomplètes ou issues d'un fallback —
+  consulter les logs pour le détail.

picarones/measurements/statistics.py

@@ -858,7 +858,8 @@ _ERROR_PATTERNS = [
 
 def _extract_error_pairs(gt: str, hyp: str) -> list[tuple[str, str]]:
     """Extrait les paires (gt_char_seq, hyp_char_seq) d'erreurs de substitution."""
-    from picarones.report.diff_utils import compute_word_diff
+    # Sprint A3 (B-1) : import depuis Cercle 1, plus de violation Cercle 2→3.
+    from picarones.core.diff_utils import compute_word_diff
     ops = compute_word_diff(gt, hyp)
     pairs = []
     for op in ops:

picarones/report/diff_utils.py

@@ -1,89 +1,26 @@
-"""Calcul du diff mot-à-mot entre vérité terrain et sortie OCR.
+"""Ré-export rétrocompat — la canonique est :mod:`picarones.core.diff_utils`.
 
-Produit une liste d'opérations sérialisables en JSON, consommée
-par le rendu JS dans le rapport HTML.
+Sprint A3 (item B-1 de l'audit institutional-readiness-2026-05) :
+``compute_word_diff`` et consorts ont été déplacés dans Cercle 1 pour
+respecter la règle de dépendance (Cercle 2 → Cercle 1 uniquement).
 
-Opérations possibles
---------------------
-{"op": "equal",   "text": "mot"}
-{"op": "insert",  "text": "mot"}    -- présent dans l'OCR mais pas dans la GT
-{"op": "delete",  "text": "mot"}    -- présent dans la GT mais pas dans l'OCR
-{"op": "replace", "old": "…", "new": "…"}  -- substitution (orange)
+Ce module reste pour les consommateurs externes existants (scripts,
+notebooks, plug-ins). Suppression planifiée v1.3.0.
 """
 
 from __future__ import annotations
 
-import difflib
-import re
-from typing import Any
+import warnings as _warnings
 
+from picarones.core.diff_utils import (  # noqa: F401
+    compute_char_diff,
+    compute_word_diff,
+    diff_stats,
+)
 
-def _tokenize(text: str) -> list[str]:
-    """Découpe le texte en tokens (mots + ponctuation + espaces)."""
-    # Conserver les espaces comme tokens pour un rendu fidèle
-    return re.split(r"(\s+)", text)
-
-
-def compute_word_diff(reference: str, hypothesis: str) -> list[dict[str, Any]]:
-    """Calcule un diff mot-à-mot entre deux textes.
-
-    Parameters
-    ----------
-    reference:
-        Texte de vérité terrain.
-    hypothesis:
-        Texte produit par le moteur OCR.
-
-    Returns
-    -------
-    list of dict
-        Séquence d'opérations : equal, insert, delete, replace.
-    """
-    ref_tokens = reference.split()
-    hyp_tokens = hypothesis.split()
-
-    matcher = difflib.SequenceMatcher(None, ref_tokens, hyp_tokens, autojunk=False)
-    ops: list[dict[str, Any]] = []
-
-    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
-        ref_chunk = " ".join(ref_tokens[i1:i2])
-        hyp_chunk = " ".join(hyp_tokens[j1:j2])
-
-        if tag == "equal":
-            ops.append({"op": "equal", "text": ref_chunk})
-        elif tag == "insert":
-            ops.append({"op": "insert", "text": hyp_chunk})
-        elif tag == "delete":
-            ops.append({"op": "delete", "text": ref_chunk})
-        elif tag == "replace":
-            ops.append({"op": "replace", "old": ref_chunk, "new": hyp_chunk})
-
-    return ops
-
-
-def compute_char_diff(reference: str, hypothesis: str) -> list[dict[str, Any]]:
-    """Diff caractère par caractère — utile pour les tokens courts."""
-    matcher = difflib.SequenceMatcher(None, list(reference), list(hypothesis), autojunk=False)
-    ops: list[dict[str, Any]] = []
-
-    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
-        ref_chunk = reference[i1:i2]
-        hyp_chunk = hypothesis[j1:j2]
-        if tag == "equal":
-            ops.append({"op": "equal", "text": ref_chunk})
-        elif tag == "insert":
-            ops.append({"op": "insert", "text": hyp_chunk})
-        elif tag == "delete":
-            ops.append({"op": "delete", "text": ref_chunk})
-        elif tag == "replace":
-            ops.append({"op": "replace", "old": ref_chunk, "new": hyp_chunk})
-
-    return ops
-
-
-def diff_stats(ops: list[dict[str, Any]]) -> dict[str, int]:
-    """Compte le nombre d'insertions, suppressions et substitutions."""
-    stats = {"equal": 0, "insert": 0, "delete": 0, "replace": 0}
-    for op in ops:
-        stats[op["op"]] += 1
-    return stats
+_warnings.warn(
+    "picarones.report.diff_utils est déprécié — utiliser "
+    "picarones.core.diff_utils. Ce ré-export sera retiré en v1.3.0.",
+    DeprecationWarning,
+    stacklevel=2,
+)

picarones/report/difficulty_render.py

@@ -0,0 +1,45 @@
+"""Helpers de rendu pour le score de difficulté intrinsèque.
+
+Sprint A3 (item B-2 de l'audit institutional-readiness-2026-05) :
+``difficulty_color`` vivait précédemment dans
+``picarones/measurements/difficulty.py`` et y violait la règle
+Cercle 2 → Cercle 3 par un import paresseux de
+``picarones.report.colors``. La fonction est désormais placée à sa
+juste place — Cercle 3, à côté de la palette qu'elle consomme — et
+``measurements/difficulty.py`` ne contient plus que de la logique
+purement numérique.
+
+Le module pur ``picarones.measurements.difficulty`` reste utilisable
+sans dépendance vers ``picarones.report``.
+"""
+
+from __future__ import annotations
+
+from picarones.report.colors import (
+    COLOR_GREEN,
+    COLOR_ORANGE,
+    COLOR_RED,
+    COLOR_YELLOW,
+)
+
+
+def difficulty_color(score: float) -> str:
+    """Retourne une couleur CSS pour un score de difficulté ∈ [0, 1].
+
+    Convention :
+
+    - score < 0.25  → vert      (« facile »)
+    - score < 0.50  → jaune     (« modéré »)
+    - score < 0.75  → orange    (« difficile »)
+    - score ≥ 0.75  → rouge     (« très difficile »)
+
+    Le label texte correspondant est produit par
+    :func:`picarones.measurements.difficulty.difficulty_label`.
+    """
+    if score < 0.25:
+        return COLOR_GREEN
+    if score < 0.50:
+        return COLOR_YELLOW
+    if score < 0.75:
+        return COLOR_ORANGE
+    return COLOR_RED

picarones/report/generator.py

@@ -36,7 +36,7 @@ def _load_vendor_js(name: str) -> str:
     return f"/* vendor/{name} non trouvé */"
 
 from picarones.core.results import BenchmarkResult
-from picarones.report.diff_utils import compute_char_diff, compute_word_diff
+from picarones.core.diff_utils import compute_char_diff, compute_word_diff
 from picarones.measurements.statistics import (
     compute_pairwise_stats,
     compute_reliability_curve,

picarones/report/worst_lines_render.py

@@ -19,7 +19,7 @@ from html import escape as _e
 from typing import Optional
 
 from picarones.measurements.worst_lines import WorstLineEntry
-from picarones.report.diff_utils import compute_char_diff
+from picarones.core.diff_utils import compute_char_diff
 
 
 def _color_for_cer(cer: float) -> str:

tests/core/test_circle_dependencies.py

@@ -0,0 +1,260 @@
+"""Garde-fou architectural — direction des dépendances entre cercles.
+
+Sprint A3 du plan de remédiation institutionnelle (renforce B-1, B-2,
+B-3 contre toute régression future).
+
+L'architecture en 3 cercles documentée dans
+:doc:`docs/architecture.md` impose que les imports aillent **uniquement**
+de l'extérieur vers l'intérieur :
+
+::
+
+    Cercle 3 (extras, report, cli, web)
+       │
+       ▼
+    Cercle 2 (measurements, engines, llm, pipelines, modules)
+       │
+       ▼
+    Cercle 1 (core)
+
+Ce module parse l'AST de tous les fichiers ``.py`` dans Cercles 1 et 2
+et **échoue** dès qu'un import remontant vers un cercle plus extérieur
+est détecté. Le test couvre :
+
+- Imports top-level (``from picarones.report import …``).
+- Imports paresseux à l'intérieur des fonctions (le piège classique
+  qui a permis la naissance de B-1 et B-2).
+- ``import picarones.report.X`` au format module (en plus de
+  ``from picarones.report.X import ...``).
+
+Mécanismes d'exception : aucun. Toute violation doit être corrigée en
+remontant le code à un cercle approprié, **pas** ajoutée à une
+liste d'exceptions.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PICARONES_ROOT = REPO_ROOT / "picarones"
+
+
+# ---------------------------------------------------------------------------
+# Cartographie des cercles
+# ---------------------------------------------------------------------------
+
+#: Modules de Cercle 1 (abstractions pures).
+CIRCLE_1_PREFIXES: frozenset[str] = frozenset({"picarones.core"})
+
+#: Modules de Cercle 2 (logique métier).
+CIRCLE_2_PREFIXES: frozenset[str] = frozenset(
+    {
+        "picarones.measurements",
+        "picarones.engines",
+        "picarones.llm",
+        "picarones.pipelines",
+        "picarones.modules",
+    }
+)
+
+#: Modules de Cercle 3 (entrées, plugins, rendu).
+CIRCLE_3_PREFIXES: frozenset[str] = frozenset(
+    {
+        "picarones.report",
+        "picarones.cli",
+        "picarones.web",
+        "picarones.extras",
+    }
+)
+
+
+def _circle_of(module_dotted: str) -> int:
+    """Retourne 1, 2, 3 ou 0 (hors-package) pour un nom de module."""
+    if not module_dotted.startswith("picarones"):
+        return 0
+    if any(module_dotted == p or module_dotted.startswith(p + ".") for p in CIRCLE_1_PREFIXES):
+        return 1
+    if any(module_dotted == p or module_dotted.startswith(p + ".") for p in CIRCLE_2_PREFIXES):
+        return 2
+    if any(module_dotted == p or module_dotted.startswith(p + ".") for p in CIRCLE_3_PREFIXES):
+        return 3
+    return 0
+
+
+def _file_to_module(path: Path) -> str:
+    """Convertit ``picarones/measurements/runner.py`` en
+    ``picarones.measurements.runner``."""
+    rel = path.relative_to(REPO_ROOT)
+    parts = rel.with_suffix("").parts
+    # Supprime ``__init__`` final
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Extraction des imports via AST
+# ---------------------------------------------------------------------------
+
+
+def _walk_imports(source: str) -> Iterator[tuple[str, int]]:
+    """Yield ``(module_dotted, lineno)`` pour chaque import du fichier,
+    qu'il soit top-level ou paresseux dans une fonction.
+
+    Capture :
+
+    - ``import picarones.report.X``        → ``picarones.report.X``
+    - ``from picarones.report.X import Y`` → ``picarones.report.X``
+    - ``from picarones.report import X``   → ``picarones.report.X`` (Y ignoré
+      pour la classification de cercle, mais le préfixe importe).
+    """
+    tree = ast.parse(source)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield alias.name, node.lineno
+        elif isinstance(node, ast.ImportFrom):
+            if node.level != 0:
+                # Imports relatifs ne franchissent jamais de cercle.
+                continue
+            if node.module is None:
+                continue
+            yield node.module, node.lineno
+
+
+# ---------------------------------------------------------------------------
+# Collecte des fichiers à auditer
+# ---------------------------------------------------------------------------
+
+
+def _python_files_in(*subpaths: str) -> list[Path]:
+    out: list[Path] = []
+    for sub in subpaths:
+        d = PICARONES_ROOT / sub
+        if not d.exists():
+            continue
+        out.extend(p for p in d.rglob("*.py") if "__pycache__" not in p.parts)
+    return sorted(out)
+
+
+CIRCLE_1_FILES = _python_files_in("core")
+CIRCLE_2_FILES = _python_files_in(
+    "measurements", "engines", "llm", "pipelines", "modules"
+)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("path", CIRCLE_1_FILES, ids=lambda p: str(p.relative_to(REPO_ROOT)))
+def test_circle_1_no_outer_import(path: Path) -> None:
+    """Aucun fichier de Cercle 1 ne doit importer Cercle 2 ou 3."""
+    source = path.read_text(encoding="utf-8")
+    own_module = _file_to_module(path)
+    violations: list[tuple[str, int]] = []
+    for imported, lineno in _walk_imports(source):
+        # Ignorer les imports vers le module lui-même
+        if imported == own_module:
+            continue
+        circle = _circle_of(imported)
+        if circle in (2, 3):
+            violations.append((imported, lineno))
+    assert not violations, (
+        f"{path.relative_to(REPO_ROOT)} (Cercle 1) importe vers un cercle "
+        f"plus extérieur — violation de la règle d'architecture :\n"
+        + "\n".join(f"  ligne {ln}: import {mod}" for mod, ln in violations)
+    )
+
+
+@pytest.mark.parametrize("path", CIRCLE_2_FILES, ids=lambda p: str(p.relative_to(REPO_ROOT)))
+def test_circle_2_no_outer_import(path: Path) -> None:
+    """Aucun fichier de Cercle 2 ne doit importer Cercle 3.
+
+    Cercle 2 → Cercle 1 reste autorisé (et même attendu pour les
+    abstractions partagées). Cercle 2 → Cercle 2 (entre sous-packages
+    measurements/engines/llm/…) est aussi autorisé."""
+    source = path.read_text(encoding="utf-8")
+    own_module = _file_to_module(path)
+    violations: list[tuple[str, int]] = []
+    for imported, lineno in _walk_imports(source):
+        if imported == own_module:
+            continue
+        circle = _circle_of(imported)
+        if circle == 3:
+            violations.append((imported, lineno))
+    assert not violations, (
+        f"{path.relative_to(REPO_ROOT)} (Cercle 2) importe vers Cercle 3 — "
+        f"violation de la règle d'architecture :\n"
+        + "\n".join(f"  ligne {ln}: import {mod}" for mod, ln in violations)
+        + "\n\nFix: déplacer la logique réutilisable dans Cercle 1, "
+        "ou refactorer pour que la dépendance s'inverse."
+    )
+
+
+def test_no_circle_1_file_imports_circle_3() -> None:
+    """Méta-test : énumère explicitement les violations Cercle 1 → 3.
+
+    Permet d'avoir un seul échec global lisible si la regex de
+    parametrize masque le compte total."""
+    total_violations: list[str] = []
+    for path in CIRCLE_1_FILES:
+        source = path.read_text(encoding="utf-8")
+        for imported, lineno in _walk_imports(source):
+            if _circle_of(imported) in (2, 3):
+                total_violations.append(
+                    f"{path.relative_to(REPO_ROOT)}:{lineno} → {imported}"
+                )
+    assert not total_violations, (
+        f"{len(total_violations)} violation(s) totales Cercle 1 → extérieur :\n"
+        + "\n".join(total_violations)
+    )
+
+
+def test_no_circle_2_file_imports_circle_3() -> None:
+    """Méta-test : énumère explicitement les violations Cercle 2 → 3."""
+    total_violations: list[str] = []
+    for path in CIRCLE_2_FILES:
+        source = path.read_text(encoding="utf-8")
+        for imported, lineno in _walk_imports(source):
+            if _circle_of(imported) == 3:
+                total_violations.append(
+                    f"{path.relative_to(REPO_ROOT)}:{lineno} → {imported}"
+                )
+    assert not total_violations, (
+        f"{len(total_violations)} violation(s) totales Cercle 2 → 3 :\n"
+        + "\n".join(total_violations)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Sanité
+# ---------------------------------------------------------------------------
+
+
+def test_circles_are_not_empty() -> None:
+    """Pré-requis : les listes de fichiers ne doivent pas être vides
+    (sinon les paramétrisations ne couvrent rien)."""
+    assert CIRCLE_1_FILES, "Cercle 1 vide — chemin core/ introuvable."
+    assert CIRCLE_2_FILES, "Cercle 2 vide — au moins un sous-package attendu."
+
+
+def test_circle_classification_examples() -> None:
+    """Tests d'auto-validation de ``_circle_of``."""
+    assert _circle_of("picarones.core.corpus") == 1
+    assert _circle_of("picarones.core.diff_utils") == 1
+    assert _circle_of("picarones.measurements.runner") == 2
+    assert _circle_of("picarones.engines.tesseract") == 2
+    assert _circle_of("picarones.report.generator") == 3
+    assert _circle_of("picarones.cli") == 3
+    assert _circle_of("picarones.web.app") == 3
+    assert _circle_of("picarones.extras.importers.huggingface") == 3
+    assert _circle_of("numpy") == 0
+    assert _circle_of("picarones") == 0  # le package racine lui-même

tests/{report → core}/test_diff_utils.py

@@ -1,6 +1,6 @@
-"""Tests pour picarones.report.diff_utils."""
+"""Tests pour picarones.core.diff_utils (déplacé depuis report/ en Sprint A3, B-1)."""
 
-from picarones.report.diff_utils import compute_word_diff, compute_char_diff, diff_stats
+from picarones.core.diff_utils import compute_word_diff, compute_char_diff, diff_stats
 
 
 class TestComputeWordDiff:

tests/integration/test_chantier5.py

@@ -48,9 +48,11 @@ class TestDetectorsPackage:
         "detect_engine_unstable",
         "detect_regression_in_history",
         "detect_ensemble_opportunity",
+        # Sprint A3 — détecteur d'incidents d'importer en mode dégradé.
+        "detect_importer_fallback",
     ])
-    def test_all_18_detectors_importable_from_root(self, name):
-        """Rétrocompat : les 18 détecteurs s'importent depuis le package
+    def test_all_19_detectors_importable_from_root(self, name):
+        """Rétrocompat : les 19 détecteurs (18 historiques + Sprint A3) s'importent depuis le package
         comme avant le chantier 5 (tests Sprints 20, 23, 29, 36, 44, 46, 73)."""
         from picarones.measurements.narrative import detectors
         assert hasattr(detectors, name), f"{name} disparu après chantier 5"
@@ -59,8 +61,10 @@ class TestDetectorsPackage:
     def test_DETECTORS_BY_TYPE_still_exposed(self):
         from picarones.measurements.narrative.detectors import DETECTORS_BY_TYPE
         assert isinstance(DETECTORS_BY_TYPE, dict)
-        assert len(DETECTORS_BY_TYPE) == 18, (
-            f"DETECTORS_BY_TYPE doit contenir 18 entrées, en a {len(DETECTORS_BY_TYPE)}"
+        # Sprint A3 — passage de 18 à 19 détecteurs (ajout
+        # IMPORTER_FALLBACK_TRIGGERED).
+        assert len(DETECTORS_BY_TYPE) == 19, (
+            f"DETECTORS_BY_TYPE doit contenir 19 entrées, en a {len(DETECTORS_BY_TYPE)}"
         )
 
     def test_register_default_detectors_still_callable(self):
@@ -72,7 +76,8 @@ class TestDetectorsPackage:
         ("pareto", 2),
         ("stratum", 3),
         ("quality", 4),
-        ("history", 3),
+        # Sprint A3 — history passe de 3 à 4 (ajout detect_importer_fallback).
+        ("history", 4),
         ("ensemble", 1),
     ])
     def test_submodules_have_expected_detector_count(self, submodule, detector_count):