clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/protocols.py

@@ -0,0 +1,197 @@
+"""Layer 1 Protocols: Dependency Inversion for Storage and Execution (PEP 544).
+
+Sprint 383 (INV-383-01, DEL-383-01):
+Defines abstract protocols for storage engines so Layer 1 execution modules
+(PTREngine, runtimes, operations) never directly depend on Layer 2 storage
+implementations (CardCollection).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional, Protocol, runtime_checkable
+
+from clm.layer0.model.card import MCard
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class CardStoreProtocol(Protocol):
+    """Protocol defining the storage interface required by Layer 1 execution engines.
+
+    Implements the Dependency Inversion Principle: Layer 1 engines depend on
+    this abstraction, and Layer 2 CardCollection satisfies it structurally.
+    """
+
+    def get(self, hash_or_handle: str) -> Optional[MCard]:
+        """Retrieve an MCard by content hash or handle URI."""
+        ...
+
+    def add(self, card: MCard) -> str:
+        """Add an MCard to the store and return its content hash."""
+        ...
+
+    def add_with_handle(self, card: MCard, handle: str) -> None:
+        """Add an MCard and associate it with a handle URI."""
+        ...
+
+    def get_by_handle(self, handle: str) -> Optional[MCard]:
+        """Retrieve an MCard associated with a handle URI."""
+        ...
+
+    def update_handle(self, handle: str, card: MCard) -> None:
+        """Update an existing handle URI to point to a new MCard."""
+        ...
+
+    def get_handle_history(self, handle: str) -> list[Any]:
+        """Retrieve the mutation history for a handle URI."""
+        ...
+
+    def prune_handle_history(
+        self, handle: str, older_than: Any = None, delete_all: bool = False
+    ) -> int:
+        """Prune historical handle versions."""
+        ...
+
+
+class InMemoryCardStore:
+    """Zero-dependency, purely in-memory CardStoreProtocol implementation.
+
+    Used as the default fallback when running in hermetic Layer 1 environments
+    or under CLM_ZERO_FS=true where Layer 2 storage is not mounted.
+    """
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self.db_path = db_path
+        self._cards: dict[str, MCard] = {}
+        self._handles: dict[str, str] = {}  # handle -> current_hash
+        self._history: dict[str, list[dict[str, Any]]] = {}  # handle -> list of history entries
+
+    def get(self, hash_or_handle: str) -> Optional[MCard]:
+        if hash_or_handle in self._cards:
+            return self._cards[hash_or_handle]
+        if hash_or_handle in self._handles:
+            current_hash = self._handles[hash_or_handle]
+            return self._cards.get(current_hash)
+        return None
+
+    def add(self, card: MCard) -> str:
+        card_hash = card.hash if hasattr(card, "hash") else str(card)
+        self._cards[card_hash] = card
+        return card_hash
+
+    def add_with_handle(self, card: MCard, handle: str) -> None:
+        card_hash = self.add(card)
+        self._handles[handle] = card_hash
+        if handle not in self._history:
+            self._history[handle] = []
+        self._history[handle].append({"hash": card_hash, "action": "created"})
+
+    def get_by_handle(self, handle: str) -> Optional[MCard]:
+        current_hash = self._handles.get(handle)
+        if current_hash:
+            return self._cards.get(current_hash)
+        return None
+
+    def update_handle(self, handle: str, card: MCard) -> None:
+        card_hash = self.add(card)
+        prev_hash = self._handles.get(handle)
+        self._handles[handle] = card_hash
+        if handle not in self._history:
+            self._history[handle] = []
+        self._history[handle].append({"previous_hash": prev_hash, "hash": card_hash, "action": "updated"})
+
+    def get_handle_history(self, handle: str) -> list[Any]:
+        return list(self._history.get(handle, []))
+
+    def prune_handle_history(
+        self, handle: str, older_than: Any = None, delete_all: bool = False
+    ) -> int:
+        if handle not in self._history:
+            return 0
+        deleted = len(self._history[handle])
+        self._history[handle] = []
+        return deleted
+
+    def resolve_handle(self, handle: str) -> Optional[str]:
+        return self._handles.get(handle)
+
+
+# Registry for store factory dependency injection
+StoreFactoryFn = Callable[[Optional[str]], CardStoreProtocol]
+_store_factory: Optional[StoreFactoryFn] = None
+
+
+def register_store_factory(factory: StoreFactoryFn) -> None:
+    """Register a factory function for creating CardStoreProtocol instances.
+
+    Typically called by Layer 2 during module initialization.
+    """
+    global _store_factory
+    _store_factory = factory
+
+
+def get_store_factory() -> Optional[StoreFactoryFn]:
+    """Get the currently registered store factory, if any."""
+    return _store_factory
+
+
+def get_store(db_path: Optional[str] = None) -> CardStoreProtocol:
+    """Create or retrieve a CardStoreProtocol instance.
+
+    Uses the registered factory (e.g. Layer 2 CardCollection) if available;
+    otherwise falls back to an InMemoryCardStore.
+    """
+    if _store_factory is not None:
+        try:
+            return _store_factory(db_path)
+        except Exception as e:
+            logger.warning("Registered store factory failed for %s: %s; falling back to InMemoryCardStore", db_path, e)
+
+    return InMemoryCardStore(db_path=db_path or ":memory:")
+
+
+# Registry for file loader dependency injection (Layer 4 -> Layer 1)
+FileLoaderFn = Callable[..., Any]
+_file_loader: Optional[FileLoaderFn] = None
+
+
+def register_file_loader(loader: FileLoaderFn) -> None:
+    """Register a file loader function (typically clm.layer4.loader.load_file_to_collection)."""
+    global _file_loader
+    _file_loader = loader
+
+
+def get_file_loader() -> Optional[FileLoaderFn]:
+    """Get the registered file loader function."""
+    return _file_loader
+
+
+# Registry for file registrar dependency injection (Layer 2 -> Layer 1)
+FileRegistrarFn = Callable[..., Any]
+_file_registrar_hook: Optional[FileRegistrarFn] = None
+
+
+def register_file_registrar_hook(hook: FileRegistrarFn) -> None:
+    """Register a file registrar hook (typically clm.layer2.file_registrar.register_file_mcard_py)."""
+    global _file_registrar_hook
+    _file_registrar_hook = hook
+
+
+def get_file_registrar_hook() -> Optional[FileRegistrarFn]:
+    """Get the registered file registrar hook."""
+    return _file_registrar_hook
+
+
+__all__ = [
+    "CardStoreProtocol",
+    "InMemoryCardStore",
+    "register_store_factory",
+    "get_store_factory",
+    "get_store",
+    "register_file_loader",
+    "get_file_loader",
+    "register_file_registrar_hook",
+    "get_file_registrar_hook",
+]