cks-runtime 0.1.2__tar.gz

cks_runtime-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deus-corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cks_runtime-0.1.2/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: cks-runtime
+Version: 0.1.2
+Summary: Canonical Runtime for the Canonical Knowledge Structure ecosystem
+Author: Vladyslav Hruznov
+License: MIT
+Project-URL: Homepage, https://github.com/Deus-corp/cks-runtime
+Project-URL: Repository, https://github.com/Deus-corp/cks-runtime
+Project-URL: Issues, https://github.com/Deus-corp/cks-runtime/issues
+Keywords: canonical-knowledge-structure,runtime,knowledge-runtime,transactions,sessions,versioning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# CKS Runtime
+
+> The canonical operational environment for Canonical Knowledge Structures.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+
+CKS Runtime is the canonical execution environment for
+Canonical Knowledge Structures (CKS).
+
+Where **CKS Core** defines the semantics of knowledge,
+**CKS Runtime** defines its operational lifecycle.
+
+Runtime provides the infrastructure required to execute,
+manage, version, persist and expose Canonical Knowledge Structures
+without becoming a semantic authority itself.
+
+---
+
+# Why Runtime?
+
+Canonical knowledge is immutable.
+
+Operational state is not.
+
+Applications need to:
+
+- create sessions
+- execute transactions
+- maintain history
+- persist state
+- expose APIs
+- coordinate diagnostics
+
+These responsibilities belong to Runtime rather than CKS Core.
+
+```
+Canonical Knowledge Structure
+            │
+            ▼
+        CKS Runtime
+            │
+ ┌──────────┼──────────┐
+ ▼          ▼          ▼
+Session  Versioning  Storage
+```
+
+Runtime manages operational behaviour.
+
+CKS Core defines semantic behaviour.
+
+---
+
+# Core Principles
+
+CKS Runtime is founded on four architectural principles.
+
+### Runtime is not a semantic authority.
+
+Semantic meaning permanently belongs to CKS Core.
+
+Runtime never redefines knowledge.
+
+---
+
+### Runtime orchestrates semantic services.
+
+Validation.
+
+Evolution.
+
+Serialization.
+
+Diagnostics.
+
+These services originate from CKS Core.
+
+Runtime coordinates their execution.
+
+---
+
+### Operational state belongs to Runtime.
+
+Sessions.
+
+Transactions.
+
+Persistence.
+
+Version History.
+
+These are Runtime responsibilities.
+
+---
+
+### Observable behaviour is standardized.
+
+The Runtime Standard specifies observable operational behaviour rather than implementation techniques.
+
+---
+
+# Runtime Architecture
+
+The CKS ecosystem is organized into four architectural layers.
+
+```
+Applications
+        │
+        ▼
+Adapters
+        │
+        ▼
+CKS Runtime
+        │
+        ▼
+Public CKS Core API
+        │
+        ▼
+CKS Core
+```
+
+Responsibilities are strictly separated.
+
+| Layer | Responsibility |
+|--------|----------------|
+| CKS Core | Semantic authority |
+| CKS Runtime | Operational orchestration |
+| Adapters | Protocol exposure |
+| Applications | Business logic |
+
+---
+
+# Features
+
+The current Reference Runtime provides:
+
+- Runtime Sessions
+- Transaction Management
+- Version History
+- Storage Abstraction
+- Runtime Diagnostics
+- Explainability Coordination
+- Canonical Runtime API
+- Reference Runtime Architecture
+- Runtime Conformance Model
+
+---
+
+# Design Goals
+
+CKS Runtime is designed to be:
+
+- deterministic
+- implementation-independent
+- transport-independent
+- storage-independent
+- session-oriented
+- transaction-oriented
+- semantically neutral
+
+---
+
+# Relationship to CKS Core
+
+CKS Runtime depends upon CKS Core.
+
+CKS Runtime never replaces CKS Core.
+
+```
+CKS Core
+    defines semantics
+
+        │
+
+        ▼
+
+CKS Runtime
+    orchestrates semantics
+    manages operational lifecycle
+```
+
+Runtime communicates exclusively through the public CKS Core API.
+
+---
+
+# Installation
+
+From PyPI:
+
+```bash
+pip install cks-core
+pip install cks-runtime
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Deus-corp/cks-runtime.git
+
+cd cks-runtime
+
+pip install -e .
+```
+
+---
+
+# Quick Example
+
+```python
+from cks_runtime import Runtime
+
+runtime = Runtime()
+
+session = runtime.sessions.create(
+    knowledge_structure=my_structure
+)
+
+transaction = runtime.transactions.begin(session)
+
+# Runtime coordinates execution.
+# CKS Core defines semantics.
+```
+
+---
+
+# Documentation
+
+The Runtime Standard consists of the following normative specifications.
+
+| Specification | Purpose |
+|--------------|---------|
+| SPEC-001 | Runtime Overview |
+| SPEC-002 | Session Model |
+| SPEC-003 | Runtime API |
+| SPEC-004 | Diagnostics |
+| SPEC-005 | Transactions |
+| SPEC-006 | Storage |
+| SPEC-007 | Version History |
+| SPEC-008 | Runtime Conformance |
+
+Supporting documents include:
+
+- Runtime Charter
+- Architectural Analyses
+- Architecture Decision Records
+- Reference Architecture
+
+---
+
+# Project Status
+
+Current implementation status:
+
+| Component | Status |
+|----------|--------|
+| Runtime Architecture | ✅ Complete |
+| Session Model | ✅ Complete |
+| Transaction Model | ✅ Complete |
+| Version History | ✅ Complete |
+| Diagnostics | ✅ Complete |
+| Storage Abstraction | ✅ Complete |
+| Runtime API | ✅ Complete |
+| Runtime Documentation | ✅ Complete |
+| Reference Implementation | 🚧 In Progress |
+| Adapter Integration | ⏳ Planned |
+
+---
+
+# Long-Term Vision
+
+CKS Runtime aims to become the canonical operational foundation shared by every CKS-compatible implementation.
+
+Future adapter standards—including MCP, CLI, HTTP and others—will rely on Runtime rather than communicating directly with CKS Core.
+
+This preserves a single semantic authority while allowing unlimited operational implementations.
+
+---
+
+# License
+
+MIT

