docs(objects): explain change notifications and shared errors

crates/objects/src/changes.rs

@@ -1,26 +1,37 @@
+//! Heap 产生、Store/VM 取走、宿主缓存消费的变更通知数据；不保存对象所有权。
+//! 通知反映已提交的修改，不是可重放操作日志，也不保证消费时源对象仍存活。
+
 use crate::ObjectRef;
 
-/// A precise field change or a replacement of an object's native contents.
-/// Entries are notifications, never roots; a source can be dead when consumed.
+/// Heap::record_change 用于合并通知的键；同一对象的不同属性仍各自保留。
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ChangeKey {
+    /// Heap 属性写入/删除发布具体字段名；消费者可只失效对应字段的观察。
     Attribute(String),
+    /// 载荷替换、类型附着或共享引用更新改变整体内容；消费者按内容依赖处理。
     Contents,
 }
 
+/// Heap::take_changes 从内部有序映射生成的单条合并通知，供宿主失效缓存。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ObjectChange {
+    /// 修改来源的完整借用身份，包含代际；不能当作有效拥有根直接使用。
     pub object: ObjectRef,
+    /// 被修改的字段或整体载荷类别。
     pub key: ChangeKey,
+    /// 此对象/键在本批最后一次通知的对象版本，不是批次序号。
     pub version: u64,
 }
 
-/// Coalesced changes since the previous drain. Overflow requires the consumer
-/// to rescan its dependencies, rather than silently missing notifications.
+/// Store::take_changes 返回上次取走后累计的合并结果；取走时重置内部批次。
+/// 溢出会丢弃精确条目并要求全面重验，消费者不能把空 changes 解释为没有修改。
 #[derive(Debug, Default)]
 pub struct ChangeBatch {
+    /// 精确通知；同一对象/键重复修改仅保留最新版本，排序不表示实际修改先后。
     pub changes: Vec<ObjectChange>,
+    /// true 时须全面重验所持依赖，不能仅处理 changes 中的对象。
     pub rescan_required: bool,
 }
 
+/// Heap::record_change 的唯一对象/键数量上限；更新已有键不额外占用容量。
 pub(crate) const MAX_PENDING_CHANGES: usize = 4096;