"""Repository contracts for formal pipeline state."""
from __future__ import annotations

from typing import Any, Protocol
from uuid import UUID

from pipeline.models import PipelineJob, PipelineRun, PipelineStage, ResumeCursor


class PipelineRepository(Protocol):
    """Persistence boundary for orchestration and resumable jobs.

    The first migration does not create dedicated pipeline tables yet, so this
    interface captures the intended boundary before a persistence decision.
    """

    def create_pipeline_run(
        self,
        *,
        run_key: str | None = None,
        batch_id: UUID | None = None,
        status: str = "pending",
        metadata: dict[str, Any] | None = None,
    ) -> PipelineRun:
        ...

    def get_pipeline_run(self, run_id: UUID) -> PipelineRun:
        ...

    def save_pipeline_job(
        self,
        *,
        run_id: UUID,
        stage: PipelineStage,
        target_id: UUID | None = None,
        status: str = "pending",
        metadata: dict[str, Any] | None = None,
    ) -> PipelineJob:
        ...

    def mark_job_status(
        self,
        job_id: UUID,
        *,
        status: str,
        error_message: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> PipelineJob:
        ...

    def get_resume_cursor(self, run_id: UUID) -> ResumeCursor | None:
        ...