"""
Python-layer storage protocol for Briefcase decision audit records.

This is independent from the Rust StorageBackend trait (crates/core/src/storage/mod.rs).
These backends are invoked from Python code only and use boto3/httpx directly.
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from datetime import datetime
from typing import List


@dataclass
class StorageReceipt:
    """Proof of a successful write operation."""
    key: str
    hash: str        # SHA-256 hex digest of the written bytes
    timestamp: datetime
    backend_metadata: dict


class PythonStorageBackend(ABC):
    """Python-layer storage for decision audit records.
    Independent from the Rust StorageBackend trait."""

    @abstractmethod
    async def write(self, key: str, record: bytes) -> StorageReceipt: ...

    @abstractmethod
    async def read(self, key: str) -> bytes: ...

    @abstractmethod
    async def verify(self, key: str, receipt: StorageReceipt) -> bool: ...

    @abstractmethod
    async def list_keys(self, prefix: str, start: datetime, end: datetime) -> List[str]: ...
