"""Recourse receipts for refused/blocked decisions."""

from __future__ import annotations

from typing import Any, Dict, List, Literal, Optional

from receipts.base import BaseReceipt, Field


class RecoursePath(BaseReceipt):
    """Single recourse suggestion path."""

    receipt_type: Literal["RecoursePath"] = "RecoursePath"
    field: str = Field(..., description="Field to adjust (e.g., coherence.delta_c)")
    from_value: Optional[float] = Field(None, description="Current value")
    to_value: Optional[float] = Field(None, description="Target value to unlock gate")
    gate: str = Field(..., description="Gate this recourse targets")
    kind: Literal["documentation", "clinical_followup", "model_only", "immutable"] = Field(
        ...,
        description="Type of action implied by the recourse suggestion",
    )
    actionable: bool = Field(default=True, description="Whether this recourse is actionable")
    note: Optional[str] = Field(None, description="Optional note/constraint")


class RecourseReceipt(BaseReceipt):
    """Receipt documenting recourse suggestions for a decision/refusal."""

    receipt_type: Literal["RecourseReceipt"] = "RecourseReceipt"
    decision_receipt_id: Optional[str] = Field(
        None,
        description="Receipt ID of the decision/refusal this recourse pertains to",
    )
    recourse_paths: List[RecoursePath] = Field(
        default_factory=list,
        description="List of recourse suggestions",
    )
    metadata: Dict[str, Any] = Field(
        default_factory=dict,
        description="Optional metadata (policy constraints, non-actionable reasons, etc.)",
    )
    gatebook_hash: Optional[str] = Field(
        default=None,
        description="Hash/version of the gatebook used when computing recourse",
    )
    threshold_snapshot: Optional[Dict[str, float]] = Field(
        default=None,
        description="Key thresholds from the gatebook at time of recourse computation",
    )
