# #region OrchestratorCommands [C:2] [TYPE Module] [SEMANTICS dataset, review, command, dataclass, boundary]
# @BRIEF Typed command and result dataclasses for dataset review orchestration boundary.
# @LAYER Domain
# @RELATION DEPENDS_ON -> [DatasetReviewModels]
# @RELATION DEPENDS_ON -> [SupersetContextExtractor]

from __future__ import annotations

from dataclasses import dataclass, field

from src.core.utils.superset_context_extractor import SupersetParsedContext
from src.models.auth import User
from src.models.dataset_review import (
    CompiledPreview,
    DatasetReviewSession,
    DatasetRunContext,
    ValidationFinding,
)


# #region StartSessionCommand [C:2] [TYPE Class]
# @BRIEF Typed input contract for starting a dataset review session.
@dataclass
class StartSessionCommand:
    user: User
    environment_id: str
    source_kind: str
    source_input: str


# #endregion StartSessionCommand


# #region StartSessionResult [C:2] [TYPE Class]
# @BRIEF Session-start result carrying the persisted session and intake recovery metadata.
@dataclass
class StartSessionResult:
    session: DatasetReviewSession
    parsed_context: SupersetParsedContext | None = None
    findings: list[ValidationFinding] = field(default_factory=list)


# #endregion StartSessionResult


# #region PreparePreviewCommand [C:2] [TYPE Class]
# @BRIEF Typed input contract for compiling one Superset-backed session preview.
@dataclass
class PreparePreviewCommand:
    user: User
    session_id: str
    expected_version: int | None = None


# #endregion PreparePreviewCommand


# #region PreparePreviewResult [C:2] [TYPE Class]
# @BRIEF Result contract for one persisted compiled preview attempt.
@dataclass
class PreparePreviewResult:
    session: DatasetReviewSession
    preview: CompiledPreview
    blocked_reasons: list[str] = field(default_factory=list)


# #endregion PreparePreviewResult


# #region LaunchDatasetCommand [C:2] [TYPE Class]
# @BRIEF Typed input contract for launching one dataset-review session into SQL Lab.
@dataclass
class LaunchDatasetCommand:
    user: User
    session_id: str
    expected_version: int | None = None


# #endregion LaunchDatasetCommand


# #region LaunchDatasetResult [C:2] [TYPE Class]
# @BRIEF Launch result carrying immutable run context and any gate blockers.
@dataclass
class LaunchDatasetResult:
    session: DatasetReviewSession
    run_context: DatasetRunContext
    blocked_reasons: list[str] = field(default_factory=list)


# #endregion LaunchDatasetResult


# #endregion OrchestratorCommands
