"""Checkpoint schema — source of truth for pipeline state snapshots."""

from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Dict, Optional
from uuid import UUID


@dataclass
class Checkpoint:
    """
    A snapshot of pipeline state on a timeline.

    parent_id forms a tree: multiple children from the same parent
    = different config tries from the same starting point.

    Stage outputs are stored separately in StageOutput table,
    not carried in the checkpoint itself.
    """

    id: UUID
    timeline_id: UUID
    job_id: Optional[UUID] = None
    parent_id: Optional[UUID] = None

    stage_name: str = ""  # which stage produced this checkpoint

    # Config that produced this checkpoint
    config_overrides: Dict[str, Any] = field(default_factory=dict)

    # Pipeline stats at this point
    stats: Dict[str, Any] = field(default_factory=dict)

    # Scenario bookmark
    is_scenario: bool = False
    scenario_label: str = ""

    created_at: Optional[datetime] = None