endorphin-aster-vm/docs/architecture/README.md

系统架构

Endor 的目标是云原生语言；本仓库当前实现运行时和宿主演示，尚未提供源码编译器、云调度器或多租户执行沙箱。云原生方向在当前阶段落实为内核与进程配置分离、可预测的文本／数字表示、明确的数据持久化边界。

组件与依赖方向

CLI ────→ Core
  └─────→ Storage
Server ─→ Core
  └─────→ Storage

Core 与 Storage 互不依赖。HTTP、Tokio、SQLx、数据库、网络和后续浏览器能力属于宿主，不进入零外部依赖的 core。源码包导航见 crates。

组件	当前职责	全局契约
Core	EndorObject、对象堆、Number、wordcode、执行帧、求值器	运行时
Storage	一个确定后端上的宿主元数据读写	运行与存储
CLI	对象引导示例、元数据 put/get	CLI
Server	数据库健康检查、只读运行时信息、进程退出	Server
Gitea／Docker	远端验证、镜像构建、PostgreSQL 持久部署	部署

当前契约

• Vm 从空堆启动。EndorObject 是实现层公共结构，不是语言根类；当前没有 Python type、继承或元类。
• 堆中对象地址稳定，公开句柄校验 VM 身份和槽位代数；句柄不是跨进程 ID。
• 引用计数负责通常的释放，显式全堆追踪负责不可达循环；执行帧中的对象值也作为根。
• 函数共享不可变代码对象，语言调用使用显式帧向量；字节码参考 CPython 的职责划分，不兼容其操作码 ABI。
• Number 优先保存不同数字的无损表示；没有统一转 f64，也没有定义数值算术、相等和哈希。
• 异常对象保存数据；执行错误使用 VmError，没有 raise／try／except 传播。
• 内核不读取进程环境或修改 locale。宿主负责配置解析、I/O 和信号；详见 配置。

数据与服务边界

Storage 仅保存 aster_metadata(key, value)；连接时幂等创建当前 schema。文件与数据库中的元数据可以跨进程保留，VM 堆、执行帧、句柄不会因此恢复。宿主重启会创建新的空 VM。

HTTP 宿主通过 Arc 共享只读 Vm。GET /bootstrap 只读对象模型与堆数量，GET /health 实际探测数据库。当前没有语言执行端点、对象写入端点或认证协议；不能把现有服务称为远程执行平台。

后续扩展边界

源码前端、函数定义／迭代器指令、可变 VM 宿主回调、异常传播、自动 GC、内存配额、执行取消、能力隔离、VM 快照及语言类型体系都需要各自的设计。现有帧数／指令预算只是部分执行限额，不构成完整沙箱。

主题的详细规则只在对应文档维护，本页保留组件关系与摘要。返回 文档索引。