cks-runtime 0.1.2__py3-none-any.whl

cks_runtime/__init__.py

@@ -0,0 +1,11 @@
+"""
+CKS Runtime.
+"""
+
+from .runtime import Runtime
+from .config import RuntimeConfig
+
+__all__ = [
+    "Runtime",
+    "RuntimeConfig",
+]

cks_runtime/config.py

@@ -0,0 +1,22 @@
+"""
+Runtime configuration.
+
+SPEC-001 Runtime Overview
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class RuntimeConfig:
+    """
+    Runtime configuration.
+
+    Future specifications may extend this configuration.
+    """
+
+    runtime_name: str = "CKS Runtime"
+
+    runtime_version: str = "0.1.2"

cks_runtime/core_api/interfaces.py

@@ -0,0 +1,78 @@
+"""
+Core boundary interfaces.
+
+This module defines the exclusive semantic boundary
+between CKS Runtime and CKS Core.
+
+Runtime depends only on these abstractions.
+
+Concrete Core implementations are supplied externally.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from typing import Any
+
+
+class CoreInterface(ABC):
+    """
+    Semantic boundary between Runtime and CKS Core.
+
+    Runtime owns operational behaviour.
+
+    CKS Core owns semantic behaviour.
+
+    Runtime shall never implement semantic rules itself.
+    """
+
+    @abstractmethod
+    def validate(
+        self,
+        knowledge_structure: Any,
+    ) -> Any:
+        """
+        Execute canonical Core validation.
+
+        Validation semantics belong exclusively
+        to CKS Core.
+        """
+
+    @abstractmethod
+    def serialize(
+        self,
+        knowledge_structure: Any,
+    ) -> Any:
+        """
+        Produce canonical serialization.
+
+        Serialization semantics belong exclusively
+        to CKS Core.
+        """
+
+    @abstractmethod
+    def evolve(
+        self,
+        knowledge_structure: Any,
+        operation: Any,
+    ) -> Any:
+        """
+        Execute canonical semantic evolution.
+
+        Runtime coordinates execution.
+
+        CKS Core defines the resulting semantic state.
+        """
+
+    @abstractmethod
+    def explain(
+        self,
+        knowledge_structure: Any,
+    ) -> Any:
+        """
+        Produce semantic explanation.
+
+        Runtime may expose explanations but never
+        generates semantic explanations itself.
+        """

cks_runtime/diagnostics/aggregator.py

