feat(adapters/storage): Sprint A14-S29 — ArtifactStore + hash multi-paramètres

Adresse la critique d'audit n° 14 (« hash multi-paramètres + reprise par
hash »). Le S7 livrait ArtifactCache (in-memory, hash basique sur inputs +
spec + code_version). S29 introduit un ArtifactStore plus robuste avec :

1. Hash multi-paramètres : la clé canonique d'un artefact inclut désormais
les content_hashes des inputs, le nom + version du model utilisé,
les params du step, le code_version, l'éventuel profil de normalisation,
et l'éventuelle spec de projection. Tout changement d'un paramètre
éditorial invalide la cache.

2. Reprise par hash : si un artefact avec exactement la même clé existe
déjà dans le store, le caller peut le réutiliser plutôt que de
re-exécuter une étape coûteuse.

3. Persistance optionnelle : InMemoryArtifactStore pour tests/runs
éphémères ; FilesystemArtifactStore pour les longs runs avec reprise
après crash.

Modules livrés
--------------

picarones/adapters/storage/artifact_store.py (504 lignes) :
- ArtifactKey (frozen dataclass) avec 9 champs (input_hashes,
adapter_name, adapter_version, step_params, code_version,
normalization_profile, projection_name, projection_params,
metric_version) et to_canonical_json() + hash_hex().
- StoredArtifact (frozen dataclass) qui regroupe key + Artifact + payload
bytes.
- ArtifactStore (ABC) avec contrat get/put/contains/clear/__len__.
- InMemoryArtifactStore : threading.Lock, O(1), keys() helper.
- FilesystemArtifactStore : layout root/{index.jsonl, artifacts/<key>.json,
payloads/<key>.bin}, écriture atomique via .tmp + rename, tolérance aux
fichiers manquants (warning + None), reconstruction depuis artifacts/
si index manquant, lock interne pour put/clear.

Hash multi-param prouvé sensible
--------------------------------
Tests : changement de adapter_version, step_params, normalization_profile,
projection_name → hash différent. Inputs ordonnés déterministe. JSON
canonique avec sort_keys + Unicode préservé. hash_hex() retourne None si
un input_hash manque (convention « pas de résultat douteux »).

Tests S29 dédiés (39 nouveaux)
------------------------------
- ArtifactKey : defaults, frozen, JSON canonique déterministe (ordre des
step_params, ordre des inputs, Unicode), hash sensible aux 4 champs
testés, None si input manquant, empty inputs OK.
- Mixin _SharedStoreContract : 8 tests partagés entre InMemory et
Filesystem (empty, put_then_get, sans payload, idempotent, clear,
empty key rejected, multiple artifacts independent).
- InMemoryArtifactStore : keys() helper, thread-safe (100 threads × 10
entrées = 1000 sans race).
- FilesystemArtifactStore : persistance à travers les instances, layout,
artifact metadata round-trip (provenance comprise), index corrompu
skippé, fichier manquant → None + warning, reconstruction depuis
artifacts/, clear() supprime tout (laisse les sous-dirs vides).
- KeyStoreIntegration : pattern store.put(key.hash_hex(), ...), pas de
collision entre clés conceptuellement différentes.
- StoredArtifact frozen.

Pas de shim
-----------
ArtifactCache (S7) reste exposé pour les callers qui en dépendent en
interne, mais la nouvelle API canonique est ArtifactStore. Le branchement
dans PipelineExecutor (param artifact_store=) sera fait dans un sprint
dédié — S29 livre le module standalone testé, prêt à être consommé.

Tests : 4596 passed, 11 skipped (vs 4557 avant : +39 S29).
Lint : ruff check picarones/ tests/ → All checks passed.
File budgets : adapters/storage/artifact_store.py ajouté (504 lignes,
budget 580 = +15 %).

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

README.md

