Organize living documentation and directory guides
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 13m40s

This commit is contained in:
2026-10-18 20:58:42 +08:00
parent 6fa95b64b0
commit 8bbe78e01e
30 changed files with 674 additions and 396 deletions
+12
View File
@@ -0,0 +1,12 @@
# Cargo 工作区
本目录包含四个 crate。目录名不用 aster- 前缀,Cargo 包名和二进制名保留现有名称;路径依赖定义在根 Cargo.toml。
| 目录 | 包名/产物 | 职责 |
| --- | --- | --- |
| [core](core/README.md) | aster-core | 零外部依赖的对象运行时、堆与字节码 VM |
| [storage](storage/README.md) | aster-storage | 宿主元数据与 SQLite/PostgreSQL 适配,不依赖 core |
| [cli](cli/README.md) | aster-cli,二进制 aster | 引导演示和 metadata 命令 |
| [server](server/README.md) | aster-server | 最小常驻 HTTP 宿主 |
CLI/Server 依赖 Core 和 Storage,Core 与 Storage 互不依赖。网络、数据库、浏览器、进程配置和信号留在宿主。全局说明见 [架构](../docs/architecture/README.md),查功能位置从 [文档索引](../docs/README.md) 进入。返回 [项目入口](../README.md)。
+10
View File
@@ -0,0 +1,10 @@
# aster-cli / aster
命令行宿主。bootstrap 演示两个运行时对象并释放;metadata put/get 使用独立 Storage,不让数据库配置进入 Core。
| 内容 | 职责 |
| --- | --- |
| Cargo.toml | CLI 包、aster 二进制名称、core/storage/Tokio 依赖 |
| [src](src/README.md) | 参数路由、命令执行和退出码 |
用法见 [运行指南](../../docs/operations/README.md),文本参数与环境边界见 [配置](../../docs/operations/configuration.md)。此 CLI 当前不是 Endor 源码解释命令。返回 [工作区](../README.md)。
+7
View File
@@ -0,0 +1,7 @@
# CLI 入口
[main.rs](main.rs) 是唯一入口:main 将 run 的结果转成进程退出码;run 解析 bootstrap、metadata put/get 和 help,错误打印到 stderr 并返回失败。
bootstrap 创建并显式释放两个对象,不打开数据库。metadata 每次读取 StorageConfig、连接、操作并关闭池。参数目前由 std::env::args 读取,非 Unicode 参数可能 panic,现状及后续边界见 [配置](../../../docs/operations/configuration.md)。
新增命令时更新用法、[运行指南](../../../docs/operations/README.md) 和 [smoke.py 的导航](../../../scripts/README.md)。返回 [cli](../README.md)。
+13
View File
@@ -0,0 +1,13 @@
# aster-core
Endor VM 内核,保持零外部依赖。负责 EndorObject、堆、代际句柄、引用计数/循环回收、基本载荷和小型 wordcode 执行器。公共 Rust API 从 src/lib.rs 导出。
| 内容 | 入口 |
| --- | --- |
| Cargo.toml | 包元数据和工作区 lint;没有外部依赖 |
| [src](src/README.md) | 文件职责、公开接口和常见修改位置 |
| [tests](tests/README.md) | 对象、基本载荷、执行语义与生命周期检查 |
内核通过 Vm::new 从空堆启动;代码对象和全局字典由宿主显式创建,再 execute/call。没有环境变量探测、数据库、HTTP、Python type 系统或源码前端。
对象结果所有权见 [生命周期](../../docs/runtime/lifecycle.md),对象/字节码设计见 [运行时](../../docs/runtime/README.md),限额与 UTF-8 边界见 [配置](../../docs/operations/configuration.md)。本地不构建或运行测试,验证入口见 [验证](../../docs/operations/validation.md)。返回 [工作区](../README.md)。
+29
View File
@@ -0,0 +1,29 @@
# Core 源码导航
本目录解释实现文件如何分工;跨文件的设计规则只在 [运行时文档](../../../docs/runtime/README.md) 维护。公开 API 的最终导出入口是 lib.rs。
| 文件 | 内容 |
| --- | --- |
| [lib.rs](lib.rs) | 声明模块、公开类型导出、对象和字节码 rustdoc 示例 |
| [object.rs](object.rs) | Value、CompareOp、ObjectPayload、ObjectHeader、EndorObject、Record、NativeFunction |
| [heap.rs](heap.rs) | ObjectRef、稳定 Box 槽位、代际验证、引用事务、迭代释放、显式循环收集;含私有边界测试 |
| [vm.rs](vm.rs) | Vm/VmError、构造和对象操作入口、retain/release、循环回收入口 |
| [builtins.rs](builtins.rs) | String、Dict、Cell、Function、BaseException 载荷与 trace 边 |
| [number.rs](number.rs) | EndorNumber、Integer/Decimal/Rational/BinaryFloat/Complex 表示及装箱载荷 |
| [vm_builtins.rs](vm_builtins.rs) | 内置载荷校验、代码/函数工厂、Dict/Cell 操作、键语义和可变引用更新 |
| [instruction.rs](instruction.rs) | Opcode、逻辑指令、EXTENDED_ARG 编解码、指令位置与比较参数 |
| [code.rs](code.rs) | CodeLayout、EndorCode、共享 EndorCodeObject、操作数/控制流/栈校验 |
| [frame.rs](frame.rs) | EndorFrame、栈条目、执行位置元数据、ExecutionLimits |
| [eval.rs](eval.rs) | execute/call、参数绑定、帧切换、取指分派、结果根转移与失败清理 |
## 常见修改入口
| 要修改什么 | 涉及文件 | 同步说明 |
| --- | --- | --- |
| 对象公共操作或头部 | object.rs、vm.rs、heap.rs | [对象模型](../../../docs/runtime/objects.md) |
| 内置载荷、无损数字或容器行为 | builtins.rs/number.rs、vm_builtins.rs | [基本对象](../../../docs/runtime/builtins.md) |
| 新操作码 | instruction.rs、code.rs 的参数和栈验证、eval.rs 分派 | [字节码 VM](../../../docs/runtime/bytecode.md)、execution 测试 |
| 调用、闭包或返回值根管理 | frame.rs、eval.rs、函数 trace | [生命周期](../../../docs/runtime/lifecycle.md)、builtins 与 execution 测试 |
| 新公开 API | 对应实现模块与 lib.rs 导出 | 所属主题、示例、[tests 导航](../tests/README.md) |
复制 ObjectRef/Value 不增加引用;不能在自定义载荷中擅自改变已登记的托管边。对象 API 不暴露原始指针或句柄索引构造。返回 [core](../README.md)。
+11
View File
@@ -0,0 +1,11 @@
# Core 公开行为检查
本目录通过 aster_core 公共 API 检查宿主可观察的语义,不为检查开放内部句柄构造器。
| 文件 | 覆盖 |
| --- | --- |
| [runtime.rs](runtime.rs) | 空堆启动、默认操作、引用/借用、属性原子性、稳定地址、长链/循环、原生回调、VM 销毁 |
| [builtins.rs](builtins.rs) | 无损 Number、Unicode 字符串、Dict 顺序与键、Cell、函数环境/共享代码、异常数据 |
| [execution.rs](execution.rs) | wordcode 与校验、控制流、参数/默认值、嵌套帧、闭包、返回值存活、失败清理、限额 |
堆内部伪造句柄与计数溢出检查在 src/heap.rs,公开示例由 src/lib.rs rustdoc 提供。文件职责见 [src](../src/README.md),检查方式和结果边界见 [验证](../../../docs/operations/validation.md)。本地不执行测试;存在测试文件不代表某次提交已通过。返回 [core](../README.md)。
+10
View File
@@ -0,0 +1,10 @@
# aster-server
最小常驻 HTTP 宿主,提供数据库健康检查和只读 VM 引导信息。它通过 Arc 共享 Vm,没有语言执行接口或可变 VM 请求上下文。
| 内容 | 职责 |
| --- | --- |
| Cargo.toml | core/storage、Axum、Tokio、Serde 依赖 |
| [src](src/README.md) | 启动顺序、AppState、路由、信号与退出 |
HTTP 返回内容和运行方式见 [运行指南](../../docs/operations/README.md),变量见 [配置](../../docs/operations/configuration.md),生产端口/数据库见 [部署](../../docs/operations/deployment.md)。返回 [工作区](../README.md)。
+14
View File
@@ -0,0 +1,14 @@
# Server 入口
[main.rs](main.rs) 包含当前所有宿主启动代码:
| 部分 | 职责 |
| --- | --- |
| AppState | 共享只读 Arc<Vm> 与可克隆的 Storage 连接池 |
| main/run | 创建 VM、连接数据库、写 host.version、绑定地址、组装路由、服务结束后关闭存储 |
| health | ping 数据库,返回 200/503 及后端标签 |
| bootstrap | 返回对象模型、type_system=false 和堆对象数量,不分配对象 |
| shutdown_signal | Ctrl-C;Unix 上同时接受 SIGTERM,触发 Axum 优雅退出 |
| tests | 关闭数据库池后健康状态变为 unavailable |
改变端点时同步 [运行指南](../../../docs/operations/README.md) 与 [smoke.py](../../../scripts/README.md);改变启动变量时同步 [配置](../../../docs/operations/configuration.md)。网络、信号和数据库逻辑不进入 Core。返回 [server](../README.md)。
+11
View File
@@ -0,0 +1,11 @@
# aster-storage
宿主元数据存储,依赖 SQLx/Tokio,不依赖 VM 内核。一个 Storage 选择 SQLite 或 PostgreSQL;明确配置 PostgreSQL 后失败不回退。
| 内容 | 入口 |
| --- | --- |
| Cargo.toml | SQLx、Tokio 和检查所需依赖 |
| [src](src/README.md) | 配置解析、连接池、元数据表和操作 |
| [tests](tests/README.md) | 配置、持久化、隔离与专用 PostgreSQL 检查 |
Storage 仅保存 key/value 元数据,不保存 EndorObject 或执行帧。运行与连接规则见 [运行指南](../../docs/operations/README.md),环境优先级与错误规则见 [配置](../../docs/operations/configuration.md),生产数据与迁移边界见 [部署](../../docs/operations/deployment.md)。返回 [工作区](../README.md)。
+10
View File
@@ -0,0 +1,10 @@
# Storage 源码导航
| 文件 | 职责 |
| --- | --- |
| [lib.rs](lib.rs) | StorageConfig::from_values/from_env、StorageError、SQLite/PostgreSQL 连接池、schema 初始化、ping/put/get/close |
| [schema.sql](schema.sql) | 当前 aster_metadata 文本 key/value 表,幂等建表 |
配置改动同步 [配置表](../../../docs/operations/configuration.md) 与 storage 测试。schema 改动须考虑已有数据库,当前没有版本化迁移;不得将 CREATE IF NOT EXISTS 当作已有结构升级。Storage 克隆共享连接池,close 影响所有克隆。
连接与持久化契约见 [运行指南](../../../docs/operations/README.md),测试定位见 [tests](../tests/README.md)。返回 [storage](../README.md)。
+8
View File
@@ -0,0 +1,8 @@
# Storage 行为检查
| 文件 | 覆盖与前提 |
| --- | --- |
| [storage.rs](storage.rs) | 配置默认值/优先级/错误、内存共享与实例隔离、临时文件重连、目录错误;不处理 PostgreSQL 协议的 socket 仅检查连接超时和不降级 |
| [postgres.rs](postgres.rs) | 真实 PostgreSQL 写入/覆盖/缺失键/重连;默认 ignore,显式运行需 ASTER_TEST_POSTGRES_URL 指向专用测试库 |
SQLite 文件检查使用临时目录;PostgreSQL 成功路径不使用生产数据库。ces-control 脚本提供一次性的测试数据库,见 [验证](../../../docs/operations/validation.md) 和 [scripts](../../../scripts/README.md)。不在本地运行或为测试下载 SQLite 依赖。返回 [storage](../README.md)。