# app/modules/contracts/base.py
"""
Base protocol definitions for cross-module communication.

Protocols define the interface that services must implement without
requiring inheritance. This allows for:
- Duck typing with static type checking
- Easy mocking in tests
- Module independence
"""

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from sqlalchemy.orm import Session


@runtime_checkable
class ServiceProtocol(Protocol):
    """
    Base protocol for all module services.

    Services should be stateless and operate on database sessions
    passed as arguments. This ensures:
    - Thread safety
    - Transaction boundaries are clear
    - Easy testing with mock sessions
    """



@runtime_checkable
class CRUDServiceProtocol(Protocol):
    """
    Protocol for services that provide CRUD operations.

    All methods receive a database session as the first argument.
    """

    def get_by_id(self, db: "Session", id: int) -> object | None:
        """Get entity by ID."""
        ...

    def delete(self, db: "Session", id: int) -> bool:
        """Delete entity by ID. Returns True if deleted."""
        ...