Architecture overview

Entelechy is built in layers, each depending only on those below it, the boundaries held by tests.

Host Core        memory, devices, time, budgets
Capability ABI   declared capabilities, opaque handles
Entelechy IR     typed computation, backend-neutral
Kernel Runtime   prepare, validate, atomic swap
Graph Runtime    composition by KernelID, typed ports
Interfaces       CLI, Player, protocol, C ABI, bridges

Dependency rules

• The core (crates/core) depends on the core alone; a backend (crates/backends) on the core alone; only the interface layer (crates/interface) on everything.
• The core and the front end take no external dependency.
• unsafe lives in two crates, the JIT and the C ABI (the workspace sets unsafe_code = "forbid").
• crates/interface/entelechy/tests/layers.rs checks all of this.

Layers and crates

Layer	Responsibility	Crates
Host Core	handles, budgets, bounds; the .field format	entelechy-host
Capability ABI	the world a Kernel sees, pinned to ABI_VERSION	entelechy-abi
Entelechy IR	typed, SSA-like; validation, fusion, optimizer	entelechy-ir
Shared rules	invocations, addresses, combines, the rasterizer’s contract	entelechy-rules
Kernel Runtime	prepare, publish, execute, atomically replace	entelechy-kernel
Graph Runtime	composition by KernelID, cached dirty-tracked evaluation	entelechy-graph
Front end	.ent lexer/parser, compiler to IR, .esn lowering	entelechy-language, entelechy-compiler, entelechy-scene
Backends	reference interpreter, Cranelift/WASM JIT, WGSL/wgpu GPU	entelechy-cpu, entelechy-jit, entelechy-gpu
Session	documents, publication, sync; the live scene every interface drives	entelechy-documents, entelechy-session
Interfaces	CLI, Player, protocol, C ABI, import/export	entelechy, entelechy-player, entelechy-protocol, entelechy-ffi, …

The full list is in Rust crates.

The life of a change

save .ent / .esn  ─►  parse + compile (front end)
                     │  failure: reported at file:line:column, old version keeps running
                     ▼
                  IR validation (entelechy-ir)
                     ▼
                  backend preparation (off the frame; on a GPU, the pipeline compile)
                     ▼
                  atomic swap at the next frame (entelechy-kernel)
                     ▼
                  the graph re-evaluates what it affects (entelechy-graph)
                     │  evaluation failure: no state or file write commits
                     ▼
                  state commits, files are written

Principles

CORE-ARCHITECTURE.md and AGENTS.md set the invariants:

• Keep the world stable. Keep the laws replaceable. Keep composition open. Let capability grow.
• The Host provides fundamentals only; domain capability lives in packages (packages/).
• Kernels compute, Graphs own relationships; binding is by Kernel id, never by file.
• Why each choice was made is recorded in docs/DECISIONS.md (32 entries); see Design decisions.