from __future__ import annotations

from abc import ABC, abstractmethod

from domain.geospatial.planning_restrictions import PlanningRestrictions
from domain.geospatial.spatial_reference import SpatialReference


class SpatialRepository(ABC):
    """Caches the OS spatial reference data (coordinates + planning flags) by
    UPRN — a per-UPRN write-through cache of the S3 reference lookup (ADR-0020).

    Written by Ingestion, read by Modelling (which hydrates the planning
    protections onto the Property). One shared row per UPRN; ``save`` upserts.
    """

    @abstractmethod
    def save(self, uprn: int, reference: SpatialReference) -> None: ...

    @abstractmethod
    def get_for_uprns(
        self, uprns: list[int]
    ) -> dict[int, PlanningRestrictions]:
        """The planning protections for each covered UPRN, keyed by UPRN.
        UPRNs with no cached row are omitted (the caller defaults them to
        unrestricted)."""
        ...