refactor(domain): Sprint A14-S40 — PipelineSpec migré dans domain/

PipelineSpec et PipelineStep sont des types purs (dataclasses pydantic
frozen sans dépendance d'exécution). Le module canonique migre du
cercle 2 (picarones/pipeline/) vers le cercle 1 (picarones/domain/) où
vivent les autres types purs (Artifact, EvaluationView, ProjectionSpec,
ProvenanceRecord).

picarones/domain/pipeline_spec.py
---------------------------------
Module canonique. Contient PipelineStep, PipelineSpec, INITIAL_STEP_ID
inchangés (copie verbatim).

picarones/pipeline/spec.py
--------------------------
Devient un alias de chemin pur :
from picarones.domain.pipeline_spec import (
INITIAL_STEP_ID, PipelineSpec, PipelineStep,
)
+ __all__ identique.

Pas un shim au sens architectural (adaptation d'API incompatible) —
c'est un re-export de convenance pour ne pas casser les 13 callsites
qui importent depuis picarones.pipeline.spec.

picarones/domain/__init__.py
----------------------------
Re-exporte PipelineSpec, PipelineStep, INITIAL_STEP_ID au top-level.
Permet :
from picarones.domain import PipelineSpec # canonique
from picarones.domain.pipeline_spec import PipelineSpec # canonique
from picarones.pipeline.spec import PipelineSpec # alias
from picarones.pipeline import PipelineSpec # convenience

Tests S40 dédiés (5 nouveaux)
-----------------------------
- test_canonical_path_in_domain : import depuis domain.pipeline_spec.
- test_domain_top_level_reexports : import depuis domain.
- test_legacy_pipeline_path_aliased : import depuis pipeline.spec.
- test_all_paths_resolve_to_same_classes : `is` strict — toutes les
classes sont LE MÊME objet (pas une copie).
- test_pipeline_module_init_reexports_too : pipeline/ continue d'exposer.

Tests existants (87 pipeline + 622 domain/integration) : 100 %
préservés.

Tests : 4831 passed, 11 skipped (vs 4826 avant : +5 S40).
Lint : ruff check picarones/ tests/ → All checks passed.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

picarones/domain/__init__.py

@@ -57,6 +57,11 @@ from picarones.domain.evaluation_spec import (
     EvaluationView,
     MetricSpec,
 )
+from picarones.domain.pipeline_spec import (
+    INITIAL_STEP_ID,
+    PipelineSpec,
+    PipelineStep,
+)
 from picarones.domain.projection_spec import ProjectionSpec
 from picarones.domain.provenance import ProvenanceRecord
 from picarones.domain.run_manifest import RunManifest, utcnow
@@ -87,6 +92,10 @@ __all__ = [
     "EvaluationView",
     "EvaluationSpec",
     "ProjectionSpec",
+    # S6 + S40 — Pipeline spec (canonique en domain/ depuis S40)
+    "PipelineSpec",
+    "PipelineStep",
+    "INITIAL_STEP_ID",
     # S17 — Run manifest (pure domain ; RunResult vit dans app/)
     "RunManifest",
     "utcnow",

picarones/domain/pipeline_spec.py

@@ -0,0 +1,180 @@
+"""``PipelineStep`` et ``PipelineSpec`` — Sprints A14-S6 / S40.
+
+Description **purement déclarative** d'un DAG de transformation
+documentaire.  Sérialisable en YAML, versionnable en git, valide
+sans avoir besoin d'instancier les modules concrets.
+
+Sprint S40 — migration depuis ``picarones.pipeline.spec``
+---------------------------------------------------------
+Le module canonique est désormais en cercle 1 (``picarones/domain/``)
+— c'est un type pur qui n'a aucune dépendance d'exécution
+(``picarones/pipeline/`` qui contient le runtime n'est en fait pas
+nécessaire pour décrire la spec).  ``picarones.pipeline.spec`` reste
+exposé en re-export pour ne pas casser les callers existants — ce
+n'est pas un shim au sens architectural (adaptation d'une API
+incompatible) mais un alias de chemin.
+
+Différence avec l'ancien ``picarones.core.pipeline`` (Sprint 63)
+----------------------------------------------------------------
+L'ancien ``PipelineStep`` portait un champ ``module: BaseModule``
+— une **instance** d'objet exécutable.  Conséquence : la spec
+n'était pas sérialisable en YAML, et un test qui voulait juste
+valider la cohérence des types devait instancier des stubs.
+
+Ici, ``PipelineStep`` ne porte qu'un ``adapter_name: str``.  Le
+mapping ``nom → instance`` est maintenu par un service applicatif
+(``picarones.app.services.adapter_registry`` au S19) et résolu au
+moment de l'exécution, pas de la spec.
+
+Bénéfices :
+
+- Le YAML d'une pipeline composée est versionnable en git
+  indépendamment de l'environnement Python (BnF peut commit
+  ``ocr_llm_alto_remap.yaml`` sans imposer aux contributeurs
+  d'avoir tous les SDK installés).
+- ``validate_spec`` peut s'exécuter sans instancier aucun module
+  → tests rapides et déterministes.
+- Le rapport de reproductibilité peut citer le YAML exact, le
+  commit du code et la version des adapters utilisés —
+  séparation propre de la déclaration et de l'implémentation.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de typage des ``params`` par adapter ici (chaque adapter
+  validera ses propres params au moment de l'exécution).
+- Pas de versioning de spec — un nouveau champ se traduit par un
+  rebump pydantic.  Si on veut migrer entre versions de schéma,
+  on l'ajoutera quand le besoin sera concret.
+- Pas d'``outputs_preferred`` (mapping logique "preferred_text =
+  step3.RAW_TEXT").  Reporté quand un caller en aura concrètement
+  besoin.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from picarones.domain.artifacts import ArtifactType
+
+
+#: Identifiant d'étape — alphanum + ``_-``.  Doit être un nom court
+#: lisible par un humain dans les logs et le rapport.
+_STEP_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
+
+#: Sentinel pour ``inputs_from`` qui désigne les artefacts initiaux
+#: fournis au runner (typiquement ``IMAGE``).
+INITIAL_STEP_ID = "__initial__"
+
+
+class PipelineStep(BaseModel):
+    """Une étape déclarative dans un DAG de pipeline.
+
+    Attributs
+    ---------
+    id:
+        Identifiant unique de l'étape dans la pipeline (alphanum +
+        ``_-``).  Sert dans les logs, le rapport, et comme cible
+        des références ``inputs_from`` des étapes en aval.
+    kind:
+        Catégorie informationnelle de l'étape (``"ocr"``,
+        ``"post_correction"``, ``"alto_remapping"``,
+        ``"alto_reconstruction"``, etc.).  Pas de validation
+        d'enum — c'est un label libre que les services et le
+        rapport peuvent grouper.  Par convention, en
+        ``snake_case``.
+    adapter_name:
+        Nom de l'adapter dans le registre runtime (résolu par
+        ``app/services`` au S19).  Convention :
+        ``"<provider>:<engine_or_model>"`` (ex : ``"tesseract"``,
+        ``"openai:gpt-4o"``, ``"mistral:large"``,
+        ``"<vendor>:<custom_module>"``).
+    params:
+        Paramètres passés à l'adapter au moment de l'exécution.
+        Format libre (chaque adapter valide les siens) — typage
+        scalaire pour rester sérialisable en YAML.
+    input_types:
+        Types d'artefacts consommés par l'étape.  Validés par
+        ``validate_spec`` contre les outputs des étapes antérieures.
+    output_types:
+        Types d'artefacts produits.  Validés au runtime par
+        l'executor (qui vérifie que tous les types déclarés sont
+        bien dans le dict retourné par l'adapter).
+    inputs_from:
+        DAG branchant (héritage du Sprint 66).  Pour chaque type
+        d'entrée, désigne explicitement l'étape source.  La chaîne
+        spéciale ``"__initial__"`` désigne les entrées initiales
+        du runner.  Si le dict est vide, l'executor prend la
+        version la plus récente de chaque type dans le bag.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str = Field(min_length=1, max_length=128)
+    kind: str = Field(min_length=1, max_length=64)
+    adapter_name: str = Field(min_length=1, max_length=256)
+    params: dict[str, str | int | float | bool] = Field(default_factory=dict)
+    input_types: tuple[ArtifactType, ...] = Field(default_factory=tuple)
+    output_types: tuple[ArtifactType, ...] = Field(default_factory=tuple)
+    inputs_from: dict[ArtifactType, str] = Field(default_factory=dict)
+
+    @field_validator("id")
+    @classmethod
+    def _validate_step_id(cls, v: str) -> str:
+        if not _STEP_ID_RE.match(v):
+            from picarones.domain.errors import PicaronesError
+            raise PicaronesError(
+                f"step id invalide : {v!r}.  "
+                f"Doit matcher {_STEP_ID_RE.pattern!r} (alphanum + _-)."
+            )
+        if v == INITIAL_STEP_ID:
+            from picarones.domain.errors import PicaronesError
+            raise PicaronesError(
+                f"step id réservé : {INITIAL_STEP_ID!r} désigne "
+                "les entrées initiales du runner."
+            )
+        return v
+
+
+class PipelineSpec(BaseModel):
+    """DAG déclaratif d'une pipeline composée.
+
+    Sérialisable en YAML via ``model_dump()`` + ``yaml.safe_dump``,
+    chargeable via ``model_validate(yaml.safe_load(text))``.  Le
+    round-trip est testé.
+
+    Attributs
+    ---------
+    name:
+        Nom court de la pipeline (utilisé dans les logs, le cache,
+        le rapport).  Convention ``snake_case``.
+    description:
+        Phrase courte d'introduction affichée dans le rapport.
+    initial_inputs:
+        Types d'artefacts qui doivent être fournis par le caller
+        au moment de l'exécution.  Convention : ``(IMAGE,)`` pour
+        une pipeline OCR classique, ``(IMAGE, RAW_TEXT)`` pour
+        une post-correction qui part d'un OCR pré-calculé.
+    steps:
+        Étapes du DAG, ordonnées par dépendance topologique
+        d'exécution.  Si une étape ``s2`` dépend de ``s1``, alors
+        ``s1`` apparaît avant ``s2``.  ``validate_spec`` détecte
+        les violations.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str = Field(min_length=1, max_length=128)
+    description: str = ""
+    initial_inputs: tuple[ArtifactType, ...] = Field(default_factory=tuple)
+    steps: tuple[PipelineStep, ...] = Field(default_factory=tuple)
+
+    def step_by_id(self, step_id: str) -> PipelineStep | None:
+        for s in self.steps:
+            if s.id == step_id:
+                return s
+        return None
+
+
+__all__ = ["PipelineStep", "PipelineSpec", "INITIAL_STEP_ID"]

picarones/pipeline/spec.py

@@ -1,170 +1,25 @@
-"""``PipelineStep`` et ``PipelineSpec`` — Sprint A14-S6.
+"""``PipelineStep`` et ``PipelineSpec`` — re-export depuis ``domain``.
 
-Description **purement déclarative** d'un DAG de transformation
-documentaire.  Sérialisable en YAML, versionnable en git, valide
-sans avoir besoin d'instancier les modules concrets.
+Sprint A14-S40 a migré le module canonique vers
+``picarones.domain.pipeline_spec`` (cercle 1, types purs).  Ce
+module reste un alias de chemin pour ne pas casser les callers
+existants — ce n'est pas un shim au sens architectural
+(adaptation d'une API incompatible) mais une convenance de chemin.
 
-Différence avec l'ancien ``picarones.core.pipeline`` (Sprint 63)
-----------------------------------------------------------------
-L'ancien ``PipelineStep`` portait un champ ``module: BaseModule``
-— une **instance** d'objet exécutable.  Conséquence : la spec
-n'était pas sérialisable en YAML, et un test qui voulait juste
-valider la cohérence des types devait instancier des stubs.
+Les nouveaux callers doivent importer directement depuis
+``picarones.domain`` :
 
-Ici, ``PipelineStep`` ne porte qu'un ``adapter_name: str``.  Le
-mapping ``nom → instance`` est maintenu par un service applicatif
-(``picarones.app.services.adapter_registry`` au S19) et résolu au
-moment de l'exécution, pas de la spec.
+::
 
-Bénéfices :
-
-- Le YAML d'une pipeline composée est versionnable en git
-  indépendamment de l'environnement Python (BnF peut commit
-  ``ocr_llm_alto_remap.yaml`` sans imposer aux contributeurs
-  d'avoir tous les SDK installés).
-- ``validate_spec`` peut s'exécuter sans instancier aucun module
-  → tests rapides et déterministes.
-- Le rapport de reproductibilité peut citer le YAML exact, le
-  commit du code et la version des adapters utilisés —
-  séparation propre de la déclaration et de l'implémentation.
-
-Anti-sur-ingénierie
--------------------
-- Pas de typage des ``params`` par adapter ici (chaque adapter
-  validera ses propres params au moment de l'exécution).
-- Pas de versioning de spec — un nouveau champ se traduit par un
-  rebump pydantic.  Si on veut migrer entre versions de schéma,
-  on l'ajoutera quand le besoin sera concret.
-- Pas d'``outputs_preferred`` (mapping logique "preferred_text =
-  step3.RAW_TEXT").  Reporté quand un caller en aura concrètement
-  besoin.
+    from picarones.domain import PipelineSpec, PipelineStep, INITIAL_STEP_ID
 """
 
 from __future__ import annotations
 
