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

# 系统架构

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

## 组件与依赖方向

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

CLI、Server 依赖 Host 保存文件信息，不依赖 Storage；Core 与 Storage 也互不依赖。CLI 的 parse 命令使用 Frontend；Frontend 只依赖 peg，Core 不依赖 Frontend。HTTP、Tokio、SQLx、数据库、网络和浏览器能力不进入零依赖的 core。包与文件定位见 [crates](../../crates/README.md)。

| 组件 | 当前职责 | 全局契约 |
| --- | --- | --- |
| Core | EndorObject、对象堆、Number、wordcode、执行帧、求值器 | [运行时](../runtime/README.md) |
| Frontend | 手写 UTF-8 lexer、token PEG parser、基础函数／表达式 AST，不执行源码 | [源码前端](../runtime/frontend.md) |
| Host | 基础信息的逐键 UTF-8 JSON 文件与旧库导入 | [宿主信息](../operations/host-information.md) |
| Storage | 按显式配置建立 SQLite／PostgreSQL 连接池，不定义应用表 | [数据库特殊类](../runtime/database-objects.md) |
| CLI | 对象引导演示、源码解析与文件信息命令 | [CLI](../../crates/cli/README.md) |
| Server | HTTP 存活检查、只读 VM 信息及文件版本记录 | [Server](../../crates/server/README.md) |
| Gitea／Docker | 双数据库适配验证、镜像构建、宿主与 PostgreSQL 资源部署 | [部署](../operations/deployment.md) |

## 当前契约

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

## 数据与服务边界

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

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

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

## 后续边界

特殊类接口与异步数据库调用、AST 到字节码的编译与名称／类型分析、更多指令、异常传播、自动 GC、内存配额、取消和能力隔离等均需按实际需求设计。当前帧／指令限额不等于完整沙箱。返回 [文档索引](../README.md)。