"""Job / Experiment Repository Protocol（Phase 4）。"""

from __future__ import annotations

from typing import Protocol

from app.domain.entities.research import ExperimentRecord, JobRecord


class JobRepository(Protocol):
    def create(self, job: JobRecord) -> JobRecord: ...

    def get(self, job_id: str) -> JobRecord | None: ...

    def update(self, job: JobRecord) -> None: ...

    def list_recent(self, kind: str | None = None, limit: int = 20) -> list[JobRecord]: ...

    def list_by_status(self, status: str, limit: int = 100) -> list[JobRecord]:
        """按状态查询（服务启动清理残留 queued/running 用）。"""


class ExperimentRepository(Protocol):
    def save(self, experiment: ExperimentRecord) -> ExperimentRecord: ...

    def get(self, experiment_id: str) -> ExperimentRecord | None: ...

    def list_recent(self, limit: int = 50) -> list[ExperimentRecord]: ...