sprint27: snapshots de reproductibilité dans le rapport HTML

Avant Sprint 27
---------------
Le rapport HTML auto-contenu n'embarquait que
``pareto.pricing_meta.last_updated`` — une simple date qui ne disait
rien sur le contenu de la table de prix utilisée. Si quelqu'un
modifiait ``picarones/data/pricing.yaml`` après génération, il était
impossible de reconstituer ce qu'avait vu le lecteur du rapport.
Idem pour le glossaire et le profil de normalisation : aucune trace
dans le HTML produit.

Pour un outil scientifique qui se présente comme « factuel » (cf.
moteur narratif Sprint 19, garde-fou anti-hallucination Sprint 23),
c'est un trou méthodologique : on traçait les *nombres* sans tracer
les *paramètres* qui les produisaient.

Sprint 27 — apport
------------------
Nouveau module ``picarones/report/snapshot.py`` qui expose quatre
fonctions de snapshot pures + une API agrégée ``snapshot_all()``.
Le résultat est embarqué dans ``report_data["snapshots"]`` par
``ReportGenerator.generate()`` :

- **pricing** : YAML brut intégral de ``data/pricing.yaml`` +
dict parsé. Un lecteur peut extraire ``raw_yaml``
et reconstituer exactement la table utilisée.
- **glossary** : entrées du glossaire dans la langue du rapport,
triées par clé pour reproductibilité bit-à-bit.
Filtrage optionnel par ``used_keys``.
- **normalization** : profil sérialisé (``name``, ``nfc``, ``caseless``,
``diplomatic_table``, ``exclude_chars`` triés,
``description``).
- **environment** : version Picarones, version Python, plateforme,
commit git court (12 chars) si dispo, liste
figée des paquets installés (200 max), triée
case-insensitive et dédupliquée par nom.

``schema_version: 1`` ouvert dans le bloc pour les futures évolutions.

``ReportGenerator`` accepte un nouveau paramètre
``normalization_profile=...`` (fallback à
``benchmark.metadata["normalization_profile"]``) pour que le snapshot
soit fidèle au profil effectivement utilisé.

Garanties
---------
- Déterminisme strict sur les sections statiques (pricing, glossary,
normalization). Seul ``environment.git_commit`` peut varier selon
l'état du repo, et c'est documenté.
- Dégradé non bloquant : pricing.yaml absent, pyyaml absent, git
inaccessible → ``{"available": False, "reason": "..."}`` plutôt que
d'exception.
- Aucun effet de bord : lecture seule, aucun chemin écrit, aucun
cache global mutable.

Tests (+23, soit 1377 passing au total)
---------------------------------------

tests/test_sprint27_reproducibility_snapshots.py couvre :

- Snapshot pricing : YAML par défaut chargé, custom YAML round-trip,
fichier absent → unavailable, sections meta et engines exposées.
- Snapshot glossary : fr complet, filtre used_keys, langue inconnue,
entrées triées pour déterminisme.
- Snapshot normalization : profil built-in sérialisé, None →
unavailable, exclude_chars triés.
- Snapshot environment : version Picarones cohérente, python/platform
présents, paquets triés et uniques, git_commit str|None.
- snapshot_all : 4 blocs + schema_version, déterminisme inter-appels.
- Intégration ReportGenerator : bloc snapshots présent dans le HTML,
pricing YAML brut embarqué, environment présent, glossary présent,
nom du profil de normalisation présent, raw_yaml disponible pour
rejouer la table.

Out of scope (reporté)
----------------------
Le mode ``--external-images`` (rapport léger qui externalise les
images dans ``<output>_assets/`` au lieu du base64) n'est pas inclus
ici — il sera traité dans un sous-sprint dédié pour ne pas mélanger
deux préoccupations indépendantes (reproductibilité scientifique vs
poids du rapport).

https://claude.ai/code/session_01L4RGWMrAajn5ZEFgTKjA5P

picarones/report/generator.py

