cks-runtime 0.1.2__py3-none-any.whl

cks_runtime/storage/memory_storage.py

@@ -0,0 +1,127 @@
+"""
+In-memory Runtime Storage.
+
+Reference implementation used by tests.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+
+from cks_runtime.session.session import RuntimeSession
+from cks_runtime.storage.exceptions import (
+    SessionNotFound,
+    VersionNotFound,
+)
+from cks_runtime.storage.storage import RuntimeStorage
+from cks_runtime.versioning.version import RuntimeVersion
+
+
+class InMemoryStorage(RuntimeStorage):
+    """
+    Reference Runtime Storage implementation.
+
+    Provides deterministic in-memory persistence for:
+
+    - Runtime Sessions;
+    - Runtime Versions.
+
+    Intended primarily for testing and as the
+    reference Runtime Storage implementation.
+    """
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, RuntimeSession] = {}
+        self._versions: dict[str, RuntimeVersion] = {}
+
+    def save_session(
+        self,
+        session: RuntimeSession,
+    ) -> None:
+        """
+        Persist a Runtime Session.
+        """
+
+        self._sessions[
+            session.session_id
+        ] = deepcopy(session)
+
+    def load_session(
+        self,
+        session_id: str,
+    ) -> RuntimeSession:
+        """
+        Restore a Runtime Session.
+        """
+
+        try:
+            session = self._sessions[
+                session_id
+            ]
+        except KeyError as exc:
+            raise SessionNotFound(
+                session_id
+            ) from exc
+
+        return deepcopy(session)
+
+    def save_version(
+        self,
+        version: RuntimeVersion,
+    ) -> None:
+        """
+        Persist a Runtime Version.
+        """
+
+        self._versions[
+            version.version_id
+        ] = deepcopy(version)
+
+    def load_version(
+        self,
+        version_id: str,
+    ) -> RuntimeVersion:
+        """
+        Restore a Runtime Version.
+        """
+
+        try:
+            version = self._versions[
+                version_id
+            ]
+        except KeyError as exc:
+            raise VersionNotFound(
+                version_id
+            ) from exc
+
+        return deepcopy(version)
+
+    def has_session(
+        self,
+        session_id: str,
+    ) -> bool:
+        """
+        Determine whether a Runtime Session exists.
+        """
+
+        return session_id in self._sessions
+
+
+    def has_version(
+        self,
+        version_id: str,
+    ) -> bool:
+        """
+        Determine whether a Runtime Version exists.
+        """
+
+        return version_id in self._versions
+
+
+    def clear(self) -> None:
+        """
+        Remove every persisted Runtime object.
+        """
+
+        self._sessions.clear()
+        self._versions.clear()

cks_runtime/storage/storage.py

@@ -0,0 +1,90 @@
+"""
+Abstract Runtime Storage.
+
+SPEC-006 Storage.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+
+from cks_runtime.session.session import RuntimeSession
+from cks_runtime.versioning.version import RuntimeVersion
+
+
+class RuntimeStorage(ABC):
+    """
+    Abstract Runtime Storage.
+
+    Storage persists Runtime operational state.
+
+    Storage never:
+
+    - owns Sessions;
+    - owns Transactions;
+    - interprets semantics.
+    """
+
+    @abstractmethod
+    def save_session(
+        self,
+        session: RuntimeSession,
+    ) -> None:
+        """
+        Persist a Runtime Session.
+        """
+
+    @abstractmethod
+    def load_session(
+        self,
+        session_id: str,
+    ) -> RuntimeSession:
+        """
+        Restore a Runtime Session.
+        """
+
+    @abstractmethod
+    def has_session(
+        self,
+        session_id: str,
+    ) -> bool:
+        """
+        Check whether a Runtime Session exists.
+        """
+
+    @abstractmethod
+    def save_version(
+        self,
+        version: RuntimeVersion,
+    ) -> None:
+        """
+        Persist a Runtime Version.
+        """
+
+    @abstractmethod
+    def load_version(
+        self,
+        version_id: str,
+    ) -> RuntimeVersion:
+        """
+        Restore a Runtime Version.
+        """
+
+    @abstractmethod
+    def has_version(
+        self,
+        version_id: str,
+    ) -> bool:
+        """
+        Check whether a Runtime Version exists.
+        """
+
+    @abstractmethod
+    def clear(self) -> None:
+        """
+        Remove every persisted object.
+
+        Intended primarily for testing and
+        deterministic reference implementations.
+        """

