endorphin-aster-vm/docs/operations/validation.md

# 验证范围与结果边界

本页维护当前检查入口和覆盖范围，不累计已失效的测试数量、机器资源快照或旧对象模型的通过记录。历史行为查 Git 历史；某个版本是否通过，只能依据该提交对应的实际结果。

## 执行约定

本地不运行 Cargo 构建、测试、Clippy、冒烟、Docker 或依赖下载；允许阅读、格式化、ASDL 源码生成／产物同步检查和静态文件／文档检查。指定运行验证环境为 ces-control。按用户要求不主动追踪 CI／部署结果，有问题由用户反馈后再查。

## 检查入口

以下命令只在指定的验证环境执行，不表示已经运行：

```sh
sh scripts/check.sh
cargo test -p storage --test postgres --locked -- --ignored
python3 scripts/smoke.py
```

check.sh 先运行 generate_ast.py --check 验证 ASDL 产物同步，以及仅远端执行的 test_generate_ast.py 生成器回归检查、test_endor_examples.py 报告失败路径检查，再执行 cargo fmt --all --check、独立词法／语法文件的 rustfmt --edition 2024 --check crates/frontend/src/lexer.peg crates/frontend/src/grammar.peg、cargo test --workspace --locked 和 cargo clippy --workspace --all-targets --locked -- -D warnings。workspace 测试也包含 rustdoc 示例；显式忽略的 PostgreSQL 测试需要单独执行。

ci-ces-control.sh 负责准备全新专用临时 PostgreSQL 和测试 URL；成功路径使用真实数据库，不用模拟 socket 代替。测试库与生产数据不共享挂载。没有 ASTER_TEST_POSTGRES_URL 时，显式执行 PostgreSQL 测试会失败，不标记为通过。

## Endor 示例实际输出

在对应 Gitea 仓库的 Actions → 本次提交的 run 页面，打开 Show Endor example execution output 步骤可看实际运行报告；下载 endor-execution-output-<sha> artifact 可保存两种格式：

- endor-examples.md：逐例展示源码、执行命令、预期值、实际 stdout／stderr、退出码和 PASS／FAIL／NOT_RUN。
- endor-examples.json：保留精确输出（包括换行）、提交 SHA、UTC 时间、构建／定位命令结果和逐例状态，供工具读取。

[endor_examples.py](../../scripts/endor_examples.py) 构建真实 CLI，通过 Cargo metadata 定位二进制并执行 [cases.json](../../crates/compiler/examples/cases.json) 中的全部示例；不以预期值冒充实际值。stdout 必须精确匹配、stderr 为空且退出码为 0 才通过。单例超时 30 秒；构建失败不运行示例并标记 NOT_RUN；报告本身的异常标记 FAIL。一个案例失败仍收集后续案例。示例报告不代表 workspace、数据库、宿主和部署全部通过，整体结果仍看工作流。

ci-ces-control.sh 在检查容器退出后、清理前将两份文件复制到宿主 ci-output；验证步骤提前失败时已有 NOT_RUN 占位说明。报告运行不掩盖前面检查的失败；后续数据库或宿主检查失败也不丢报告。工作流用 always() 展示并上传，artifact 保留 30 天，不写进 Git 或生产数据目录。普通 Actions 日志仍保留完整测试／构建信息；报告上传失败会使工作流失败。

## 覆盖范围与文件位置

| 范围 | 当前检查内容 | 入口 |
| --- | --- | --- |
| 堆内部边界 | 非法索引、槽位代数、代数耗尽、计数溢出原子性 | [objects/src](../../crates/objects/src/README.md) 的 heap.rs 私有单元测试 |
| 独立对象存储 | 不依赖 VM 的稳定地址、跨存储拒绝、更新失败原子性、循环回收、函数校验与共享代码所有权 | [objects/tests](../../crates/objects/tests/README.md) 的 store.rs |
| 对象运行时 | 地址稳定、引用／借用、属性、长链、循环、原生操作、VM 销毁 | [core/tests](../../crates/core/tests/README.md) 的 runtime.rs |
| 基本对象 | Number 表示、字符串、Dict／Cell 引用与更新、函数环境、异常数据 | 同目录 builtins.rs |
| 字节码 | 编解码、非法指令／控制流、跳转、调用、闭包、字节码创建函数／默认值／环境捕获、函数创建及后续失败清理、结果存活与限额 | 同目录 execution.rs |
| Endor 阅读器 | 字符串、分块 UTF-8 流、文件、读取失败、URI provider、修订标签与来源诊断 | [frontend/tests](../../crates/frontend/tests/README.md) 的 reader.rs |
| AST 与接口生成 | 三类根、声明／语句层次、Visitor 及失败退出、Unicode 位置、JSON 往返、schema／范围错误和跨语言产物标识 | frontend/tests/ast.rs 与 scripts/test_generate_ast.py，见 [AST 模型](../runtime/ast.md) |
| 源码前端 | 字符 PEG 词法边界、逐 Token 原文位置与首个错误诊断、Unicode 范围、数字原文、字符串与错误、优先级／结合性、函数／绑定、完整输入与错误位置、源码样例 | [frontend/tests](../../crates/frontend/tests/README.md) |
| 源码编译与执行 | 真实 Endor 文件到 VM、名称／初始化检查、参数与函数值、精确常量、宿主成员回调、跨 VM 模板、错误清理、递归限额、交互命名空间及扩展操作数 | [compiler/tests](../../crates/compiler/tests/README.md) |
| CLI 执行 | run／eval 文件与 stdin、入口、返回值、语义／编译／运行错误、traceback 和退出码 | [cli/tests](../../crates/cli/tests/README.md) |
| CLI 解析 | AST 输出、未执行源码、文件／stdin 来源和行列错误、EOF 读取与非法 UTF-8 退出 | [cli/tests](../../crates/cli/tests/README.md) |
| 公开示例 | 对象操作、手写指令执行与释放 | objects 与 core 的 src/lib.rs rustdoc，见 [objects/src](../../crates/objects/src/README.md)、[core/src](../../crates/core/src/README.md) |
| 宿主文件信息 | UTF-8 值／路径、持久读取、同键替换、并发、坏记录、幂等迁移与保留新值 | [host/tests](../../crates/host/tests/README.md) |
| 数据库连接 | 不自动建表、显式配置、隔离／共享、调用方数据重连、失败不降级、真实 PostgreSQL | [storage/tests](../../crates/storage/tests/README.md) |
| 端到端宿主 | 文件 metadata 跨进程读写、日文值、Server 文件版本；忽略失效数据库变量且不创建 SQLite 文件、HTTP 与 SIGTERM | [scripts](../../scripts/README.md) 的 smoke.py |

测试源码说明验证意图，不能证明已通过；现有测试也不代表完整 Python 兼容、panic 恢复、云沙箱或 VM 快照已经实现。

## 文档修改的静态检查

修改后核对所有受版本管理目录存在 README、父目录有入口、相对链接指向现存文件；运行 git diff --check 检查差异空白。静态文本检索可以查出旧路径和过时 API；维护规则见 [开发与文档维护](../contributing/README.md)。这些检查不执行 VM 或数据库。

仅修改文档时也不据此宣称运行检查通过。推送触发现有 CI 时，仍由原流程检查和部署；报告应分别说明静态检查、运行测试与推送结果。

返回 [运行指南](README.md) 或 [文档索引](../README.md)。