@@ -19,7 +19,7 @@ import base64
 import io
 import json
 from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
 
 # ---------------------------------------------------------------------------
 # Ressources vendor (embarquées dans le rapport HTML)
@@ -618,6 +618,7 @@ class ReportGenerator:
         benchmark: BenchmarkResult,
         images_b64: Optional[dict[str, str]] = None,
         lang: str = "fr",
+        normalization_profile: Any = None,
     ) -> None:
         """
         Parameters
@@ -629,15 +630,25 @@ class ReportGenerator:
             Si None, le générateur cherche dans ``benchmark.metadata["_images_b64"]``.
         lang:
             Code langue du rapport : ``"fr"`` (défaut) ou ``"en"``.
+        normalization_profile:
+            Profil de normalisation effectivement utilisé (Sprint 27 — pour
+            le snapshot de reproductibilité). ``None`` retombe sur le
+            profil mentionné dans ``benchmark.metadata["normalization_profile"]``
+            s'il est présent, sinon snapshot indisponible.
         """
         self.benchmark = benchmark
         self.images_b64: dict[str, str] = images_b64 or {}
         self.lang = lang
+        self.normalization_profile = normalization_profile
 
         # Récupérer les images embarquées dans les metadata (fixtures)
         if not self.images_b64:
             self.images_b64 = benchmark.metadata.get("_images_b64", {})  # type: ignore[assignment]
 
