docs: explain match assertions and annotation type distinctions

crates/core/tests/native_context.rs

@@ -442,10 +442,12 @@ fn native_types_preflight_arguments_and_clean_wrong_result_roots() {
         ))
         .unwrap();
     assert!(
+        // 错误实参在回调前由 parameter 1 约束拒绝，后面的计数零验证未进入宿主代码。
         matches!(vm.call(function, &[Value::Text("bad".into())]), Err(VmError::TypeMismatch { position, .. }) if position == "parameter 1")
     );
     assert_eq!(calls.load(Ordering::SeqCst), 0);
     assert!(
+        // 合法数值允许回调执行一次，但宿主返回值违约应明确定位 return。
         matches!(vm.call(function, &[Value::Number(7.into())]), Err(VmError::TypeMismatch { position, .. }) if position == "return")
     );
     assert_eq!(calls.load(Ordering::SeqCst), 1);
@@ -519,8 +521,10 @@ fn delegated_source_results_obey_every_native_contract_without_extra_frames() {
         Value::Text("source result".into())
     );
     assert!(
+        // 多层原生委托结果返回外层时，仍需兑现 outer 自己的返回约束并标明其名称。
         matches!(vm.call_with_limits(outer, &[], limits), Err(VmError::TypeMismatch { function, position, .. }) if function == "outer" && position == "return")
     );
+    // 零源码帧预算必须由受委托源码入口拒绝，不能因原生委托不占帧而绕过限制。
     assert!(matches!(
         vm.call_with_limits(
             outer,
@@ -656,7 +660,7 @@ fn legacy_native_signatures_check_optional_variadic_types_and_metadata() {
     }
     // 独立堆隔离当前签名/效果场景，计数与拥有根不会跨测试污染。
     let mut vm = Vm::new().unwrap();
-    // 分配上下文载荷，签名类型与显式 captures 各自通过 trace 保活。
+    // 分配旧式 NativeFunction 载荷，签名引用的类型定义仍通过 trace 保活。
     let function = vm
         .allocate(
             NativeFunction::new("legacy", echo).with_signature(CallSignature {
@@ -678,6 +682,7 @@ fn legacy_native_signatures_check_optional_variadic_types_and_metadata() {
     );
     assert!(vm.call(function, &[Value::Bool(true)]).is_err());
     assert!(
+        // 可变参数允许空列表，但旧式 echo 此时返回 Nil，不符合声明的 Number 返回约束。
         matches!(vm.call(function, &[]), Err(VmError::TypeMismatch { position, .. }) if position == "return")
     );
     // 故意同时配置互相矛盾的签名和独立 arity，查询/调用都应报元数据错误。
@@ -835,6 +840,7 @@ fn native_union_and_nullable_contracts_accept_each_branch_and_reject_invalid_met
         );
     }
     assert!(
+        // 联合都不匹配时诊断需完整保留 String | Bool 候选，不只显示最后尝试的一项。
         matches!(vm.call(function, &[Value::Number(3.into())]), Err(VmError::TypeMismatch { expected, .. }) if expected == "String | Bool")
     );
     assert_eq!(calls.load(Ordering::SeqCst), 3);