docs: explain match assertions and annotation type distinctions

crates/core/tests/execution.rs

@@ -237,6 +237,7 @@ fn malformed_wordcode_and_unaligned_jumps_are_rejected_at_construction() {
         vec![255, 1, 255, 1, 255, 1, 255, 1, 1, 0],
         vec![13, 1],
     ] {
+        // 每份非法物理编码都必须在代码构造阶段拒绝，不能等到 VM 取指才失败。
         assert!(matches!(
             EndorCode::new(bytes, vec![Value::Nil], vec![], vec![]),
             Err(VmError::InvalidBytecode { .. })
@@ -482,6 +483,7 @@ fn argument_count_and_foreign_argument_failures_do_not_retain_inputs() {
     let function = vm
         .new_function("identity", code, globals, vec![], vec![])
         .unwrap();
+    // 无实参调用必须准确报告缺少唯一必需参数，不把缺参隐式当作 Nil。
     assert!(matches!(
         vm.call(function, &[]),
         Err(VmError::ArgumentCount {
@@ -490,6 +492,7 @@ fn argument_count_and_foreign_argument_failures_do_not_retain_inputs() {
             ..
         })
     ));
+    // 两个实参超过该函数的最大数量一，预检应在进入函数体前拒绝。
     assert!(matches!(
         vm.call(function, &[Value::Nil, Value::Nil]),
         Err(VmError::ArgumentCount {
@@ -1011,6 +1014,7 @@ fn unbound_names_deleted_locals_and_invalid_null_values_fail_cleanly() {
         vec![],
         CodeLayout::default(),
     );
+    // Null 是 VM 协议哨兵而非语言值，源码执行把它用于非法值路径时必须拒绝。
     assert!(matches!(
         vm.execute(null, globals),
         Err(VmError::InvalidBytecode { .. })
@@ -1699,6 +1703,7 @@ fn suspended_read_only_call_keeps_roots_and_releases_them_on_completion() {
             1,
         )
         .unwrap();
+    // 首量子只消耗一条 Nop，应保存暂停帧并报告累计一条，不能提前完成。
     assert!(matches!(
         progress,
         ExecutionProgress::Pending { instructions: 1 }
@@ -1852,13 +1857,13 @@ fn managed_coroutines_interleave_without_replaying_writes() {
     let second = vm
         .new_coroutine(function, &[], ExecutionLimits::default())
         .unwrap();
+    // 推进第一份到首次 StoreGlobal 之后，累计两条指令。
     assert!(matches!(
-        // 推进第一份到首次 StoreGlobal 之后，累计两条指令。
         vm.resume_coroutine(first, 2).unwrap(),
         CoroutineProgress::Pending { instructions: 2 }
     ));
+    // 第二份也停在首次写入之后，后续都不应重放这个前缀。
     assert!(matches!(
-        // 第二份也停在首次写入之后，后续都不应重放这个前缀。
         vm.resume_coroutine(second, 2).unwrap(),
         CoroutineProgress::Pending { instructions: 2 }
     ));
@@ -1965,13 +1970,13 @@ fn managed_coroutine_hard_budget_accumulates_and_error_releases_frames() {
             },
         )
         .unwrap();
+    // 首量子只执行 Nop 并停放，累计已用一条。
     assert!(matches!(
-        // 首量子只执行 Nop 并停放，累计已用一条。
         vm.resume_coroutine(coroutine, 1).unwrap(),
         CoroutineProgress::Pending { instructions: 1 }
     ));
+    // 第二次执行 LoadConst 后预算耗尽，尚未 Return，因此应终止而非再次 Pending。
     assert!(matches!(
-        // 第二次执行 LoadConst 后预算耗尽，尚未 Return，因此应终止而非再次 Pending。
         vm.resume_coroutine(coroutine, 1),
         Err(VmError::ExecutionLimit("instructions"))
     ));