SPEC-002

Session Model

Status: Draft

Standard: CKS Runtime

Category: Foundational Runtime Specification

1. Purpose

This specification defines the canonical Runtime Session model.

A Runtime Session is the fundamental operational execution unit of the Runtime Standard.

Every Runtime operation shall execute within exactly one Session.

This specification establishes the conceptual execution boundary used throughout the Runtime Standard.

2. Scope

This specification defines:

the Session concept;
Session ownership;
Session state;
Session lifecycle;
Session isolation;
Session responsibilities.

Implementation details are intentionally omitted.

3. Session Definition

A Runtime Session is an isolated operational environment responsible for managing the lifecycle of Canonical Knowledge Structures within a Runtime execution context.

A Session represents operational state.

A Session does not represent semantic state.

Semantic meaning remains exclusively defined by CKS Core.

The Session model defines an execution context rather than a knowledge model.

4. Session Identity

Each Session possesses a unique Runtime identity.

Session identities are implementation-defined.

Runtime identities are operational identifiers and shall never be interpreted as canonical knowledge identifiers.

Session identity is completely independent of every canonical identity defined by CKS Core.

5. Session State

A Session maintains operational state associated with Canonical Knowledge Structures.

Conceptually, Session state consists of:

references to managed Canonical Knowledge Structures;
Runtime metadata;
diagnostics;
transaction context;
Version History;
Storage context;
explainability context.

In the reference implementation, RuntimeSession is a dataclass that holds the knowledge_structure, session metadata, diagnostics, version history, and an optional active transaction. The SessionManager owns the registry of active sessions.

Runtime implementations may maintain additional implementation-specific state provided such state does not alter canonical semantics.

6. Session Lifecycle

Every Session progresses through a canonical lifecycle.

Created
    ↓
Initialized
    ↓
Active
    ↓
Closed

Transactions, persistence operations and version creation occur during the Active lifecycle state.

Implementations may internally refine this lifecycle provided its externally observable behaviour remains equivalent.

The reference implementation tracks the lifecycle state through a closed flag on RuntimeSession. The SessionManager is responsible for removing closed sessions from the active registry.

7. Session Responsibilities

A Runtime Session is responsible for:

maintaining Runtime operational state;
coordinating validation requests;
coordinating transaction execution;
maintaining diagnostic collections;
maintaining Runtime history;
exposing Runtime capabilities through Runtime APIs.

A Session shall never:

redefine canonical semantics;
modify validation rules;
reinterpret canonical diagnostics;
replace canonical evolution.

8. Session Isolation

Sessions are operationally isolated.

Operations performed within one Session shall not directly modify another Session.

Session isolation guarantees independent execution contexts.

Communication between Sessions, when supported, shall occur exclusively through Runtime-defined mechanisms.

9. Session Ownership

A Runtime execution context owns one or more Sessions.

Each Session belongs to exactly one Runtime ownership context.

A Session shall not simultaneously belong to multiple Runtime ownership contexts.

Ownership is operational rather than semantic.

10. Relationship to Runtime

Runtime coordinates Sessions.

Sessions coordinate operational state.

Knowledge semantics remain delegated to CKS Core.

The conceptual dependency hierarchy is:

Runtime
        ↓
Session
        ↓
Canonical Knowledge Structure
        ↓
CKS Core

In the reference implementation this hierarchy is realised by the Runtime façade, which delegates session management to SessionManager. SessionManager owns the collection of RuntimeSession objects and provides the sole interface for creating, retrieving, and closing sessions.

Each layer owns a distinct architectural responsibility.

11. Relationship to Adapters

External adapters shall never manipulate Canonical Knowledge Structures directly.

Adapters communicate exclusively through Runtime APIs.

Runtime APIs provide access to Session-scoped operations.

Examples include:

MCP adapters;
CLI adapters;
HTTP adapters;
Python API adapters.

The Session therefore represents the canonical execution boundary inside Runtime between operational services and managed knowledge state.

12. Design Principles

The Session model follows several architectural principles.

Operational Isolation

Sessions execute independently.

Semantic Neutrality

Sessions preserve the semantic guarantees established by CKS Core.

Deterministic Coordination

Sessions coordinate Runtime operations without introducing semantic ambiguity.

Extensibility

Future Runtime specifications may extend Session behaviour without altering the architectural role of the Session model.

13. Conformance

A Runtime implementation conforms to this specification when every Runtime operation:

executes within exactly one Session;
preserves Session isolation;
preserves the semantic guarantees established by CKS Core;
maintains Session ownership as defined by this specification.

Conformance to this specification does not imply conformance to the complete Runtime Standard.

14. Summary

The Runtime Session is the fundamental operational execution context of the CKS Runtime Standard.

Sessions own Runtime operational state, coordinate operational behaviour and provide the execution boundary through which Runtime capabilities are exposed while preserving the canonical semantic guarantees established by CKS Core.

Subsequent Runtime specifications build upon the Session model introduced by this specification.