"""Abstract persistence adapter for workflow runs and artifacts."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any, Dict, List, Optional


class PersistenceAdapter(ABC):
    """Abstract base class for workflow persistence backends."""

    @abstractmethod
    def save_run(self, run_id: str, summary: Dict[str, Any]) -> None:
        """Persist a workflow run summary.

        Args:
            run_id: Unique run identifier.
            summary: Run summary dict (phases, status, metrics, etc.).
        """

    @abstractmethod
    def load_run(self, run_id: str) -> Optional[Dict[str, Any]]:
        """Load a previously saved run summary.

        Args:
            run_id: Unique run identifier.

        Returns:
            Run summary dict, or None if not found.
        """

    @abstractmethod
    def save_artifact_meta(self, run_id: str, artifact: Dict[str, Any]) -> None:
        """Save metadata about a generated artifact.

        Args:
            run_id: Run that produced the artifact.
            artifact: Artifact metadata (name, path, format, size, etc.).
        """

    @abstractmethod
    def list_runs(self, limit: int = 20) -> List[Dict[str, Any]]:
        """List recent workflow runs.

        Args:
            limit: Maximum number of runs to return.

        Returns:
            List of run summary dicts, most recent first.
        """