cks_runtime/transaction/transaction.py

@@ -0,0 +1,149 @@
+"""
+Runtime Transaction model.
+
+A Transaction is the exclusive mechanism through which
+Runtime Session operational state may evolve.
+
+Transactions coordinate execution.
+They do not define semantic behaviour.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+
+class TransactionStatus(Enum):
+    """
+    Canonical Runtime Transaction states.
+    """
+
+    CREATED = "created"
+    EXECUTING = "executing"
+    VALIDATING = "validating"
+    COMMITTED = "committed"
+    ROLLED_BACK = "rolled_back"
+    ABORTED = "aborted"
+
+
+@dataclass
+class RuntimeTransaction:
+    """
+    Represents one Runtime Transaction.
+
+    Ownership:
+
+    - exactly one Runtime Session owns a Transaction;
+    - Transaction modifies operational state only;
+    - semantic validation belongs to CKS Core.
+    """
+
+    session: Any
+
+    transaction_id: str = field(
+        default_factory=lambda: str(uuid4())
+    )
+
+    operations: list[Any] = field(
+        default_factory=list
+    )
+
+    diagnostics: list[Any] = field(
+        default_factory=list
+    )
+
+    status: TransactionStatus = (
+        TransactionStatus.CREATED
+    )
+
+    def _ensure_not_completed(self) -> bool:
+        """
+        Return False when the Transaction has
+        already reached a terminal state.
+        """
+
+        return not self.completed
+
+    def add_operation(
+        self,
+        operation: Any,
+    ) -> None:
+        """
+        Register a Runtime operation.
+        """
+
+        self.operations.append(operation)
+
+    def add_diagnostic(
+        self,
+        diagnostic: Any,
+    ) -> None:
+        """
+        Register a Runtime or Core diagnostic.
+        """
+
+        self.diagnostics.append(diagnostic)
+
+    def mark_executing(self) -> None:
+        """
+        Mark Transaction as executing.
+        """
+
+        if not self._ensure_not_completed():
+            return
+
+        self.status = TransactionStatus.EXECUTING
+
+    def mark_validating(self) -> None:
+        """
+        Mark Transaction as validating.
+        """
+
+        if not self._ensure_not_completed():
+            return
+
+        self.status = TransactionStatus.VALIDATING
+
+    def commit(self) -> None:
+        """
+        Complete Transaction successfully.
+        """
+
+        if not self._ensure_not_completed():
+            return
+
+        self.status = TransactionStatus.COMMITTED
+
+    def rollback(self) -> None:
+        """
+        Roll back pending operational changes.
+        """
+
+        if not self._ensure_not_completed():
+            return
+
+        self.status = TransactionStatus.ROLLED_BACK
+
+    def abort(self) -> None:
+        """
+        Abort Transaction execution.
+        """
+
+        if not self._ensure_not_completed():
+            return
+
+        self.status = TransactionStatus.ABORTED
+
+    @property
+    def completed(self) -> bool:
+        """
+        Whether the Transaction has reached
+        a terminal state.
+        """
+
+        return self.status in {
+            TransactionStatus.COMMITTED,
+            TransactionStatus.ROLLED_BACK,
+            TransactionStatus.ABORTED,
+        }

cks_runtime/transaction/transaction_manager.py

@@ -0,0 +1,125 @@
+"""
+Runtime Transaction Manager.
+
+Owns Transaction lifecycle.
+
+Responsibilities:
+
+- begin Transactions;
+- retrieve Transactions;
+- coordinate completion;
+- preserve Session ownership.
+
+Does not:
+
+- perform semantic validation;
+- create Versions;
+- persist Runtime state;
+- modify CKS Core behaviour.
+"""
+
+from typing import Any
+
+from .transaction import RuntimeTransaction
+
+
+class TransactionManager:
+    """
+    Coordinates Runtime Transactions.
+    """
+
+    def __init__(self) -> None:
+        self._transactions: dict[
+            str,
+            RuntimeTransaction
+        ] = {}
+
+    def begin(
+        self,
+        session: Any,
+    ) -> RuntimeTransaction:
+        """
+        Begin a Transaction for a Session.
+
+        Exactly one active Transaction may exist
+        per Session.
+        """
+
+        if session.active_transaction is not None:
+            raise RuntimeError(
+                "Session already has an active transaction."
+            )
+
+        transaction = RuntimeTransaction(
+            session=session
+        )
+
+        self._transactions[
+            transaction.transaction_id
+        ] = transaction
+
+        session.active_transaction = transaction
+
+        return transaction
+
+    def retrieve(
+        self,
+        transaction_id: str,
+    ) -> RuntimeTransaction | None:
+        """
+        Retrieve a Transaction by identity.
+        """
+
+        return self._transactions.get(
+            transaction_id
+        )
+
+    def commit(
+        self,
+        transaction: RuntimeTransaction,
+    ) -> None:
+        """
+        Commit a Transaction.
+        """
+
+        transaction.commit()
+
+        transaction.session.active_transaction = None
+
+    def rollback(
+        self,
+        transaction: RuntimeTransaction,
+    ) -> None:
+        """
+        Roll back a Transaction.
+        """
+
+        transaction.rollback()
+
+        transaction.session.active_transaction = None
+
+    def abort(
+        self,
+        transaction: RuntimeTransaction,
+    ) -> None:
+        """
+        Abort a Transaction.
+        """
+
+        transaction.abort()
+
+        transaction.session.active_transaction = None
+
+    def list_transactions(
+        self,
+    ) -> list[RuntimeTransaction]:
+        """
+        Return known Transactions.
+
+        Primarily intended for Runtime
+        management and testing.
+        """
+
+        return list(
+            self._transactions.values()
+        )

cks_runtime/versioning/version.py

@@ -0,0 +1,44 @@
+"""
+Immutable Runtime Version.
+
+A Runtime Version records the operational state of a
+Runtime Session immediately following a committed Transaction.
+
+Versions are immutable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, UTC
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeVersion:
+    """
+    Immutable Runtime Version.
+
+    Ownership:
+
+    - owned by exactly one Runtime Session;
+    - created from exactly one committed Transaction;
+    - records operational state only.
+    """
+
+    session_id: str
+
+    transaction_id: str
+
+    knowledge_structure: Any
+
+    metadata: dict[str, Any]
+
+    version_id: str = field(
+        default_factory=lambda: str(uuid4())
+    )
+
+    created_at: datetime = field(
+        default_factory=lambda: datetime.now(UTC)
+    )

