ecko
How the runtime is organized
A conceptual map, for reasoning about behaviour. The runtime implementation is not public - Ecko ships as binaries - so this describes components and responsibilities rather than files.
Three crates, one binary
| component | holds | constraint |
|---|---|---|
| kernel | lexer, parser, VM, evaluator, ai, contracts, mock mode | no network, no SQL, no heavy dependencies |
| standard library | native std.* modules; registers itself with the module registry | where every gated capability lives |
| facade + CLI | the public API and every ecko command | installs the standard library before evaluating |
The kernel's dependency floor is a design constraint, not an accident: it is what keeps the language layer free of the things that need gating, and it is why capability enforcement has a clean boundary to sit on.
The parts
- Lexer and parser - tokens with spans, recursive descent with precedence climbing. See The pipeline.
- The VM - bytecode compiler and stack machine, the shipped engine. See The stack VM.
- The evaluator - the AST tier for
ai, contracts andasync, and the bridge both engines meet at. See Two execution tiers. - The value model - one value type, copy-on-write collections. See The value model.
- Built-ins - roughly 95 global functions, plus the AI-adjacent surface (
tokens,cost,retry,session,embed) and the async surface (channel,send,recv,cancel). - The provider layer - one abstraction over OpenAI, OpenRouter and Ollama on a shared async runtime, with mock fallback and per-provider tool serialization. See Providers.
- Cache, trace, Python FFI - the content-addressed prompt cache, JSONL tracing, and
py()over a persistent worker process. - The formatter - canonical printing, and a gate on new syntax.
- The analyzer -
ecko check, also drivingecko lsp, so the editor and the compiler apply identical rules.
One binary, one mental model
Everything above is in the single executable you installed. There is no runtime to match, no optional native extension, no separate language-server package that can drift out of step. That is a deliberate constraint rather than a packaging convenience: it is what makes a file a program and what keeps a container image around 22 MB.
Where new functionality goes
The kernel is frozen. The standard library requires a syscall or FFI justification. Everything else is an Ecko-written package - portable, capability-gated, deletable. The official packages are that layer made concrete, with no privileged access of any kind.