From ca00c1d1107a3816ba99d9b6d9263db8c62d53a4 Mon Sep 17 00:00:00 2001
From: Codex Bot <codex-bot@gitea.entroia.local>
Date: Sun, 15 Nov 2026 19:41:49 +0800
Subject: [PATCH] docs(objects): explain read observation lifetime and equality

---
 crates/objects/src/heap.rs | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/crates/objects/src/heap.rs b/crates/objects/src/heap.rs
index 8bdc255..3e80595 100644
--- a/crates/objects/src/heap.rs
+++ b/crates/objects/src/heap.rs
@@ -106,6 +106,7 @@ pub enum ReadDependency {
         object: ObjectRef,
     },
     /// 指定文本名称的命中/缺失值快照；None 与 Some(Nil) 区分。
+    /// Store 重验使用 Value 的表示相等；其中对象按句柄身份比较，不递归验证被引用对象内容。
     Name {
         /// 接受名称查找的字典身份。
         object: ObjectRef,
@@ -129,10 +130,15 @@ impl ReadDependency {
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 /// 精确依赖的排序/去重键；与 ReadDependency 分开，观察值不参与键身份。
 enum ReadKey {
+    /// 整对象观察按完整身份去重。
     Object(ObjectRef),
+    /// 字典种类观察与同对象的版本/名称观察分别保留。
     DictionaryKind(ObjectRef),
+    /// 同一字典的不同文本键各自保存首次查找值。
     Name(ObjectRef, String),
 }
+/// Store::end_read_tracking_precise 返回的子调用观察；结束子区间不结束外层只读作用域。
+/// 列表中的身份均借用，内容读取优先于验证分类；只包含该作用域进入前已有对象的已登记读取。
 #[derive(Debug)]
 pub struct TrackedReads {
     /// 子区间对象读取与用途分类。
@@ -140,6 +146,8 @@ pub struct TrackedReads {
     /// 精确观察列表，供 Store::read_dependency_valid 重验。
     pub dependencies: Vec<ReadDependency>,
 }
+/// Store::end_read_only_precise 和 VM 精确只读调用返回的整个作用域观察。
+/// 对象/键分别去重且保留首次快照，不保活观察目标；缓存使用者通过 Store 重验依赖。
 #[derive(Debug)]
 pub struct ReadSet {
     /// 整个作用域读取到的借用对象身份。