"""Port defining how the application accesses test data.

This is a domain contract — implementations live in infrastructure/.
"""

# Enable future language features for compatibility
from __future__ import annotations

# Import uuid
import uuid

# Import Protocol from typing
from typing import Protocol

# Import TestState from app.domain.enums
from app.domain.enums import TestState


# Define class TestRepository
class TestRepository(Protocol):
    """Data access contract for tests."""

    # -- Single-entity access ----------------------------------------------

    def find_by_id(self, test_id: uuid.UUID) -> object | None:
        """Return a Test ORM model by primary key, or None.

        Returns the ORM model directly (not a domain entity) because
        the TestEntity is constructed at the service layer via
        ``TestEntity.from_orm()``.

        Args:
            test_id (uuid.UUID): Primary key of the test to look up.

        Returns:
            object | None: The ORM model instance, or None if not found.
        """
        # ...
        ...

    # -- List access -------------------------------------------------------

    def list_by_technique(self, technique_id: uuid.UUID) -> list[object]:
        """Return all test ORM models associated with the given technique.

        Args:
            technique_id (uuid.UUID): Primary key of the technique whose tests to retrieve.

        Returns:
            list[object]: ORM model instances for all tests linked to this technique.
        """
        # ...
        ...

    # Define function list_by_state
    def list_by_state(self, state: TestState) -> list[object]:
        """Return all test ORM models in the given state.

        Args:
            state (TestState): The state to filter tests by.

        Returns:
            list[object]: ORM model instances for all tests currently in *state*.
        """
        # ...
        ...

    # Define function count_by_technique_and_state
    def count_by_technique_and_state(
        self,
        # Entry: technique_id
        technique_id: uuid.UUID,
    ) -> dict[TestState, int]:
        """Return test counts grouped by state for a single technique.

        Args:
            technique_id (uuid.UUID): Primary key of the technique whose test
                counts to aggregate.

        Returns:
            dict[TestState, int]: Mapping from each test state to the number of
                tests in that state for the given technique.
        """
        # ...
        ...

    # -- Batch queries -----------------------------------------------------

    def get_states_and_results_for_technique(
        self,
        # Entry: technique_id
        technique_id: uuid.UUID,
    ) -> list[tuple[str, str | None]]:
        """Return (state, detection_result) pairs for all tests of a technique.

        Used by TechniqueEntity.recalculate_status() without loading full
        test models.

        Args:
            technique_id (uuid.UUID): Primary key of the technique whose test
                data to retrieve.

        Returns:
            list[tuple[str, str | None]]: Each tuple contains the test state
                string and the detection result string (or None if not yet set).
        """
        # ...
        ...
