CK.Lib.Py — CKP v3.5 Python Runtime

Python runtime for the Concept Kernel Protocol (CKP v3.5).

What This Is

Every Concept Kernel that runs Python uses CK.Lib.Py. It provides:

• Base processor class that reads conceptkernel.yaml and dispatches NATS messages to @on handlers
• Instance lifecycle (create, seal, proof) following the three-loop model
• PROV-O provenance recording for every action
• Action composition via edge predicates (COMPOSES/EXTENDS/TRIGGERS)
• RBAC grants checking against conceptkernel.yaml grants block
• URN parsing, validation, and building per CKP URN scheme

Architecture — Where Things Run

CLUSTER / LOCAL MACHINE (Python, nats-py)       BROWSER / MOBILE (JS, nats.ws)
─────────────────────────────────────────       ──────────────────────────────────
CK.Lib.Py                                       CK.Lib.Js
  KernelProcessor                                  CKClient (ck-client.js)
  NatsKernelLoop (nats-py)                         NATS WSS (nats.ws)
  instance.py (writes to storage/)                 CKPage (ck-page.js)
  prov.py (PROV-O chains)                          CKBus (ck-bus.js)
  actions.py (edge composition)                    CKRegistry (ck-registry.js)
         │                                                │
         │  NATS (nats:// or wss://)                      │  NATS WSS only
         │  Subject: input.{KernelName}                   │  Subject: input.{KernelName}
         └──────────────── NATS SERVER ───────────────────┘
                    wss://stream.tech.games
                    JWT auth via Keycloak

Python kernels run on the cluster or local machine. They connect to NATS via nats-py (native TCP or WSS). They have filesystem access to their storage/ directory. They write instances, proofs, and ledger entries.

JavaScript clients run in the browser or CLI. They connect to NATS via nats.ws (WebSocket only). They have NO filesystem access. They send action messages and receive results. They are ckp:InlineKernel / ckp:NATSBrowserClient per the published ontology.

Messages are identical regardless of sender. A { "action": "scout.scan" } published to input.Delvinator.ThreadScout produces the same result whether it came from a Python kernel, a JS browser, or delvinator.sh.

Ontology Grounding

Published ontology: https://conceptkernel.org/ontology/v3.5-alpha6/

Published ontology modules (all live at alpha-6 endpoint):

Modules

The Three-Loop Contract

CK.Lib.Py enforces the CKP three-loop separation:

CK LOOP (identity — read by KernelProcessor.__init__)
│  conceptkernel.yaml → self.identity, self.name, self.urn
│  ontology.yaml → defines what instances look like (the TYPE)
│  rules.shacl → validation constraints
│  CLAUDE.md, SKILL.md → for Claude Code agents
│
│  KernelProcessor READS these. It NEVER WRITES them.
│  Tool loop cannot modify CK loop — enforced by code structure.
│
TOOL LOOP (execution — this is where processor.py runs)
│  @on("action") handlers process input and return dicts
│  The handler NEVER opens storage/ for writing
│  It returns data; NatsKernelLoop handles storage writes
│
DATA LOOP (results — written by NatsKernelLoop or instance.py)
   storage/instances/i-{trace}-{ts}/
     manifest.json   ← create_instance()
     data.json        ← seal_instance()
     proof.json       ← seal_instance() generates proof
     ledger.json      ← append_ledger()

How a Kernel Processor Works

from cklib import KernelProcessor, on, emit

class MyKernel(KernelProcessor):
    """Processor reads conceptkernel.yaml on init.
    Exposes @on handlers that match spec.actions.
    Returns dicts — never writes to storage directly."""

    @on("my.action")
    def handle(self, data):
        # data = the message body from NATS or CLI
        # Process...
        result = {"answer": 42}
        # Return typed event — NatsKernelLoop writes the instance
        return emit("ActionCompleted", result=result)

if __name__ == "__main__":
    MyKernel.run()
    # CLI: python processor.py --status
    #       python processor.py --action my.action --data '{"key": "value"}'
    #       python processor.py --listen    (NATS subscriber mode)
    #       python processor.py --serve     (HTTP API mode)

NATS Processing Cycle

When --listen is invoked, NatsKernelLoop (from nats_kernel.py) runs:

1. Connect to NATS WSS (wss://stream.tech.games)
2. Subscribe to input.{KernelName}
3. For each message:
   a. Parse headers (Trace-Id, X-Kernel-ID, X-User-ID)
   b. Parse body as JSON
   c. Dispatch to handle_message() → @on handler
   d. Write instance to storage/instances/i-{trace}-{ts}/message.json
   e. Publish result to result.{KernelName}
   f. Publish event to event.{KernelName} (type: "instance_created")

Instance creation happens INSIDE the NATS loop — the handler just returns data. This is the three-loop isolation: tool returns, platform writes.

Related Repositories

License

MIT