"""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.

    Stage outputs stored as JSONB — each stage serializes to JSON,
    the checkpoint stores it without knowing the shape.

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

    id: UUID
    timeline_id: UUID
    parent_id: Optional[UUID] = None  # null = root checkpoint

    # Stage outputs — JSONB per stage, opaque to the checkpoint layer
    stage_outputs: Dict[str, Any] = field(default_factory=dict)

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

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

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

    created_at: Optional[datetime] = None