docs(core): correct public execution and ownership contracts

crates/core/src/eval.rs

@@ -94,7 +94,7 @@ impl Vm {
     ) -> Result<(Value, crate::ReadSet), VmError> {
         // 快照进入前对象身份；之后新建结果允许初始化，但已有对象受写屏障保护。
         let scope = self.objects.begin_read_only();
-        // 先保存调用结果，使成功和错误都能在返回前释放临时函数根。
+        // 先保存调用结果，成功和错误都须关闭本层只读作用域；不消费调用者的函数或参数根。
         let result = self.call_with_limits(function, arguments, limits);
         // 结束域先取回借用观察，之后才将调用成功值与观察组合返回。
         let reads = self.objects.end_read_only_precise(scope)?;
@@ -116,7 +116,7 @@ impl Vm {
         }
         // 新调用从空诊断开始，后续失败才写入该次剩余帧回溯。
         self.last_traceback.clear();
-        // 累计调用准备和指令工作量，切片恢复不会将其清零。
+        // 本次同步调用独立累计调用准备和指令工作量，整个源码调用栈共用这一硬预算。
         let mut executed = 0;
         // 原生调用可能在准备阶段完成并直接移交拥有结果，源码则进入帧循环。
         let frame = match self.prepare_call(function, arguments.to_vec(), &mut executed, limits)? {
@@ -417,7 +417,7 @@ impl Vm {
         if slice == 0 {
             return Err(VmError::InvalidArgument("execution slice must be positive"));
         }
-        // 把准备状态包装为托管载荷，trace 会为其保留与帧根一致的内部强边。
+        // 借用并校验现有协程载荷，读取其硬预算和停放状态；此处尚未替换载荷。
         let coroutine = self.payload::<Coroutine>(reference, "coroutine")?;
         // 硬限制来自创建时状态，不能在每个量子重新给予预算。
         let limits = coroutine.limits;
@@ -605,7 +605,7 @@ impl Vm {
     pub fn cancel_coroutine(&mut self, reference: ObjectRef) -> Result<bool, VmError> {
         // 先拒绝只读上下文，避免用托管协程绕过活跃只读保护。
         self.check_coroutine_entry()?;
-        // 把准备状态包装为托管载荷，trace 会为其保留与帧根一致的内部强边。
+        // 借用并校验现有协程状态，先排除正在执行或已结束的情况，再提交取消。
         let coroutine = self.payload::<Coroutine>(reference, "coroutine")?;
         // 正执行状态拒绝取消，避免在 Rust 回调重入时移除执行者状态。
         if matches!(coroutine.state, CoroutineState::Running) {
@@ -615,7 +615,7 @@ impl Vm {
         if matches!(coroutine.state, CoroutineState::Finished) {
             return Ok(false);
         }
-        // 硬限制来自创建时状态，不能在每个量子重新给予预算。
+        // 取消后仍保留创建时硬限制元数据，只清理帧/结果拥有边，不创建新执行预算。
         let limits = coroutine.limits;
         // 取消保留累计诊断计数，不把已经执行的副作用或预算消耗抹除。
         let executed = coroutine.executed;
@@ -632,7 +632,8 @@ impl Vm {
 
     /// Outer-to-inner execution locations from the last failed call/execute.
     /// These are copied metadata, not heap references or language exceptions.
-    /// 宿主错误报告借用最近失败的复制位置元数据，不保留故障对象图。
+    /// 宿主错误报告借用最近记录的复制位置元数据，不保留故障对象图。
+    /// 仅源码帧执行失败路径生成回溯，参数准备或入口拒绝等错误不保证产生新的非空条目。
     pub fn last_traceback(&self) -> &[ExecutionLocation] {
         &self.last_traceback
     }

crates/core/src/frame.rs

@@ -1,5 +1,5 @@
 //! eval 创建、推进并清理执行状态的数据结构；这里不执行指令，也不自动释放复制句柄。
-//! 活跃帧用外部执行根保留对象；停放到 Coroutine 载荷后由其 trace 边保留同一组身份。
+//! 活跃帧及 VM 内的只读续执行帧用外部执行根保留对象；停放到 Coroutine 载荷后改由 trace 边保留。
 //! Arc 只共享 Rust 帧/代码内存，根与内部边的转换由 eval 显式完成。
 
 use std::sync::Arc;
@@ -34,6 +34,7 @@ impl NativeReturn {
 /// Internal activation record, analogous to _PyInterpreterFrame. It has no
 /// EndorObject header; introspection objects can be added independently later.
 #[derive(Debug)]
+/// eval 内部持有的源码帧；公开 getter 只能观察已有帧引用，当前 Vm 不提供活动帧枚举或借出入口。
 pub struct EndorFrame {
     /// 活跃帧拥有的函数根；函数强边使 code/globals/builtins 保持可达。
     pub(crate) function: ObjectRef,
@@ -134,7 +135,7 @@ impl Default for ExecutionLimits {
 /// owned value plus borrowed read dependencies. Instruction counts accumulate.
 #[derive(Debug)]
 pub enum ExecutionProgress {
-    /// 软切片耗尽，状态仍保存于 VM/托管协程中，不能重放此前代码。
+    /// 只读软切片耗尽，帧和只读作用域仍保存于 VM 的单个续执行槽，不重放此前代码。
     Pending {
         /// 从执行开始累计的计数，不是当前切片的局部数量。
         instructions: usize,
@@ -220,7 +221,7 @@ impl EndorFrame {
         }
         // 每个委托约束都独立持有定义根，重复引用不能去重。
         for check in &self.native_returns {
-            // 参数联合等元数据可能包含多个定义，枚举完整引用集合。
+            // 返回联合约束可能包含多个定义，按实际出现次数枚举完整引用集合。
             for reference in check.expected.references() {
                 visit(reference);
             }

crates/core/src/vm.rs

@@ -44,11 +44,13 @@ impl Vm {
     }
 
     /// 宿主参数检查委托 Store，统一源码/原生数量区间并扣除已绑定接收者。
+    /// None 表示未发布数量元数据，不能仅凭此结果断定该对象可以调用。
     pub fn call_arity(&self, function: ObjectRef) -> Result<Option<objects::CallArity>, VmError> {
         self.objects.call_arity(function)
     }
 
     /// 宿主初始化 Function 名义类型配置，Store 保存弱引用用于后续函数分配。
+    /// 同一身份可重复设置，配置后不能换成另一类型；存活由宿主根或已附着对象等其他拥有图保证。
     pub fn set_function_type(&mut self, definition: ObjectRef) -> Result<(), VmError> {
         self.objects.set_function_type(definition)
     }
@@ -198,7 +200,7 @@ impl Vm {
 
     /// 嵌入方创建空 Store 和空执行状态；不注册类型、函数或语言全局空间。
     pub fn new() -> Result<Self, VmError> {
-        // 空状态与 Store::new 保持一致，执行时按需建立全局空间与帧。
+        // 空状态与 Store::new 保持一致；对象/环境由调用方显式分配，执行入口按需准备帧。
         Ok(Self {
             objects: ObjectStore::new()?,
             last_traceback: Vec::new(),