Skip to content
CKS Documentation

ADR-004

Storage Abstraction

Section titled “Storage Abstraction”

Status: Accepted

Date: 2026-07-15

Category: Architecture Decision Record

Context

Section titled “Context”

CKS Runtime requires persistence capabilities to preserve operational state beyond the lifetime of an executing Runtime instance.

Runtime must support:

  • Session restoration;
  • Version History preservation;
  • Runtime continuity;
  • recovery after process termination.

Persistence technologies vary significantly between implementations.

Possible storage technologies include:

  • in-memory storage;
  • filesystem storage;
  • embedded databases;
  • relational databases;
  • distributed storage;
  • cloud storage.

An architectural decision is required regarding the ownership and abstraction boundary of persistence.

Problem

Section titled “Problem”

If Runtime directly depends on a specific storage implementation:

  • Runtime becomes coupled to infrastructure;
  • portability is reduced;
  • testing becomes more difficult;
  • alternative storage implementations become expensive.

If Storage owns semantic knowledge:

  • Core responsibilities are duplicated;
  • semantic boundaries are violated;
  • Runtime becomes dependent on storage representation.

A clear separation is required.

Decision

Section titled “Decision”

CKS Runtime shall use an implementation-independent Storage abstraction.

The reference implementation provides this abstraction through the RuntimeStorage abstract class in cks_runtime.storage.storage, which defines the canonical interface that every storage backend must satisfy.

Storage is responsible only for persistence of Runtime operational state.

Storage shall never define, validate or interpret knowledge semantics.

Storage shall preserve Runtime state without changing its observable meaning.

Ownership Model

Section titled “Ownership Model”

Two independent ownership relationships exist.

Semantic Authority

Section titled “Semantic Authority”
CKS Core


    defines


Canonical Knowledge Semantics

Operational Persistence

Section titled “Operational Persistence”
CKS Runtime


    owns


Runtime Operational State


        |


        v


Storage


    persists


Runtime State

Storage is subordinate to Runtime.

Storage does not own:

  • Sessions;
  • Transactions;
  • Version semantics;
  • Knowledge semantics.

Storage Responsibilities

Section titled “Storage Responsibilities”

Storage may provide:

  • persistence of Sessions;
  • persistence of committed Runtime state;
  • persistence of Versions;
  • persistence of Runtime metadata;
  • restoration capability.

The reference implementation ships with InMemoryStorage, a deterministic in‑memory backend that implements the RuntimeStorage interface and is suitable for testing and single‑process usage.

Storage shall not provide:

  • semantic validation;
  • knowledge interpretation;
  • transaction decisions;
  • lifecycle ownership;
  • recovery policy.

Transaction Boundary

Section titled “Transaction Boundary”

Persistence occurs only after successful Transaction completion.

The canonical flow is:

Session


    │


Transaction


    │


Commit


    │


Version Creation


    │


Storage Persistence

In the reference implementation, this flow is enforced by the ExecutionPipeline.commit method, which calls self._runtime.storage.save_version and self._runtime.storage.save_session only after a successful transaction commit.

Storage shall never:

  • commit Transactions;
  • decide Transaction outcomes;
  • persist partially completed Transactions.

Recovery Boundary

Section titled “Recovery Boundary”

Storage provides persistence and restoration capabilities.

Runtime owns:

  • recovery process;
  • Session reconstruction;
  • lifecycle restoration.

The reference implementation provides load_session and load_version methods on the RuntimeStorage interface, with corresponding error types (SessionNotFound, VersionNotFound) defined in cks_runtime.storage.exceptions.

Consequences

Section titled “Consequences”

Positive consequences include:

  • storage technology independence;
  • simpler Runtime testing;
  • deterministic persistence boundaries;
  • clean separation between execution and infrastructure;
  • support for multiple deployment models.

Negative consequences include:

  • additional abstraction layer;
  • explicit Storage interface design;
  • possible limitations imposed by abstraction.

These trade-offs are considered acceptable.

Alternatives Considered

Section titled “Alternatives Considered”

Direct Database Dependency

Section titled “Direct Database Dependency”

Runtime directly manages a database implementation.

Rejected because Runtime becomes coupled to a specific persistence technology.

Storage-Owned Lifecycle

Section titled “Storage-Owned Lifecycle”

Storage manages Sessions and Transactions.

Rejected because lifecycle ownership belongs to Runtime.

Knowledge-Aware Storage

Section titled “Knowledge-Aware Storage”

Storage understands canonical objects, relations and semantics.

Rejected because semantic ownership belongs exclusively to CKS Core.

Rationale

Section titled “Rationale”

Runtime must remain the authority over operational lifecycle.

Storage is an infrastructure capability, not an architectural owner.

The Storage abstraction allows Runtime to evolve independently from persistence technologies while preserving deterministic observable behaviour.

Relationship to Specifications

Section titled “Relationship to Specifications”

This decision is reflected by:

  • SPEC-006 Storage;
  • SPEC-005 Transactions;
  • SPEC-007 Version History;
  • SPEC-002 Session Model.

Future Runtime specifications shall preserve Storage abstraction.

Status

Section titled “Status”

Accepted.

Every conformant Runtime implementation shall interact with persistence mechanisms exclusively through the Runtime Storage abstraction.