"""Abstract unit-of-work contract for multi-statement atomic writes.

A `UnitOfWork` is a callable that returns an async context manager: entering
it starts an atomic transaction, a normal exit commits it, and an exception
rolls it back. Services depend on this interface only — the concrete
mechanism (a locked `BEGIN IMMEDIATE` transaction on the shared connection)
lives in `app.db.connection.unit_of_work` / `repositories_impl.sqlite.
unit_of_work.SQLiteUnitOfWork`. See the backend-perf audit
(`scratchpad/audit/backend-perf.md` §3) for why a lock is required on a
single shared connection rather than a bare `BEGIN`/`COMMIT`.
"""

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from contextlib import AbstractAsyncContextManager, asynccontextmanager


class UnitOfWork(ABC):
    @abstractmethod
    def __call__(self) -> AbstractAsyncContextManager[None]:
        """Return an async context manager wrapping its body in one atomic unit of work."""


@asynccontextmanager
async def _noop() -> AsyncIterator[None]:
    yield


class NoOpUnitOfWork(UnitOfWork):
    """Default fallback: wraps nothing, so each write commits immediately.

    Used as the default for service constructors so call sites that predate
    the unit-of-work work (e.g. `scripts/seed_demo.py`, direct-construction
    test fixtures) keep behaving exactly as before — one implicit transaction
    per write — without having to pass a real `UnitOfWork`.
    """

    def __call__(self) -> AbstractAsyncContextManager[None]:
        return _noop()