@@ -0,0 +1,115 @@
+"""
+Runtime Diagnostic Aggregator.
+
+Aggregates Runtime and Core diagnostics.
+
+Aggregation preserves ordering and ownership.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from .diagnostic import (
+    Diagnostic,
+    DiagnosticSeverity,
+)
+
+
+class DiagnosticAggregator:
+    """
+    Collects Runtime Diagnostics.
+
+    Diagnostics remain immutable.
+
+    Aggregation never modifies their meaning.
+    """
+
+    def __init__(self) -> None:
+        self._diagnostics: list[Diagnostic] = []
+
+
+    def add(
+        self,
+        diagnostic: Diagnostic,
+    ) -> None:
+        """
+        Add a Diagnostic.
+        """
+
+        self._diagnostics.append(
+            diagnostic
+        )
+
+
+    def extend(
+        self,
+        diagnostics: Iterable[Diagnostic],
+    ) -> None:
+        """
+        Add multiple Diagnostics.
+        """
+
+        self._diagnostics.extend(
+            diagnostics
+        )
+
+
+    def clear(
+        self,
+    ) -> None:
+        """
+        Remove all Diagnostics.
+        """
+
+        self._diagnostics.clear()
+
+
+    def all(
+        self,
+    ) -> tuple[Diagnostic, ...]:
+        """
+        Return an immutable snapshot.
+        """
+
+        return tuple(
+            self._diagnostics
+        )
+
+
+    def count(
+        self,
+    ) -> int:
+        return len(
+            self._diagnostics
+        )
+
+
+    def has_errors(
+        self,
+    ) -> bool:
+        """
+        True if any Runtime Diagnostic has ERROR severity.
+        """
+
+        return any(
+            diagnostic.severity
+            is DiagnosticSeverity.ERROR
+            for diagnostic in self._diagnostics
+        )
+
+
+    def __len__(
+        self,
+    ) -> int:
+        return len(
+            self._diagnostics
+        )
+
+
+    def __iter__(
+        self,
+    ):
+        return iter(
+            self._diagnostics
+        )

cks_runtime/diagnostics/diagnostic.py

@@ -0,0 +1,68 @@
+"""
+Runtime Diagnostic model.
+
+Runtime Diagnostics describe operational observations.
+
+They never modify Runtime state and never redefine
+CKS Core semantics.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+
+class DiagnosticSource(str, Enum):
+    """
+    Origin of a Diagnostic.
+    """
+
+    CORE = "core"
+    RUNTIME = "runtime"
+
+
+class DiagnosticSeverity(str, Enum):
+    """
+    Runtime Diagnostic severity.
+    """
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """
+    Immutable Runtime Diagnostic.
+
+    Ownership:
+
+    - Core Diagnostics belong to CKS Core;
+    - Runtime Diagnostics belong to Runtime;
+    - Runtime preserves diagnostics without modifying them.
+    """
+
+    message: str
+
+    source: DiagnosticSource
+
+    severity: DiagnosticSeverity
+
+    code: str | None = None
+
+    metadata: dict[str, Any] = field(
+        default_factory=dict
+    )
+
+    diagnostic_id: UUID = field(
+        default_factory=uuid4
+    )
+
+    created_at: datetime = field(
+        default_factory=lambda: datetime.now(UTC)
+    )

cks_runtime/runtime.py

@@ -0,0 +1,85 @@
+"""
+Canonical Runtime.
+
+SPEC-001 Runtime Overview.
+
+Runtime coordinates operational behaviour.
+
+Runtime never owns semantics.
+"""
+
+from __future__ import annotations
+
+from cks_runtime.config import RuntimeConfig
+
+from cks_runtime.core_api.interfaces import CoreInterface
+
+from cks_runtime.diagnostics.aggregator import (
+    DiagnosticAggregator,
+)
+
+from cks_runtime.session.session_manager import (
+    SessionManager,
+)
+
+from cks_runtime.storage.memory_storage import (
+    InMemoryStorage,
+)
+
+from cks_runtime.storage.storage import (
+    RuntimeStorage,
+)
+
+from cks_runtime.transaction.transaction_manager import (
+    TransactionManager,
+)
+
+from cks_runtime.versioning.version_manager import (
+    VersionManager,
+)
+
+
+class Runtime:
+    """
+    Canonical Runtime.
+
+    Coordinates Runtime subsystems.
+
+    Ownership:
+
+    - Sessions;
+    - Transactions;
+    - Version History;
+    - Diagnostics;
+    - Storage.
+
+    Runtime never owns semantic behaviour.
+    Semantic behaviour belongs exclusively
+    to CKS Core.
+    """
+
+    def __init__(
+        self,
+        *,
+        core: CoreInterface | None = None,
+        storage: RuntimeStorage | None = None,
+        config: RuntimeConfig | None = None,
+    ) -> None:
+
+        self.config = config or RuntimeConfig()
+
+        self.core = core
+
+        self.storage = (
+            storage
+            if storage is not None
+            else InMemoryStorage()
+        )
+
+        self.sessions = SessionManager()
+
+        self.transactions = TransactionManager()
+
+        self.versions = VersionManager()
+
+        self.diagnostics = DiagnosticAggregator()

cks_runtime/session/session.py

