spanforge 2.0.0__py3-none-any.whl

spanforge/namespaces/__init__.py

@@ -0,0 +1,215 @@
+"""spanforge.namespaces — Namespace-specific payload dataclasses (v2.0).
+
+Each sub-module provides dataclasses that model the ``payload`` field of
+:class:`~spanforge.event.Event` for a given namespace.
+
+All payload classes share the same contract:
+
+* ``to_dict() -> dict`` — serialise to a plain dict for ``Event.payload``.
+* ``from_dict(data) -> cls`` — reconstruct from a plain dict.
+* ``__post_init__`` — validates every field at construction time.
+
+Sub-modules
+-----------
+audit
+    :class:`AuditKeyRotatedPayload`, :class:`AuditChainVerifiedPayload`,
+    :class:`AuditChainTamperedPayload`, :class:`AuditChainPayload`
+cache
+    :class:`CacheHitPayload`, :class:`CacheMissPayload`,
+    :class:`CacheEvictedPayload`, :class:`CacheWrittenPayload`
+chain (RFC-0001 SPANFORGE)
+    :class:`ChainPayload`
+confidence (RFC-0001 SPANFORGE)
+    :class:`ConfidencePayload`
+consent (RFC-0001 SPANFORGE)
+    :class:`ConsentPayload`
+hitl (RFC-0001 SPANFORGE)
+    :class:`HITLPayload`
+playbook (RFC-0001 SPANFORGE)
+    *removed*
+cost
+    :class:`CostTokenRecordedPayload`, :class:`CostSessionRecordedPayload`,
+    :class:`CostAttributedPayload`
+decision (RFC-0001 SPANFORGE)
+    :class:`DecisionDriver`, :class:`DecisionPayload`
+diff
+    :class:`DiffComputedPayload`, :class:`DiffRegressionFlaggedPayload`
+drift (RFC-0001 SPANFORGE)
+    :class:`DriftPayload`
+eval_
+    :class:`EvalScoreRecordedPayload`, :class:`EvalRegressionDetectedPayload`,
+    :class:`EvalScenarioStartedPayload`, :class:`EvalScenarioCompletedPayload`
+fence
+    :class:`FenceValidatedPayload`, :class:`FenceRetryTriggeredPayload`,
+    :class:`FenceMaxRetriesExceededPayload`
+guard
+    :class:`GuardPayload`
+latency (RFC-0001 SPANFORGE)
+    :class:`LatencyPayload`
+playbook (RFC-0001 SPANFORGE)
+    *removed*
+prompt
+    :class:`PromptRenderedPayload`, :class:`PromptTemplateLoadedPayload`,
+    :class:`PromptVersionChangedPayload`
+redact
+    :class:`RedactPiiDetectedPayload`, :class:`RedactPhiDetectedPayload`,
+    :class:`RedactAppliedPayload`
+template
+    :class:`TemplateRegisteredPayload`, :class:`TemplateVariableBoundPayload`,
+    :class:`TemplateValidationFailedPayload`
+tool_call (RFC-0001 SPANFORGE)
+    :class:`ToolCallPayload`
+trace
+    :class:`GenAISystem`, :class:`GenAIOperationName`, :class:`SpanKind`,
+    :class:`TokenUsage`, :class:`ModelInfo`, :class:`CostBreakdown`,
+    :class:`PricingTier`, :class:`ToolCall`, :class:`ReasoningStep`,
+    :class:`DecisionPoint`, :class:`SpanPayload`, :class:`AgentStepPayload`,
+    :class:`AgentRunPayload`
+"""
+
+from spanforge.namespaces.audit import (
+    AuditChainPayload,
+    AuditChainTamperedPayload,
+    AuditChainVerifiedPayload,
+    AuditKeyRotatedPayload,
+)
+from spanforge.namespaces.cache import (
+    CacheEvictedPayload,
+    CacheHitPayload,
+    CacheMissPayload,
+    CacheWrittenPayload,
+)
+from spanforge.namespaces.chain import ChainPayload
+from spanforge.namespaces.confidence import ConfidencePayload
+from spanforge.namespaces.consent import ConsentPayload
+from spanforge.namespaces.hitl import HITLPayload
+from spanforge.namespaces.cost import (
+    CostAttributedPayload,
+    CostSessionRecordedPayload,
+    CostTokenRecordedPayload,
+)
+from spanforge.namespaces.decision import DecisionDriver, DecisionPayload
+from spanforge.namespaces.diff import (
+    DiffComputedPayload,
+    DiffRegressionFlaggedPayload,
+)
+from spanforge.namespaces.drift import DriftPayload
+from spanforge.namespaces.eval_ import (
+    EvalRegressionDetectedPayload,
+    EvalScenarioCompletedPayload,
+    EvalScenarioStartedPayload,
+    EvalScoreRecordedPayload,
+)
+from spanforge.namespaces.fence import (
+    FenceMaxRetriesExceededPayload,
+    FenceRetryTriggeredPayload,
+    FenceValidatedPayload,
+)
+from spanforge.namespaces.guard import GuardPayload
+from spanforge.namespaces.latency import LatencyPayload
+from spanforge.namespaces.prompt import (
+    PromptRenderedPayload,
+    PromptTemplateLoadedPayload,
+    PromptVersionChangedPayload,
+)
+from spanforge.namespaces.redact import (
+    RedactAppliedPayload,
+    RedactPhiDetectedPayload,
+    RedactPiiDetectedPayload,
+)
+from spanforge.namespaces.template import (
+    TemplateRegisteredPayload,
+    TemplateValidationFailedPayload,
+    TemplateVariableBoundPayload,
+)
+from spanforge.namespaces.tool_call import ToolCallPayload
+from spanforge.namespaces.trace import (
+    AgentRunPayload,
+    AgentStepPayload,
+    CostBreakdown,
+    DecisionPoint,
+    GenAIOperationName,
+    GenAISystem,
+    ModelInfo,
+    PricingTier,
+    ReasoningStep,
+    SpanKind,
+    SpanPayload,
+    TokenUsage,
+    ToolCall,
+)
+
+__all__: list = [
+    "AgentRunPayload",
+    "AgentStepPayload",
+    # audit (legacy + RFC-0001 SPANFORGE)
+    "AuditChainPayload",
+    "AuditChainTamperedPayload",
+    "AuditChainVerifiedPayload",
+    "AuditKeyRotatedPayload",
+    # cache
+    "CacheEvictedPayload",
+    "CacheHitPayload",
+    "CacheMissPayload",
+    "CacheWrittenPayload",
+    # chain (RFC-0001 SPANFORGE)
+    "ChainPayload",
+    # confidence (RFC-0001 SPANFORGE)
+    "ConfidencePayload",
+    # consent (RFC-0001 SPANFORGE)
+    "ConsentPayload",
+    # cost
+    "CostAttributedPayload",
+    "CostBreakdown",
+    "CostSessionRecordedPayload",
+    "CostTokenRecordedPayload",
+    # decision (RFC-0001 SPANFORGE)
+    "DecisionDriver",
+    "DecisionPayload",
+    # diff
+    "DiffComputedPayload",
+    "DiffRegressionFlaggedPayload",
+    # drift (RFC-0001 SPANFORGE)
+    "DriftPayload",
+    # eval
+    "EvalRegressionDetectedPayload",
+    "EvalScenarioCompletedPayload",
+    "EvalScenarioStartedPayload",
+    "EvalScoreRecordedPayload",
+    # fence
+    "FenceMaxRetriesExceededPayload",
+    "FenceRetryTriggeredPayload",
+    "FenceValidatedPayload",
+    # guard
+    "GuardPayload",
+    # hitl (RFC-0001 SPANFORGE)
+    "HITLPayload",
+    # latency (RFC-0001 SPANFORGE)
+    "LatencyPayload",
+    # trace — value objects and payloads
+    "GenAIOperationName",
+    "GenAISystem",
+    "ModelInfo",
+    "PricingTier",
+    # prompt
+    "PromptRenderedPayload",
+    "PromptTemplateLoadedPayload",
+    "PromptVersionChangedPayload",
+    "ReasoningStep",
+    # redact
+    "RedactAppliedPayload",
+    "RedactPhiDetectedPayload",
+    "RedactPiiDetectedPayload",
+    "SpanKind",
+    "SpanPayload",
+    # template
+    "TemplateRegisteredPayload",
+    "TemplateValidationFailedPayload",
+    "TemplateVariableBoundPayload",
+    "TokenUsage",
+    "ToolCall",
+    # tool_call (RFC-0001 SPANFORGE)
+    "ToolCallPayload",
+    # Backward-compat trace value object
+    "DecisionPoint",
+]

