docs(tests): explain runtime payload fixtures and allocation stress

crates/core/tests/runtime.rs

@@ -9,6 +9,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 use endor_core::{CompareOp, NativeFunction, ObjectPayload, ObjectRef, Record, Value, Vm, VmError};
 
 #[derive(Debug)]
+/// 生命周期场景的宿主资源：以 Drop 计数观测真正销毁，edges 同时让载荷参与托管图。
 struct Resource {
     /// VM 外观察实际析构次数的共享计数器。
     drops: Arc<AtomicUsize>,
@@ -49,6 +50,7 @@ impl ObjectPayload for Resource {
 }
 
 #[derive(Debug)]
+/// 协议覆盖场景的自定义整数载荷，与内置 EndorNumberObject 分开，专门验证 Store 的动态分派。
 struct Number(i64);
 
 impl ObjectPayload for Number {
@@ -72,7 +74,7 @@ impl ObjectPayload for Number {
         Ok(self.0 != 0)
     }
 
-    /// 载荷自定义哈希协议；Number 按值，ReflectedOrdering 明确拒绝。
+    /// Store::hash 调用此载荷协议，按整数值生成哈希；负数按 Rust as 转为 u64。
     fn hash(&self, _identity: ObjectRef) -> Result<u64, VmError> {
         Ok(self.0 as u64)
     }
@@ -299,11 +301,11 @@ fn released_handles_cannot_alias_new_objects_or_new_vms() {
 fn boxed_objects_keep_their_addresses_when_the_slot_vector_grows() {
     // 建立独立堆，句柄不能跨测试/VM 使用。
     let mut vm = Vm::new().unwrap();
-    // 第一个独立对象/资源保留一份根，与 second/equal 比较身份或引用关系。
+    // 保持首个对象存活，扩容前后比较其独立 Box 地址而非槽向量中的位置。
     let first = vm.new_object().unwrap();
     // 保存对象实体地址，不保存可能因向量扩容变化的槽地址。
     let address = std::ptr::from_ref(vm.object(first).unwrap());
-    // 压力设置：足够多次分配或链节点，检验稳定盒与非递归清理。
+    // 额外分配四千零九十六个对象，迫使 slots 向量扩容；所有对象在 VM 结束时清理。
     for _ in 0..4096 {
         vm.new_object().unwrap();
     }
@@ -461,6 +463,7 @@ fn rust_payload_operations_override_defaults_without_language_types() {
 }
 
 #[derive(Debug)]
+/// 反向比较场景的右操作数：只对 Gt 返回 true，用于识别左 Lt 是否正确交换方向。
 struct ReflectedOrdering;
 
 impl ObjectPayload for ReflectedOrdering {
@@ -483,7 +486,7 @@ impl ObjectPayload for ReflectedOrdering {
         Ok(Some(operation == CompareOp::Gt))
     }
 
-    /// 载荷自定义哈希协议；Number 按值，ReflectedOrdering 明确拒绝。
+    /// Store::hash 调用时明确返回不支持，不能退回默认对象身份哈希。
     fn hash(&self, _identity: ObjectRef) -> Result<u64, VmError> {
         Err(VmError::UnsupportedOperation("hash"))
     }
@@ -562,6 +565,7 @@ fn native_calls_dispatch_validate_arguments_and_propagate_errors() {
 }
 
 #[derive(Debug)]
+/// 非法结果场景的故障注入载荷：只保存未 trace 的借用身份，调用时故意返还它让 VM 拒绝。
 struct ReturnsObject(ObjectRef);
 
 impl ObjectPayload for ReturnsObject {
@@ -595,7 +599,7 @@ fn native_results_cannot_smuggle_foreign_or_dead_handles_into_the_vm() {
     assert_eq!(vm.call(invalid_return, &[]), Err(VmError::ForeignHandle));
     // 本堆对象释放后制造过期返回值，不与异堆错误混淆。
     let dead = vm.new_object().unwrap();
-    // 之后只剩失效句柄文本，回调返回不能把它重新保活。
+    // 之后只剩失效的借用身份，回调返回不能把它重新保活。
     vm.release(dead).unwrap();
     // 故意不 trace 持有的句柄，因为这里测试的是非法借用结果而非合法拥有边。
     let invalid_return = vm.allocate(ReturnsObject(dead)).unwrap();