架构总览

Entelechy 按层构建，每一层只依赖它下面的层，并由测试守住边界。

Host Core        内存、设备、时间、预算
Capability ABI   声明的能力、不透明句柄
Entelechy IR     类型化计算，与后端无关
Kernel Runtime   准备、校验、原子替换
Graph Runtime    按 KernelID 组合、类型化端口
Interfaces       CLI、Player、协议、C ABI、桥接

依赖规则

• 核心层（crates/core）只依赖核心层；后端（crates/backends）只依赖核心层；只有接口层（crates/interface）依赖一切。
• 核心层与前端不引入任何外部依赖。
• unsafe 只存在于两个 crate：JIT 与 C ABI（工作区默认 unsafe_code = "forbid"）。
• 这些规则由 crates/interface/entelechy/tests/layers.rs 检查。

各层与 crate

层	职责	crate
Host Core	句柄、预算、边界；.field 文件格式	entelechy-host
Capability ABI	Kernel 可见的世界：能力集合与类型，绑定到 ABI_VERSION	entelechy-abi
Entelechy IR	类型化、类 SSA 的表示；校验、融合、优化	entelechy-ir
共享规则	所有后端都遵守的调用、地址、合并、光栅化契约	entelechy-rules
Kernel Runtime	准备、发布、执行、原子替换 Kernel 版本	entelechy-kernel
Graph Runtime	按 KernelID 组合，带缓存与脏标记的求值	entelechy-graph
语言前端	.ent 词法/语法、编译到 IR、.esn 场景降级	entelechy-language、entelechy-compiler、entelechy-scene
后端	参考解释器、Cranelift/WASM JIT、WGSL/wgpu GPU	entelechy-cpu、entelechy-jit、entelechy-gpu
会话	文档、发布、同步；所有界面驱动的实时场景	entelechy-documents、entelechy-session
接口	CLI、Player、协议、C ABI、导入导出	entelechy、entelechy-player、entelechy-protocol、entelechy-ffi 等

完整列表见 Rust crates。

一个改动的生命周期

保存 .ent / .esn  ─►  解析 + 编译（frontend）
                     │  失败：在 文件:行:列 报告，旧版本继续运行
                     ▼
                  IR 校验（entelechy-ir）
                     ▼
                  后端准备（离帧进行，GPU 上包括管线编译）
                     ▼
                  在下一帧整体原子替换（entelechy-kernel）
                     ▼
                  图重新求值受影响的节点（entelechy-graph）
                     │  求值失败：状态与文件写入都不提交
                     ▼
                  提交状态，写出文件

设计原则

仓库的 CORE-ARCHITECTURE.md 与 AGENTS.md 规定了几条不变量：

• 保持世界稳定，保持定律可替换，保持组合开放，让能力生长。
• Host 只提供基础能力，不包含领域概念；领域能力以包（packages/）的形式存在。
• Kernel 是纯计算，Graph 拥有关系；绑定以 Kernel id 为准，而不是文件。
• 每个决定为什么这样做，都记录在 docs/DECISIONS.md（32 条），见设计决策。