-import re
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-from picarones.domain.artifacts import ArtifactType
-
-
-#: Identifiant d'étape — alphanum + ``_-``.  Doit être un nom court
-#: lisible par un humain dans les logs et le rapport.
-_STEP_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
-
-#: Sentinel pour ``inputs_from`` qui désigne les artefacts initiaux
-#: fournis au runner (typiquement ``IMAGE``).
-INITIAL_STEP_ID = "__initial__"
-
-
-class PipelineStep(BaseModel):
-    """Une étape déclarative dans un DAG de pipeline.
-
-    Attributs
-    ---------
-    id:
-        Identifiant unique de l'étape dans la pipeline (alphanum +
-        ``_-``).  Sert dans les logs, le rapport, et comme cible
-        des références ``inputs_from`` des étapes en aval.
-    kind:
-        Catégorie informationnelle de l'étape (``"ocr"``,
-        ``"post_correction"``, ``"alto_remapping"``,
-        ``"alto_reconstruction"``, etc.).  Pas de validation
-        d'enum — c'est un label libre que les services et le
-        rapport peuvent grouper.  Par convention, en
-        ``snake_case``.
-    adapter_name:
-        Nom de l'adapter dans le registre runtime (résolu par
-        ``app/services`` au S19).  Convention :
-        ``"<provider>:<engine_or_model>"`` (ex : ``"tesseract"``,
-        ``"openai:gpt-4o"``, ``"mistral:large"``,
-        ``"<vendor>:<custom_module>"``).
-    params:
-        Paramètres passés à l'adapter au moment de l'exécution.
-        Format libre (chaque adapter valide les siens) — typage
-        scalaire pour rester sérialisable en YAML.
-    input_types:
-        Types d'artefacts consommés par l'étape.  Validés par
-        ``validate_spec`` contre les outputs des étapes antérieures.
-    output_types:
-        Types d'artefacts produits.  Validés au runtime par
-        l'executor (qui vérifie que tous les types déclarés sont
-        bien dans le dict retourné par l'adapter).
-    inputs_from:
-        DAG branchant (héritage du Sprint 66).  Pour chaque type
-        d'entrée, désigne explicitement l'étape source.  La chaîne
-        spéciale ``"__initial__"`` désigne les entrées initiales
-        du runner.  Si le dict est vide, l'executor prend la
-        version la plus récente de chaque type dans le bag.
-    """
-
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    id: str = Field(min_length=1, max_length=128)
-    kind: str = Field(min_length=1, max_length=64)
-    adapter_name: str = Field(min_length=1, max_length=256)
-    params: dict[str, str | int | float | bool] = Field(default_factory=dict)
-    input_types: tuple[ArtifactType, ...] = Field(default_factory=tuple)
-    output_types: tuple[ArtifactType, ...] = Field(default_factory=tuple)
-    inputs_from: dict[ArtifactType, str] = Field(default_factory=dict)
-
-    @field_validator("id")
-    @classmethod
-    def _validate_step_id(cls, v: str) -> str:
-        if not _STEP_ID_RE.match(v):
-            from picarones.domain.errors import PicaronesError
-            raise PicaronesError(
-                f"step id invalide : {v!r}.  "
-                f"Doit matcher {_STEP_ID_RE.pattern!r} (alphanum + _-)."
-            )
-        if v == INITIAL_STEP_ID:
-            from picarones.domain.errors import PicaronesError
-            raise PicaronesError(
-                f"step id réservé : {INITIAL_STEP_ID!r} désigne "
-                "les entrées initiales du runner."
-            )
-        return v
-
-
-class PipelineSpec(BaseModel):
-    """DAG déclaratif d'une pipeline composée.
-
-    Sérialisable en YAML via ``model_dump()`` + ``yaml.safe_dump``,
-    chargeable via ``model_validate(yaml.safe_load(text))``.  Le
-    round-trip est testé.
-
-    Attributs
-    ---------
-    name:
-        Nom court de la pipeline (utilisé dans les logs, le cache,
-        le rapport).  Convention ``snake_case``.
-    description:
-        Phrase courte d'introduction affichée dans le rapport.
-    initial_inputs:
-        Types d'artefacts qui doivent être fournis par le caller
-        au moment de l'exécution.  Convention : ``(IMAGE,)`` pour
-        une pipeline OCR classique, ``(IMAGE, RAW_TEXT)`` pour
-        une post-correction qui part d'un OCR pré-calculé.
-    steps:
-        Étapes du DAG, ordonnées par dépendance topologique
-        d'exécution.  Si une étape ``s2`` dépend de ``s1``, alors
-        ``s1`` apparaît avant ``s2``.  ``validate_spec`` détecte
-        les violations.
-    """
-
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    name: str = Field(min_length=1, max_length=128)
-    description: str = ""
-    initial_inputs: tuple[ArtifactType, ...] = Field(default_factory=tuple)
-    steps: tuple[PipelineStep, ...] = Field(default_factory=tuple)
-
-    def step_by_id(self, step_id: str) -> PipelineStep | None:
-        for s in self.steps:
-            if s.id == step_id:
-                return s
-        return None
-
+from picarones.domain.pipeline_spec import (
+    INITIAL_STEP_ID,
+    PipelineSpec,
+    PipelineStep,
+)
 
 __all__ = ["PipelineStep", "PipelineSpec", "INITIAL_STEP_ID"]

