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

Core 源码导航

本目录解释实现文件如何分工；跨文件的设计规则只在 运行时文档 维护。公开 API 的最终导出入口是 lib.rs。

文件	内容
lib.rs	声明模块、公开类型导出、对象和字节码 rustdoc 示例
object.rs	Value、CompareOp、ObjectPayload、ObjectHeader、EndorObject、Record、NativeFunction
heap.rs	ObjectRef、稳定 Box 槽位、代际验证、引用事务、迭代释放、显式循环收集；含私有边界测试
vm.rs	Vm／VmError、构造和对象操作入口、retain／release、循环回收入口
builtins.rs	String、Dict、Cell、Function、BaseException 载荷与 trace 边
number.rs	EndorNumber、Integer／Decimal／Rational／BinaryFloat／Complex 表示及装箱载荷
vm_builtins.rs	内置载荷校验、代码／函数工厂、Dict／Cell 操作、键语义和可变引用更新
instruction.rs	Opcode、逻辑指令、EXTENDED_ARG 编解码、指令位置与比较参数
code.rs	CodeLayout、EndorCode、共享 EndorCodeObject、操作数／控制流／栈校验
frame.rs	EndorFrame、栈条目、执行位置元数据、ExecutionLimits
eval.rs	execute／call、参数绑定、帧切换、取指分派、结果根转移与失败清理

常见修改入口

要修改什么	涉及文件	同步说明
对象公共操作或头部	object.rs、vm.rs、heap.rs	对象模型
内置载荷、无损数字或容器行为	builtins.rs／number.rs、vm_builtins.rs	基本对象
新操作码	instruction.rs、code.rs 的参数和栈验证、eval.rs 分派	字节码 VM、execution 测试
调用、闭包或返回值根管理	frame.rs、eval.rs、函数 trace	生命周期、builtins 与 execution 测试
新公开 API	对应实现模块与 lib.rs 导出	所属主题、示例、tests 导航

复制 ObjectRef／Value 不增加引用；不能在自定义载荷中擅自改变已登记的托管边。对象 API 不暴露原始指针或句柄索引构造。返回 core。