"""Lightweight receipts for gatebook drift and operational heartbeats."""

from __future__ import annotations

from typing import Any, Dict, Literal, Optional

from receipts.base import BaseReceipt, Field


class GateDiffReceipt(BaseReceipt):
    """
    Captures a proposed gatebook threshold change and its provenance.

    Used by Drift Guard/autopatcher to record what changed, where, and why.
    """

    receipt_type: Literal["GateDiffReceipt"] = "GateDiffReceipt"
    gatebook_path: str = Field(..., description="Path of the gatebook that was diffed")
    param_path: str = Field(..., description="Dot-path of the parameter that changed")
    old_value: Optional[Any] = Field(None, description="Previous value")
    new_value: Optional[Any] = Field(None, description="Proposed value")
    reason: Optional[str] = Field(None, description="Why the change is proposed (drift summary, etc.)")
    impact_summary: Optional[Dict[str, Any]] = Field(
        default=None,
        description="Optional impact summary (pass→fail, fail→pass counts, slices)",
    )


class EchoReceipt(BaseReceipt):
    """
    Simple heartbeat receipt to confirm an automated job ran.
    """

    receipt_type: Literal["EchoReceipt"] = "EchoReceipt"
    message: str = Field(..., description="Human-readable heartbeat message")
    component: Optional[str] = Field(None, description="Component emitting the heartbeat")
    status: Literal["ok", "warn", "error"] = Field(default="ok", description="Health status for quick triage")
    payload: Dict[str, Any] = Field(default_factory=dict, description="Optional diagnostic payload")
