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 {