"""Local immutable shadow-report port for future reconciliation evidence."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Iterable, Protocol, runtime_checkable


@dataclass(frozen=True, slots=True)
class ShadowReport:
    """A small immutable report envelope suitable for local test storage."""

    report_id: str
    content: str


@runtime_checkable
class ReportStore(Protocol):
    """Append-only local report storage contract.

    Implementations for this phase, if any, must be explicitly local and use
    caller-provided test storage.  No production storage adapter is provided.
    """

    def append_shadow_report(self, report: ShadowReport) -> None:
        """Append one immutable shadow report."""

    def get_shadow_report(self, report_id: str) -> ShadowReport | None:
        """Read one previously appended shadow report."""

    def iter_shadow_reports(self) -> Iterable[ShadowReport]:
        """Iterate locally stored immutable shadow reports."""