Telo Kernel

The Telo Kernel is the declarative execution host for Telo manifests. It loads YAML, compiles CEL expressions, resolves and registers controllers, indexes resource instances, and orchestrates the boot/teardown lifecycle of every kind it knows about.

Target: Node.js (Rust/Go ports planned)

Input: A module manifest YAML file or a directory of YAML files

1. Core Concepts

The Telo Kernel is a declarative execution host. You describe resources in YAML; the kernel loads them, wires up controllers, and keeps the process alive until all work is done.

The kernel performs three functions:

• Loader: Reads YAML files, compiles CEL (!cel values, !interpolate holes), and resolves controller entrypoints.
• Registry: Indexes resource instances by a composite key of module.Kind.name.
• Kernel: Orchestrates the boot sequence, manages the event bus, and routes invocations.

Module loading and resource discovery happen during the load phase, before any resource is initialized.

2. Resource Definitions

Every resource in a manifest is an instance of a Telo.Definition. A definition declares several orthogonal facets:

Capability

capability assigns a single lifecycle role. The kernel uses it to determine when to call init(), run(), or invoke() on the controller. A definition declares exactly one capability.

→ docs/capabilities.md

Topology

topology names the structural composition pattern of a kind — how it is assembled internally from steps, routes, or nodes. It drives built-in execution when no controller is declared, structural validation in the analyzer, and canvas rendering in the editor.

→ docs/topology.md (design proposal — not yet implemented)

Inheritance

extends declares that a definition fulfills an abstract interface (Telo.Abstract) declared by another module. This is the plugin pattern for subsystems like workflow backends.

→ docs/inheritance.md

For the complete Telo.Definition field reference, see docs/resource-definition.md.

3. CEL Interpolation

Before a manifest object is processed, every CEL expression — a !cel value, each hole of an !interpolate or !sql — is compiled. This runs as part of loading — any compilation error halts the boot sequence immediately.

Host environment variables reach CEL only through typed root entries: declare a variables:/secrets:/ports: entry with an env: key and read it as !cel "variables.X" / !cel "secrets.X" / !cel "ports.X".

variables:
  manifestPath:
    env: MY_MANIFEST_PATH
    type: string
resources:
  - !cel "variables.manifestPath"

Interpolation

• !cel "expr" — one expression; the value keeps its CEL type (integer, boolean, …).
• !interpolate "text ${{ expr }} text" — text with holes, always a string; each hole converts through CEL's string().

A plain string holding ${{ is never compiled: it is the deprecated untagged spelling, rewritten at load by the untagged-interpolation migration and refused (ERR_UNTAGGED_INTERPOLATION) where it survives.

4. Telo.Definition

Modules declare the resource kinds they handle using Telo.Definition:

kind: Telo.Definition
metadata:
  name: Server # fully-qualified kind: Http.Server
  module: Http
capability: Service # one of: Runnable, Service, Invocable, Mount, Provider, Template
schema: # JSON Schema — validated against each resource before create()
  type: object
  properties:
    port: { type: integer }
    host: { type: string }
  required: [port]
controllers:
  # Ordered list of Package URL (PURL) candidates — first match for the current runtime is used
  - pkg:npm/@telorun/run@>=1.0.0?local_path=./nodejs#sequence
  - pkg:cargo/telorun-run@>=1.0.0?local_path=./rust#sequence

When a Telo.Definition instance initializes, it resolves and loads the controller module and registers it with the kernel. For the full resolution algorithm (local path, host node_modules, registry cache) and PURL format, see controllers.md.