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

系统架构

Endor 的目标是云原生语言；本仓库当前实现运行时和宿主演示，尚无源码编译器、云调度器或多租户执行沙箱。当前侧重核心语义独立于进程环境，以及数据库能力按对象需求显式提供。

组件与依赖方向

CLI ────→ Core + Host
Server ─→ Core + Host
未来数据库特殊类的宿主实现 ─→ Storage

CLI、Server 依赖 Host 保存文件信息，不依赖 Storage；Core 与 Storage 也互不依赖。HTTP、Tokio、SQLx、数据库、网络和浏览器能力不进入零依赖的 core。包与文件定位见 crates。

组件	当前职责	全局契约
Core	EndorObject、对象堆、Number、wordcode、执行帧、求值器	运行时
Host	基础信息的逐键 UTF-8 JSON 文件与旧库导入	宿主信息
Storage	按显式配置建立 SQLite／PostgreSQL 连接池，不定义应用表	数据库特殊类
CLI	对象引导演示与文件信息命令	CLI
Server	HTTP 存活检查、只读 VM 信息及文件版本记录	Server
Gitea／Docker	双数据库适配验证、镜像构建、宿主与 PostgreSQL 资源部署	部署

当前契约

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

数据与服务边界

数据库用于未来某种特殊类，不保存基础信息、版本、部署记录或普通对象。Storage 连接不建应用表，不提供统一 KV；实际数据布局和查询由特殊类定义。当前只有连接适配，还没有实现该类或把它接入 Vm。

HTTP 宿主通过 Arc 共享只读 Vm。GET /bootstrap 只读对象模型和数量，GET /health 仅报告 HTTP 可响应。没有语言执行、对象写入或认证协议，不能称为远程执行平台。重启仍创建新空 VM，没有堆快照。

部署保留既有 PostgreSQL 服务与数据目录，应用启动不依赖数据库连接。基础信息从数据库改为 Host 文件层；发布脚本一次性只读导入旧 PostgreSQL 记录，不删除原表或卷。脚本结果未主动跟踪，不能据此认定远端已经完成迁移。

后续边界

特殊类接口与异步数据库调用、源码前端、更多指令、异常传播、自动 GC、内存配额、取消和能力隔离等均需按实际需求设计。当前帧／指令限额不等于完整沙箱。返回 文档索引。