endorphin-aster-vm/crates/core/src/README.md

Core VM 源码导航

本目录只实现 VM、内部执行帧和 wordcode 求值循环。核心对象、对象堆、内置载荷、指令与代码对象数据属于独立 objects/src。

文件	职责
lib.rs	VM 类型导出、objects 类型兼容重导出（含 ReadAccess/CallSignature/CallType/CallEffect）、宿主调用与字节码 rustdoc 示例
vm.rs	Vm 拥有 ObjectStore、错误位置记录与挂起的只读执行状态；对象操作和宿主 new_class 和显式/类型化Trait注册/关系查询显式委托给 objects；函数／字段检查统一开关、统一参数区间/已知调用效果查询与函数类型配置
frame.rs	EndorFrame、栈条目、源码与原生委托返回契约执行根、执行位置元数据、ExecutionLimits、ExecutionProgress 与 VM 内续算帧状态
eval.rs	execute／call、只读调用/可恢复分片/取消与依赖结果、参数绑定、原生实现前数量/类型/效果检查和原生/类型化Trait委托返回检查、可选注解/动态覆写兼容检查、源码类字段环境绑定、帧切换、取指分派、MakeFunction、结果根转移与失败清理

常见修改入口

要修改什么	涉及位置	同步说明
对象表示、分配、引用或内置对象行为	objects/src；兼容方法需要时同步 vm.rs 委托	对象模型、基本对象
新操作码或代码布局	objects 的 instruction.rs／code.rs、core 的 eval.rs	字节码 VM、execution 检查
调用、闭包或返回值根管理	frame.rs、eval.rs、objects 的函数 trace	生命周期
新 VM 公开 API	vm.rs／eval.rs 与 lib.rs 导出	所属主题、示例、tests 导航

core 不访问对象私有字段或 Heap；执行器只通过受校验的对象存储操作维护帧根。返回 core。

独立托管调用帧：frame.rs 定义 CoroutineProgress 和私有可追踪帧载荷；eval.rs 提供 new_coroutine/resume_coroutine/cancel_coroutine，暂停帧以托管边保活，恢复时转回执行根。与跨量子只读续算分开，所有权及边界见 docs/runtime/bytecode.md。

eval.rs的LoadGlobal及可恢复只读结果支持ReadDependency；frame.rs携带精确观察，lib.rs重导出只读观察类型，兼容旧reads对象列表。

同步call_read_only_precise_with_limits同样返回ReadSet，供宿主精确校验缓存；原call_read_only_with_limits继续返回保守objects列表，预算、结果拥有式引用和失败关闭只读作用域的语义不变。