docs: clarify interpreted execution and platform resource versions
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 6m46s

This commit is contained in:
2026-10-19 13:23:07 +08:00
parent 483d9d1717
commit 78fc859825
17 changed files with 103 additions and 20 deletions
+12 -1
View File
@@ -1,6 +1,13 @@
# 系统架构
Endor 的目标是云原生语言;本仓库当前实现运行时、基础语法前端和宿主演示,尚无源码编译器、云调度器或多租户执行沙箱。当前侧重核心语义独立于进程环境,以及数据库能力按对象需求显式提供。
Endor 的目标是云原生语言;本仓库当前实现运行时、基础语法前端和宿主演示,尚未实现 AST 到字节码生成,也没有云调度器或多租户执行沙箱。当前侧重核心语义独立于进程环境,以及数据库能力按对象需求显式提供。
## 本目录
| 文件 | 职责 |
| --- | --- |
| README.md | 当前组件边界、依赖方向和跨组件约束 |
| [execution-and-versions.md](execution-and-versions.md) | 解释执行流程、资源修订/依赖锁与平台升级的设计方向,区分已实现与计划 |
## 组件与依赖方向
@@ -40,6 +47,10 @@ HTTP 宿主通过 Arc 共享只读 Vm。GET /bootstrap 只读对象模型和数
部署保留既有 PostgreSQL 服务与数据目录,应用启动不依赖数据库连接。基础信息从数据库改为 Host 文件层;发布脚本一次性只读导入旧 PostgreSQL 记录,不删除原表或卷。脚本结果未主动跟踪,不能据此认定远端已经完成迁移。
## 执行与版本方向
Endor 的目标流程是源码经阅读器、lexer、parser 和内部字节码生成后,由 VM 解释执行。源码资源与依赖版本由平台管理,不要求真实代码文件或项目级 Git 作为语言执行单位;使用者无需单独构建程序。解释器由平台统一升级,升级实现不改写用户源码修订。资源身份、修订与依赖锁尚未实现,持久化字节码缓存暂不作为首版要求;完整说明见 [解释执行与平台资源版本](execution-and-versions.md)。
## 后续边界
特殊类接口与异步数据库调用、AST 到字节码的编译与名称/类型分析、更多指令、异常传播、自动 GC、内存配额、取消和能力隔离等均需按实际需求设计。当前帧/指令限额不等于完整沙箱。返回 [文档索引](../README.md)。
@@ -0,0 +1,53 @@
# 解释执行与平台资源版本
本页记录 Endor 的执行模型与平台资源管理方向。阅读器、基础 AST 和字节码 VM 已分别实现;AST 到字节码生成、平台资源存储、发布和依赖锁尚未实现。下述版本模型是后续设计方向,不是现有 API 或已定稿的 URI 协议。
## 解释型语言的执行过程
Endor 由平台解释执行,目标流程为:
```text
源码 → EndorReader → lexer → PEG parser → AST
→ 名称/局部槽与闭包分析 → 生成字节码 → VM 解释执行
```
生成字节码是解释器内部的执行准备,可以称为内部编译。使用者提交或调用源码资源,由平台完成这些步骤,无需先构建独立程序。现有 VM 解释 wordcode;后续接入源码时沿用该执行器。
当前 frontend 到 AST 为止,core 可执行由 Rust API 构造的代码对象,两者还未连接。`cli parse` 仅输出 AST,尚无源码执行命令或 REPL。仓库中的 Cargo/Docker 构建用于构建 Rust 实现和宿主,不是 Endor 使用者的程序构建步骤。
## 名称、资源与修订
平台目标是将代码存为可发布到 workspace/namespace 的资源,通过 Endor URI 寻找。语言运行不应要求资源对应真实源码文件或一个 Git 项目。本仓库自身仍用 Git 管理 Rust 实现与文档;文件和流也继续作为宿主输入适配。
后续资源模型应区分以下概念,具体持久化结构尚未设计:
| 概念 | 作用 | 变化方式 |
| --- | --- | --- |
| workspace/namespace 名称与 URI | 供使用者查找和组织资源 | 名称可以重命名,入口可以指向新的修订 |
| 资源身份 | 连接同一资源的修订历史 | 应独立于可变名称和实际存储位置 |
| 资源修订 | 标识一次不可变的源码及其相关元数据 | 编辑后产生新修订,保留旧修订供明确选择 |
| 源码内容 hash | 校验或寻址原始文本内容 | 可作为设计选项;算法、字节范围和修订格式未定 |
| 依赖锁 | 固定所选择的依赖资源与修订 | 更新依赖时显式形成新的选择记录 |
| 发布快照 | 把多份资源及依赖选择作为一次一致发布 | 按实际原子发布需求增加,不强制所有资源归为一个项目 |
相同源码可以处在不同的依赖上下文,因此源码 hash 本身不足以确定完整执行输入。原文内容身份、包含依赖的修订身份是否使用同一种 hash,需要另行决定。Reader 会原样保留文本,但当前不计算或验证任何 hash。
重命名或移动存储位置不应迫使已锁定引用改选内容;修改源码则产生新修订。可变 URI 的重新解析可以选到新修订,已有依赖锁应继续指向原资源与修订。实现时还需解决资源保留、权限和删除策略;固定版本不等于永久可访问。
版本选择属于平台资源及依赖元数据,不要求在每个业务语句中写 hash,也没有新增 workspace/namespace/版本锁的语言语法。URI 将来可以提供修订选择方式,具体形式未定。并发编辑时防止覆盖的写入锁或条件更新,与选择执行版本的依赖锁是两项独立机制,当前均未实现。
## 平台解释器升级
解释器及内部字节码生成器按平台统一发布管理,首版方向不要求每份资源自行选择编译器版本。同一份源码修订 R1,可以由旧解释器生成字节码 A,也可以在平台升级后由新解释器重新处理为字节码 B;升级实现不会因此把源码 R1 改成 R2。
源码与依赖锁回答“选了哪份用户代码”,平台版本回答“由哪套运行语义处理”。锁定源码不保证跨解释器版本、外部数据和宿主能力变化后的结果完全相同。语言语义迁移、升级中正在执行的帧如何处理、是否需要历史运行环境,留待实际兼容性需求设计;当前不承诺热切换执行帧。
现有 `host.version`、`deployment.release`、镜像 SHA 和部署目录记录的是 Rust 实现/宿主发布,不能用作 Endor 用户资源的修订或依赖锁。资源版本也不复用 VM 的代际对象句柄。
## 字节码复用与首版范围
首版源码执行可先不持久化字节码缓存,平台升级后按需重新准备源码,不提前引入编译产物仓库或用户侧产物版本管理。同一进程内可以复用已准备的不可变代码对象;core 当前已有函数共享代码对象的能力,不要求每次函数调用都重新生成字节码。
只有引入跨进程或跨升级的持久化字节码缓存后,才需要明确失效策略。缓存有效性至少取决于相关源码/依赖输入与解释器、字节码格式兼容性;可在平台升级时统一失效,也可使用内部兼容标识。无需把实现版本强塞进每个资源 URI;具体缓存方案尚未选择。
近期先完成源码到现有 VM 的连接,再按平台接口需求设计资源存储、修订与依赖锁。Reader 已提供宿主 provider 扩展点,当前只接收不透明 revision 标签,实际契约见 [Endor 阅读器](../runtime/reader.md)。返回 [系统架构](README.md) 或 [文档索引](../README.md)。