feat(domain): Deadline — contrat de timeout propagé cross-process

Type valeur pur en couche 1, propagé via RunContext aux adapters
(cf. ADR-0001). Représente soit une échéance monotonic absolue,
soit l'absence de contrainte temporelle (``infinite``).

## Propriétés garanties

- **Immuable** : ``__slots__`` + ``__setattr__`` qui lève
``AttributeError``. Hashable, donc utilisable comme clé de dict
ou élément de set.
- **Cross-process safe** : ``__getstate__`` / ``__setstate__``
convertissent vers ``remaining_seconds`` au moment du transfert
(pickle) ; ``to_dict`` / ``from_dict`` même pattern pour JSON.
Conséquence : un overhead de dispatch de N secondes n'est PAS
facturé au worker — le budget visible côté receveur est le
budget *au moment du handoff*, pas le budget original. Le
wall-clock total peut excéder le budget original par l'overhead
de dispatch, mais le contrat de durée vue par l'adapter est
respecté.
- **Numériquement défensif** : ``remaining_seconds()`` ne retourne
jamais de négatif (``max(0.0, ...)``). ``clamp_to_remaining``
borne un délai par le budget restant (utile pour le backoff
retry de Phase 3).
- **Validations strictes** : ``in_seconds(budget <= 0)`` rejeté ;
``from_dict`` validate la structure du dict ; constructeurs
hostiles aux types non-numériques.

## API

- ``Deadline.infinite()`` — pas d'échéance.
- ``Deadline.in_seconds(budget)`` — échéance dans budget secondes.
- ``Deadline.at_monotonic(t)`` — instant monotonic absolu (tests).
- ``deadline.remaining_seconds()`` — None si infinie.
- ``deadline.is_expired()``, ``deadline.is_infinite``.
- ``deadline.as_sdk_timeout()`` — valeur pour ``httpx.timeout=``,
``pytesseract.timeout=``, etc. Nom explicite pour l'intention
au call-site adapter (Phase 3).
- ``deadline.clamp_to_remaining(seconds)`` — borne un délai.
- ``deadline.to_dict()`` / ``Deadline.from_dict(d)`` — sérialisation
IPC/JSON, utilisée par ``RunManifest`` à Phase 8 et par le
dispatch IPC du SubprocessExecutor à Phase 5.

## Validation

