docs(objects): clarify protocol tracking and ownership boundaries

crates/core/src/eval.rs

@@ -1126,6 +1126,7 @@ impl Vm {
             Value::Bool(value) => Ok(*value),
             Value::Text(value) => Ok(!value.is_empty()),
             Value::Number(value) => Ok(!value.is_zero()),
+            // 对象真值走 Store 的载荷协议；该底层入口当前不自动登记对象版本依赖。
             Value::Object(reference) => self.is_true(*reference),
         }
     }

crates/objects/src/builtins.rs

@@ -24,7 +24,7 @@ impl EndorStringObject {
         Self { text: text.into() }
     }
 
-    /// 字典 key_equal 和宿主查询借用 UTF-8 内容；借用不创建托管根，也不修改字符串。
+    /// 字典 key_equal、eval 文本比较和宿主查询借用 UTF-8 内容；借用不创建托管根，也不修改字符串。
     pub fn as_str(&self) -> &str {
         &self.text
     }
@@ -41,7 +41,7 @@ impl EndorStringObject {
 }
 
 impl ObjectPayload for EndorStringObject {
-    /// ObjectStore::assign 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
+    /// ObjectStore::assign_from 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
     fn reference_assignment_only(&self) -> bool {
         true
     }
@@ -120,7 +120,7 @@ impl EndorDictObject {
 }
 
 impl ObjectPayload for EndorDictObject {
-    /// ObjectStore::assign 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
+    /// ObjectStore::assign_from 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
     fn reference_assignment_only(&self) -> bool {
         true
     }
@@ -174,7 +174,7 @@ impl EndorCellObject {
 }
 
 impl ObjectPayload for EndorCellObject {
-    /// ObjectStore::assign 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
+    /// ObjectStore::assign_from 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
     fn reference_assignment_only(&self) -> bool {
         true
     }
@@ -276,7 +276,7 @@ impl ObjectPayload for EndorFunctionObject {
     fn is_function(&self) -> bool {
         true
     }
-    /// ObjectStore::assign 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
+    /// ObjectStore::assign_from 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
     fn reference_assignment_only(&self) -> bool {
         true
     }
@@ -362,7 +362,7 @@ impl EndorBaseExceptionObject {
         self.suppress_context = true;
         self
     }
-    /// 分配前的构建器记录上下文强边；不自动改变 suppress_context，也不执行上下文异常。
+    /// 分配前的构建器保存上下文句柄；allocate 后才登记强边，不自动改变 suppress_context 或执行异常。
     pub fn with_context(mut self, context: ObjectRef) -> Self {
         self.context = Some(context);
         self
@@ -390,11 +390,11 @@ impl EndorBaseExceptionObject {
     pub fn args(&self) -> &[Value] {
         &self.args
     }
-    /// ObjectStore::validate_builtin/trace 读取可选显式原因；返回借用身份，不创建新拥有根。
+    /// ObjectStore::validate_builtin 和宿主读取可选显式原因；返回借用身份，不创建新拥有根。
     pub fn cause(&self) -> Option<ObjectRef> {
         self.cause
     }
-    /// ObjectStore::validate_builtin/trace 读取可选上下文；即使已抑制显示，此强边仍参与追踪。
+    /// ObjectStore::validate_builtin 和宿主读取可选上下文；即使已抑制显示，分配后的上下文边仍参与追踪。
     pub fn context(&self) -> Option<ObjectRef> {
         self.context
     }
@@ -413,7 +413,7 @@ impl EndorBaseExceptionObject {
 }
 
 impl ObjectPayload for EndorBaseExceptionObject {
-    /// ObjectStore::assign 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
+    /// ObjectStore::assign_from 调用，声明默认 assign_from 不会就地修改载荷；只读阶段可跳过写尝试，允许调用方重绑局部引用。
     fn reference_assignment_only(&self) -> bool {
         true
     }

crates/objects/src/changes.rs

@@ -23,7 +23,8 @@ pub struct ObjectChange {
     pub version: u64,
 }
 
-/// Store::take_changes 返回上次取走后累计的合并结果；取走时重置内部批次。
+/// Store::take_changes 返回上次取走后累计发布的合并结果；取走时重置内部批次。
+/// 只读域中新建结果的允许写入更新对象版本，但不发布到此应用通知批次。
 /// 溢出会丢弃精确条目并要求全面重验，消费者不能把空 changes 解释为没有修改。
 #[derive(Debug, Default)]
 pub struct ChangeBatch {

crates/objects/src/object.rs

@@ -106,6 +106,7 @@ pub trait ObjectPayload: Any + fmt::Debug + Send + Sync {
     fn kind_name(&self) -> &'static str;
 
     /// Heap 在分配/替换载荷时收集内部强边（含重复边）；GC 此后使用边快照。
+    /// 单独调用 trace 只枚举借用身份，不替调用者取得拥有根。
     /// 默认无边；实现不能在快照建立后通过内部可变性悄悄改变这些引用。
     fn trace(&self, _visit: &mut dyn FnMut(ObjectRef)) {}
 
@@ -249,6 +250,7 @@ impl EndorNativeFunctionObject {
         &self.name
     }
     /// 构造阶段补充完整签名，并同步数量限制；分配后签名中的引用由 Heap 边快照持有。
+    /// 此构建器不验证签名结构；Store::native_signature 查询或 VM 调用时再校验完整契约。
     pub fn with_signature(mut self, signature: crate::CallSignature) -> Self {
         self.arity = Some(signature.arity);
         self.signature = Some(signature);
@@ -306,7 +308,8 @@ impl ObjectPayload for EndorNativeFunctionObject {
     fn call_arity(&self) -> Option<crate::CallArity> {
         self.arity
     }
-    // VM 分派或宿主直接调用：先检查数量，再将同一参数切片借给 Rust 回调。
+    // VM 分派或宿主直接调用：此载荷方法只检查数量，再将同一参数切片借给 Rust 回调。
+    // 直接调用不执行 VM 的完整参数/返回类型检查，结果中的对象也仍借用；完整调用请经 Vm::call。
     fn call(&self, arguments: &[Value]) -> Result<Value, VmError> {
         // 未声明 arity 时不在这里限制数量；声明后错误必须先于回调的任何副作用返回。
         if let Some(arity) = self.arity {

crates/objects/src/store.rs

@@ -58,6 +58,7 @@ impl ObjectStore {
     }
     /// 缓存使用者重验一次观察；失效句柄或当前读取失败都表示依赖不再有效。
     /// 经正常读取入口比较，因此若当前另有读取作用域，也会登记相应观察。
+    /// 名称/字典种类比较当前状态而非永久失效位，删除遮蔽或恢复原值后可再次有效。
     pub fn read_dependency_valid(&self, dependency: &crate::ReadDependency) -> bool {
         // 整对象检查版本；种类只检查仍是字典；名称检查当前 Option<Value> 是否保持相等。
         match dependency {
@@ -104,12 +105,14 @@ impl ObjectStore {
     }
 
     /// 宿主缓存或类型配置把有效强句柄转为弱句柄；不增加计数，也不消耗调用方已有根。
+    /// 仍经 object 验证，处于只读追踪作用域时会登记此对象的版本读取。
     pub fn downgrade(&self, reference: ObjectRef) -> Result<WeakObjectRef, VmError> {
         self.object(reference)?;
         Ok(WeakObjectRef(reference))
     }
 
     /// 宿主升级弱句柄：存活则 retain 一份外部根，已释放返回 None；跨堆引用仍是错误。
+    /// 存活验证经过 object，可能登记读取；升级失败不交付拥有根。
     pub fn upgrade(&mut self, weak: WeakObjectRef) -> Result<Option<ObjectRef>, VmError> {
         // 先验证代际与堆身份；只有 InvalidHandle 被解释为过期，其他错误原样传播。
         match self.object(weak.0) {
@@ -344,21 +347,25 @@ impl ObjectStore {
     }
 
     /// Vm::str 委托用户可见文本表示，默认载荷实现回退到 repr。
+    /// 当前文本协议直接借用 Heap 载荷，不自动登记对象版本读取；不能把调用成功当成已收集内容依赖。
     pub fn str(&self, reference: ObjectRef) -> Result<String, VmError> {
         self.heap.get(reference)?.payload().str(reference)
     }
 
     /// VM 真值转换调用载荷协议；错误保持为错误，不把协议失败解释为 false。
+    /// 当前真值协议直接借用 Heap 载荷，不自动登记对象版本读取；不能把调用成功当成已收集内容依赖。
     pub fn is_true(&self, reference: ObjectRef) -> Result<bool, VmError> {
         self.heap.get(reference)?.payload().is_true()
     }
 
     /// 通用字典键准入及宿主哈希调用载荷协议，载荷可明确拒绝哈希。
+    /// 当前哈希协议直接借用 Heap 载荷，不自动登记对象版本读取；不能把调用成功当成已收集内容依赖。
     pub fn hash(&self, reference: ObjectRef) -> Result<u64, VmError> {
         self.heap.get(reference)?.payload().hash(reference)
     }
 
     /// VM 对象比较和字典对象键查找共用的双向协议；不运行源码函数比较方法。
+    /// 此入口自身不登记双方版本；调用方其他读取可能另外收集依赖。
     pub fn compare(
         &self,
         left: ObjectRef,

crates/objects/src/store_builtins.rs

@@ -80,6 +80,7 @@ impl ObjectStore {
 
     /// Vm 的执行入口及 eval 创建闭包时调用，组合代码、全局空间、默认值和捕获槽。
     /// name 用作函数标识；code 指向可执行代码；closure 按该代码的自由变量顺序排列。
+    /// 输入对象均借用，成功返回一份函数拥有根；代码、环境、默认值和捕获对象由函数内部边保活。
     pub fn new_function(
         &mut self,
         name: impl Into<String>,
@@ -150,6 +151,7 @@ impl ObjectStore {
     /// eval 查找全局名和内置名时调用：既记录命中值，也记录“此名称不存在”。
     /// 这里只查一个字典；全局未命中后再查 builtins 的顺序由 eval 决定。
     /// 通用 dict_get 和条目迭代仍采用整字典依赖。
+    /// 返回 Value 中对象身份仅借用；名称观察快照也不取得对象根。
     pub fn dict_get_name(
         &self,
         dictionary: ObjectRef,
@@ -201,6 +203,7 @@ impl ObjectStore {
     }
 
     /// Vm::dict_delete 删除一个键；返回值说明是否存在该键，错误通过 Result 单独传播。
+    /// 缺键时只完成读取并返回 false，不触发替换写屏障；已有键在只读域内删除仍会被拒绝。
     pub fn dict_delete(&mut self, dictionary: ObjectRef, key: &Value) -> Result<bool, VmError> {
         // 先复制载荷准备新状态；Rust clone 不 retain，提交前仍由旧字典持有原有引用边。
         let mut dict = self.payload::<EndorDictObject>(dictionary, "dict")?.clone();