# Aster VM 后续开发交接

从 [文档索引](../README.md) 查询当前实现，再按目录 README 找文件。不要把旧聊天、早期报告或未查询的 CI 状态当成当前契约。

## 当前项目与命名

仓库为 endorphin-aster-vm，归属 ProjectEndorphin。包与目录为 core、objects、frontend、storage、host、cli、server；core 的 Rust 库名为 endor_core，命令为 cli／server。旧部署服务、数据库和路径保留既有标识以保护数据。

## 当前包边界

Objects 零依赖，统一拥有核心对象、Number、代码对象／指令数据与静态验证、私有堆、ObjectStore 和共享 VmError；不依赖 Core。Core 仅依赖本地 Objects，保留 Vm、执行帧、取指求值循环；原有对象方法委托给 ObjectStore，并重导出既有对象类型。不要把对象定义或引用事务搬回 Core，也不开放私有句柄构造。源码导航见 [objects](../../crates/objects/README.md) 与 [core](../../crates/core/README.md)。

## 已实现

- EndorObject、稳定 Box、代际句柄、显式强引用及手动循环回收；VM 从空堆启动，没有 Python type／元类或语言根类。
- Function、NativeFunction、Dict、Cell、异常数据、UTF-8 String 和无损表示优先的 Number。
- 小型 wordcode、共享代码对象、操作数／控制流／栈校验、显式执行帧及 execute／call；MakeFunction 可在执行中创建带默认参数与共享闭包 Cell 的函数。对象返回值持有根，用后 release_value；借用读取不自动 retain。
- EndorReader 在 lexer 前提供字符串／流／文件／宿主 URI provider 输入，产出不可变 SourceUnit，保存来源与不透明修订标签；带来源的词法／语法错误保留行列，CLI parse 支持文件和 stdin。没有平台 URI 后端或版本锁实现，见 [阅读器](../runtime/reader.md)。
- Frontend 使用 peg 0.8.6，词法规则在 lexer.peg（字符 → Token），语法规则在 grammar.peg（Token → AST）；lexer.rs 保留逐 Token 游标与诊断位置换算，提供完整输入解析、基础函数／表达式 AST、Unicode 字节范围与行列诊断；CLI parse 可读 UTF-8 文件／stdin 输出 AST，不执行源码。当前语法以未完成设计稿为起点，可以继续调整，见 [源码前端](../runtime/frontend.md)。
- Host 文件信息独立于数据库：host.version、deployment.release 与 metadata put/get 使用 UTF-8 JSON。旧 PostgreSQL 基础信息只读导入缺失文件，不删除原库，见 [文件信息](../operations/host-information.md)。
- Storage 只提供显式 DatabaseConfig／DatabaseConnection；没有默认数据库、自动应用建表或基础信息 KV。特殊类的名称／接口尚未定义，没有将连接接入 VM。
- CLI 引导与文件信息，Server HTTP 存活／只读 VM 信息；生产 PostgreSQL 作为未来特殊类的预置资源保留。

## 资料位置

正式说明在 docs，多层 README 负责导航；源码目录 README 描述本目录。outputs 已移除，CPython 3.14 的 284 项对象研究表、生成脚本及早期历史报告保留在本地忽略的 work/research，不上传 Git。

## 尚未实现

AST 到字节码生成、平台资源存储／修订与依赖锁、名称／闭包与类型分析、源码闭包声明、导入／类／Agent 语法、迭代器等扩展指令、数值算术／相等／哈希、完整异常传播、可变 VM／异步数据库回调、生成器、自动 GC、堆快照、内存配额、取消及不可信代码沙箱。宿主回调 panic 后的执行根恢复也未完成。不能把未来设计写成已有能力。

## 工作约定

本地不构建、不运行测试／冒烟，不下载依赖；只允许静态阅读、格式化、语法／链接检查。运行验证交给 ces-control 的 SQLite、真实 PostgreSQL 与宿主流程。按用户要求不主动跟踪 CI／部署，结果未查询就明确写未核实。

数据库、卷和已有资料保留；不得改其他项目或共享 Runner。研究材料与 AGENTS.md 不提交。Git 身份按本地工作约定使用专用 codex-bot，不能借用仓库所有者凭据。

所有本项目对话标题包含 Aster VM。文档与代码同版本维护，不重新建立 outputs 或重复正文目录。开始下一项任务前先看 git status／最新提交，读取本地 AGENTS.md；本页不代替实时状态。

## 已确认的设计方向

Endor 由平台解释执行；AST 到字节码是解释器内部准备步骤，使用者无需先构建程序。代码未来以 workspace／namespace 下的资源提供，通过 Endor URI 查找，不要求真实源码文件或项目级 Git。资源修订与依赖锁选择用户代码，平台统一升级解释器；升级实现不自动改写源码修订。版本信息主要属于资源与依赖元数据，URI 具体格式、hash 方案和发布快照仍待设计。首版源码执行暂不要求持久化字节码缓存，VM 内代码对象共享继续保留。完整方向与尚未实现的边界见 [执行与版本模型](../architecture/execution-and-versions.md)。

## 下一步

前端已完成到 AST 的首版实现；下一步连接解释器内部的字节码生成：AST → 名称／局部槽与闭包分析 → 字节码 → 现有 VM，不改成 AST 直接解释。可以先连接字符串、名称、let、位置参数函数和调用，再补算术指令与数值语义。参数与返回类型目前只保存为语法节点，不引入 Python type／元类或借此实现整个语言类型系统。语法不必等外部设计稿全部定稿，按用户要求先实现可用子集、以后再调整；当前尚无源码执行命令。