"""``TilePixelHandle`` ABC for read-only mmap-backed JPEG access.

Concrete impls (e.g., ``PostgresFilesystemStore``'s internal
``_FilesystemTilePixelHandle``) subclass and provide an
``__enter__`` that returns a read-only :class:`memoryview` over the
mmap. Consumers use the handle in a ``with`` block; the underlying
mmap is unmapped on ``__exit__``.

Invariant I-4 of ``tile_store.md`` makes the read-only guarantee a
contract obligation: a writer that mutates through the memoryview
is a Critical Reliability finding at code-review time.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from pathlib import Path
from types import TracebackType


class TilePixelHandle(ABC):
    """Opaque read-only view of a tile's JPEG bytes.

    Lifetime is bounded by the caller's ``with`` block. The handle
    MUST NOT outlive its ``__exit__``; consumers MUST NOT cache the
    :class:`memoryview` past the block.
    """

    @property
    @abstractmethod
    def filesystem_path(self) -> Path:
        """Absolute path to the JPEG file backing this handle.

        Used only by C12 operator tooling (post-flight inspection)
        and the C11 ``TileUploader`` post-landing copy. In-flight
        consumers MUST NOT open a second handle to the same path;
        they MUST use this :class:`TilePixelHandle`.
        """

    @abstractmethod
    def __enter__(self) -> memoryview:
        """Return a read-only :class:`memoryview` over the JPEG bytes."""

    @abstractmethod
    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> None:
        """Release the mmap. Always called by the ``with`` block."""
