Skip to content

SPEC-004

Diagnostics

Status: Draft

Standard: CKS Runtime

Category: Runtime Diagnostics Specification

1. Purpose

This specification defines the Runtime Diagnostics model.

Runtime Diagnostics describe operational events that occur during the execution of Runtime services.

This specification also defines how canonical diagnostics produced by CKS Core are transported, associated and exposed within Runtime.

2. Scope

This specification defines:

  • diagnostic categories;
  • diagnostic ownership;
  • diagnostic aggregation;
  • diagnostic lifetime;
  • diagnostic exposure;
  • Runtime responsibilities.

It does not redefine the canonical Diagnostic model defined by CKS Core.

3. Diagnostic Philosophy

Diagnostics communicate observations.

Diagnostics are observational artifacts rather than state transitions.

Diagnostics never modify Canonical Knowledge Structures.

Runtime may retain, aggregate and expose diagnostics without altering their meaning.

Diagnostics are immutable after creation.

Runtime may create references, associations or retention records, but shall not alter diagnostic meaning.

4. Diagnostic Categories

Runtime distinguishes two categories of diagnostics.

Core Diagnostics

Core Diagnostics originate exclusively from CKS Core.

Examples include:

  • structural diagnostics;
  • semantic diagnostics;
  • constraint diagnostics;
  • validation diagnostics.

Runtime shall preserve these diagnostics without modification.

Runtime may associate Core Diagnostics with Runtime execution context without changing their canonical identity.

Runtime Diagnostics

Runtime Diagnostics describe operational behavior.

Examples include:

  • session events;
  • transaction failures;
  • persistence failures;
  • storage events;
  • runtime lifecycle events.

Runtime Diagnostics shall never redefine canonical semantics.

5. Diagnostic Ownership

Core Diagnostics are owned by CKS Core.

Runtime Diagnostics are owned by Runtime.

Ownership shall remain immutable throughout the diagnostic lifetime.

Ownership is independent from storage location.

Persisting a diagnostic does not transfer ownership.

6. Diagnostic Aggregation

Runtime aggregates diagnostics originating from multiple Runtime components.

Conceptually:

                Runtime

                    │

        Diagnostic Aggregator

          ┌─────────┴─────────┐

          │                   │

   Core Diagnostics    Runtime Diagnostics
````

In the reference implementation, aggregation is performed by the
`DiagnosticAggregator` class. It collects both `Diagnostic` objects
(Runtime‑owned) and diagnostics forwarded from `CksCoreAdapter`
(Core‑owned), preserving their ownership and immutability.

Aggregation shall preserve diagnostic ownership.

Aggregation shall never modify diagnostic content.

---

# 7. Session Association

Every Runtime Diagnostic belongs to exactly one Runtime Session.

Core Diagnostics become associated with the Session during Runtime execution.

Session association is a Runtime operational association and does not change Core Diagnostic ownership.

Diagnostics shall never simultaneously belong to multiple Sessions.

---

# 8. Diagnostic Lifetime

Runtime Diagnostic lifetime is controlled by Runtime retention policies.

Core Diagnostic lifetime is defined by CKS Core.

Runtime retention shall not affect Core Diagnostic semantics.

Removing diagnostics shall never modify the associated Canonical Knowledge Structure.

---

# 9. Runtime Responsibilities

Runtime is responsible for:

* collecting diagnostics;
* preserving diagnostic ownership;
* preserving diagnostic ordering where deterministic ordering exists;
* exposing diagnostics through Runtime APIs;
* associating diagnostics with Sessions.

Runtime shall not reinterpret canonical diagnostics produced by CKS Core.

---

# 10. Diagnostic Exposure Model

Runtime API may expose diagnostics together with operation results.

Conceptually:

```text
Runtime Operation Result

        │

        ├── Operation Outcome

        ├── Core Diagnostics

        └── Runtime Diagnostics

The reference implementation realises this model in the RuntimeValidationResult class, which combines the validation outcome, Core diagnostics, and Runtime diagnostics into a single immutable object returned by CksCoreAdapter.validate.

Diagnostic exposure shall preserve:

  • diagnostic ownership;
  • diagnostic identity;
  • diagnostic meaning;
  • deterministic ordering when applicable.

Runtime may transform external representation while preserving diagnostic semantics.

11. Relationship to CKS Core

CKS Core produces canonical diagnostics.

Runtime receives those diagnostics.

Runtime may:

  • associate;
  • aggregate;
  • retain;
  • expose

diagnostics.

Runtime shall never modify:

  • diagnostic identity;
  • diagnostic severity;
  • diagnostic meaning.

12. Relationship to Runtime Components

Runtime components may emit Runtime Diagnostics.

Examples include:

  • Session Manager;
  • Transaction Engine;
  • Storage Layer;
  • Version Manager;
  • Explainability Coordinator.

All Runtime Diagnostics are collected through the Runtime diagnostic aggregation mechanism.

Validation-related diagnostics originate from CKS Core through Runtime validation coordination.

13. Diagnostic Flow

The canonical Runtime diagnostic flow is:

Runtime Operation

        │

        ├──────────────┐

        ▼              ▼

CKS Core         Runtime Components

        │              │

        ▼              ▼

Core Diagnostics   Runtime Diagnostics

        └──────┬───────┘

               ▼

      Diagnostic Aggregator

               ▼

          Runtime API

               ▼

            Adapters

The reference implementation follows this flow in the ExecutionPipeline.commit method: Core validation is invoked via CksCoreAdapter, diagnostics are aggregated through runtime.diagnostics, and the final RuntimeValidationResult is propagated back to the caller.

14. Design Principles

The Runtime Diagnostics model follows these principles.

Semantic Preservation

Runtime preserves canonical diagnostic semantics.

Operational Transparency

Runtime Diagnostics describe operational behavior only.

Deterministic Exposure

Runtime shall preserve deterministic diagnostic ordering whenever the originating components provide deterministic ordering.

Transport Independence

Diagnostics remain independent of the transport through which they are exposed.

15. Conformance

A Runtime implementation conforms to this specification when it:

  • preserves Core Diagnostics unchanged;
  • separates Runtime Diagnostics from Core Diagnostics;
  • aggregates diagnostics without semantic modification;
  • preserves diagnostic ownership across aggregation and persistence;
  • associates diagnostics with Runtime Sessions.

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

16. Summary

Runtime Diagnostics provide operational observability while preserving the canonical semantic diagnostics defined by CKS Core.

The Runtime Standard distinguishes diagnostic ownership, aggregates diagnostic information originating from Runtime components and CKS Core, and provides a unified operational view while preserving the ownership, identity and semantics of every diagnostic.