cks_runtime/versioning/version_manager.py

@@ -0,0 +1,81 @@
+"""
+Runtime Version Manager.
+
+Creates immutable Runtime Versions from the
+current Runtime Session state.
+"""
+
+from __future__ import annotations
+
+from cks_runtime.session.session import RuntimeSession
+from cks_runtime.versioning.version import RuntimeVersion
+
+
+class VersionManager:
+    """
+    Coordinates Runtime Version creation.
+    """
+
+    def create(
+        self,
+        session: RuntimeSession,
+    ) -> RuntimeVersion:
+        """
+        Create a new Runtime Version.
+
+        The Version is appended to the owning
+        Session Version History.
+        """
+
+        version = RuntimeVersion(
+            session_id=session.session_id,
+            transaction_id=(
+                session.active_transaction.transaction_id
+                if session.active_transaction is not None
+                else ""
+            ),
+            knowledge_structure=session.knowledge_structure,
+            metadata=dict(session.metadata),
+        )
+
+        session.version_history.append(version)
+
+        return version
+
+    def latest(
+        self,
+        session: RuntimeSession,
+    ) -> RuntimeVersion | None:
+        """
+        Return the latest Runtime Version.
+        """
+
+        if not session.version_history:
+            return None
+
+        return session.version_history[-1]
+
+    def retrieve(
+        self,
+        session: RuntimeSession,
+        version_id: str,
+    ) -> RuntimeVersion | None:
+        """
+        Retrieve a Runtime Version by identifier.
+        """
+
+        for version in session.version_history:
+            if version.version_id == version_id:
+                return version
+
+        return None
+
+    def list_versions(
+        self,
+        session: RuntimeSession,
+    ) -> tuple[RuntimeVersion, ...]:
+        """
+        Return immutable Runtime Version history.
+        """
+
+        return tuple(session.version_history)