@telorun/kernel

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 expressions, 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:

Facet	Field	Purpose
capability	Lifecycle role	One of Runnable, Service, Invocable, Mount, Provider — mutually exclusive
topology	Composition	How the kind is structured internally: Sequence, Router, Workflow
extends	Inheritance	Abstract interface this kind fulfills (cross-module plugin pattern)
controllers	Execution	PURL-referenced controller implementations

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 ${{ ... }} expression 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 ${{ variables.X }} / ${{ secrets.X }} / ${{ ports.X }}.

variables:
  manifestPath:
    env: MY_MANIFEST_PATH
    type: string
resources:
  - ${{ variables.manifestPath }}

Interpolation

• ${{ expr }} — the interpolation syntax used throughout Telo

When the entire string is a single interpolation, the result preserves the CEL type (integer, boolean, etc.). Mixed strings are coerced to string.

---

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
  - pkg:golang/github.com/telorun/run@>=1.0.0?local_path=./go#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.