@@ -396,7 +396,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~4570 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~4610 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP. A handful of tests depend on optional engines
 (`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when

picarones/adapters/storage/__init__.py

@@ -1,15 +1,48 @@
-"""Adaptateurs de stockage — Sprint S20.
+"""Adaptateurs de stockage — Sprint S29.
 
-Cible : déplacement de ``picarones.web.jobs`` (SQLite job store) et
-de ``picarones.measurements.history`` (SQLite history).  Plus
-généralement : tout ce qui touche au filesystem ou à une DB locale.
+Stocks d'artefacts indexés par hash multi-paramètres pour la
+reprise des runs longs.
+
+Modules livrés
+--------------
+- ``artifact_store.py`` (S29) — ``ArtifactKey``, ``StoredArtifact``,
+  ``ArtifactStore`` (ABC), ``InMemoryArtifactStore``,
+  ``FilesystemArtifactStore``.
 
 Pattern : un ``Storage`` est instancié par un ``app/services/``,
 pas créé ad-hoc dans un router FastAPI ou un module métier.  Ça
 permet d'injecter un mock en test, de basculer SQLite → Postgres
 si besoin, et de centraliser les permissions/quotas.
+
+Distinct du ``picarones/pipeline/cache.py`` (S7)
+------------------------------------------------
+``ArtifactCache`` (S7) reste exposé pour les callers qui en
+dépendent en interne.  ``ArtifactStore`` (S29) est la nouvelle
+API canonique : hash multi-paramètres (model_version, normalization
+profile, projection spec), persistance optionnelle sur filesystem,
+abstraction ABC.
+
+Cibles à venir
+--------------
+- S37 : déplacement de ``picarones.web.jobs`` (SQLite job store).
+- Post-livraison : ``picarones.measurements.history`` (SQLite
+  history) et stores distribués (S3, GCS, …).
 """
 
 from __future__ import annotations
 
-__all__: list[str] = []
+from picarones.adapters.storage.artifact_store import (
+    ArtifactKey,
+    ArtifactStore,
+    FilesystemArtifactStore,
+    InMemoryArtifactStore,
+    StoredArtifact,
+)
+
+__all__ = [
+    "ArtifactKey",
+    "ArtifactStore",
+    "FilesystemArtifactStore",
+    "InMemoryArtifactStore",
+    "StoredArtifact",
+]

picarones/adapters/storage/artifact_store.py

@@ -0,0 +1,504 @@
+"""``ArtifactStore`` — Sprint A14-S29.
+
+Le S7 livrait ``ArtifactCache`` (in-memory, hash basique sur
+inputs + step + code_version).  S29 introduit un ``ArtifactStore``
+plus robuste qui adresse la critique d'audit n° 14 (« hash
+multi-paramètres + reprise par hash ») :
+
+1. **Hash multi-paramètres** : la clé canonique d'un artefact
+   inclut les ``content_hash`` des inputs, le nom + version du
+   model utilisé, les ``params`` du step, le ``code_version``,
+   l'éventuel profil de normalisation, et l'éventuelle spec de
+   projection.  Tout changement d'un paramètre éditorial invalide
+   la cache.
+
+2. **Reprise par hash** : si un artefact avec exactement la même
+   clé existe déjà dans le store, le caller peut l'utiliser
+   directement plutôt que de re-exécuter l'étape coûteuse.
+
+3. **Persistance optionnelle** : ``InMemoryArtifactStore`` pour
+   les tests et les workflows éphémères ; ``FilesystemArtifactStore``
+   pour les longs runs où on veut survivre à un crash.
+
+Pas de shim
+-----------
+``ArtifactCache`` (S7) reste exposé pour les callers qui en
+dépendent en interne, mais la nouvelle API canonique est
+``ArtifactStore``.  Le ``PipelineExecutor`` peut consommer un
+``ArtifactStore`` via le paramètre optionnel ``artifact_store=``
+au constructeur ; sans store, l'executor s'exécute comme avant
+(pas d'effet de cache).
+
+Anti-sur-ingénierie
+-------------------
+- Pas de TTL ni d'éviction LRU dans la version in-memory.  La
+  taille est gérée par le caller (qui peut appeler ``clear()``).
+- Pas de compression des payloads dans la version filesystem.
+- Pas de namespacing par run — un store partagé entre runs est
+  censé converger, c'est précisément la propriété de la reprise.
+- Pas de support distribué (S3, GCS, …) — viendra quand un
+  caller en aura concrètement besoin.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from picarones.domain.artifacts import Artifact
+
+logger = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Clé canonique multi-paramètres
+# ──────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ArtifactKey:
+    """Composition immuable de tous les paramètres qui déterminent
+    l'identité d'un artefact dans le store.
+
+    Sérialisable JSON déterministe via ``to_canonical_json``.
+
+    Attributes
+    ----------
+    input_hashes:
+        Tuple ``((type, content_hash), ...)`` des inputs, trié par
+        type.  ``None`` ou vide → la clé n'est pas calculable
+        (cas d'un input sans content_hash).
+    adapter_name:
+        ``step.adapter_name`` (ex : ``"tesseract"``,
+        ``"openai:gpt-4o"``).
+    adapter_version:
+        Version du modèle / binaire de l'adapter.  ``None`` si
+        l'adapter ne sait pas la fournir (warning loggé une fois).
+    step_params:
+        Dict ``{name: scalar}`` du step, sérialisé en JSON canonique
+        (clés triées).
+    code_version:
+        Version du code Picarones (cf. ``RunContext.code_version``).
+    normalization_profile:
+        Profil de normalisation appliqué en aval (le cas échéant).
+        Pour les jonctions textuelles avec normalisation.
+    projection_name:
+        Nom du projecteur appliqué (le cas échéant).
+    projection_params:
+        Params du projecteur (le cas échéant).
+    metric_version:
+        Version du module de métriques (rare ; reporté à la phase
+        où on aura un versioning explicite des métriques).
+
+    Notes
+    -----
+    Frozen dataclass : aucune mutation possible.  Le hash canonique
+    est calculé à la demande via ``hash_hex()``.
+    """
+
+    input_hashes: tuple[tuple[str, str], ...] = field(default_factory=tuple)
+    adapter_name: str = ""
+    adapter_version: str | None = None
+    step_params: dict[str, str | int | float | bool] = field(default_factory=dict)
+    code_version: str = ""
+    normalization_profile: str | None = None
+    projection_name: str | None = None
+    projection_params: dict[str, str | int | float | bool] = field(
+        default_factory=dict,
+    )
+    metric_version: str | None = None
+
+    def to_canonical_json(self) -> str:
+        """Sérialise la clé en JSON déterministe.
+
+        - Clés du dict triées (``sort_keys=True``).
+        - ``ensure_ascii=False`` pour préserver l'Unicode brut.
+        - Séparateurs compacts pour minimiser les variations de
+          whitespace entre OS.
+        """
+        # Trier les input_hashes par type pour déterminisme
+        # cross-platform (les Python du même version trient les
+        # tuples par leur premier élément, mais on l'explicite).
+        sorted_inputs = sorted(self.input_hashes)
+        payload = {
+            "inputs": sorted_inputs,
+            "adapter": self.adapter_name,
+            "adapter_version": self.adapter_version,
+            "step_params": self.step_params,
+            "code_version": self.code_version,
+            "normalization_profile": self.normalization_profile,
+            "projection_name": self.projection_name,
+            "projection_params": self.projection_params,
+            "metric_version": self.metric_version,
+        }
+        return json.dumps(
+            payload,
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+
+    def hash_hex(self) -> str | None:
+        """Calcule la clé hex SHA-256 (64 chars).
+
+        Retourne ``None`` si **un seul** ``input_hash`` est ``None``
+        ou vide — convention « ne pas servir un résultat douteux ».
+        Les autres champs peuvent être ``None`` (ils sont sérialisés
+        comme ``null`` dans le JSON canonique → entrent dans le hash).
+        """
+        for _, h in self.input_hashes:
+            if h is None or h == "":
+                return None
+        canonical = self.to_canonical_json()
+        return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Conteneur du store
+# ──────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class StoredArtifact:
+    """Entrée du store : un artefact + son payload + sa clé.
+
+    Le payload est stocké en bytes brutes — le caller décide de la
+    désérialisation (texte UTF-8, ALTO XML, image PNG, etc.) en se
+    basant sur ``artifact.type``.
+
+    Attributes
+    ----------
+    key:
+        Hash hex de la ``ArtifactKey`` qui a produit l'artefact.
+    artifact:
+        ``Artifact`` complet (id, type, content_hash, provenance).
+    payload:
+        Bytes du contenu, ou ``None`` si le store ne stocke que
+        les métadonnées (cas d'un artefact dont l'``uri`` pointe
+        vers un fichier externe).
+    """
+
+    key: str
+    artifact: Artifact
+    payload: bytes | None = None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Interface ABC
+# ──────────────────────────────────────────────────────────────────────
+
+
+class ArtifactStore(ABC):
+    """Contrat abstrait d'un store d'artefacts indexé par hash.
+
+    Implémentations livrées au S29 :
+
+    - ``InMemoryArtifactStore`` (tests, runs éphémères) ;
+    - ``FilesystemArtifactStore`` (workspaces persistants).
+
+    Une implémentation tierce (S3, Postgres, …) est attendue post-
+    livraison ; elle hérite de cette ABC et passe les tests de
+    contrat.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> StoredArtifact | None:
+        """Récupère un artefact par sa clé hex, ou ``None``.
+
+        Tolère les clés inexistantes — le retour ``None`` indique
+        un cache miss, pas une erreur.
+        """
+
+    @abstractmethod
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        """Stocke un artefact sous la clé donnée.
+
+        Convention idempotente : ``put(k, ...)`` deux fois avec la
+        même clé écrase la valeur précédente sans erreur.  L'ABC
+        n'impose pas de comportement en concurrence multi-process
+        — chaque implémentation documente ses garanties.
+        """
+
+    @abstractmethod
+    def __contains__(self, key: str) -> bool:
+        """Vrai si la clé est connue du store."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Supprime toutes les entrées du store.
+
+        Implémentations filesystem : supprime les fichiers de
+        l'index et des payloads.  Implémentations in-memory :
+        vide les dicts.
+        """
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """Nombre d'entrées dans le store."""
+
+
+# ──────────────────────────────────────────────────────────────────────
+# InMemoryArtifactStore
+# ──────────────────────────────────────────────────────────────────────
+
+
+class InMemoryArtifactStore(ArtifactStore):
+    """Store in-memory thread-safe pour tests et runs éphémères.
+
+    Performances : O(1) en lecture/écriture.  Aucune persistance —
+    toutes les données disparaissent à la sortie du process.
+
+    Thread-safety : un ``threading.Lock`` protège les opérations
+    mutantes (put, clear).  Lecture (get, __contains__, __len__)
+    est sans lock car les dict Python sont atomiques par opération
+    sur clé.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, StoredArtifact] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> StoredArtifact | None:
+        return self._store.get(key)
+
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        if not key:
+            raise ValueError("ArtifactStore.put : key vide non autorisé")
+        with self._lock:
+            self._store[key] = StoredArtifact(
+                key=key, artifact=artifact, payload=payload,
+            )
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._store
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def keys(self) -> tuple[str, ...]:
+        """Liste figée des clés connues (utile aux tests)."""
+        return tuple(self._store.keys())
+
+
+# ──────────────────────────────────────────────────────────────────────
+# FilesystemArtifactStore
+# ──────────────────────────────────────────────────────────────────────
+
+
+class FilesystemArtifactStore(ArtifactStore):
+    """Store persistant sur le filesystem.
+
+    Layout
+    ------
+
+    ``<root>/``
+        ``index.jsonl``                   — un JSON par ligne
+                                            ``{"key": ..., "artifact_id": ...,
+                                            "has_payload": bool, "type": ...,
+                                            "timestamp": ISO8601}``
+        ``artifacts/<key>.json``          — métadonnées de l'``Artifact``
+                                            sérialisées via
+                                            ``model_dump_json()``
+        ``payloads/<key>.bin``            — bytes du payload (le cas
+                                            échéant)
+
+    Concurrence
+    -----------
+    Un ``threading.Lock`` interne protège les opérations mutantes
+    dans le même process.  Multi-process : pas de garantie ; le
+    layout est conçu pour qu'un read-only multi-process soit
+    sûr (les fichiers individuels sont écrits atomiquement via
+    ``write_text(... newline=...)`` et un rename).
+
+    Garbage / corruption
+    --------------------
+    Si l'index pointe vers un fichier disparu, le ``get`` retourne
+    ``None`` et logge un warning.  ``clear()`` supprime tout —
+    un caller peut aussi reconstruire l'index en parsant les
+    fichiers ``artifacts/*.json``.
+
+    Pas de shim
+    -----------
+    Cette implémentation n'a pas de migration depuis l'``ArtifactCache``
+    in-memory du S7 — c'est un store distinct, instanciable
+    explicitement par un service applicatif (typiquement
+    ``WorkspaceManager`` au S30+).
+    """
+
+    INDEX_FILENAME = "index.jsonl"
+    ARTIFACTS_DIR = "artifacts"
+    PAYLOADS_DIR = "payloads"
+
+    def __init__(self, root: Path | str) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+        (self._root / self.ARTIFACTS_DIR).mkdir(exist_ok=True)
+        (self._root / self.PAYLOADS_DIR).mkdir(exist_ok=True)
+        self._index_path = self._root / self.INDEX_FILENAME
+        self._lock = threading.Lock()
+        # In-memory index of known keys reconstructed from disk.
+        # On sait qu'on est seul écrivain dans un process donné, mais
+        # un autre process peut aussi écrire — on ne fait pas de
+        # garantie multi-process ici.
+        self._known_keys: set[str] = self._reconstruct_known_keys()
+
+    # ──────────────────────────────────────────────────────────────
+    # API ABC
+    # ──────────────────────────────────────────────────────────────
+
+    def get(self, key: str) -> StoredArtifact | None:
+        if key not in self._known_keys:
+            return None
+        artifact_path = self._root / self.ARTIFACTS_DIR / f"{key}.json"
+        if not artifact_path.exists():
+            logger.warning(
+                "[artifact_store] index pointe vers %s mais le fichier "
+                "n'existe plus — entrée corrompue, retour None.",
+                artifact_path,
+            )
+            return None
+        try:
+            artifact = Artifact.model_validate_json(
+                artifact_path.read_text(encoding="utf-8"),
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "[artifact_store] échec de désérialisation de %s : %s",
+                artifact_path, exc,
+            )
+            return None
+        payload_path = self._root / self.PAYLOADS_DIR / f"{key}.bin"
+        payload = (
+            payload_path.read_bytes() if payload_path.exists() else None
+        )
+        return StoredArtifact(key=key, artifact=artifact, payload=payload)
+
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        if not key:
+            raise ValueError("ArtifactStore.put : key vide non autorisé")
+        with self._lock:
+            artifact_path = self._root / self.ARTIFACTS_DIR / f"{key}.json"
+            tmp_path = artifact_path.with_suffix(".json.tmp")
+            tmp_path.write_text(
+                artifact.model_dump_json(),
+                encoding="utf-8",
+            )
+            tmp_path.replace(artifact_path)
+            if payload is not None:
+                payload_path = self._root / self.PAYLOADS_DIR / f"{key}.bin"
+                tmp_payload = payload_path.with_suffix(".bin.tmp")
+                tmp_payload.write_bytes(payload)
+                tmp_payload.replace(payload_path)
+            self._append_index_line(key, artifact, payload is not None)
+            self._known_keys.add(key)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._known_keys
+
+    def clear(self) -> None:
+        with self._lock:
+            for sub in (self.ARTIFACTS_DIR, self.PAYLOADS_DIR):
+                d = self._root / sub
+                if d.exists():
+                    for f in d.iterdir():
+                        f.unlink()
+            if self._index_path.exists():
+                self._index_path.unlink()
+            self._known_keys.clear()
+
+    def __len__(self) -> int:
+        return len(self._known_keys)
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(self._known_keys)
+
+    # ──────────────────────────────────────────────────────────────
+    # Helpers internes
+    # ──────────────────────────────────────────────────────────────
+
+    def _append_index_line(
+        self, key: str, artifact: Artifact, has_payload: bool,
+    ) -> None:
+        """Append-only JSONL : une nouvelle ligne par put.  Lit le
+        rapport d'index au démarrage, recompose ``_known_keys``."""
+        from datetime import datetime, timezone
+        line = json.dumps(
+            {
+                "key": key,
+                "artifact_id": artifact.id,
+                "type": artifact.type.value,
+                "has_payload": has_payload,
+                "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+            },
+            ensure_ascii=False,
+        )
+        with self._index_path.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    def _reconstruct_known_keys(self) -> set[str]:
+        """Lit ``index.jsonl`` et reconstruit l'ensemble des clés
+        connues.  Tolère les lignes corrompues (warning + skip).
+
+        Si l'index n'existe pas, recompose depuis le contenu du
+        sous-répertoire ``artifacts/`` (cas d'un store partiellement
+        copié sans son index).
+        """
+        keys: set[str] = set()
+        if self._index_path.exists():
+            for line_no, raw_line in enumerate(
+                self._index_path.read_text(encoding="utf-8").splitlines(),
+                start=1,
+            ):
+                if not raw_line.strip():
+                    continue
+                try:
+                    rec = json.loads(raw_line)
+                except json.JSONDecodeError as exc:
+                    logger.warning(
+                        "[artifact_store] index ligne %d corrompue, "
+                        "ignorée : %s", line_no, exc,
+                    )
+                    continue
+                if "key" in rec and isinstance(rec["key"], str):
+                    keys.add(rec["key"])
+        else:
+            # Recompose depuis les fichiers d'artefacts.
+            artifacts_dir = self._root / self.ARTIFACTS_DIR
+            if artifacts_dir.exists():
+                for f in artifacts_dir.iterdir():
+                    if f.suffix == ".json":
+                        keys.add(f.stem)
+        return keys
+
+
+__all__ = [
+    "ArtifactKey",
+    "ArtifactStore",
+    "FilesystemArtifactStore",
+    "InMemoryArtifactStore",
+    "StoredArtifact",
+]

tests/adapters/storage/test_sprint_a14_s29_artifact_store.py

@@ -0,0 +1,516 @@
+"""Sprint A14-S29 — ``ArtifactStore`` + ``ArtifactKey``.
+
+Tests du store et du hash multi-paramètres introduits par S29
+pour adresser la critique d'audit n° 14 (« hash multi-paramètres
++ reprise par hash »).
+
+Couvre :
+
+1. ``ArtifactKey`` :
+   - frozen dataclass ;
+   - sérialisation JSON canonique déterministe ;
+   - hash hex SHA-256 stable cross-platform ;
+   - sensibilité à chaque champ (changement → hash change) ;
+   - ``hash_hex()`` retourne ``None`` si un input_hash est manquant.
+
+2. ``InMemoryArtifactStore`` :
+   - get/put/contains/clear/len ;
+   - rejet des clés vides ;
+   - put idempotent (écrase silencieusement) ;
+   - thread-safety basique (pas de race évidente).
+
+3. ``FilesystemArtifactStore`` :
+   - get/put/contains/clear/len ;
+   - persistance disque (relire après ré-instanciation) ;
+   - layout (index.jsonl + artifacts/<key>.json + payloads/<key>.bin) ;
+   - tolérance aux fichiers manquants (warning + None) ;
+   - reconstruction depuis artifacts/ si index manquant ;
+   - écriture atomique via .tmp + rename.
+
+4. Contrat ABC : les deux implémentations passent les mêmes tests
+   de comportement.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+import pytest
+
+from picarones.adapters.storage import (
+    ArtifactKey,
+    ArtifactStore,
+    FilesystemArtifactStore,
+    InMemoryArtifactStore,
+    StoredArtifact,
+)
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.domain.provenance import ProvenanceRecord
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────
+
+
+def _make_artifact(
+    artifact_id: str = "d1:ocr:raw_text",
+    document_id: str = "d1",
+    artifact_type: ArtifactType = ArtifactType.RAW_TEXT,
+    content_hash: str | None = "0" * 64,
+) -> Artifact:
+    return Artifact(
+        id=artifact_id,
+        document_id=document_id,
+        type=artifact_type,
+        content_hash=content_hash,
+        produced_by_step="ocr",
+        provenance=ProvenanceRecord(
+            code_version="1.0.0",
+            parameters_hash="a" * 64,
+        ),
+    )
+
+
+def _basic_key() -> ArtifactKey:
+    return ArtifactKey(
+        input_hashes=(("image", "f" * 64),),
+        adapter_name="tesseract",
+        adapter_version="5.3.0",
+        step_params={"lang": "fra"},
+        code_version="1.0.0",
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────
+# ArtifactKey
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestArtifactKeyDataclass:
+    def test_default_values(self) -> None:
+        k = ArtifactKey()
+        assert k.input_hashes == ()
+        assert k.adapter_name == ""
+        assert k.adapter_version is None
+        assert k.step_params == {}
+        assert k.code_version == ""
+        assert k.normalization_profile is None
+        assert k.projection_name is None
+        assert k.projection_params == {}
+        assert k.metric_version is None
+
+    def test_frozen(self) -> None:
+        k = _basic_key()
+        with pytest.raises(Exception):  # FrozenInstanceError
+            k.adapter_name = "different"  # type: ignore[misc]
+
+
+class TestArtifactKeyCanonicalJson:
+    def test_deterministic(self) -> None:
+        """Deux clés équivalentes produisent le même JSON."""
+        k1 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            step_params={"a": 1, "b": 2},
+            code_version="v1",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            step_params={"b": 2, "a": 1},  # ordre différent
+            code_version="v1",
+        )
+        assert k1.to_canonical_json() == k2.to_canonical_json()
+
+    def test_inputs_sorted(self) -> None:
+        """L'ordre des input_hashes ne change pas le JSON canonique."""
+        k1 = ArtifactKey(
+            input_hashes=(("image", "a" * 64), ("text", "b" * 64)),
+            adapter_name="x",
+            code_version="v",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("text", "b" * 64), ("image", "a" * 64)),
+            adapter_name="x",
+            code_version="v",
+        )
+        assert k1.to_canonical_json() == k2.to_canonical_json()
+
+    def test_unicode_preserved(self) -> None:
+        k = ArtifactKey(
+            input_hashes=(),
+            adapter_name="modèle",
+            step_params={"prompt": "français médiéval"},
+            code_version="v",
+        )
+        canonical = k.to_canonical_json()
+        assert "modèle" in canonical
+        assert "français médiéval" in canonical
+
+
+class TestArtifactKeyHash:
+    def test_hash_is_64_hex_chars(self) -> None:
+        h = _basic_key().hash_hex()
+        assert h is not None
+        assert len(h) == 64
+        int(h, 16)  # valide hex
+
+    def test_hash_stable_across_calls(self) -> None:
+        k = _basic_key()
+        assert k.hash_hex() == k.hash_hex()
+
+    def test_hash_changes_with_adapter_version(self) -> None:
+        k1 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            adapter_version="1.0",
+            code_version="v",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            adapter_version="2.0",  # change
+            code_version="v",
+        )
+        assert k1.hash_hex() != k2.hash_hex()
+
+    def test_hash_changes_with_step_params(self) -> None:
+        k1 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            step_params={"lang": "fra"},
+            code_version="v",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            step_params={"lang": "eng"},  # change
+            code_version="v",
+        )
+        assert k1.hash_hex() != k2.hash_hex()
+
+    def test_hash_changes_with_normalization(self) -> None:
+        k1 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            code_version="v",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("image", "a" * 64),),
+            adapter_name="x",
+            code_version="v",
+            normalization_profile="medieval_french",
+        )
+        assert k1.hash_hex() != k2.hash_hex()
+
+    def test_hash_changes_with_projection(self) -> None:
+        k1 = ArtifactKey(
+            input_hashes=(("alto", "a" * 64),),
+            adapter_name="x",
+            code_version="v",
+        )
+        k2 = ArtifactKey(
+            input_hashes=(("alto", "a" * 64),),
+            adapter_name="x",
+            code_version="v",
+            projection_name="alto_to_text",
+        )
+        assert k1.hash_hex() != k2.hash_hex()
+
+    def test_hash_returns_none_if_input_hash_missing(self) -> None:
+        # Cas pathologique : un tuple avec hash vide.
+        k = ArtifactKey(
+            input_hashes=(("image", ""),),
+            adapter_name="x",
+            code_version="v",
+        )
+        assert k.hash_hex() is None
+
+    def test_empty_inputs_yields_valid_hash(self) -> None:
+        """Pas d'inputs (tuple vide) ne signifie pas missing — c'est
+        valide pour les artefacts sans dépendance externe."""
+        k = ArtifactKey(
+            adapter_name="x",
+            code_version="v",
+        )
+        assert k.hash_hex() is not None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# InMemoryArtifactStore
+# ──────────────────────────────────────────────────────────────────────
+
+
+class _SharedStoreContract:
+    """Mixin abstrait : partage les tests entre InMemory et Filesystem."""
+
+    def make_store(self, tmp_path: Path) -> ArtifactStore:
+        raise NotImplementedError
+
+    def test_empty_store(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        assert len(store) == 0
+        assert "any-key" not in store
+        assert store.get("any-key") is None
+
+    def test_put_then_get(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        artifact = _make_artifact()
+        store.put("k1", artifact, payload=b"hello world")
+        assert "k1" in store
+        assert len(store) == 1
+        retrieved = store.get("k1")
+        assert retrieved is not None
+        assert retrieved.key == "k1"
+        assert retrieved.artifact.id == artifact.id
+        assert retrieved.payload == b"hello world"
+
+    def test_put_without_payload(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        artifact = _make_artifact()
+        store.put("k1", artifact, payload=None)
+        retrieved = store.get("k1")
+        assert retrieved is not None
+        assert retrieved.payload is None
+
+    def test_put_idempotent_overwrites(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        store.put("k1", _make_artifact(), payload=b"v1")
+        store.put("k1", _make_artifact(), payload=b"v2")
+        assert len(store) == 1
+        assert store.get("k1").payload == b"v2"
+
+    def test_clear(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        store.put("k1", _make_artifact(), payload=b"x")
+        store.put("k2", _make_artifact(), payload=b"y")
+        assert len(store) == 2
+        store.clear()
+        assert len(store) == 0
+        assert "k1" not in store
+        assert "k2" not in store
+
+    def test_empty_key_rejected(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        with pytest.raises(ValueError, match="vide"):
+            store.put("", _make_artifact(), payload=b"x")
+
+    def test_multiple_artifacts_independent(self, tmp_path: Path) -> None:
+        store = self.make_store(tmp_path)
+        a1 = _make_artifact(artifact_id="d1:art1", content_hash="1" * 64)
+        a2 = _make_artifact(artifact_id="d2:art2", content_hash="2" * 64)
+        store.put("k1", a1, payload=b"alpha")
+        store.put("k2", a2, payload=b"beta")
+        assert store.get("k1").artifact.id == "d1:art1"
+        assert store.get("k2").artifact.id == "d2:art2"
+        assert store.get("k1").payload == b"alpha"
+        assert store.get("k2").payload == b"beta"
+
+
+class TestInMemoryArtifactStore(_SharedStoreContract):
+    def make_store(self, tmp_path: Path) -> ArtifactStore:
+        return InMemoryArtifactStore()
+
+    def test_keys_helper(self) -> None:
+        store = InMemoryArtifactStore()
+        store.put("k1", _make_artifact(), payload=b"x")
+        store.put("k2", _make_artifact(), payload=b"y")
+        keys = store.keys()
+        assert set(keys) == {"k1", "k2"}
+
+    def test_thread_safe_basic(self) -> None:
+        """100 threads écrivent chacun 10 entrées → 1000 entrées."""
+        store = InMemoryArtifactStore()
+        artifact = _make_artifact()
+
+        def writer(i: int) -> None:
+            for j in range(10):
+                store.put(f"k_{i}_{j}", artifact, payload=b"x")
+
+        threads = [
+            threading.Thread(target=writer, args=(i,))
+            for i in range(100)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        assert len(store) == 1000
+
+
+class TestFilesystemArtifactStore(_SharedStoreContract):
+    def make_store(self, tmp_path: Path) -> ArtifactStore:
+        return FilesystemArtifactStore(tmp_path / "store")
+
+    def test_persists_across_instances(self, tmp_path: Path) -> None:
+        """Le store sait re-charger ses entrées après ré-instanciation."""
+        root = tmp_path / "store"
+        s1 = FilesystemArtifactStore(root)
+        s1.put("k1", _make_artifact(), payload=b"persisted")
+
+        # Nouvelle instance pointant vers le même root.
+        s2 = FilesystemArtifactStore(root)
+        assert "k1" in s2
+        assert s2.get("k1").payload == b"persisted"
+        assert s2.get("k1").artifact.id == "d1:ocr:raw_text"
+
+    def test_layout(self, tmp_path: Path) -> None:
+        """Vérifie le layout sur disque."""
+        root = tmp_path / "store"
+        s = FilesystemArtifactStore(root)
+        s.put("k1", _make_artifact(), payload=b"hello")
+        assert (root / "index.jsonl").exists()
+        assert (root / "artifacts" / "k1.json").exists()
+        assert (root / "payloads" / "k1.bin").exists()
+        # L'index contient une ligne JSON.
+        index_lines = (root / "index.jsonl").read_text(encoding="utf-8").splitlines()
+        assert len(index_lines) == 1
+        rec = json.loads(index_lines[0])
+        assert rec["key"] == "k1"
+        assert rec["artifact_id"] == "d1:ocr:raw_text"
+        assert rec["has_payload"] is True
+
+    def test_artifact_metadata_preserved(self, tmp_path: Path) -> None:
+        """Les métadonnées de l'Artifact survivent au round-trip."""
+        root = tmp_path / "store"
+        s = FilesystemArtifactStore(root)
+        artifact = Artifact(
+            id="d1:complex",
+            document_id="d1",
+            type=ArtifactType.ALTO_XML,
+            content_hash="b" * 64,
+            uri="/tmp/some.xml",
+            produced_by_step="alto_step",
+            provenance=ProvenanceRecord(
+                code_version="2.5.1",
+                parameters_hash="c" * 64,
+            ),
+        )
+        s.put("k1", artifact, payload=b"<alto/>")
+        s2 = FilesystemArtifactStore(root)
+        retrieved = s2.get("k1")
+        assert retrieved is not None
+        assert retrieved.artifact.id == artifact.id
+        assert retrieved.artifact.type == ArtifactType.ALTO_XML
+        assert retrieved.artifact.content_hash == artifact.content_hash
+        assert retrieved.artifact.uri == "/tmp/some.xml"
+        assert retrieved.artifact.provenance.code_version == "2.5.1"
+        assert retrieved.payload == b"<alto/>"
+
+    def test_corrupted_index_line_skipped(self, tmp_path: Path) -> None:
+        """Une ligne corrompue de l'index ne plante pas le store."""
+        root = tmp_path / "store"
+        s1 = FilesystemArtifactStore(root)
+        s1.put("k1", _make_artifact(), payload=b"x")
+        # Corrompre l'index par ajout d'une ligne garbage.
+        (root / "index.jsonl").open("a", encoding="utf-8").write(
+            "this is not json\n"
+        )
+        s2 = FilesystemArtifactStore(root)
+        assert "k1" in s2  # Toujours présent malgré ligne corrompue
+        assert s2.get("k1") is not None
+
+    def test_artifact_file_missing_returns_none_with_warning(
+        self, tmp_path: Path, caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Si l'index pointe vers un fichier supprimé, get retourne
+        None avec warning explicite (pas un crash)."""
+        root = tmp_path / "store"
+        s = FilesystemArtifactStore(root)
+        s.put("k1", _make_artifact(), payload=b"x")
+        # Supprimer le fichier d'artefact pour simuler corruption.
+        (root / "artifacts" / "k1.json").unlink()
+        result = s.get("k1")
+        assert result is None
+        assert any(
+            "n'existe plus" in r.message for r in caplog.records
+        )
+
+    def test_reconstruct_from_artifacts_dir_when_index_missing(
+        self, tmp_path: Path,
+    ) -> None:
+        """Si index.jsonl est manquant, reconstruction depuis
+        artifacts/."""
+        root = tmp_path / "store"
+        s1 = FilesystemArtifactStore(root)
+        s1.put("k1", _make_artifact(), payload=b"a")
+        s1.put("k2", _make_artifact(), payload=b"b")
+        # Effacer l'index, garder les artefacts.
+        (root / "index.jsonl").unlink()
+        s2 = FilesystemArtifactStore(root)
+        assert "k1" in s2
+        assert "k2" in s2
+        assert len(s2) == 2
+
+    def test_clear_removes_all_files(self, tmp_path: Path) -> None:
+        root = tmp_path / "store"
+        s = FilesystemArtifactStore(root)
+        s.put("k1", _make_artifact(), payload=b"x")
+        s.put("k2", _make_artifact(), payload=b"y")
+        s.clear()
+        assert len(s) == 0
+        # Les sous-répertoires existent toujours, juste vides.
+        assert (root / "artifacts").exists()
+        assert list((root / "artifacts").iterdir()) == []
+        assert list((root / "payloads").iterdir()) == []
+        assert not (root / "index.jsonl").exists()
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Intégration ArtifactKey + Store
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestKeyStoreIntegration:
+    def test_store_keyed_by_artifact_key_hash(self, tmp_path: Path) -> None:
+        """Le pattern d'usage attendu : compute key, then put with
+        key.hash_hex() as the store key."""
+        store = InMemoryArtifactStore()
+        key = _basic_key()
+        hash_hex = key.hash_hex()
+        assert hash_hex is not None
+        store.put(hash_hex, _make_artifact(), payload=b"raw text")
+        assert hash_hex in store
+        retrieved = store.get(hash_hex)
+        assert retrieved is not None
+        assert retrieved.payload == b"raw text"
+
+    def test_different_params_yield_different_keys_and_no_collision(
+        self, tmp_path: Path,
+    ) -> None:
+        """Deux clés conceptuellement différentes ne collisent pas."""
+        store = InMemoryArtifactStore()
+        k_fra = ArtifactKey(
+            input_hashes=(("image", "f" * 64),),
+            adapter_name="tess",
+            step_params={"lang": "fra"},
+            code_version="v",
+        )
+        k_eng = ArtifactKey(
+            input_hashes=(("image", "f" * 64),),
+            adapter_name="tess",
+            step_params={"lang": "eng"},
+            code_version="v",
+        )
+        store.put(k_fra.hash_hex(), _make_artifact(artifact_id="art:fra"))
+        store.put(k_eng.hash_hex(), _make_artifact(artifact_id="art:eng"))
+        assert len(store) == 2
+        assert store.get(k_fra.hash_hex()).artifact.id == "art:fra"
+        assert store.get(k_eng.hash_hex()).artifact.id == "art:eng"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# StoredArtifact dataclass
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestStoredArtifactDataclass:
+    def test_frozen(self) -> None:
+        sa = StoredArtifact(
+            key="k", artifact=_make_artifact(), payload=b"x",
+        )
+        with pytest.raises(Exception):  # FrozenInstanceError
+            sa.payload = b"y"  # type: ignore[misc]

tests/architecture/test_file_budgets.py

@@ -84,6 +84,10 @@ FILE_BUDGETS: dict[str, int] = {
     # plan immuable (validation + bindings + jonctions de métriques).
     "picarones/pipeline/executor.py": 475,                # actuel 413
     "picarones/pipeline/planner.py": 465,                 # actuel 403
+    # Sprint A14-S29 — ArtifactStore (ABC + 2 implémentations) avec
+    # hash multi-paramètres pour adresser la critique d'audit n° 14
+    # « hash multi-paramètres + reprise par hash ».
+    "picarones/adapters/storage/artifact_store.py": 580,  # actuel 504
     "picarones/core/corpus.py": 600,                      # actuel 511
     "picarones/fixtures.py": 600,                         # actuel 510
     "picarones/measurements/inter_engine.py": 575,        # actuel 484