tests/domain/test_sprint_a14_s40_pipeline_spec_in_domain.py

@@ -0,0 +1,81 @@
+"""Sprint A14-S40 — PipelineSpec migré dans domain/.
+
+Vérifie que :
+
+1. ``picarones.domain.pipeline_spec`` est le module canonique.
+2. ``picarones.domain`` re-exporte ``PipelineSpec``, ``PipelineStep``,
+   ``INITIAL_STEP_ID``.
+3. ``picarones.pipeline.spec`` continue d'exposer les mêmes classes
+   (alias de chemin pour la rétrocompat).
+4. Les deux chemins d'import retournent **la même classe**
+   (``is`` strict, pas seulement ``==``).
+"""
+
+from __future__ import annotations
+
+
+def test_canonical_path_in_domain() -> None:
+    """``picarones.domain.pipeline_spec`` expose les classes canoniques."""
+    from picarones.domain.pipeline_spec import (
+        INITIAL_STEP_ID,
+        PipelineSpec,
+        PipelineStep,
+    )
+    assert PipelineSpec is not None
+    assert PipelineStep is not None
+    assert INITIAL_STEP_ID == "__initial__"
+
+
+def test_domain_top_level_reexports() -> None:
+    """``picarones.domain`` re-exporte au top-level."""
+    from picarones.domain import (
+        INITIAL_STEP_ID,
+        PipelineSpec,
+        PipelineStep,
+    )
+    assert PipelineSpec is not None
+    assert PipelineStep is not None
+    assert INITIAL_STEP_ID == "__initial__"
+
+
+def test_legacy_pipeline_path_aliased() -> None:
+    """``picarones.pipeline.spec`` reste un alias de chemin."""
+    from picarones.pipeline.spec import (
+        INITIAL_STEP_ID,
+        PipelineSpec,
+        PipelineStep,
+    )
+    assert PipelineSpec is not None
+    assert PipelineStep is not None
+    assert INITIAL_STEP_ID == "__initial__"
+
+
+def test_all_paths_resolve_to_same_classes() -> None:
+    """Les imports depuis les 3 emplacements pointent vers le MÊME objet."""
+    from picarones.domain import PipelineSpec as DomainSpec
+    from picarones.domain import PipelineStep as DomainStep
+    from picarones.domain import INITIAL_STEP_ID as DomainInitial
+    from picarones.domain.pipeline_spec import PipelineSpec as CanonSpec
+    from picarones.domain.pipeline_spec import PipelineStep as CanonStep
+    from picarones.pipeline.spec import PipelineSpec as LegacySpec
+    from picarones.pipeline.spec import PipelineStep as LegacyStep
+    from picarones.pipeline.spec import INITIAL_STEP_ID as LegacyInitial
+
+    # is strict — toutes les classes pointent vers le même objet.
+    assert DomainSpec is CanonSpec
+    assert DomainSpec is LegacySpec
+    assert DomainStep is CanonStep
+    assert DomainStep is LegacyStep
+    assert DomainInitial == LegacyInitial
+
+
+def test_pipeline_module_init_reexports_too() -> None:
+    """``picarones.pipeline`` continue d'exposer pour rétrocompat."""
+    from picarones.pipeline import PipelineSpec, PipelineStep, INITIAL_STEP_ID
+    from picarones.domain.pipeline_spec import (
+        PipelineSpec as CanonSpec,
+        PipelineStep as CanonStep,
+    )
+    assert PipelineSpec is CanonSpec
+    assert PipelineStep is CanonStep
+    assert INITIAL_STEP_ID == "__initial__"