spanforge/namespaces/audit.py

@@ -0,0 +1,253 @@
+"""spanforge.namespaces.audit — Audit chain payload types (RFC-0001 §11 + RFC-0001 SPANFORGE).
+
+Classes
+-------
+AuditKeyRotatedPayload      llm.audit.key.rotated
+AuditChainVerifiedPayload   llm.audit.chain.verified
+AuditChainTamperedPayload   llm.audit.chain.tampered
+AuditChainPayload           audit.event_signed / audit.chain_verified / audit.tamper_detected
+                            RFC-0001 SPANFORGE tamper-evident cross-reference chain
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "AuditChainPayload",
+    "AuditChainTamperedPayload",
+    "AuditChainVerifiedPayload",
+    "AuditKeyRotatedPayload",
+]
+
+_VALID_ROTATION_REASONS = frozenset({
+    "scheduled", "suspected_compromise", "policy_update", "key_expiry", "manual"
+})
+_VALID_SEVERITIES = frozenset({"low", "medium", "high", "critical"})
+
+
+@dataclass
+class AuditKeyRotatedPayload:
+    """RFC-0001 §11.5 — An HMAC signing key was rotated.
+
+    ``key_algorithm`` defaults to ``"HMAC-SHA256"`` (the only algorithm
+    mandated by the RFC).  ``effective_from_event_id`` is the ULID of the
+    first event signed with the new key.
+    """
+
+    key_id: str
+    previous_key_id: str
+    rotated_at: str   # ISO 8601 timestamp with exactly 6 decimal places
+    rotated_by: str
+    rotation_reason: str | None = None
+    key_algorithm: str = "HMAC-SHA256"
+    effective_from_event_id: str | None = None  # ULID
+
+    def __post_init__(self) -> None:
+        if not self.key_id:
+            raise ValueError("AuditKeyRotatedPayload.key_id must be non-empty")
+        if not self.previous_key_id:
+            raise ValueError("AuditKeyRotatedPayload.previous_key_id must be non-empty")
+        if not self.rotated_at:
+            raise ValueError("AuditKeyRotatedPayload.rotated_at must be non-empty")
+        if not self.rotated_by:
+            raise ValueError("AuditKeyRotatedPayload.rotated_by must be non-empty")
+        if self.rotation_reason is not None and self.rotation_reason not in _VALID_ROTATION_REASONS:
+            raise ValueError(
+                f"AuditKeyRotatedPayload.rotation_reason must be one of {sorted(_VALID_ROTATION_REASONS)}"  # noqa: E501
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_id": self.key_id,
+            "previous_key_id": self.previous_key_id,
+            "rotated_at": self.rotated_at,
+            "rotated_by": self.rotated_by,
+            "key_algorithm": self.key_algorithm,
+        }
+        if self.rotation_reason is not None:
+            d["rotation_reason"] = self.rotation_reason
+        if self.effective_from_event_id is not None:
+            d["effective_from_event_id"] = self.effective_from_event_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditKeyRotatedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_id=data["key_id"],
+            previous_key_id=data["previous_key_id"],
+            rotated_at=data["rotated_at"],
+            rotated_by=data["rotated_by"],
+            rotation_reason=data.get("rotation_reason"),
+            key_algorithm=data.get("key_algorithm", "HMAC-SHA256"),
+            effective_from_event_id=data.get("effective_from_event_id"),
+        )
+
+
+@dataclass
+class AuditChainVerifiedPayload:
+    """RFC-0001 §11 — An audit chain segment was verified intact."""
+
+    verified_from_event_id: str
+    verified_to_event_id: str
+    event_count: int
+    verified_at: str
+    verified_by: str
+
+    def __post_init__(self) -> None:
+        if not self.verified_from_event_id:
+            raise ValueError("AuditChainVerifiedPayload.verified_from_event_id must be non-empty")
+        if not self.verified_to_event_id:
+            raise ValueError("AuditChainVerifiedPayload.verified_to_event_id must be non-empty")
+        if not isinstance(self.event_count, int) or self.event_count < 0:
+            raise ValueError("AuditChainVerifiedPayload.event_count must be a non-negative int")
+        if not self.verified_at:
+            raise ValueError("AuditChainVerifiedPayload.verified_at must be non-empty")
+        if not self.verified_by:
+            raise ValueError("AuditChainVerifiedPayload.verified_by must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        return {
+            "verified_from_event_id": self.verified_from_event_id,
+            "verified_to_event_id": self.verified_to_event_id,
+            "event_count": self.event_count,
+            "verified_at": self.verified_at,
+            "verified_by": self.verified_by,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainVerifiedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            verified_from_event_id=data["verified_from_event_id"],
+            verified_to_event_id=data["verified_to_event_id"],
+            event_count=int(data["event_count"]),
+            verified_at=data["verified_at"],
+            verified_by=data["verified_by"],
+        )
+
+
+@dataclass
+class AuditChainTamperedPayload:
+    """RFC-0001 §11 — Tampering or a gap was detected in the audit chain."""
+
+    first_tampered_event_id: str
+    tampered_count: int
+    detected_at: str
+    detected_by: str
+    gap_count: int | None = None
+    gap_prev_ids: list[str] = field(default_factory=list)
+    severity: str | None = None  # "low"|"medium"|"high"|"critical"
+
+    def __post_init__(self) -> None:
+        if not self.first_tampered_event_id:
+            raise ValueError("AuditChainTamperedPayload.first_tampered_event_id must be non-empty")
+        if not isinstance(self.tampered_count, int) or self.tampered_count < 0:
+            raise ValueError("AuditChainTamperedPayload.tampered_count must be a non-negative int")
+        if not self.detected_at:
+            raise ValueError("AuditChainTamperedPayload.detected_at must be non-empty")
+        if not self.detected_by:
+            raise ValueError("AuditChainTamperedPayload.detected_by must be non-empty")
+        if self.severity is not None and self.severity not in _VALID_SEVERITIES:
+            raise ValueError(f"AuditChainTamperedPayload.severity must be one of {sorted(_VALID_SEVERITIES)}")  # noqa: E501
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "first_tampered_event_id": self.first_tampered_event_id,
+            "tampered_count": self.tampered_count,
+            "detected_at": self.detected_at,
+            "detected_by": self.detected_by,
+        }
+        if self.gap_count is not None:
+            d["gap_count"] = self.gap_count
+        if self.gap_prev_ids:
+            d["gap_prev_ids"] = list(self.gap_prev_ids)
+        if self.severity is not None:
+            d["severity"] = self.severity
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainTamperedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            first_tampered_event_id=data["first_tampered_event_id"],
+            tampered_count=int(data["tampered_count"]),
+            detected_at=data["detected_at"],
+            detected_by=data["detected_by"],
+            gap_count=int(data["gap_count"]) if "gap_count" in data else None,
+            gap_prev_ids=list(data.get("gap_prev_ids", [])),
+            severity=data.get("severity"),
+        )
+
+
+@dataclass
+class AuditChainPayload:
+    """RFC-0001 SPANFORGE — tamper-evident cross-reference audit chain event.
+
+    Every event emitted in the 10 RFC-0001 SPANFORGE namespaces is cross-
+    referenced into this immutable audit chain.  Each entry holds the HMAC
+    of the referenced event and the chained HMAC of all prior chain entries,
+    making any post-emission mutation detectable.
+
+    Events:
+        audit.event_signed      — a new event was appended to the chain
+        audit.chain_verified    — a chain segment was verified intact
+        audit.tamper_detected   — a break in the HMAC sequence was detected
+    """
+
+    event_id: str           # ULID of the referenced event
+    event_type: str         # wire event type string of the referenced event
+    event_hmac: str         # HMAC-SHA256 of the referenced event canonical JSON
+    chain_position: int     # monotonically increasing position in the chain
+    signer_id: str          # identity of the signing service / key ID
+    signed_at: str          # ISO 8601 timestamp with 6 decimal places
+    prev_chain_hmac: str | None = None  # HMAC of the previous chain entry; None for entry 0
+
+    def __post_init__(self) -> None:
+        if not self.event_id:
+            raise ValueError("AuditChainPayload.event_id must be non-empty")
+        if not self.event_type:
+            raise ValueError("AuditChainPayload.event_type must be non-empty")
+        if not self.event_hmac:
+            raise ValueError("AuditChainPayload.event_hmac must be non-empty")
+        if not isinstance(self.chain_position, int) or self.chain_position < 0:
+            raise ValueError("AuditChainPayload.chain_position must be a non-negative int")
+        if not self.signer_id:
+            raise ValueError("AuditChainPayload.signer_id must be non-empty")
+        if not self.signed_at:
+            raise ValueError("AuditChainPayload.signed_at must be non-empty")
+        if self.chain_position > 0 and not self.prev_chain_hmac:
+            raise ValueError(
+                "AuditChainPayload.prev_chain_hmac is required when chain_position > 0"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "event_hmac": self.event_hmac,
+            "chain_position": self.chain_position,
+            "signer_id": self.signer_id,
+            "signed_at": self.signed_at,
+        }
+        if self.prev_chain_hmac is not None:
+            d["prev_chain_hmac"] = self.prev_chain_hmac
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            event_id=data["event_id"],
+            event_type=data["event_type"],
+            event_hmac=data["event_hmac"],
+            chain_position=int(data["chain_position"]),
+            signer_id=data["signer_id"],
+            signed_at=data["signed_at"],
+            prev_chain_hmac=data.get("prev_chain_hmac"),
+        )

spanforge/namespaces/cache.py

@@ -0,0 +1,209 @@
+"""spanforge.namespaces.cache — Cache payload types (RFC-0001).
+
+Classes
+-------
+CacheHitPayload     llm.cache.hit
+CacheMissPayload    llm.cache.miss
+CacheEvictedPayload llm.cache.evicted
+CacheWrittenPayload llm.cache.written
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from spanforge.namespaces.trace import CostBreakdown, ModelInfo, TokenUsage
+
+__all__ = [
+    "CacheEvictedPayload",
+    "CacheHitPayload",
+    "CacheMissPayload",
+    "CacheWrittenPayload",
+]
+
+_VALID_EVICTION_REASONS = frozenset({
+    "ttl_expired", "lru_eviction", "manual_invalidation",
+    "capacity_exceeded", "schema_upgrade",
+})
+
+
+@dataclass
+class CacheHitPayload:
+    """Payload for llm.cache.hit — semantic cache lookup succeeded."""
+
+    key_hash: str
+    namespace: str
+    similarity_score: float
+    ttl_remaining_seconds: int | None = None
+    cached_model: ModelInfo | None = None
+    cost_saved: CostBreakdown | None = None
+    tokens_saved: TokenUsage | None = None
+    lookup_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheHitPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheHitPayload.namespace must be non-empty")
+        if not (0.0 <= self.similarity_score <= 1.0):
+            raise ValueError("CacheHitPayload.similarity_score must be in [0,1]")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "similarity_score": self.similarity_score,
+        }
+        if self.ttl_remaining_seconds is not None:
+            d["ttl_remaining_seconds"] = self.ttl_remaining_seconds
+        if self.cached_model is not None:
+            d["cached_model"] = self.cached_model.to_dict()
+        if self.cost_saved is not None:
+            d["cost_saved"] = self.cost_saved.to_dict()
+        if self.tokens_saved is not None:
+            d["tokens_saved"] = self.tokens_saved.to_dict()
+        if self.lookup_duration_ms is not None:
+            d["lookup_duration_ms"] = self.lookup_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheHitPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            similarity_score=float(data["similarity_score"]),
+            ttl_remaining_seconds=int(data["ttl_remaining_seconds"]) if "ttl_remaining_seconds" in data else None,  # noqa: E501
+            cached_model=ModelInfo.from_dict(data["cached_model"]) if "cached_model" in data else None,  # noqa: E501
+            cost_saved=CostBreakdown.from_dict(data["cost_saved"]) if "cost_saved" in data else None,  # noqa: E501
+            tokens_saved=TokenUsage.from_dict(data["tokens_saved"]) if "tokens_saved" in data else None,  # noqa: E501
+            lookup_duration_ms=float(data["lookup_duration_ms"]) if "lookup_duration_ms" in data else None,  # noqa: E501
+        )
+
+
+@dataclass
+class CacheMissPayload:
+    """Payload for llm.cache.miss — semantic cache lookup failed."""
+
+    key_hash: str
+    namespace: str
+    best_similarity_score: float | None = None
+    similarity_threshold: float | None = None
+    lookup_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheMissPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheMissPayload.namespace must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {"key_hash": self.key_hash, "namespace": self.namespace}
+        if self.best_similarity_score is not None:
+            d["best_similarity_score"] = self.best_similarity_score
+        if self.similarity_threshold is not None:
+            d["similarity_threshold"] = self.similarity_threshold
+        if self.lookup_duration_ms is not None:
+            d["lookup_duration_ms"] = self.lookup_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheMissPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            best_similarity_score=float(data["best_similarity_score"]) if "best_similarity_score" in data else None,  # noqa: E501
+            similarity_threshold=float(data["similarity_threshold"]) if "similarity_threshold" in data else None,  # noqa: E501
+            lookup_duration_ms=float(data["lookup_duration_ms"]) if "lookup_duration_ms" in data else None,  # noqa: E501
+        )
+
+
+@dataclass
+class CacheEvictedPayload:
+    """Payload for llm.cache.evicted — a cache entry was removed."""
+
+    key_hash: str
+    namespace: str
+    eviction_reason: str
+    entry_age_seconds: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheEvictedPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheEvictedPayload.namespace must be non-empty")
+        if self.eviction_reason not in _VALID_EVICTION_REASONS:
+            raise ValueError(
+                f"CacheEvictedPayload.eviction_reason must be one of {sorted(_VALID_EVICTION_REASONS)}"  # noqa: E501
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "eviction_reason": self.eviction_reason,
+        }
+        if self.entry_age_seconds is not None:
+            d["entry_age_seconds"] = self.entry_age_seconds
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheEvictedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            eviction_reason=data["eviction_reason"],
+            entry_age_seconds=int(data["entry_age_seconds"]) if "entry_age_seconds" in data else None,  # noqa: E501
+        )
+
+
+@dataclass
+class CacheWrittenPayload:
+    """Payload for llm.cache.written — a response was written to cache."""
+
+    key_hash: str
+    namespace: str
+    ttl_seconds: int
+    model: ModelInfo | None = None
+    response_token_count: int | None = None
+    write_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheWrittenPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheWrittenPayload.namespace must be non-empty")
+        if not isinstance(self.ttl_seconds, int) or self.ttl_seconds < 0:
+            raise ValueError("CacheWrittenPayload.ttl_seconds must be a non-negative int")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "ttl_seconds": self.ttl_seconds,
+        }
+        if self.model is not None:
+            d["model"] = self.model.to_dict()
+        if self.response_token_count is not None:
+            d["response_token_count"] = self.response_token_count
+        if self.write_duration_ms is not None:
+            d["write_duration_ms"] = self.write_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheWrittenPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            ttl_seconds=int(data["ttl_seconds"]),
+            model=ModelInfo.from_dict(data["model"]) if "model" in data else None,
+            response_token_count=int(data["response_token_count"]) if "response_token_count" in data else None,  # noqa: E501
+            write_duration_ms=float(data["write_duration_ms"]) if "write_duration_ms" in data else None,  # noqa: E501
+        )