"""The ComparableProperties repository port (ADR-0029 decision 3; ADR-0031).

Owns the cohort IO for EPC Prediction — given a target's postcode, return the
candidate `ComparableProperty`s (the postcode's other lodged certs, mapped to
`EpcPropertyData` with their register metadata + resolved coordinates). The pure
domain `select_comparables` then filters these into the reference cohort, and
`EpcPrediction.predict` synthesises the picture. Kept a port so the orchestrator
depends on the cohort source abstractly and tests substitute a fake.
"""

from __future__ import annotations

from abc import ABC, abstractmethod

from domain.epc_prediction.comparable_properties import ComparableProperty


class ComparablePropertiesRepository(ABC):
    @abstractmethod
    def candidates_for(self, postcode: str) -> list[ComparableProperty]:
        """Every candidate neighbour in `postcode` — one `ComparableProperty` per lodged
        cert, carrying its `EpcPropertyData`, certificate number, address,
        registration date, and resolved coordinates (None when unresolvable)."""
        ...