+        # Sprint 27 — fallback : profil de normalisation depuis les metadata
+        if self.normalization_profile is None:
+            self.normalization_profile = benchmark.metadata.get("normalization_profile")
+
     def generate(self, output_path: str | Path) -> Path:
         """Génère le fichier HTML et le sauvegarde sur disque.
 
@@ -663,6 +674,17 @@ class ReportGenerator:
 
         labels = get_labels(self.lang)
         report_data = _build_report_data(self.benchmark, images_b64)
+
+        # Sprint 27 — snapshots de reproductibilité (pricing, glossaire,
+        # profil de normalisation, environnement). Embarqués dans le JSON
+        # du rapport pour qu'un lecteur puisse régénérer la synthèse, le
+        # Pareto et le glossaire sans accès au code source.
+        from picarones.report.snapshot import snapshot_all
+        report_data["snapshots"] = snapshot_all(
+            lang=self.lang,
+            normalization_profile=self.normalization_profile,
+        )
+
         report_json = json.dumps(report_data, ensure_ascii=False, separators=(",", ":"))
         i18n_json = json.dumps(labels, ensure_ascii=False, separators=(",", ":"))
         chartjs_js = _load_vendor_js("chart.umd.min.js")

picarones/report/snapshot.py

@@ -0,0 +1,266 @@
+"""Snapshots de reproductibilité pour le rapport HTML (Sprint 27).
+
+Le rapport HTML auto-contenu doit pouvoir être *rejoué* sans avoir
+accès au code source du moment où il a été généré : un lecteur en
+2026 doit pouvoir comprendre exactement quelle table de prix, quelle
+définition de métrique, quel profil de normalisation, et quelle
+version de Picarones ont produit les chiffres affichés.
+
+Avant le Sprint 27, le rapport intégrait uniquement
+``pareto.pricing_meta.last_updated`` — une simple date de mise à jour
+qui ne disait rien sur le contenu de la table. Si quelqu'un modifiait
+``picarones/data/pricing.yaml`` après génération, il était impossible
+de reconstituer ce qu'avait vu le lecteur du rapport.
+
+Quatre snapshots sont produits par ce module et embarqués dans
+``report_data.snapshots`` :
+
+- ``pricing``       — YAML brut intégral de la table de prix.
+- ``glossary``      — entrées du glossaire pour la langue du rapport.
+- ``normalization`` — profil de normalisation effectivement appliqué.
+- ``environment``   — version Picarones, Python, plateforme, commit git
+                      si dispo, liste figée des dépendances installées.
+
+Garanties
+---------
+- **Déterminisme** : sur entrées identiques, ``snapshot_all()`` produit
+  un dict bit-à-bit identique. Les listes sont triées, les timestamps
+  sont absents.
+- **Pas d'effet de bord** : le module ne modifie aucun état global ;
+  les chemins YAML sont uniquement lus, jamais écrits.
+- **Dégradé non bloquant** : si pyyaml est absent, si ``pricing.yaml``
+  n'existe pas, si git n'est pas installé, le snapshot retourne un
+  dict ``{"available": False, "reason": "..."}`` plutôt que de lever.
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+import subprocess
+import sys
+from importlib.metadata import distributions
+from pathlib import Path
+from typing import Any, Optional
+
+from picarones import __version__
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Pricing snapshot
+# ---------------------------------------------------------------------------
+
+def pricing_snapshot(pricing_path: Optional[Path] = None) -> dict[str, Any]:
+    """Retourne le YAML brut + dict parsé de la table de prix utilisée.
+
+    Si ``pricing_path`` n'est pas fourni, utilise le chemin par défaut
+    de ``picarones.core.pricing._DEFAULT_PRICING_PATH``.
+    """
+    if pricing_path is None:
+        try:
+            from picarones.core.pricing import _DEFAULT_PRICING_PATH
+            pricing_path = _DEFAULT_PRICING_PATH
+        except ImportError:
+            return {"available": False, "reason": "module pricing introuvable"}
+
+    pricing_path = Path(pricing_path)
+    if not pricing_path.exists():
+        return {
+            "available": False,
+            "reason": f"pricing.yaml introuvable : {pricing_path}",
+            "expected_path": str(pricing_path),
+        }
+
+    try:
+        raw = pricing_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return {
+            "available": False,
+            "reason": f"lecture impossible : {exc}",
+            "expected_path": str(pricing_path),
+        }
+
+    try:
+        import yaml
+        data = yaml.safe_load(raw) or {}
+    except (ImportError, Exception) as exc:
+        # Pas de yaml ou parsing en échec — on garde le brut quand même.
+        logger.warning("[snapshot] parsing pricing.yaml échoué : %s", exc)
+        data = {}
+
+    return {
+        "available": True,
+        "source_path": str(pricing_path),
+        "filename": pricing_path.name,
+        "size_bytes": len(raw.encode("utf-8")),
+        "raw_yaml": raw,
+        "data": data,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Glossary snapshot
+# ---------------------------------------------------------------------------
+
+def glossary_snapshot(
+    lang: str = "fr",
+    used_keys: Optional[list[str] | set[str]] = None,
+) -> dict[str, Any]:
+    """Retourne les entrées du glossaire qui figurent dans le rapport.
+
+    ``used_keys`` permet de ne snapshotter que les termes effectivement
+    référencés (réduit la taille). ``None`` → toutes les entrées de la
+    langue (mode conservateur).
+    """
+    try:
+        from picarones.report.glossary import load_glossary, SUPPORTED_LANGS
+    except ImportError:
+        return {"available": False, "reason": "module glossary introuvable"}
+
+    full = load_glossary(lang) or {}
+    if not full:
+        return {
+            "available": False,
+            "reason": f"aucune entrée pour lang={lang!r}",
+            "supported_langs": SUPPORTED_LANGS,
+        }
+
+    if used_keys is not None:
+        keys = set(used_keys)
+        entries = {k: v for k, v in full.items() if k in keys}
+    else:
+        entries = dict(full)
+
+    # Tri pour reproductibilité bit-à-bit.
+    entries_sorted = {k: entries[k] for k in sorted(entries)}
+
+    return {
+        "available": True,
+        "lang": lang,
+        "entry_count": len(entries_sorted),
+        "entries": entries_sorted,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Normalization profile snapshot
+# ---------------------------------------------------------------------------
+
+def normalization_snapshot(profile: Any) -> dict[str, Any]:
+    """Sérialise un ``NormalizationProfile``.
+
+    Couvre les profils built-in (``medieval_french``, ``nfc``, …) et les
+    profils custom YAML chargés au runtime — l'objectif est qu'un
+    lecteur du rapport puisse régénérer exactement la même
+    normalisation à partir de ce snapshot.
+    """
+    if profile is None:
+        return {"available": False, "reason": "aucun profil fourni"}
+
+    # NormalizationProfile est un dataclass — on accède aux champs par
+    # nom plutôt que via ``asdict`` pour bien contrôler le format.
+    try:
+        return {
+            "available": True,
+            "name": getattr(profile, "name", "unknown"),
+            "nfc": bool(getattr(profile, "nfc", True)),
+            "caseless": bool(getattr(profile, "caseless", False)),
+            "diplomatic_table": dict(getattr(profile, "diplomatic_table", {}) or {}),
+            "exclude_chars": sorted(getattr(profile, "exclude_chars", set()) or set()),
+            "description": getattr(profile, "description", ""),
+        }
+    except Exception as exc:
+        return {"available": False, "reason": f"sérialisation échouée : {exc}"}
+
+
+# ---------------------------------------------------------------------------
+# Environment snapshot
+# ---------------------------------------------------------------------------
+
+def _git_commit(repo_path: Optional[Path] = None) -> Optional[str]:
+    """Retourne le commit git court (12 chars) si on est dans un repo, sinon None."""
+    cwd = repo_path or Path(__file__).resolve().parents[2]
+    try:
+        out = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"],
+            cwd=str(cwd),
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=2,
+        ).strip()
+        return out[:12] if out else None
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+
+def _installed_packages(limit: int = 200) -> list[str]:
+    """Liste figée des paquets installés au format ``name==version``.
+
+    Triée par nom (case-insensitive) pour reproductibilité. Cappée à
+    ``limit`` paquets pour ne pas exploser le poids du rapport.
+    """
+    try:
+        pkgs: list[str] = []
+        seen: set[str] = set()
+        for d in distributions():
+            try:
+                name = (d.metadata.get("Name") or "").strip()
+                version = (d.version or "").strip()
+            except Exception:
+                continue
+            if not name or name.lower() in seen:
+                continue
+            seen.add(name.lower())
+            pkgs.append(f"{name}=={version}")
+        pkgs.sort(key=str.lower)
+        return pkgs[:limit]
+    except Exception as exc:  # pragma: no cover — défense en profondeur
+        logger.warning("[snapshot] enum dépendances échoué : %s", exc)
+        return []
+
+
+def environment_snapshot(repo_path: Optional[Path] = None) -> dict[str, Any]:
+    """Retourne version Picarones, Python, plateforme, commit, deps figées."""
+    return {
+        "available": True,
+        "picarones_version": __version__,
+        "python_version": platform.python_version(),
+        "python_implementation": platform.python_implementation(),
+        "platform": platform.platform(),
+        "executable": sys.executable,
+        "git_commit": _git_commit(repo_path),
+        "installed_packages": _installed_packages(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# API agrégée
+# ---------------------------------------------------------------------------
+
+def snapshot_all(
+    *,
+    lang: str = "fr",
+    glossary_used_keys: Optional[list[str] | set[str]] = None,
+    pricing_path: Optional[Path] = None,
+    normalization_profile: Any = None,
+    repo_path: Optional[Path] = None,
+) -> dict[str, Any]:
+    """Construit le bloc ``snapshots`` à embarquer dans ``report_data``."""
+    return {
+        "pricing": pricing_snapshot(pricing_path=pricing_path),
+        "glossary": glossary_snapshot(lang=lang, used_keys=glossary_used_keys),
+        "normalization": normalization_snapshot(normalization_profile),
+        "environment": environment_snapshot(repo_path=repo_path),
+        "schema_version": 1,
+    }
+
+
+__all__ = [
+    "pricing_snapshot",
+    "glossary_snapshot",
+    "normalization_snapshot",
+    "environment_snapshot",
+    "snapshot_all",
+]

tests/test_sprint27_reproducibility_snapshots.py

@@ -0,0 +1,277 @@
+"""Tests Sprint 27 — snapshots de reproductibilité dans le rapport HTML.
+
+Le Sprint 27 ajoute le bloc ``report_data["snapshots"]`` qui embarque
+dans chaque rapport HTML auto-contenu :
+
+  - le YAML brut intégral de ``picarones/data/pricing.yaml`` ;
+  - les entrées du glossaire dans la langue du rapport ;
+  - le profil de normalisation effectivement utilisé ;
+  - la version Picarones, la version Python, la plateforme,
+    le commit git si dispo, et la liste figée des paquets installés.
+
+Le but est qu'un lecteur du rapport puisse rejouer la synthèse, le
+Pareto et le glossaire sans accès au code source du moment où le
+rapport a été généré.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# 1. Fonctions snapshot unitaires
+# ---------------------------------------------------------------------------
+
+class TestPricingSnapshot:
+    def test_default_pricing_yaml_is_loaded(self):
+        from picarones.report.snapshot import pricing_snapshot
+        s = pricing_snapshot()
+        assert s["available"] is True
+        assert s["filename"] == "pricing.yaml"
+        assert s["size_bytes"] > 100, "pricing.yaml ne doit pas être quasi-vide"
+        # raw_yaml et data sont cohérents
+        assert isinstance(s["raw_yaml"], str)
+        assert isinstance(s["data"], dict)
+
+    def test_data_contains_meta_and_engines(self):
+        from picarones.report.snapshot import pricing_snapshot
+        s = pricing_snapshot()
+        assert "meta" in s["data"], "le snapshot doit exposer la section meta"
+        assert "engines" in s["data"], "le snapshot doit exposer engines"
+
+    def test_missing_path_returns_unavailable(self, tmp_path):
+        from picarones.report.snapshot import pricing_snapshot
+        s = pricing_snapshot(pricing_path=tmp_path / "ne-pas-exister.yaml")
+        assert s["available"] is False
+        assert "introuvable" in s["reason"].lower()
+
+    def test_custom_yaml_round_trips(self, tmp_path):
+        from picarones.report.snapshot import pricing_snapshot
+        custom = tmp_path / "custom.yaml"
+        custom.write_text(
+            "meta:\n  currency: USD\n  last_updated: 2026-01-01\nengines:\n  fake: {type: local}\n",
+            encoding="utf-8",
+        )
+        s = pricing_snapshot(pricing_path=custom)
+        assert s["available"] is True
+        assert s["data"]["meta"]["currency"] == "USD"
+        assert "fake" in s["data"]["engines"]
+        # Le brut doit être identique au fichier source — preuve de fidélité.
+        assert s["raw_yaml"] == custom.read_text(encoding="utf-8")
+
+
+class TestGlossarySnapshot:
+    def test_default_lang_returns_entries(self):
+        from picarones.report.snapshot import glossary_snapshot
+        s = glossary_snapshot(lang="fr")
+        assert s["available"] is True
+        assert s["entry_count"] > 10
+        # Quelques clés canoniques attendues
+        for k in ("cer", "wer"):
+            assert k in s["entries"]
+
+    def test_used_keys_filter(self):
+        from picarones.report.snapshot import glossary_snapshot
+        s = glossary_snapshot(lang="fr", used_keys=["cer"])
+        assert s["entry_count"] == 1
+        assert list(s["entries"]) == ["cer"]
+
+    def test_unknown_lang_falls_back(self):
+        # `load_glossary` retombe sur fr si la langue est absente — donc
+        # le snapshot doit être disponible avec lang='fr' ou la langue
+        # demandée selon ce qu'on retourne. On vérifie qu'on ne crashe pas.
+        from picarones.report.snapshot import glossary_snapshot
+        s = glossary_snapshot(lang="xx-pas-existante")
+        # Soit on retombe sur fr (available=True), soit on signale unavailable.
+        assert "available" in s
+
+    def test_entries_sorted_for_determinism(self):
+        from picarones.report.snapshot import glossary_snapshot
+        s = glossary_snapshot(lang="fr")
+        keys = list(s["entries"])
+        assert keys == sorted(keys), (
+            "Les entrées doivent être triées pour produire un snapshot "
+            "bit-à-bit reproductible."
+        )
+
+
+class TestNormalizationSnapshot:
+    def test_builtin_profile_serializes(self):
+        from picarones.core.normalization import get_builtin_profile
+        from picarones.report.snapshot import normalization_snapshot
+        p = get_builtin_profile("medieval_french")
+        s = normalization_snapshot(p)
+        assert s["available"] is True
+        assert s["name"] == "medieval_french"
+        assert s["nfc"] is True
+        # La table contient des correspondances connues
+        assert s["diplomatic_table"].get("ſ") == "s"
+
+    def test_none_profile_returns_unavailable(self):
+        from picarones.report.snapshot import normalization_snapshot
+        s = normalization_snapshot(None)
+        assert s["available"] is False
+
+    def test_exclude_chars_sorted(self):
+        from picarones.core.normalization import get_builtin_profile
+        from picarones.report.snapshot import normalization_snapshot
+        p = get_builtin_profile("sans_ponctuation")
+        s = normalization_snapshot(p)
+        # Liste triée pour reproductibilité
+        assert s["exclude_chars"] == sorted(s["exclude_chars"])
+
+
+class TestEnvironmentSnapshot:
+    def test_returns_picarones_version(self):
+        from picarones import __version__
+        from picarones.report.snapshot import environment_snapshot
+        s = environment_snapshot()
+        assert s["available"] is True
+        assert s["picarones_version"] == __version__
+
+    def test_python_and_platform_present(self):
+        from picarones.report.snapshot import environment_snapshot
+        s = environment_snapshot()
+        assert s["python_version"]
+        assert s["python_implementation"]
+        assert s["platform"]
+
+    def test_installed_packages_sorted_unique(self):
+        from picarones.report.snapshot import environment_snapshot
+        s = environment_snapshot()
+        pkgs = s["installed_packages"]
+        assert isinstance(pkgs, list)
+        # Triés case-insensitive
+        assert pkgs == sorted(pkgs, key=str.lower)
+        # Pas de doublons
+        names = [p.split("==", 1)[0].lower() for p in pkgs]
+        assert len(names) == len(set(names))
+
+    def test_git_commit_is_str_or_none(self):
+        from picarones.report.snapshot import environment_snapshot
+        s = environment_snapshot()
+        commit = s.get("git_commit")
+        assert commit is None or (isinstance(commit, str) and 0 < len(commit) <= 12)
+
+
+# ---------------------------------------------------------------------------
+# 2. snapshot_all : l'API agrégée appelée par ReportGenerator
+# ---------------------------------------------------------------------------
+
+class TestSnapshotAll:
+    def test_contains_all_four_blocks(self):
+        from picarones.report.snapshot import snapshot_all
+        s = snapshot_all()
+        for k in ("pricing", "glossary", "normalization", "environment"):
+            assert k in s, f"snapshot_all doit exposer la clé '{k}'"
+        assert s["schema_version"] == 1
+
+    def test_deterministic_for_same_inputs(self):
+        from picarones.core.normalization import get_builtin_profile
+        from picarones.report.snapshot import snapshot_all
+        profile = get_builtin_profile("nfc")
+
+        a = snapshot_all(lang="fr", normalization_profile=profile)
+        b = snapshot_all(lang="fr", normalization_profile=profile)
+        # Les sections statiques (pricing, glossary, normalization) sont
+        # déterministes ; environment peut varier sur git_commit selon
+        # l'état du repo. On compare donc les trois sections clés.
+        for k in ("pricing", "glossary", "normalization"):
+            assert a[k] == b[k], f"Section '{k}' non déterministe"
+
+
+# ---------------------------------------------------------------------------
+# 3. Intégration ReportGenerator : snapshots embarqués dans le HTML
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(scope="module")
+def generated_report_html(tmp_path_factory) -> str:
+    """Génère un rapport démo et retourne son contenu HTML."""
+    from picarones import fixtures
+    from picarones.core.normalization import get_builtin_profile
+    from picarones.report.generator import ReportGenerator
+
+    b = fixtures.generate_sample_benchmark(n_docs=6)
+    out_dir = tmp_path_factory.mktemp("rep27")
+    out = out_dir / "report.html"
+    gen = ReportGenerator(
+        b,
+        lang="fr",
+        normalization_profile=get_builtin_profile("medieval_french"),
+    )
+    gen.generate(out)
+    return out.read_text(encoding="utf-8")
+
+
+def _extract_report_data(html: str) -> dict:
+    """Récupère le dict ``report_data`` injecté dans le HTML.
+
+    Le générateur sérialise ``report_data`` en JSON dans une balise
+    ``<script id="picarones-data" type="application/json">``. Cette
+    fonction parse le JSON pour permettre des assertions précises.
+    """
+    m = re.search(
+        r'<script[^>]*id="picarones-data"[^>]*>(.*?)</script>',
+        html,
+        re.DOTALL,
+    )
+    if not m:
+        # Fallback : chercher la première occurrence de ``"snapshots"``
+        # et ouvrir le JSON englobant.
+        idx = html.find('"snapshots"')
+        assert idx >= 0, "Aucun bloc 'snapshots' trouvé dans le rapport"
+        # On retourne un dict factice pour ne pas bloquer les tests qui
+        # ne dépendent pas du parse précis.
+        return {"snapshots": {"present_in_html": True}}
+    return json.loads(m.group(1))
+
+
+class TestReportEmbedsSnapshots:
+    def test_html_contains_snapshots_block(self, generated_report_html):
+        assert '"snapshots"' in generated_report_html
+        assert '"schema_version":1' in generated_report_html
+
+    def test_pricing_yaml_embedded_raw(self, generated_report_html):
+        # Le YAML brut doit être présent (chercher une ligne caractéristique)
+        assert "engines:" in generated_report_html
+        # ``meta:`` apparaît aussi dans pricing.yaml
+        assert "meta:" in generated_report_html
+
+    def test_environment_block_embedded(self, generated_report_html):
+        assert '"picarones_version"' in generated_report_html
+        assert '"python_version"' in generated_report_html
+        assert '"installed_packages"' in generated_report_html
+
+    def test_glossary_block_embedded(self, generated_report_html):
+        # Quelques clés du glossaire doivent figurer dans le HTML — mais
+        # comme le glossaire est aussi rendu côté UI dans une autre var,
+        # on vérifie au moins la présence du JSON glossary dans snapshots.
+        assert '"entries"' in generated_report_html
+
+    def test_normalization_profile_embedded(self, generated_report_html):
+        # Le snapshot doit nommer le profil utilisé
+        assert "medieval_french" in generated_report_html
+
+
+class TestReportSnapshotPersistsAcrossPricingChanges:
+    """Garantie de reproductibilité : un rapport généré aujourd'hui reste
+    cohérent avec le pricing au moment de la génération, même si
+    ``picarones/data/pricing.yaml`` change ensuite."""
+
+    def test_snapshot_carries_full_yaml_for_replay(self, generated_report_html):
+        # Si quelqu'un ouvre le HTML demain et veut rejouer la table de
+        # prix, il peut extraire le ``raw_yaml`` du bloc snapshots et le
+        # parser. On vérifie que le brut YAML est bien là tel quel.
+        assert "raw_yaml" in generated_report_html
+        # Les hypothèses détaillées (assumptions, notes, sources) sont
+        # dans le YAML — au moins une doit apparaître dans le HTML
+        # via le bloc raw_yaml.
+        assert ("assumptions" in generated_report_html
+                or "notes" in generated_report_html
+                or "sources" in generated_report_html), (
+            "Le YAML pricing brut doit embarquer assumptions/notes/sources"
+        )