cks_runtime-0.1.2/README.md

@@ -0,0 +1,282 @@
+# CKS Runtime
+
+> The canonical operational environment for Canonical Knowledge Structures.
+
+![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Status](https://img.shields.io/badge/status-alpha-orange)
+
+CKS Runtime is the canonical execution environment for
+Canonical Knowledge Structures (CKS).
+
+Where **CKS Core** defines the semantics of knowledge,
+**CKS Runtime** defines its operational lifecycle.
+
+Runtime provides the infrastructure required to execute,
+manage, version, persist and expose Canonical Knowledge Structures
+without becoming a semantic authority itself.
+
+---
+
+# Why Runtime?
+
+Canonical knowledge is immutable.
+
+Operational state is not.
+
+Applications need to:
+
+- create sessions
+- execute transactions
+- maintain history
+- persist state
+- expose APIs
+- coordinate diagnostics
+
+These responsibilities belong to Runtime rather than CKS Core.
+
+```
+Canonical Knowledge Structure
+            │
+            ▼
+        CKS Runtime
+            │
+ ┌──────────┼──────────┐
+ ▼          ▼          ▼
+Session  Versioning  Storage
+```
+
+Runtime manages operational behaviour.
+
+CKS Core defines semantic behaviour.
+
+---
+
+# Core Principles
+
+CKS Runtime is founded on four architectural principles.
+
+### Runtime is not a semantic authority.
+
+Semantic meaning permanently belongs to CKS Core.
+
+Runtime never redefines knowledge.
+
+---
+
+### Runtime orchestrates semantic services.
+
+Validation.
+
+Evolution.
+
+Serialization.
+
+Diagnostics.
+
+These services originate from CKS Core.
+
+Runtime coordinates their execution.
+
+---
+
+### Operational state belongs to Runtime.
+
+Sessions.
+
+Transactions.
+
+Persistence.
+
+Version History.
+
+These are Runtime responsibilities.
+
+---
+
+### Observable behaviour is standardized.
+
+The Runtime Standard specifies observable operational behaviour rather than implementation techniques.
+
+---
+
+# Runtime Architecture
+
+The CKS ecosystem is organized into four architectural layers.
+
+```
+Applications
+        │
+        ▼
+Adapters
+        │
+        ▼
+CKS Runtime
+        │
+        ▼
+Public CKS Core API
+        │
+        ▼
+CKS Core
+```
+
+Responsibilities are strictly separated.
+
+| Layer | Responsibility |
+|--------|----------------|
+| CKS Core | Semantic authority |
+| CKS Runtime | Operational orchestration |
+| Adapters | Protocol exposure |
+| Applications | Business logic |
+
+---
+
+# Features
+
+The current Reference Runtime provides:
+
+- Runtime Sessions
+- Transaction Management
+- Version History
+- Storage Abstraction
+- Runtime Diagnostics
+- Explainability Coordination
+- Canonical Runtime API
+- Reference Runtime Architecture
+- Runtime Conformance Model
+
+---
+
+# Design Goals
+
+CKS Runtime is designed to be:
+
+- deterministic
+- implementation-independent
+- transport-independent
+- storage-independent
+- session-oriented
+- transaction-oriented
+- semantically neutral
+
+---
+
+# Relationship to CKS Core
+
+CKS Runtime depends upon CKS Core.
+
+CKS Runtime never replaces CKS Core.
+
+```
+CKS Core
+    defines semantics
+
+        │
+
+        ▼
+
+CKS Runtime
+    orchestrates semantics
+    manages operational lifecycle
+```
+
+Runtime communicates exclusively through the public CKS Core API.
+
+---
+
+# Installation
+
+From PyPI:
+
+```bash
+pip install cks-core
+pip install cks-runtime
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/Deus-corp/cks-runtime.git
+
+cd cks-runtime
+
+pip install -e .
+```
+
+---
+
+# Quick Example
+
+```python
+from cks_runtime import Runtime
+
+runtime = Runtime()
+
+session = runtime.sessions.create(
+    knowledge_structure=my_structure
+)
+
+transaction = runtime.transactions.begin(session)
+
+# Runtime coordinates execution.
+# CKS Core defines semantics.
+```
+
+---
+
+# Documentation
+
+The Runtime Standard consists of the following normative specifications.
+
+| Specification | Purpose |
+|--------------|---------|
+| SPEC-001 | Runtime Overview |
+| SPEC-002 | Session Model |
+| SPEC-003 | Runtime API |
+| SPEC-004 | Diagnostics |
+| SPEC-005 | Transactions |
+| SPEC-006 | Storage |
+| SPEC-007 | Version History |
+| SPEC-008 | Runtime Conformance |
+
+Supporting documents include:
+
+- Runtime Charter
+- Architectural Analyses
+- Architecture Decision Records
+- Reference Architecture
+
+---
+
+# Project Status
+
+Current implementation status:
+
+| Component | Status |
+|----------|--------|
+| Runtime Architecture | ✅ Complete |
+| Session Model | ✅ Complete |
+| Transaction Model | ✅ Complete |
+| Version History | ✅ Complete |
+| Diagnostics | ✅ Complete |
+| Storage Abstraction | ✅ Complete |
+| Runtime API | ✅ Complete |
+| Runtime Documentation | ✅ Complete |
+| Reference Implementation | 🚧 In Progress |
+| Adapter Integration | ⏳ Planned |
+
+---
+
+# Long-Term Vision
+
+CKS Runtime aims to become the canonical operational foundation shared by every CKS-compatible implementation.
+
+Future adapter standards—including MCP, CLI, HTTP and others—will rely on Runtime rather than communicating directly with CKS Core.
+
+This preserves a single semantic authority while allowing unlimited operational implementations.
+
+---
+
+# License
+
+MIT

cks_runtime-0.1.2/cks_runtime/__init__.py

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

cks_runtime-0.1.2/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-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.
+        """