"""C6 `TileStore` + `DescriptorIndex` Protocols.

Concrete impl: `PostgresFilesystemStore` (Postgres mirror + filesystem mmap +
FAISS HNSW). See `_docs/02_document/components/08_c6_tile_cache/`.
"""

from __future__ import annotations

from collections.abc import Iterable
from typing import Protocol

from gps_denied_onboard._types.tile import Tile, TileRecord


class TileStore(Protocol):
    """Tile metadata + body store (mirrors satellite-provider; cached locally)."""

    def get(self, tile_id: str) -> Tile | None: ...

    def query_by_lat_lon(
        self, lat: float, lon: float, zoom: int, radius_m: float
    ) -> Iterable[TileRecord]: ...

    def put(self, record: TileRecord) -> None: ...


class DescriptorIndex(Protocol):
    """Vector index over tile descriptors (FAISS HNSW concrete impl)."""

    def add(self, tile_id: str, descriptor) -> None: ...

    def search(self, descriptor, top_k: int) -> Iterable[tuple[str, float]]: ...