- 50/50 tests covering construction, query, cross-process semantics
(pickle + to_dict/from_dict avec sleep entre handoff prouvant la
non-facturation du dispatch), immutability, dunder protocols, et
patterns d'usage réalistes (retry loop, SDK timeout, backoff clamp).
- mypy strict sur ``picarones/domain/`` passe (annotation de classe
explicite des ``__slots__`` requise).
- Sprint narrative ratchet inchangé (formulation par intention, pas
par phase — l'historique vit dans CHANGELOG + ADR-0001).
- 181 tests architecture, 154 tests pipeline, 129 tests domain :
aucune régression.

Import canonique : ``from picarones.domain import Deadline``.
Pas exposé au top-level ``picarones`` — c'est un contrat interne
pour la couche pipeline + adapters, pas une API consommée par les
utilisateurs externes.

https://claude.ai/code/session_01B93huMjNh4CG2rNcexgDeL

picarones/domain/__init__.py

@@ -46,6 +46,7 @@ from __future__ import annotations
 from picarones.domain.artifact_key import ArtifactKey
 from picarones.domain.artifacts import Artifact, ArtifactType, compute_content_hash
 from picarones.domain.corpus import CorpusSpec
+from picarones.domain.deadline import Deadline
 from picarones.domain.documents import DocumentRef, GroundTruthRef
 from picarones.domain.errors import (
     ArtifactValidationError,
@@ -91,6 +92,8 @@ __all__ = [
     "CorpusSpec",
     "DocumentRef",
     "GroundTruthRef",
+    # Contrat de timeout propagé cross-process (cf. ADR-0001)
+    "Deadline",
     # S4 — Provenance
     "ProvenanceRecord",
     # S4 — Errors

picarones/domain/deadline.py

@@ -0,0 +1,320 @@
+"""``Deadline`` — type pur représentant une échéance d'opération.
+
+Contrat de timeout propagé cross-process à travers la couche
+adapters.  Voir
+[ADR-0001](../../docs/explanation/adr/0001-multi-domain-execution.md)
+pour la motivation architecturale et la sémantique étendue
+(multi-domaines d'exécution, terminaison structurée).
+
+Sémantique
+----------
+
+Une ``Deadline`` est soit **infinie** (aucune contrainte temporelle),
+soit **finie** avec une expiration absolue exprimée dans l'horloge
+monotonic du process courant.
+
+L'horloge monotonic (``time.monotonic()``) :
+
+- ne recule jamais (à la différence de ``time.time()`` qui peut
+  sauter avec NTP),
+- a une origine **arbitraire et privée au process** — l'instant
+  ``t=0.0`` ne correspond à rien de comparable entre processes.
+
+Cross-process : la sérialisation (pickle, JSON) convertit
+automatiquement vers ``remaining_seconds`` au moment du transfert.
+À la réception, une nouvelle ``Deadline`` est construite relativement
+à l'horloge monotonic du process receveur.  Conséquence : un overhead
+de dispatch de 5 secondes n'est pas facturé au worker — le budget
+qu'il voit est le budget restant au moment du handoff, pas le budget
+original.  Le wall-clock total peut donc dépasser le budget original
+par l'overhead de dispatch.
+
+Si un workflow nécessite une deadline **absolue cross-process**
+(rare ; un soak test global par exemple), passer par wall-clock
+(``time.time_ns()``) à la place — non couvert par ce type pour
+éviter la confusion sémantique.
+
+Usage typique
+-------------
+
+::
+
+    deadline = Deadline.in_seconds(60.0)
+    # ... travail ...
+    if deadline.is_expired():
+        raise DeadlineExceeded(...)
+    remaining = deadline.remaining_seconds()  # 54.8
+    sdk_call(timeout=deadline.as_sdk_timeout())
+
+API publique
+------------
+
+- ``Deadline.infinite()`` — pas d'échéance.
+- ``Deadline.in_seconds(budget)`` — échéance dans ``budget`` secondes.
+- ``Deadline.at_monotonic(t)`` — échéance à l'instant monotonic ``t``
+  (rare ; surtout pour les tests qui veulent une deadline déjà
+  expirée).
+- ``deadline.remaining_seconds()`` — ``None`` si infinie, sinon
+  ``max(0.0, expires - now)``.
+- ``deadline.is_expired()`` — ``False`` si infinie, sinon
+  ``now >= expires``.
+- ``deadline.is_infinite`` — propriété booléenne.
+- ``deadline.as_sdk_timeout()`` — valeur à passer à un SDK
+  (``httpx.timeout=``, ``pytesseract.timeout=``).  Identique à
+  ``remaining_seconds()`` ; nom explicite pour l'intention.
+- ``deadline.clamp_to_remaining(seconds)`` — borne ``seconds`` par
+  le budget restant.  Utile pour le retry backoff qui ne doit pas
+  dépasser la deadline.
+
+Limitations assumées
+--------------------
+
+- Pas de hiérarchie de deadlines (sub-deadline d'un step plus serrée
+  que celle du doc) : le caller construit explicitement
+  ``Deadline.in_seconds(min(step_budget, parent.remaining_seconds()))``.
+- Pas de wall-clock — uniquement monotonic.
+- Pas de notification d'expiration (pas de signal/callback).  Les
+  consommateurs polling via ``is_expired()`` ou check via
+  ``remaining_seconds()`` avant chaque opération bloquante.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from picarones.domain.errors import PicaronesError
+
+
+class Deadline:
+    """Type valeur immuable représentant une échéance d'opération.
+
+    Voir le module docstring pour la sémantique complète et l'usage.
+    """
+
+    # Annotation de classe nécessaire en plus de ``__slots__`` pour
+    # que mypy résolve les accès à l'attribut (l'assignation passe
+    # par ``object.__setattr__`` à cause de l'immutabilité, mypy ne
+    # peut pas l'inférer du seul ``__slots__``).
+    _expires_at_monotonic: float | None
+    __slots__ = ("_expires_at_monotonic",)
+
+    # Le constructeur public est ``__init__`` mais on attend qu'il
+    # soit appelé avec ``expires_at_monotonic: float | None`` — c'est
+    # un détail d'implémentation, les callers utilisent les
+    # classmethods (``infinite``, ``in_seconds``, ``at_monotonic``).
+
+    def __init__(self, expires_at_monotonic: float | None) -> None:
+        if expires_at_monotonic is not None and not isinstance(
+            expires_at_monotonic, (int, float),
+        ):
+            raise PicaronesError(
+                f"Deadline : expires_at_monotonic doit être float ou None, "
+                f"reçu {type(expires_at_monotonic).__name__}",
+            )
+        object.__setattr__(
+            self, "_expires_at_monotonic",
+            float(expires_at_monotonic) if expires_at_monotonic is not None
+            else None,
+        )
+
+    # ──────────────────────────────────────────────────────────────────
+    # Constructeurs
+    # ──────────────────────────────────────────────────────────────────
+
+    @classmethod
+    def infinite(cls) -> "Deadline":
+        """Pas d'échéance — ``remaining_seconds()`` retourne ``None``
+        et ``is_expired()`` retourne ``False``."""
+        return cls(expires_at_monotonic=None)
+
+    @classmethod
+    def in_seconds(cls, budget: float) -> "Deadline":
+        """Échéance dans ``budget`` secondes à partir de maintenant.
+
+        ``budget`` doit être > 0.  Une valeur de 0 est rejetée parce
+        qu'elle représente une expiration immédiate inutile en
+        pratique (préfère ``Deadline.at_monotonic(0)`` pour tester
+        une deadline déjà expirée).
+        """
+        if not isinstance(budget, (int, float)):
+            raise PicaronesError(
+                f"Deadline.in_seconds : budget doit être numérique, "
+                f"reçu {type(budget).__name__}",
+            )
+        if budget <= 0:
+            raise PicaronesError(
+                f"Deadline.in_seconds : budget doit être > 0 "
+                f"(reçu {budget}).  Pour une deadline déjà expirée "
+                f"en test, utiliser ``Deadline.at_monotonic(0.0)``.",
+            )
+        return cls(expires_at_monotonic=time.monotonic() + float(budget))
+
+    @classmethod
+    def at_monotonic(cls, expires_at: float) -> "Deadline":
+        """Échéance à l'instant monotonic absolu ``expires_at``.
+
+        Surtout utile en tests pour construire des deadlines déjà
+        expirées (``at_monotonic(0.0)``) ou très lointaines
+        (``at_monotonic(time.monotonic() + 3600)``).
+        """
+        return cls(expires_at_monotonic=expires_at)
+
+    # ──────────────────────────────────────────────────────────────────
+    # Interrogation
+    # ──────────────────────────────────────────────────────────────────
+
+    @property
+    def is_infinite(self) -> bool:
+        return self._expires_at_monotonic is None
+
+    def remaining_seconds(self) -> float | None:
+        """Secondes restantes avant expiration, ou ``None`` si infinie.
+
+        Ne retourne jamais de valeur négative : ``max(0.0, ...)``.
+        """
+        if self._expires_at_monotonic is None:
+            return None
+        return max(0.0, self._expires_at_monotonic - time.monotonic())
+
+    def is_expired(self) -> bool:
+        if self._expires_at_monotonic is None:
+            return False
+        return time.monotonic() >= self._expires_at_monotonic
+
+    def as_sdk_timeout(self) -> float | None:
+        """Valeur à passer à un SDK comme paramètre ``timeout=``.
+
+        Identique à ``remaining_seconds()`` ; le nom explicite
+        l'intention au call-site (``sdk.call(timeout=deadline.as_sdk_timeout())``).
+        """
+        return self.remaining_seconds()
+
+    def clamp_to_remaining(self, seconds: float) -> float:
+        """Retourne ``min(seconds, remaining_seconds())``.
+
+        Si infinie, retourne ``seconds`` tel quel.  Utile pour borner
+        le backoff d'un retry helper qui ne doit pas dépasser le
+        budget restant.
+
+        ``seconds`` doit être >= 0.
+        """
+        if seconds < 0:
+            raise PicaronesError(
+                f"Deadline.clamp_to_remaining : seconds doit être >= 0 "
+                f"(reçu {seconds})",
+            )
+        if self._expires_at_monotonic is None:
+            return seconds
+        # ``remaining_seconds()`` retourne ``float`` ici (pas ``None``)
+        # puisqu'on vient de vérifier que la deadline est finie — le
+        # narrower de type est explicite pour mypy.
+        remaining = self.remaining_seconds()
+        assert remaining is not None
+        return min(seconds, remaining)
+
+    # ──────────────────────────────────────────────────────────────────
+    # Sérialisation cross-process
+    # ──────────────────────────────────────────────────────────────────
+    #
+    # ``expires_at_monotonic`` n'a aucun sens dans un autre process
+    # (chaque process a son origine monotonic privée).  On sérialise
+    # toujours via ``remaining_seconds`` qui est, lui, transposable :
+    # à la réception, on reconstruit un ``Deadline`` relatif à
+    # l'horloge monotonic du process receveur.
+
+    def to_dict(self) -> dict[str, float | None]:
+        """Forme sérialisable JSON / IPC.
+
+        ``{"remaining_seconds": float | None}``.  ``None`` = infinie.
+        """
+        return {"remaining_seconds": self.remaining_seconds()}
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Deadline":
+        """Reconstruit une ``Deadline`` depuis sa forme sérialisée.
+
+        Lève ``PicaronesError`` si ``data`` n'a pas la forme
+        attendue ou contient un type incorrect.
+        """
+        if not isinstance(data, dict):
+            raise PicaronesError(
+                f"Deadline.from_dict : data doit être un dict, "
+                f"reçu {type(data).__name__}",
+            )
+        if "remaining_seconds" not in data:
+            raise PicaronesError(
+                "Deadline.from_dict : clé 'remaining_seconds' "
+                "manquante.",
+            )
+        r = data["remaining_seconds"]
+        if r is None:
+            return cls.infinite()
+        if not isinstance(r, (int, float)):
+            raise PicaronesError(
+                f"Deadline.from_dict : remaining_seconds doit être "
+                f"numérique ou None, reçu {type(r).__name__}",
+            )
+        if r <= 0:
+            # Une deadline reçue avec budget ≤ 0 est déjà expirée
+            # côté émetteur.  On reconstruit une deadline expirée
+            # (pas d'erreur — c'est un état valide, juste rare).
+            return cls.at_monotonic(time.monotonic())
+        return cls.in_seconds(float(r))
+
+    # Pickle support : utilise le même protocole de transposition
+    # que ``to_dict`` / ``from_dict``.
+
+    def __getstate__(self) -> dict[str, float | None]:
+        return self.to_dict()
+
+    def __setstate__(self, state: dict[str, float | None]) -> None:
+        r = state.get("remaining_seconds")
+        if r is None:
+            object.__setattr__(self, "_expires_at_monotonic", None)
+        elif r <= 0:
+            # Cohérent avec ``from_dict`` : reconstruit comme expirée.
+            object.__setattr__(
+                self, "_expires_at_monotonic", time.monotonic(),
+            )
+        else:
+            object.__setattr__(
+                self, "_expires_at_monotonic", time.monotonic() + float(r),
+            )
+
+    # ──────────────────────────────────────────────────────────────────
+    # Dunder — immutabilité, égalité, repr
+    # ──────────────────────────────────────────────────────────────────
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError(
+            f"Deadline est immuable — impossible d'assigner {name!r}",
+        )
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError(
+            f"Deadline est immuable — impossible de supprimer {name!r}",
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Deadline):
+            return NotImplemented
+        # Égalité **stricte** sur ``expires_at_monotonic`` — deux
+        # ``Deadline.in_seconds(60)`` créées à des instants différents
+        # ne sont PAS égales.  L'égalité sur ``remaining_seconds()``
+        # serait dépendante du moment du check, donc instable.
+        return self._expires_at_monotonic == other._expires_at_monotonic
+
+    def __hash__(self) -> int:
+        return hash(self._expires_at_monotonic)
+
+    def __repr__(self) -> str:
+        if self._expires_at_monotonic is None:
+            return "Deadline.infinite()"
+        remaining = self.remaining_seconds()
+        if remaining is None or remaining <= 0.0:
+            return "Deadline(expired)"
+        return f"Deadline(remaining={remaining:.3f}s)"
+
+
+__all__ = ["Deadline"]

tests/domain/test_deadline.py

@@ -0,0 +1,393 @@
+"""Tests de ``picarones.domain.deadline.Deadline``.
+
+Phase 1 du chantier de refonte du modèle d'exécution.  Le type est
+pur (stdlib + PicaronesError uniquement), donc le suite couvre
+exhaustivement :
+
+- Construction (infinite, in_seconds, at_monotonic) + rejets.
+- Interrogation (remaining_seconds, is_expired, is_infinite,
+  as_sdk_timeout, clamp_to_remaining).
+- Sérialisation cross-process (to_dict / from_dict / pickle).
+- Immutabilité (setattr, delattr).
+- Égalité / hash / repr.
+- Garanties critiques cross-process (l'overhead de dispatch ne
+  facture pas le worker).
+"""
+
+from __future__ import annotations
+
+import pickle
+import time
+
+import pytest
+
+from picarones.domain.deadline import Deadline
+from picarones.domain.errors import PicaronesError
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Construction
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestConstruction:
+    def test_infinite_is_infinite(self) -> None:
+        d = Deadline.infinite()
+        assert d.is_infinite is True
+        assert d.remaining_seconds() is None
+        assert d.is_expired() is False
+
+    def test_in_seconds_positive_budget(self) -> None:
+        d = Deadline.in_seconds(60.0)
+        assert d.is_infinite is False
+        # Marge de scheduling : remaining doit être ~60s mais peut
+        # avoir perdu quelques ms entre construction et check.
+        r = d.remaining_seconds()
+        assert r is not None
+        assert 59.0 < r <= 60.0
+
+    def test_in_seconds_int_budget_accepted(self) -> None:
+        """int est coercé en float."""
+        d = Deadline.in_seconds(30)
+        assert d.is_infinite is False
+        assert d.remaining_seconds() is not None
+
+    def test_in_seconds_zero_rejected(self) -> None:
+        with pytest.raises(PicaronesError, match="budget doit être > 0"):
+            Deadline.in_seconds(0)
+
+    def test_in_seconds_negative_rejected(self) -> None:
+        with pytest.raises(PicaronesError, match="budget doit être > 0"):
+            Deadline.in_seconds(-1.0)
+
+    def test_in_seconds_non_numeric_rejected(self) -> None:
+        with pytest.raises(PicaronesError, match="budget doit être numérique"):
+            Deadline.in_seconds("60")  # type: ignore[arg-type]
+
+    def test_at_monotonic_in_past_is_expired(self) -> None:
+        """Une deadline absolue dans le passé est valide ET expirée."""
+        d = Deadline.at_monotonic(0.0)
+        assert d.is_expired() is True
+        assert d.remaining_seconds() == 0.0
+
+    def test_at_monotonic_in_future_not_expired(self) -> None:
+        d = Deadline.at_monotonic(time.monotonic() + 100.0)
+        assert d.is_expired() is False
+        assert d.remaining_seconds() > 0
+
+    def test_direct_constructor_rejects_wrong_type(self) -> None:
+        with pytest.raises(PicaronesError, match="doit être float ou None"):
+            Deadline(expires_at_monotonic="now")  # type: ignore[arg-type]
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Interrogation
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestQuery:
+    def test_remaining_seconds_never_negative(self) -> None:
+        """Une deadline expirée retourne 0.0, pas une valeur négative."""
+        d = Deadline.at_monotonic(0.0)
+        assert d.remaining_seconds() == 0.0
+
+    def test_is_expired_transitions_after_time_passes(self) -> None:
+        d = Deadline.in_seconds(0.05)  # 50ms
+        assert d.is_expired() is False
+        time.sleep(0.1)
+        assert d.is_expired() is True
+
+    def test_as_sdk_timeout_matches_remaining_seconds(self) -> None:
+        d = Deadline.in_seconds(10.0)
+        # Les deux peuvent légèrement différer si appelés à des
+        # instants différents — on vérifie qu'ils sont du même ordre.
+        a = d.as_sdk_timeout()
+        b = d.remaining_seconds()
+        assert a is not None and b is not None
+        assert abs(a - b) < 0.1
+
+    def test_as_sdk_timeout_infinite_returns_none(self) -> None:
+        assert Deadline.infinite().as_sdk_timeout() is None
+
+    def test_clamp_to_remaining_clamps_when_seconds_exceeds(self) -> None:
+        d = Deadline.in_seconds(0.5)
+        clamped = d.clamp_to_remaining(10.0)
+        assert clamped <= 0.5
+
+    def test_clamp_to_remaining_returns_seconds_when_under(self) -> None:
+        d = Deadline.in_seconds(60.0)
+        assert d.clamp_to_remaining(1.0) == 1.0
+
+    def test_clamp_to_remaining_infinite_returns_seconds(self) -> None:
+        assert Deadline.infinite().clamp_to_remaining(5.0) == 5.0
+
+    def test_clamp_to_remaining_rejects_negative(self) -> None:
+        d = Deadline.in_seconds(10.0)
+        with pytest.raises(PicaronesError, match="seconds doit être >= 0"):
+            d.clamp_to_remaining(-1.0)
+
+    def test_clamp_to_remaining_zero_is_zero(self) -> None:
+        """clamp(0) = 0 — pas d'erreur, c'est un cas valide
+        (ex : pas de wait avant retry)."""
+        d = Deadline.in_seconds(10.0)
+        assert d.clamp_to_remaining(0.0) == 0.0
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Sérialisation cross-process — propriété critique
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestCrossProcessSerialization:
+    """La promesse centrale : un overhead de dispatch (sleep entre
+    sérialisation et désérialisation) n'est PAS facturé au worker.
+    Le budget que voit le worker est le budget restant *au moment du
+    handoff*, pas le budget original.
+
+    C'est la propriété qui rend ``Deadline`` utilisable cross-process
+    et qui justifie de ne PAS sérialiser ``expires_at_monotonic``.
+    """
+
+    def test_to_dict_infinite(self) -> None:
+        d = Deadline.infinite()
+        assert d.to_dict() == {"remaining_seconds": None}
+
+    def test_to_dict_finite(self) -> None:
+        d = Deadline.in_seconds(60.0)
+        out = d.to_dict()
+        assert "remaining_seconds" in out
+        assert 59.0 < out["remaining_seconds"] <= 60.0
+
+    def test_from_dict_infinite(self) -> None:
+        d = Deadline.from_dict({"remaining_seconds": None})
+        assert d.is_infinite is True
+
+    def test_from_dict_finite(self) -> None:
+        d = Deadline.from_dict({"remaining_seconds": 30.0})
+        r = d.remaining_seconds()
+        assert r is not None
+        assert 29.0 < r <= 30.0
+
+    def test_from_dict_negative_treated_as_expired(self) -> None:
+        d = Deadline.from_dict({"remaining_seconds": -5.0})
+        assert d.is_expired() is True
+
+    def test_from_dict_zero_treated_as_expired(self) -> None:
+        d = Deadline.from_dict({"remaining_seconds": 0.0})
+        assert d.is_expired() is True
+
+    def test_from_dict_rejects_non_dict(self) -> None:
+        with pytest.raises(PicaronesError, match="doit être un dict"):
+            Deadline.from_dict("60")  # type: ignore[arg-type]
+
+    def test_from_dict_rejects_missing_key(self) -> None:
+        with pytest.raises(PicaronesError, match="clé 'remaining_seconds'"):
+            Deadline.from_dict({"other": 1})
+
+    def test_from_dict_rejects_non_numeric(self) -> None:
+        with pytest.raises(PicaronesError, match="doit être numérique"):
+            Deadline.from_dict({"remaining_seconds": "60"})
+
+    def test_dispatch_overhead_not_charged_to_worker(self) -> None:
+        """Propriété critique : créer une deadline de 60s, simuler
+        un dispatch (sleep 0.5s), désérialiser → le receveur voit
+        un budget *non* réduit par le sleep, parce qu'on transmet
+        le ``remaining_seconds`` au moment du handoff, pas du
+        moment de la création."""
+        original = Deadline.in_seconds(60.0)
+        # On capture le serialized maintenant (= au moment du handoff
+        # côté émetteur).
+        serialized = original.to_dict()
+        assert 59.5 < serialized["remaining_seconds"] <= 60.0
+
+        # Simule un long dispatch (le worker met 5s à recevoir).
+        time.sleep(0.5)
+
+        # Le worker reconstruit depuis le payload reçu.  Comme on
+        # repart de l'instant *receveur*, le budget restant est
+        # ~remaining_seconds du moment du handoff, indépendant du
+        # délai de transport.
+        reconstructed = Deadline.from_dict(serialized)
+        r = reconstructed.remaining_seconds()
+        assert r is not None
+        # Le receveur voit ~remaining_seconds(handoff) - 0 (il vient
+        # de le reconstruire).
+        assert 59.0 < r <= 60.0, (
+            f"reconstructed remaining={r} : le dispatch overhead "
+            f"a été facturé alors qu'il ne devrait pas"
+        )
+
+    def test_pickle_roundtrip_infinite(self) -> None:
+        d = Deadline.infinite()
+        restored = pickle.loads(pickle.dumps(d))
+        assert restored.is_infinite is True
+
+    def test_pickle_roundtrip_finite(self) -> None:
+        d = Deadline.in_seconds(45.0)
+        restored = pickle.loads(pickle.dumps(d))
+        r = restored.remaining_seconds()
+        assert r is not None
+        assert 44.0 < r <= 45.0
+
+    def test_pickle_preserves_handoff_semantics(self) -> None:
+        """Même propriété que ``test_dispatch_overhead_not_charged``
+        mais via pickle (le canal réel cross-process).
+        """
+        d = Deadline.in_seconds(30.0)
+        payload = pickle.dumps(d)
+        time.sleep(0.3)
+        restored = pickle.loads(payload)
+        r = restored.remaining_seconds()
+        assert r is not None
+        # On veut voir ~30s, pas ~29.7s — la sleep n'a pas mangé
+        # le budget.
+        assert 29.5 < r <= 30.0
+
+    def test_pickle_expired_stays_expired(self) -> None:
+        d = Deadline.at_monotonic(0.0)
+        assert d.is_expired() is True
+        restored = pickle.loads(pickle.dumps(d))
+        assert restored.is_expired() is True
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Immutabilité
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestImmutability:
+    def test_setattr_raises(self) -> None:
+        d = Deadline.in_seconds(10.0)
+        with pytest.raises(AttributeError, match="immuable"):
+            d._expires_at_monotonic = 0.0
+
+    def test_setattr_new_field_raises(self) -> None:
+        d = Deadline.in_seconds(10.0)
+        with pytest.raises(AttributeError, match="immuable"):
+            d.new_field = "x"  # type: ignore[attr-defined]
+
+    def test_delattr_raises(self) -> None:
+        d = Deadline.in_seconds(10.0)
+        with pytest.raises(AttributeError, match="immuable"):
+            del d._expires_at_monotonic
+
+    def test_slots_no_dict(self) -> None:
+        """``__slots__`` empêche la création d'un ``__dict__``
+        (économie mémoire, pas de mutation accidentelle)."""
+        d = Deadline.in_seconds(10.0)
+        assert not hasattr(d, "__dict__")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Égalité, hash, repr
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestDunderProtocols:
+    def test_infinite_equals_infinite(self) -> None:
+        assert Deadline.infinite() == Deadline.infinite()
+
+    def test_infinite_not_equals_finite(self) -> None:
+        assert Deadline.infinite() != Deadline.in_seconds(10.0)
+
+    def test_same_absolute_deadline_is_equal(self) -> None:
+        """Deux ``Deadline`` construites à partir du même
+        ``expires_at_monotonic`` absolu sont égales."""
+        t = time.monotonic() + 100.0
+        assert Deadline.at_monotonic(t) == Deadline.at_monotonic(t)
+
+    def test_two_in_seconds_calls_not_equal(self) -> None:
+        """Deux appels successifs à ``in_seconds(60)`` créent des
+        deadlines avec des ``expires_at_monotonic`` *différents*
+        (même de quelques µs).  Égalité stricte → non égales.
+        Documenté dans le code source.
+        """
+        d1 = Deadline.in_seconds(60.0)
+        d2 = Deadline.in_seconds(60.0)
+        # Théoriquement collisions possibles si time.monotonic() ne
+        # bouge pas entre les deux appels, mais ultra rare en
+        # pratique.  Le test peut flaquer ultra rarement — on évite
+        # un assert strict ici.
+        # On vérifie au moins qu'il ne sont pas systématiquement
+        # égaux (i.e. l'égalité n'est pas sur le budget mais sur
+        # l'instant absolu).
+        if d1._expires_at_monotonic != d2._expires_at_monotonic:
+            assert d1 != d2
+
+    def test_eq_with_non_deadline_returns_not_implemented(self) -> None:
+        d = Deadline.infinite()
+        # Python protocole __eq__ : si NotImplemented, fallback à
+        # ``is``.  Donc != est True, pas une exception.
+        assert (d == "infinite") is False
+        assert (d == 42) is False
+
+    def test_hashable(self) -> None:
+        """``Deadline`` doit être hashable pour pouvoir être utilisée
+        comme clé de dict ou élément de set."""
+        s = {Deadline.infinite(), Deadline.in_seconds(10.0)}
+        assert len(s) == 2
+
+    def test_hash_consistent_with_eq(self) -> None:
+        """Si ``a == b`` alors ``hash(a) == hash(b)``."""
+        t = time.monotonic() + 50.0
+        a = Deadline.at_monotonic(t)
+        b = Deadline.at_monotonic(t)
+        assert a == b
+        assert hash(a) == hash(b)
+
+    def test_repr_infinite(self) -> None:
+        assert repr(Deadline.infinite()) == "Deadline.infinite()"
+
+    def test_repr_finite_shows_remaining(self) -> None:
+        d = Deadline.in_seconds(42.5)
+        r = repr(d)
+        assert "remaining" in r
+        assert "42" in r
+
+    def test_repr_expired(self) -> None:
+        d = Deadline.at_monotonic(0.0)
+        assert repr(d) == "Deadline(expired)"
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Smoke : la deadline est utilisable dans des patterns réalistes
+# ──────────────────────────────────────────────────────────────────────
+
+
+class TestRealWorldUsage:
+    def test_retry_loop_respects_deadline(self) -> None:
+        """Simule un retry helper qui doit s'arrêter quand la
+        deadline expire — pattern qui sera implémenté en Phase 3
+        dans ``adapters/_retry.py``."""
+        deadline = Deadline.in_seconds(0.15)  # 150ms
+        attempts = 0
+        while not deadline.is_expired():
+            attempts += 1
+            time.sleep(0.05)
+        # Avec budget 150ms et sleep 50ms : ~3 tentatives.
+        assert 2 <= attempts <= 4
+
+    def test_clamp_for_retry_backoff(self) -> None:
+        """Le retry helper veut attendre ``base ** attempt`` secondes
+        mais ne doit jamais dépasser le budget restant.  Pattern
+        Phase 3."""
+        deadline = Deadline.in_seconds(2.0)
+        # Backoff "naïf" : 5 secondes.  Le clamp doit le borner.
+        wait = deadline.clamp_to_remaining(5.0)
+        assert wait <= 2.0
+        assert wait > 1.5  # Bornes : on n'a pas perdu beaucoup de temps
+
+    def test_sdk_timeout_pattern(self) -> None:
+        """Pattern call-site adapter : passer la deadline au SDK
+        comme paramètre ``timeout=``."""
+        deadline = Deadline.in_seconds(10.0)
+        # En vrai : ``client.call(url, timeout=deadline.as_sdk_timeout())``
+        sdk_timeout = deadline.as_sdk_timeout()
+        assert sdk_timeout is not None
+        assert sdk_timeout > 9.0
+
+    def test_infinite_deadline_passes_none_to_sdk(self) -> None:
+        """Une deadline infinie produit ``None`` ; la plupart des
+        SDKs (httpx, requests, pytesseract) interprètent ``None``
+        comme 'pas de timeout', ce qui est le comportement voulu."""
+        assert Deadline.infinite().as_sdk_timeout() is None