CKS Runtime
The canonical operational environment for Canonical Knowledge Structures.
🚀 Live demo → — explore the CKS ecosystem graph directly in your browser, no server required.
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. Now fully async with PostgreSQL support.
Ecosystem
CKS Runtime is part of a family of interoperable projects built on the Canonical Knowledge Structure.
| Project | Description | Repository |
|---|---|---|
| cks-core | Canonical semantic engine – the single source of canonical truth. | cks-core |
| cks-runtime | Operational environment – sessions, transactions, persistence. | cks-runtime |
| cks-mcp | MCP server – exposes CKS to LLMs and autonomous agents. | cks-mcp |
| cks-studio | Visual workspace – explore, monitor, and manage graphs. | cks-studio |
| cks-website | Documentation & demo site. | cks-website |
📖 Full documentation, case studies, and an interactive demo are available at the CKS Documentation Site.
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 |
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
- CKS Core Integration (via
CksCoreAdapter) - Execution Engine – canonical operations (Validate, Serialize, Explain, Evolve, Diff) via
CoreBridge - Operation Dispatcher – registry-based operation resolution
- Event System – lifecycle events published via
EventBus - Time-Travel Operations –
ListVersionsOperation,RevertVersionOperation - Structural Diff – compact change computation between versions
- Three‑way merge of knowledge structures via
cks-core'smerge()function - Query Subgraph – k‑hop neighbourhood extraction with type filters and budget/ranking, delegated to cks-core's query_subgraph()
- Persistent Storage – SQLite-backed storage via
SQLiteStorage, surviving server restarts. Configurable throughRuntimeConfig.storage_path. - Indexed & Vectorized Embeddings –
search_embeddingsuses NumPy matrix operations for ~10× faster similarity search, with a database index for multi-session scalability. - PostgreSQL Storage Backend — production-grade, async connection pooling, JSONB payloads, outbox with
SELECT ... FOR UPDATE SKIP LOCKED, and pgvector-powered semantic search with HNSW index. - Shared Patch Codec — consistent serialization/deserialization of structural operators across SQLite and Postgres backends.
- Session Garbage Collector – background task that automatically archives stale closed sessions, keeping storage compact in long-running deployments. Configurable retention window and sweep interval.
- Local embeddings via fastembed – offline, token-free semantic search with
FastEmbedEmbeddingClient(pip install cks-runtime[fastembed]). - Gossip Replication (ADR-008) — peer-to-peer session exchange: replica identity, HMAC-signed envelopes, replay protection, peer discovery (
PeerDiscovery,HTTPPeerDiscovery), weighted peer selection with backoff (PeerScheduler), and a background anti-entropy service (GossipService). HTTP transport viaaiohttp(pip install cks-runtime[gossip]). - CRDT Adapter (ADR-013) — conflict-free replicated storage layer beneath gossip: a grow-only set with a content-addressed Merkle prefix tree, an MV-Register with causal ordering and automatic fork detection, and quarantine validation (
cks.validate()+ Merkle-identity checks) wired into every incoming merge. PublishesCRDTForkDetectedevents and detects duplicate replica IDs to block silent divergence. - Autonomous Sweepers — seven background, detection-only sweepers that escalate findings into the persistent outbox rather than acting unilaterally:
ContradictionSweeper,InferenceStalenessSweeper(ADR-009),ProvenanceStalenessSweeper(ADR-010),TemporalStalenessSweeper(ADR-011),GraphFreshnessSweeper,GraphAutoUpdateSweeper, andGraphHealthSweeper. Shared observability viaSweeperStatusMixin/list_agent_statuses(), and remote start/stop control through persisted overrides (ADR-015). - Agent Infrastructure — liveness tracking (
cks_agent_liveness) and stop signalling (ADR-016) for external standalone agent processes (Critic, Enrichment, Fork Resolution, Pipeline);AgentStepStarted/AgentStepCompletedevents for pipeline observability. - Graph Registry —
register_graph/get_graph/list_graphspersist named session references, the storage foundation forcks-mcp's Memory Agent. - Backup & Disaster Recovery (ADR-012) —
export_storage()/import_storage()across every backend for full data dumps and clear/merge restores. - Persistent Outbox — task-type filtering, dead-letter queue (
dead_letter_outbox_task,list_dead_letter_tasks), and batch peek/drain by type, so multiple workers can share one outbox table without stealing each other's tasks.
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:
pip install cks-runtime
Or from source:
git clone https://github.com/PunctumActus/cks-runtime.git
cd cks-runtime
pip install -e .
Quick Example
from cks_runtime import Runtime
from cks_runtime.adapters.cks_core import CksCoreAdapter
from cks_runtime.operations.operation_types import (
ValidateOperation,
EvolveOperation,
ListVersionsOperation,
RevertVersionOperation,
)
# Create Runtime with real CKS Core
runtime = Runtime(core=CksCoreAdapter())
# Create a session and validate a knowledge structure
session = runtime.create_session({"example": True})
tx = runtime.begin_transaction(session)
tx.add_operation(ValidateOperation("v1", knowledge_structure=session.knowledge_structure))
version = runtime.commit_transaction(tx)
# Evolve the structure
tx2 = runtime.begin_transaction(session)
tx2.add_operation(EvolveOperation("evolve", knowledge_structure=session.knowledge_structure, evolution=[]))
version2 = runtime.commit_transaction(tx2)
# List versions
versions = runtime.executor.execute(ListVersionsOperation(), session)
print(versions.payload)
# Revert to the first version
tx3 = runtime.begin_transaction(session)
tx3.add_operation(RevertVersionOperation("revert", target_version_id=version.version_id))
runtime.commit_transaction(tx3)
Storage Backends
CKS Runtime supports pluggable storage backends through a unified async interface (AsyncRuntimeStorage):
| Backend | Type | Status | Notes |
|---|---|---|---|
| InMemoryStorage | Sync | ✅ Stable | For testing and ephemeral sessions |
| SQLiteStorage | Sync | ✅ Stable | Persistent, single‑writer, WAL mode |
| PostgresStorage | Async | ✅ Stable | Production‑grade, connection pooling, JSONB, outbox, pgvector embeddings with HNSW index |
Sync backends (InMemoryStorage, SQLiteStorage) are automatically adapted to the async interface via SyncStorageAdapter (using asyncio.to_thread), so existing code works unchanged. Use await Runtime.create(...) for full async startup, or plain Runtime(...) for lightweight testing without persistence.
Documentation
📚 CKS Documentation — architecture guides, case studies, and API reference across all CKS projects.
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 |
| Async Runtime | ✅ Complete |
| PostgreSQL Backend | ✅ Complete |
| Session Garbage Collector | ✅ Complete |
| Core Integration (CoreBridge) | ✅ Complete |
| Execution Engine (Operations + Dispatcher) | ✅ Complete |
| Event System | ✅ Complete |
| Time-Travel Operations | ✅ Complete |
| Structural Diff | ✅ Complete |
| Query Subgraph | ✅ Complete |
| Persistent Storage (SQLite) | ✅ Complete |
| Gossip Replication (ADR-008) | ✅ Complete — peer discovery, anti-entropy, duplicate replica ID detection |
| CRDT Adapter (ADR-013) | ✅ Complete — G-Set + Merkle tree, MV-Register, fork detection, quarantine |
| Autonomous Sweepers (7) | ✅ Complete — contradiction, inference/provenance/temporal staleness, graph freshness/auto-update/health |
| Sweeper Control (ADR-015) | ✅ Complete |
| Agent Liveness & Control (ADR-016) | ✅ Complete |
| Graph Registry | ✅ Complete |
| Backup & Disaster Recovery (ADR-012) | ✅ Complete |
| Outbox: task-type filter, DLQ | ✅ Complete |
| Test Suite | ✅ 790 tests passing (+68 requiring optional backends: Postgres, gossip) |
The current implementation serves as the reference implementation of the CKS Runtime Standard (SPEC-001 … SPEC-008).
Future work focuses on Runtime Platform 2.0: dependency resolution and
parallel execution in the Execution Engine, distributed transactions and
leader election, and a unified observability platform. See ROADMAP.md
for the full breakdown.
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cks_runtime-1.57.3.tar.gz.
File metadata
- Download URL: cks_runtime-1.57.3.tar.gz
- Upload date:
- Size: 207.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1c1561ac2a62df17f3209a2c2c61df5745fc6f01c43eed4e794cf5764c74c3ca
|
|
| MD5 |
0c6f4443250195d4bbde3c5852fe4b86
|
|
| BLAKE2b-256 |
54474af3a1df1ce523ffbec60e235dc6be10d567206c8bb928556a0234e2fa58
|
File details
Details for the file cks_runtime-1.57.3-py3-none-any.whl.
File metadata
- Download URL: cks_runtime-1.57.3-py3-none-any.whl
- Upload date:
- Size: 251.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.15
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
72b486ccc9222f3cbdc46d6439a4da9bc8bbbbc5595135a72a82e11ecce82437
|
|
| MD5 |
2ccb2470df316dc1579cd1bfb1aaa347
|
|
| BLAKE2b-256 |
cf1090d7403878f44186fdd865f5d2178ba41bfb2d896fc0932569f1f688b78b
|
