docs: explain match assertions and annotation type distinctions

crates/objects/src/heap.rs

@@ -926,7 +926,9 @@ mod tests {
             generation: 1,
             ..reference
         };
+        // 槽索引越界时，即使堆身份和代际来自有效对象，也必须拒绝只读访问。
         assert!(matches!(heap.get(invalid), Err(VmError::InvalidHandle)));
+        // 可变访问同样检查代际，伪造旧代际不能借出当前对象。
         assert!(matches!(heap.get_mut(stale), Err(VmError::InvalidHandle)));
     }
 
@@ -942,6 +944,7 @@ mod tests {
         let second = heap.allocate(Box::new(Record)).unwrap();
         assert_eq!(first.index, second.index);
         assert_ne!(first.generation, second.generation);
+        // 复用同一槽但代际变化后，旧句柄必须失效，不能别名到新对象。
         assert!(matches!(heap.get(first), Err(VmError::InvalidHandle)));
         // 内部故障注入：把槽及对象身份同步改成最高代际，再验证释放后的永久退休。
         heap.slots[second.index].generation = u64::MAX;

crates/objects/src/native.rs

@@ -119,6 +119,7 @@ impl CallType {
     pub fn is_any(&self) -> bool {
         self.alternatives()
             .iter()
+            // 只检测是否存在 Any 候选，不据此省略联合中其他定义引用的验证或保活。
             .any(|value| matches!(value, crate::AnnotationType::Any))
     }
     /// 调用/签名检查确认联合非空，且每个托管类型/能力引用有效并有正确载荷。

crates/objects/src/number.rs

@@ -608,8 +608,10 @@ impl EndorNumber {
             CompareOp::Eq => order == Some(Ordering::Equal),
             CompareOp::Ne => order != Some(Ordering::Equal),
             CompareOp::Lt => order == Some(Ordering::Less),
+            // 小于等于仅接受已知 Less 或 Equal；NaN 造成的无序 None 不满足关系。
             CompareOp::Le => matches!(order, Some(Ordering::Less | Ordering::Equal)),
             CompareOp::Gt => order == Some(Ordering::Greater),
+            // 大于等于仅接受已知 Greater 或 Equal，无序值同样返回 false。
             CompareOp::Ge => matches!(order, Some(Ordering::Greater | Ordering::Equal)),
         })
     }

crates/objects/src/types.rs

@@ -1604,21 +1604,29 @@ impl ObjectStore {
             AnnotationType::Any => true,
             AnnotationType::Unit => matches!(value, Value::Nil),
             AnnotationType::Number => {
+                // Number 同时接受直接数值；另一路只认 EndorNumberObject 载荷，不把任意名义类当数值。
                 matches!(value, Value::Number(_))
+                    // 对象句柄已在入口验证存活，仍须下转到具体数值载荷以匹配 Number 类别。
                     || matches!(value,Value::Object(object) if self.object(*object)?.payload().as_any().is::<crate::EndorNumberObject>())
             }
             AnnotationType::String => {
+                // String 同时接受直接 Text；对象表示只接受内置字符串载荷。
                 matches!(value, Value::Text(_))
+                    // 对象必须确为 EndorStringObject，不通过 str 协议把任意对象隐式转文本。
                     || matches!(value,Value::Object(object) if self.object(*object)?.payload().as_any().is::<crate::EndorStringObject>())
             }
+            // Bool 仅匹配直接布尔值，不用真值判断把其他对象归成 Bool。
             AnnotationType::Bool => matches!(value, Value::Bool(_)),
             AnnotationType::Function => {
+                // Function 看载荷的函数分类标志；任意可调用 Type 不自动属于 Function。
                 matches!(value,Value::Object(object) if self.object(*object)?.payload().is_function())
             }
             AnnotationType::Type => {
+                // Type 要求实际类型定义载荷，不按对象名或是否可调用猜测。
                 matches!(value,Value::Object(object) if self.object(*object)?.payload().as_any().is::<EndorTypeObject>())
             }
             AnnotationType::Trait => {
+                // Trait 要求实际能力定义载荷，与实现某能力的普通实例不同。
                 matches!(value,Value::Object(object) if self.object(*object)?.payload().as_any().is::<EndorTraitObject>())
             }
             AnnotationType::Nominal(definition) => match value {

crates/objects/tests/attribute_storage.rs

@@ -210,7 +210,7 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() {
     // 能力声明失败应保持定义版本和声明集合不变。
     let version = store.change_version(class).unwrap();
     assert!(matches!(
-        // 存储冲突消除后能力声明才允许提交。
+        // 当前后端仍有遮蔽字段，能力声明必须在状态提交前失败。
         store.implement_trait(class, capability),
         Err(VmError::TraitViolation { .. })
     ));
@@ -236,18 +236,22 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() {
         store.supports(proxy, capability),
         Err(VmError::TraitViolation { .. })
     ));
+    // 后端已出现遮蔽方法的冲突字段时，即使只读属性查询也必须拒绝不合法的能力存储。
     assert!(matches!(
         store.get_attr(proxy, "check"),
         Err(VmError::TraitViolation { .. })
     ));
+    // 绑定方法入口不能绕过同一存储校验，不能先创建可调用绑定再放过冲突。
     assert!(matches!(
         store.bind_attr(proxy, "check"),
         Err(VmError::TraitViolation { .. })
     ));
+    // 直接方法契约检查也拒绝代理后端冲突，防止跳过属性查找后绕过门禁。
     assert!(matches!(
         store.check_method_contract_call(function, proxy, false),
         Err(VmError::TraitViolation { .. })
     ));
+    // 显式实例存储检查应给出同类能力违规，保持各调用入口的检查一致。
     assert!(matches!(
         store.check_typed_instance_storage(proxy),
         Err(VmError::TraitViolation { .. })
@@ -289,6 +293,7 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() {
         Value::Bool(true)
     );
     assert!(store.supports(reflective, capability).unwrap());
+    // 带反射检查的载荷第一次非法写入仍须拒绝，递归防护不能误跳过最外层约束。
     assert!(matches!(
         store.set_attr(reflective, "check", Value::Nil),
         Err(VmError::TraitViolation { .. })

crates/objects/tests/store.rs

@@ -42,6 +42,7 @@ fn standalone_storage_preserves_identity_validates_edges_and_collects_cycles() {
     store.release(cell).unwrap();
     assert_eq!(store.collect_cycles(), 2);
     assert_eq!(store.object_count(), 0);
+    // 独立 Store 释放完拥有图后，原 Cell 借用句柄也应失效。
     assert!(matches!(store.object(cell), Err(VmError::InvalidHandle)));
     other.release(foreign).unwrap();
 }