@@ -0,0 +1,72 @@
+"""
+Runtime Session model.
+
+A Runtime Session is the fundamental operational
+boundary of CKS Runtime.
+
+A Session owns Runtime operational state.
+
+A Session never owns semantic meaning, which remains
+the responsibility of CKS Core.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class RuntimeSession:
+    """
+    Represents an isolated Runtime execution context.
+
+    A Runtime Session owns operational state only.
+
+    Ownership rules:
+
+    - exactly one Runtime owns a Session;
+    - exactly one Session owns its Runtime state;
+    - semantic meaning belongs exclusively to CKS Core.
+    """
+
+    knowledge_structure: Any
+
+    session_id: str = field(
+        default_factory=lambda: str(uuid4())
+    )
+
+    metadata: dict[str, Any] = field(
+        default_factory=dict
+    )
+
+    diagnostics: list[Any] = field(
+        default_factory=list
+    )
+
+    version_history: list[Any] = field(
+        default_factory=list
+    )
+
+    active_transaction: Any | None = None
+
+    closed: bool = False
+
+    @property
+    def is_active(self) -> bool:
+        """
+        Returns True while the Session remains active.
+        """
+
+        return not self.closed
+
+    def close(self) -> None:
+        """
+        Close the Runtime Session.
+
+        Closing a Session ends its operational lifecycle.
+
+        Lifecycle ownership remains the responsibility of
+        SessionManager.
+        """
+
+        self.closed = True

cks_runtime/session/session_manager.py

@@ -0,0 +1,98 @@
+"""
+Runtime Session Manager.
+
+Owns Runtime Session lifecycle.
+
+Responsibilities:
+
+- create Sessions;
+- retrieve Sessions;
+- enumerate active Sessions;
+- close Sessions.
+
+Does not own:
+
+- semantic validation;
+- persistence;
+- transactions;
+- version history.
+"""
+
+from typing import Any
+
+from .session import RuntimeSession
+
+
+class SessionManager:
+    """
+    Owns Runtime Session lifecycle.
+    """
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, RuntimeSession] = {}
+
+    def create_session(
+        self,
+        knowledge_structure: Any,
+    ) -> RuntimeSession:
+        """
+        Create and register a new Runtime Session.
+        """
+
+        session = RuntimeSession(
+            knowledge_structure=knowledge_structure,
+        )
+
+        self._sessions[
+            session.session_id
+        ] = session
+
+        return session
+
+    def get_session(
+        self,
+        session_id: str,
+    ) -> RuntimeSession | None:
+        """
+        Return a Runtime Session by identifier.
+
+        Returns None if the Session does not exist.
+        """
+
+        return self._sessions.get(
+            session_id,
+        )
+
+    def list_sessions(
+        self,
+    ) -> list[RuntimeSession]:
+        """
+        Return all currently active Runtime Sessions.
+        """
+
+        return list(
+            self._sessions.values(),
+        )
+
+    def close_session(
+        self,
+        session_id: str,
+    ) -> None:
+        """
+        Close and unregister a Runtime Session.
+
+        Unknown Session identifiers are ignored.
+        """
+
+        session = self._sessions.get(
+            session_id,
+        )
+
+        if session is None:
+            return
+
+        session.close()
+
+        del self._sessions[
+            session_id
+        ]

cks_runtime/storage/exceptions.py

@@ -0,0 +1,37 @@
+"""
+Storage exceptions.
+
+SPEC-006 Storage
+"""
+
+from __future__ import annotations
+
+
+class StorageError(Exception):
+    """
+    Base Runtime Storage exception.
+    """
+
+
+class SessionNotFound(StorageError):
+    """
+    Requested Runtime Session does not exist.
+    """
+
+    def __init__(self, session_id: str):
+        super().__init__(
+            f"Runtime Session '{session_id}' was not found."
+        )
+        self.session_id = session_id
+
+
+class VersionNotFound(StorageError):
+    """
+    Requested Runtime Version does not exist.
+    """
+
+    def __init__(self, version_id: str):
+        super().__init__(
+            f"Runtime Version '{version_id}' was not found."
+        )
+        self.version_id = version_id