refactor: separate language engine from CLI and server hosts
Verify Aster engine / verify (push) Failing after 0s
Verify Aster engine / verify (push) Failing after 0s
This commit is contained in:
+12
-15
@@ -1,18 +1,15 @@
|
||||
# 运行时设计
|
||||
# 运行时契约
|
||||
|
||||
本目录解释源码输入、前端及跨越 core／objects 的运行时契约。对象与存储定位见 [objects/src](../../crates/objects/src/README.md)，VM 与执行帧见 [core/src](../../crates/core/src/README.md)；检查分别见 [objects/tests](../../crates/objects/tests/README.md) 和 [core/tests](../../crates/core/tests/README.md)。
|
||||
|
||||
| 主题 | 内容 |
|
||||
| 文档 | 内容 |
|
||||
| --- | --- |
|
||||
| [对象模型](objects.md) | EndorObject／ObjectHeader、代际句柄、操作协议、托管引用与循环回收 |
|
||||
| [基本对象与 Number](builtins.md) | 函数、原生函数、字典、Cell、异常数据、字符串与无损数字 |
|
||||
| [Endor 阅读器](reader.md) | SourceUnit、来源／修订标签、字符串／流／文件和宿主 URI provider |
|
||||
| [源码前端](frontend.md) | 字符 PEG lexer、token PEG parser、AST、基础函数／表达式语法与诊断 |
|
||||
| [AST 模型与 ASDL](ast.md) | 统一根、声明／语句／表达式、生成器、Visitor、位置和 JSON／编辑器接口 |
|
||||
| [源码编译](compiler.md) | 名称／作用域、局部槽、字节码模板、代码装载、CLI 执行与示例 |
|
||||
| [字节码 VM](bytecode.md) | 指令编码、代码校验、局部槽、执行帧、函数创建、调用／返回与边界 |
|
||||
| [文本编码](text-encoding.md) | UTF-8、日文、外部 Shift_JIS／CP932 与宿主解码边界 |
|
||||
| [数据库特殊类](database-objects.md) | 显式连接、调用方数据模型、未来类接入与资源生命周期 |
|
||||
| [生命周期](lifecycle.md) | 宿主持有 Vm、帧执行根、结果所有权、错误退出和整体销毁 |
|
||||
| [objects.md](objects.md) | 对象、句柄与默认操作 |
|
||||
| [builtins.md](builtins.md) | Number、String、Dict、Cell、Function、异常数据 |
|
||||
| [reader.md](reader.md) | 输入、来源和修订标签 |
|
||||
| [frontend.md](frontend.md) | 词法、语法和诊断 |
|
||||
| [ast.md](ast.md) | ASDL、AST、生成与编辑器接口 |
|
||||
| [compiler.md](compiler.md) | 名称分析、编译、装载与源码样例 |
|
||||
| [bytecode.md](bytecode.md) | 指令、验证和调用协议 |
|
||||
| [lifecycle.md](lifecycle.md) | 根引用、失败、回收与销毁 |
|
||||
| [text-encoding.md](text-encoding.md) | UTF-8 和宿主转码边界 |
|
||||
|
||||
文本／环境约束和执行限额集中在 [配置](../operations/configuration.md)；组件之间的关系见 [系统架构](../architecture/README.md)，解释执行与源码／平台版本的设计方向见 [执行与版本模型](../architecture/execution-and-versions.md)。返回 [文档索引](../README.md)。
|
||||
文件信息与数据库适配属于独立 Hestia 宿主，不属于引擎；CLI 属于独立 Lyra 宿主。返回 [文档索引](../README.md)。
|
||||
|
||||
+4
-4
@@ -64,11 +64,11 @@ AST_SCHEMA_ID 从 Endor.asdl 的 UTF-8 文本计算 SHA-256，包含注释与空
|
||||
CLI 可提供具体的交换输出：
|
||||
|
||||
```sh
|
||||
cli parse --json source.endor
|
||||
cli parse --mode expression --json -
|
||||
cli parse --mode interactive --json -
|
||||
lyra parse --json source.endor
|
||||
lyra parse --mode expression --json -
|
||||
lyra parse --mode interactive --json -
|
||||
```
|
||||
|
||||
文件／stdin 阅读保持原有 UTF-8 和错误来源规则，stdin 到 EOF 后才解析。普通 cli parse 输出 AstRoot 的 Debug 文本，稳定交换使用带 schema 的 JSON；parse 的各模式均不执行源码；run／eval 执行入口见 [编译链路](compiler.md)。命令在指定远端运行。
|
||||
文件／stdin 阅读保持原有 UTF-8 和错误来源规则，stdin 到 EOF 后才解析。普通 lyra parse 输出 AstRoot 的 Debug 文本，稳定交换使用带 schema 的 JSON；parse 的各模式均不执行源码；run／eval 执行入口见 [编译链路](compiler.md)。命令在指定远端运行。
|
||||
|
||||
检查源码见 [frontend/tests](../../crates/frontend/tests/README.md) 和 [生成器检查](../../scripts/test_generate_ast.py)，边界见 [验证](../operations/validation.md)。返回 [运行时索引](README.md)。
|
||||
|
||||
@@ -34,7 +34,7 @@ CompileOptions.globals 显式声明宿主会提供的 globals／builtins 名称
|
||||
| 成员读取 | 求值对象 → LoadAttr；沿用 VM 属性协议，无自动 self 绑定 |
|
||||
| return | 求值结果 → ReturnValue；无值 return 或 AST 函数末尾无 return 时生成 nil |
|
||||
|
||||
源码 parser 仍要求函数体为 let* 加一个带值 return；更通用的表达式语句和空 return 可以由 AST 调用方构造，但不能因此宣称源码语法已开放。模块初始化只发布函数并返回 nil，不自动调用 main。CLI 选择入口属于宿主行为。
|
||||
源码 parser 仍要求函数体为 let* 加一个带值 return；更通用的表达式语句和空 return 可以由 AST 调用方构造，但不能因此宣称源码语法已开放。模块初始化只发布函数并返回 nil，不自动调用 main。Lyra 宿主选择入口属于宿主行为。
|
||||
|
||||
二元算术、非字面量的一元负号和符号值 .name 目前产生明确 Compilation 诊断，不伪造运行结果。导入、类、Agent、条件／循环、关键字参数等仍未实现。函数参数个数和对象是否可调用由 VM 在运行时检查。
|
||||
|
||||
@@ -44,12 +44,12 @@ CompiledCode 是纯 Rust 模板，嵌套代码常量在模板内部使用占位
|
||||
|
||||
宿主为模块提供 globals 字典，调用 vm.execute(code, globals) 发布函数，然后从字典借用函数句柄并调用 vm.call。函数共享装载后的代码，反复调用不重新编译；execute／call 的对象结果持有根，用后 release_value。函数指向 globals，globals 保存函数，因此宿主需保留命名空间期间的根，并在销毁时清空字典或释放根后显式 collect_cycles。编译器不清空宿主字典。
|
||||
|
||||
Expression 模式返回表达式值；Interactive 模式严格编译一次声明、let 或表达式。声明／绑定返回 nil，表达式返回值；宿主可以跨提交复用 globals，并在下一次 CompileOptions 中声明可见名称。CLI 当前没有 REPL、续行或自动会话管理。
|
||||
Expression 模式返回表达式值；Interactive 模式严格编译一次声明、let 或表达式。声明／绑定返回 nil，表达式返回值；宿主可以跨提交复用 globals，并在下一次 CompileOptions 中声明可见名称。Lyra 当前没有 REPL、续行或自动会话管理。
|
||||
|
||||
代码对象保存来源字符串、函数名和定义起始行，现有 VM traceback 保存该位置及指令偏移；没有每条指令对应的精确源码行／列映射。现有 ExecutionLimits 帧数／指令数限制可由嵌入方继续使用；本链路不构成不可信代码沙箱。
|
||||
|
||||
## CLI 与检查
|
||||
## Lyra 宿主与检查
|
||||
|
||||
cli run [--entry name] <file|-> 编译模块、执行初始化、调用无参数入口（默认 main），输出返回值一行。cli eval <file|-> 编译执行一个表达式。字符串输出原始内容，数字输出无损表示，对象使用 VM str；失败仅输出 stderr 并返回非零退出码。文件和 stdin 严格 UTF-8，stdin 到 EOF 后才处理。CLI 在成功或失败后释放代码／结果并清空自己创建的命名空间。
|
||||
lyra run [--entry name] <file|-> 编译模块、执行初始化、调用无参数入口（默认 main），输出返回值一行。lyra eval <file|-> 编译执行一个表达式。字符串输出原始内容，数字输出无损表示，对象使用 VM str；失败仅输出 stderr 并返回非零退出码。文件和 stdin 严格 UTF-8，stdin 到 EOF 后才处理。Lyra 在成功或失败后释放代码／结果并清空自己创建的命名空间。
|
||||
|
||||
可执行文件见 [示例目录](../../crates/compiler/examples/README.md)，API／所有权与错误路径见 [pipeline.rs](../../crates/compiler/tests/pipeline.rs)，进程入口见 [CLI 检查](../../crates/cli/tests/README.md)。这些检查由既有远端 workspace 测试覆盖；本地只做静态检查，不据此宣称实际执行通过，见 [验证约定](../operations/validation.md)。返回 [运行时索引](README.md)。
|
||||
可执行文件见 [示例目录](../../crates/compiler/examples/README.md)，API／所有权与错误路径见 [pipeline.rs](../../crates/compiler/tests/pipeline.rs)，进程入口见 [CLI 检查](https://gitea.entroia.com/Zayden-Jung/endorphin-lyra-cli/src/branch/main/crates/cli/tests/README.md)。引擎检查由 Aster CI 覆盖，进程入口检查由独立 Lyra CI 覆盖；本地只做静态检查，不据此宣称实际执行通过，见 [验证约定](../operations/validation.md)。返回 [运行时索引](README.md)。
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
# 数据库特殊类与连接边界
|
||||
|
||||
数据库连接用于某类明确需要数据库的特殊对象，不用于 VM 版本、部署版本、普通对象信息或统一 key/value 元数据。当前尚未定义该特殊类的名字、载荷布局或语言接口，本页说明已保留的连接能力及接入边界。
|
||||
|
||||
## 当前分层
|
||||
|
||||
- Objects 负责核心对象与私有堆，Core 负责 VM 和执行；两者不依赖 SQLx 或数据库。
|
||||
- Storage 仅暴露 DatabaseConfig、DatabaseConnection 和 DatabaseError。
|
||||
- CLI／Server 不依赖 Storage，启动、bootstrap 和 health 不访问数据库；基础信息由独立 host 文件层处理。
|
||||
- 特殊类以后由宿主实现按需取得数据库连接；尚未自动挂入 Vm 或对象工厂。
|
||||
|
||||
## 显式建立连接
|
||||
|
||||
调用方先构造 DatabaseConfig::Postgres(url)、SqliteFile(path) 或 SqliteMemory，再 await DatabaseConnection::connect。没有 from_env、默认 SQLite 路径或应用启动时的全局数据库。
|
||||
|
||||
connect 会建立真实连接，并可在显式请求 SQLite 文件时创建父目录和文件，但不创建任何应用表。SQLite WAL、连接协商等驱动自身操作不等于应用 schema 初始化。不会创建基础信息表，也不会写入运行或发布信息。
|
||||
|
||||
sqlite_pool／postgres_pool 返回匹配后端的 SQLx 池借用，另一后端返回 None。特殊类以后可在自己的适配实现里执行参数化查询、事务及由该类定义的数据结构；本层不预设通用 KV、ORM、迁移或序列化协议。现有 SQLx API 见 [Pool 文档](https://docs.rs/sqlx/0.8.6/sqlx/struct.Pool.html)。
|
||||
|
||||
## 生命周期
|
||||
|
||||
DatabaseConnection::clone 共享连接池；close().await 显式关闭所有克隆使用的池，并等待已借出连接归还。取出的 SQLx 池还能被调用方克隆，因此单个包装值销毁不保证所有使用者立即结束。
|
||||
|
||||
未来将连接放进原生载荷时，必须另行定义异步关闭、共享所有权和错误传播；当前 VM 的同步 Drop／Native 回调不等于已经完成异步数据库类。连接跨进程不能复用，也不代表 VM 快照。
|
||||
|
||||
## 既有数据和部署
|
||||
|
||||
原先的基础信息存储已从代码中移除。已有数据库表、卷、密码和服务器数据未执行删除或迁移；它们是否存在、有哪些记录不由本次代码修改推断。
|
||||
|
||||
生产继续保留预置 PostgreSQL 服务与既有数据目录，等待实际类的消费接口。应用容器不注入数据库连接变量，当前不消费该服务。部署版本通过镜像标签、release.env 和 current 链接识别，基础信息写入文件；发布时仅为旧数据做一次只读导入，不继续写数据库。详见 [宿主信息](../operations/host-information.md)。
|
||||
|
||||
## 验证
|
||||
|
||||
SQLite 检查先确认新连接没有应用表，再由测试自己创建 class_rows 验证查询和重连。真实 PostgreSQL 使用全新临时测试库，检查连接不建表，并在事务中创建提交后自动删除的临时表。这些是适配层测试，不代表特殊类已实现。
|
||||
|
||||
文件定位见 [storage](../../crates/storage/README.md)，运行与生产资源见 [部署](../operations/deployment.md)。返回 [运行时索引](README.md)。
|
||||
@@ -73,6 +73,6 @@ use、namespace、class、agent、完整类型语法、条件／循环、比较
|
||||
|
||||
词法和语法错误分别标记为 Lexical／Syntax。语法错误将 PEG 的 token 下标转换成原始源码 Span，保留期望项目列表；EOF 错误使用 source.len() 处的空区间。Diagnostic::location 返回一基行列，列按 Unicode 标量计数，CRLF 只算一次换行，不按字节列或字形簇计数。
|
||||
|
||||
`cli parse <file>` 与 `cli parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。可用 --mode 选择 module／expression／interactive，用 --json 输出带 schema 标识的 AstDocument；普通输出为 AstRoot Debug 文本，稳定交换格式见 [AST 模型](ast.md)。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
|
||||
`lyra parse <file>` 与 `lyra parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。可用 --mode 选择 module／expression／interactive，用 --json 输出带 schema 标识的 AstDocument；普通输出为 AstRoot Debug 文本，稳定交换格式见 [AST 模型](ast.md)。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
|
||||
|
||||
当前 Compiler 将 AST 经模块／函数名称分析转换为现有字节码，再交给 VM 解释执行。这是解释器内部的编译／执行准备步骤，不要求使用者先构建程序，见 [执行与版本模型](../architecture/execution-and-versions.md)。MakeFunction 已接入源码函数编译，但解析接受的二元算术和符号值仍没有执行语义；编译器会给出明确诊断，见 [编译链路](compiler.md)。源码闭包尚未实现。解析器也不是不可信代码沙箱，当前没有通用输入大小或解析递归深度限额。
|
||||
|
||||
@@ -33,6 +33,6 @@ Rust panic 尚无专门的捕获恢复或执行根 RAII 清理机制。宿主捕
|
||||
|
||||
Vm 没有独立后台线程、暂停状态或显式 shutdown 状态机。Rust 所有权销毁它所拥有的堆和剩余载荷，包括没有先做循环回收的对象；原生共享资源继续遵循各自的 Rust 所有权。外部 ObjectRef 不保活 Vm。
|
||||
|
||||
Server 的 Tokio 运行时、监听器、信号处理和 Host 文件信息由宿主管理；优雅退出见 [运行](../operations/README.md)。当前宿主不持有数据库连接。数据库能力只为未来的特殊类按需提供，异步连接关闭与原生载荷生命周期仍需单独接入，见 [数据库特殊类](database-objects.md)。数据库不自动保存或恢复 VM 对象。
|
||||
Server 的 Tokio 运行时、监听器、信号处理和 Host 文件信息由宿主管理；优雅退出见 [运行](../operations/README.md)。当前宿主不持有数据库连接。数据库能力只为未来的特殊类按需提供，异步连接关闭与原生载荷生命周期仍需单独接入，见 [数据库特殊类](https://gitea.entroia.com/Zayden-Jung/endorphin-hestia-server/src/branch/main/docs/runtime/database-objects.md)。数据库不自动保存或恢复 VM 对象。
|
||||
|
||||
源码定位：[objects/src](../../crates/objects/src/README.md) 中的 store.rs／heap.rs 负责对象生命周期，[core/src](../../crates/core/src/README.md) 中的 vm.rs／frame.rs／eval.rs 负责执行状态和帧根。返回 [运行时索引](README.md)。
|
||||
|
||||
@@ -102,6 +102,6 @@ compare 的反向规则是 Lt 对应 Gt、Le 对应 Ge，Eq／Ne 保持不变。
|
||||
|
||||
已实现：统一对象结构、稳定地址、代际句柄、身份、显式引用计数、托管属性、原生操作覆盖、比较与哈希、原生调用、资源清理和显式循环回收。
|
||||
|
||||
尚未实现：Python type 系统、语言根类、继承和描述符、可变 VM 调用上下文、自动／分代／增量 GC、语言终结器／复活、完整资源限额和 VM 快照；独立 frontend 已提供阅读器、lexer/parser 与 AST，基础源码执行由独立 [Compiler](compiler.md) 接入，见 [源码前端](frontend.md)；执行器已有帧数和指令数限额。数据库仅为未来特殊类提供按需连接，普通对象或宿主基础信息不自动持久化，详见 [数据库特殊类](database-objects.md)。
|
||||
尚未实现：Python type 系统、语言根类、继承和描述符、可变 VM 调用上下文、自动／分代／增量 GC、语言终结器／复活、完整资源限额和 VM 快照；独立 frontend 已提供阅读器、lexer/parser 与 AST，基础源码执行由独立 [Compiler](compiler.md) 接入，见 [源码前端](frontend.md)；执行器已有帧数和指令数限额。数据库仅为未来特殊类提供按需连接，普通对象或宿主基础信息不自动持久化，详见 [数据库特殊类](https://gitea.entroia.com/Zayden-Jung/endorphin-hestia-server/src/branch/main/docs/runtime/database-objects.md)。
|
||||
|
||||
验证范围与执行约定见 [验证](../operations/validation.md)。
|
||||
|
||||
@@ -42,7 +42,7 @@ revision 是宿主返回的原样标签；Reader 只拒绝全空白标签，不
|
||||
|
||||
## CLI 与交互输入
|
||||
|
||||
CLI parse 文件通过 from_file → parse_source 输出 AST；`cli parse -` 通过 from_stream 读取 stdin 到 EOF，来源为 `<stdin>`。错误保留文件或流名及行列；文件读取与非法 UTF-8 错误在进入 lexer 前返回。parse 不执行源码；run／eval 使用相同阅读器后进入 [Compiler](compiler.md)，支持范围见该契约。
|
||||
CLI parse 文件通过 from_file → parse_source 输出 AST；`lyra parse -` 通过 from_stream 读取 stdin 到 EOF，来源为 `<stdin>`。错误保留文件或流名及行列；文件读取与非法 UTF-8 错误在进入 lexer 前返回。parse 不执行源码；run／eval 使用相同阅读器后进入 [Compiler](compiler.md)，支持范围见该契约。
|
||||
|
||||
stdin 入口不是 REPL，不打印提示符、不保持求值环境，也不区分“需要继续输入”和“真正语法错误”。未来 REPL 宿主先收集一次提交的输入单元，再使用 from_text 并指定会话来源；reader 不承担交互调度。包与 namespace 的成员查找和依赖解析也不由 reader 自动完成。
|
||||
|
||||
|
||||
@@ -26,4 +26,4 @@ EndorReader 提供严格 UTF-8 文件／流读取和宿主 URI provider 适配
|
||||
|
||||
当前按 Unicode 标量值访问字符，不按人眼字形簇。预组合的“ガ”和“カ”加组合浊点可显示相似，但标量数量和序列不同；当前没有自动规范化或全角／半角转换。字符串和字典按当前内容语义处理，不为了所在地悄悄改写数据。前端当前采用的名称字符分类与源码位置规则见 [源码前端](frontend.md)，名称同样不自动规范化。
|
||||
|
||||
宿主基础信息以 UTF-8 JSON 写入；控制键的 ASCII 命名限制属于文件信息协议，值可保存日文，详见 [宿主信息](../operations/host-information.md)。配置与 locale 见 [配置](../operations/configuration.md)，返回 [运行时索引](README.md)。
|
||||
宿主基础信息以 UTF-8 JSON 写入；控制键的 ASCII 命名限制属于文件信息协议，值可保存日文，详见 [宿主信息](https://gitea.entroia.com/Zayden-Jung/endorphin-hestia-server/src/branch/main/docs/operations/host-information.md)。配置与 locale 见 [配置](../operations/configuration.md)，返回 [运行时索引](README.md)。
|
||||
|
||||
Reference in New Issue
Block a user