docs(objects): clarify native scope and contract validation phases

crates/objects/src/contracts.rs

@@ -85,6 +85,7 @@ impl CallType {
     /// Nominal inheritance and explicit capabilities participate; no structural
     /// or callable-signature inference is implied by this relation.
     /// 替换校验的值集合包含关系：provided 的每项都必须被 self 的至少一项接纳。
+    /// check_substitution 用它检查参数逆变和返回协变；只检查声明，不调用实现或保留定义根。
     pub fn accepts_type(&self, store: &ObjectStore, provided: &Self) -> Result<bool, VmError> {
         // 先验证联合全部定义边，再做包含/匹配判断，不能让无效分支藏在后面。
         self.validate(store)?;
@@ -429,7 +430,7 @@ impl ObjectStore {
         }
         Ok(())
     }
-    /// set_method 提交前，以 Patch 校验受影响后代，避免先改表再发现错误。
+    /// define_method 提交前，以 Patch 校验受影响后代，避免先改表再发现错误。
     pub(super) fn validate_override_update(
         &self,
         owner: ObjectRef,
@@ -455,7 +456,7 @@ impl ObjectStore {
         Ok(())
     }
     /// Explicit override validation, including any typed capabilities.
-    /// VM/宿主显式启用普通覆盖检查，同时校验接收者的类型化能力约束。
+    /// 宿主显式要求本次普通覆盖检查，同时校验接收者的类型化能力约束；不修改 VM/Store 检查开关。
     pub fn check_method_override_call(
         &self,
         function: ObjectRef,
@@ -466,7 +467,7 @@ impl ObjectStore {
     }
     /// Typed capabilities are explicit opt-ins and always checked. Ordinary
     /// override checking remains configurable by the VM's source-check flag.
-    /// eval 原生调用前核对实际方法；能力约束始终检查，普通覆盖由 overrides 控制。
+    /// eval 的源码建帧、原生调用及 NativeContext 准备时核对方法；能力约束始终检查，普通覆盖由 overrides 控制。
     pub fn check_method_contract_call(
         &self,
         function: ObjectRef,
@@ -526,6 +527,7 @@ impl ObjectStore {
     /// Borrowed expected results for all typed capabilities of this effective
     /// method. The evaluator retains definitions before entering the body.
     /// eval/NativeContext 收集有效方法的全部能力返回约束；返回类型句柄仍为借用。
+    /// 这是约束收集，不独立替代方法参数/覆盖或实际返回值校验；跨执行阶段保活由调用方负责。
     pub fn method_trait_returns(
         &self,
         function: ObjectRef,

crates/objects/src/native.rs

@@ -9,6 +9,7 @@ use crate::{ObjectPayload, ObjectRef, ObjectStore, Value, VmError, WeakObjectRef
 /// Borrowed results produced inside a native call. Invoke delegates to another
 /// callable through the VM's existing frame loop, without recursively entering it.
 #[derive(Debug)]
+/// 同一结果类型在回调返回时携带借用值，NativeContext::execute 成功输出后才携带已保留的输出根。
 pub enum NativeResult {
     /// 回调内为借用结果；execute 成功输出时其中对象已获得移交给 VM 的根。
     Return(Value),
@@ -38,6 +39,7 @@ impl CallArity {
         Self { required, maximum }
     }
     /// VM/契约检查查询数量是否落在闭区间，不改变元数据。
+    /// 本方法不校验上下界本身；需要诊断非法元数据时应先走 validate/check 或 Store 查询。
     pub fn accepts(self, count: usize) -> bool {
         (self.required..=self.maximum).contains(&count)
     }
@@ -73,6 +75,7 @@ pub enum CallEffect {
     ReadOnly,
     /// The native body itself is read-only; delegated effects are dynamic and
     /// checked by the VM in the same execution/heap scope.
+    /// 本体承诺只读；目标继续走同一作用域内的已发布效果检查和受控堆写屏障，不代表整条链已证明只读。
     Delegated,
     /// 声明可能修改已有托管对象，只读执行不允许。
     Mutating,
@@ -177,6 +180,7 @@ impl CallType {
 /// Immutable native contract, including an explicit receiver where applicable.
 /// Missing fixed slots are covered by variadic; optionality comes from arity.
 #[derive(Debug, Clone)]
+/// 宿主在构造阶段可填写公开字段；载荷发布后按不可变声明使用，不能私自改变已快照的定义引用。
 pub struct CallSignature {
     /// 参数数量区间决定可省略的尾部参数，不由类型列表长度直接决定。
     pub arity: CallArity,
@@ -262,6 +266,7 @@ impl CallSignature {
         Ok(())
     }
     /// 原生调用返回后校验结果类型；不重新验证整份参数元数据。
+    /// 此处只检查借用 value，不取得结果拥有根；结果保留/移交由 NativeContext 或 VM 另行处理。
     pub fn check_return(
         &self,
         store: &ObjectStore,
@@ -276,11 +281,13 @@ impl CallSignature {
 pub trait NativeCallable: fmt::Debug + Send + Sync + std::any::Any {
     /// Immutable resolved types; referenced definitions must be traced by the
     /// payload. ContextNativeFunction snapshots and traces them automatically.
+    /// ContextNativeFunction::new 在构造时调用并保存快照；查询不得经内部可变性悄悄改变已发布的类型引用。
     fn signature(&self) -> Option<CallSignature> {
         None
     }
 
     /// Optional positional contract. Missing metadata remains an explicit legacy gap.
+    /// VM/NativeContext 查询数量；默认从 signature 推出区间，覆盖时需与已发布完整签名一致。
     fn arity(&self) -> Option<CallArity> {
         self.signature().map(|signature| signature.arity)
     }
@@ -329,7 +336,8 @@ impl<'a> NativeContext<'a> {
         self.store.implement_trait(definition, capability)
     }
 
-    /// 宿主只读查询存储，修改使用上下文受控入口。
+    /// 宿主取得 &ObjectStore 查询视图，修改使用上下文受控入口。
+    /// 这里只限制 Rust 借用权限，不自行开启 Heap 只读作用域；是否处于只读执行由调用入口决定。
     pub fn store(&self) -> &ObjectStore {
         self.store
     }
@@ -363,7 +371,7 @@ impl<'a> NativeContext<'a> {
         Ok(function)
     }
 
-    /// 创建空字典并登记其外部根。
+    /// 创建空字典并登记上下文拥有的临时根；借出的身份不由回调手工 release。
     pub fn new_dict(&mut self) -> Result<ObjectRef, VmError> {
         // 只有分配/升级成功后才登记根，错误路径不留下虚假的释放条目。
         let object = self.store.new_dict()?;
@@ -371,7 +379,7 @@ impl<'a> NativeContext<'a> {
         Ok(object)
     }
 
-    /// 创建空/已初始化 Cell 并登记外部根。
+    /// 创建空/已初始化 Cell 并登记上下文临时根；若作为输出交付，execute 另保留一份输出根。
     pub fn new_cell(&mut self, value: Option<Value>) -> Result<ObjectRef, VmError> {
         // 只有分配/升级成功后才登记根，错误路径不留下虚假的释放条目。
         let object = self.store.new_cell(value)?;
@@ -441,7 +449,10 @@ impl<'a> NativeContext<'a> {
 
     /// Internal execution bridge. Every returned object reference owns a root;
     /// consumers must release Return values or all Invoke arguments/function.
-    /// VM 执行桥：校验/保护输入，执行回调，验证直接结果，最后移交输出根。
+    /// VM 的 invoke_native 调用此桥：校验/保护输入，执行回调，验证直接结果，最后移交输出根。
+    /// VM 传入从 function 载荷克隆的分派器；手工调用需自行保证二者对应，本方法不验证 Arc 身份。
+    /// Invoke 的最终返回约束由 VM 的 prepare_call/源码帧继续维护，不能把此结果当作最终调用完成。
+    /// 此桥不推进源码委托，也不维护执行预算或回溯；普通覆盖检查选项由 VM 上层传递处理。
     pub fn execute(
         // 整次回调独占借用存储，提供受控修改与查询。
         store: &'a mut ObjectStore,
@@ -569,6 +580,7 @@ impl ContextNativeFunction {
     }
 
     /// 宿主包装上下文回调，快照签名与显式捕获边，随后由 Store 分配。
+    /// 构造本身不 retain 或校验托管句柄；allocate 时登记边，Store::native_signature/调用时再验证签名结构。
     pub fn new(
         // 宿主静态诊断名，不承担语言类型身份。
         name: &'static str,