Add QueueRepositoryInterface with memory and file-backed adapters.

Provide a generic disk-backed FIFO queue with configurable path, retention, and dedup keys so consumers can buffer items across restarts without optional extras.

Co-authored-by: Cursor <[email protected]>

python_repositories/interfaces/queue_repository_interface.py

@@ -0,0 +1,41 @@
+"""Definition of QueueRepositoryInterface protocol."""
+
+from abc import abstractmethod
+from datetime import datetime
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class QueueRepositoryInterface(Protocol):
+    """Interface that defines buffered queue enqueue/dequeue methods."""
+
+    @abstractmethod
+    def enqueue(self, items: list[dict[str, Any]]) -> None:
+        """Append items to the queue.
+
+        Duplicates may be skipped when the implementation is configured with
+        dedup keys. An empty list is a no-op.
+        """
+        ...
+
+    @abstractmethod
+    def dequeue_batch(self, *, max_items: int = 1000) -> list[dict[str, Any]]:
+        """Remove and return up to ``max_items`` items in FIFO order.
+
+        Returns an empty list when the queue is empty.
+        """
+        ...
+
+    @abstractmethod
+    def size(self) -> int:
+        """Return the number of items currently in the queue."""
+        ...
+
+    @abstractmethod
+    def evict_older_than(self, cutoff: datetime) -> int:
+        """Remove items older than ``cutoff`` and return how many were removed.
+
+        Age is determined by an implementation-specific item field. When no age
+        field is configured, this is a no-op that returns ``0``.
+        """
+        ...