"""Protocol interfaces for the storage layer.

These narrow contracts allow v1's in-memory implementation to be swapped out
for persistence backends (SQLite, Postgres) in later phases without changing
the retrieval or learning layers.
"""

from __future__ import annotations

from typing import Any, Protocol, runtime_checkable

from neural_ledger.internal.models import InternalLink, InternalRecord


@runtime_checkable
class RecordStore(Protocol):
    def put_record(self, record: InternalRecord) -> None: ...
    def get_record(self, record_id: str) -> InternalRecord | None: ...
    def list_records(self, namespace: str) -> list[InternalRecord]: ...
    def delete_record(self, record_id: str) -> None: ...


@runtime_checkable
class LinkStore(Protocol):
    def add_link(self, link: InternalLink) -> None: ...
    def update_link(self, source_id: str, target_id: str, **attrs: Any) -> None: ...
    def get_link(self, source_id: str, target_id: str) -> InternalLink | None: ...
    def get_links_from(self, source_id: str) -> list[InternalLink]: ...
    def get_links_to(self, target_id: str) -> list[InternalLink]: ...
    def neighbours(self, source_id: str) -> list[str]: ...
    def has_cycle(self) -> bool: ...
    def find_cycle(self) -> list[str] | None: ...
