docs: 修正结构哈希口径注释并展开编译管线黑话

crates/oxide_compiler/src/hash/expression.rs

@@ -108,6 +108,7 @@ pub(super) fn hash_expression(expr: &Expression, h: &mut rustc_hash::FxHasher, i
             }
         }
         Expression::ClassExpression(class) => {
+            // 类表达式名与类声明名同口径：两种哈希粒度下恒计入（编译产物物化名）。
             if let Some(id) = &class.id {
                 id.name.as_str().hash(h);
             }

crates/oxide_compiler/src/hash/mod.rs

@@ -1,8 +1,10 @@
 //! AST 结构哈希：按语法域（statement/expression/class/...）递归计算
 //! `Program` 的稳定哈希，用作编译缓存键（code cache）。
 //!
-//! `structural_hash` 忽略绑定名（结构相等即可命中），
-//! `compiled_module_hash` 纳入绑定名（精确匹配避免错误复用）。
+//! `structural_hash` 为粗粒度键，忽略变量声明名、标识符读、import 本地名与
+//! 函数参数等大部分绑定名；`compiled_module_hash` 为精确键，额外纳入全部绑定名。
+//! 函数声明名、类名与 catch 参数标识名是编译产物物化名，两种粒度下恒计入哈希；
+//! catch 参数为解构形态时不贡献哈希。
 
 use oxide_parser::{
     ArrayExpressionElement, BindingPattern, ChainElement, Class, ClassElement, Declaration,
@@ -11,6 +13,8 @@ use oxide_parser::{
 };
 use std::hash::Hash;
 
+/// 哈希域标识：各语法域占用独立哈希空间，避免跨类型同形节点
+/// （如语句与表达式字段结构相同）发生碰撞。
 #[derive(Hash)]
 enum HashDomain {
     Statement,
@@ -21,6 +25,8 @@ enum HashDomain {
     SimpleAssignmentTarget,
 }
 
+/// 结构哈希统一入口：先哈希域标识、再哈希变体判别符，最后分派到臂内载荷，
+/// 保证跨域同形节点不碰撞。
 macro_rules! hash_match {
     ($domain:expr, $value:expr, $h:expr, { $($arms:tt)* }) => {{
         $domain.hash($h);
@@ -37,12 +43,15 @@ mod property;
 mod statement;
 mod target;
 
-/// 结构哈希：忽略绑定名的 `Program` 哈希（用于粗粒度缓存命中判断）。
+/// 粗粒度结构哈希：忽略变量声明名、标识符读、import 本地名与函数参数等大部分
+/// 绑定名，仅保留编译产物依赖的函数声明名、类名与 catch 参数标识名，
+/// 用于结构相等即命中的缓存判断。
 pub fn structural_hash(program: &oxide_parser::Program) -> u64 {
     hash_program(program, false)
 }
 
-/// 编译模块哈希：纳入绑定名的 `Program` 哈希（用于精确缓存命中判断）。
+/// 精确编译模块哈希：在粗粒度键基础上额外纳入全部绑定名，
+/// 避免绑定名不同但结构相同的程序错误复用缓存。
 pub fn compiled_module_hash(program: &oxide_parser::Program) -> u64 {
     hash_program(program, true)
 }
@@ -65,6 +74,9 @@ fn hash_program(program: &oxide_parser::Program, include_binding_names: bool) ->
     h.finish()
 }
 
+/// 哈希 `BindingIdentifier` 的绑定名；只由 `include_binding_names` 为真的调用点
+/// 使用（变量声明、函数与箭头参数、方法参数、catch 参数），非标识符模式
+/// （数组/对象解构）不贡献哈希。
 fn hash_binding_pattern(pattern: &BindingPattern, h: &mut rustc_hash::FxHasher) {
     if let BindingPattern::BindingIdentifier(ident) = pattern {
         ident.name.as_str().hash(h);

crates/oxide_compiler/src/hash/statement.rs

@@ -196,6 +196,8 @@ fn hash_for_statement(fr: &oxide_parser::ForStatement<'_>, h: &mut rustc_hash::F
 fn hash_function_declaration(fd: &Function<'_>, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {
     fd.r#async.hash(h);
     fd.generator.hash(h);
+    // 函数声明名是编译产物的一部分（提升与声明语义依赖它），两种哈希粒度下
+    // 均计入，不受 `include_binding_names` 控制；两个分支因此同形。
     if include_binding_names {
         if let Some(id) = &fd.id {
             id.name.as_str().hash(h);
@@ -215,6 +217,7 @@ fn hash_function_declaration(fd: &Function<'_>, h: &mut rustc_hash::FxHasher, in
 }
 
 fn hash_class(class: &Class<'_>, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {
+    // 类名与函数声明名同理，是编译产物物化名，两种哈希粒度下恒计入。
     if let Some(id) = &class.id {
         id.name.as_str().hash(h);
     }
@@ -258,6 +261,8 @@ fn hash_try_statement(ts: &oxide_parser::TryStatement<'_>, h: &mut rustc_hash::F
         hash_statement(s, h, include_binding_names);
     }
     if let Some(catch) = &ts.handler {
+        // catch 参数标识名与函数/类名同理，两种哈希粒度下恒计入；解构形态
+        // 不贡献哈希，故两个分支各模式走到同一结论。
         if let Some(param) = &catch.param {
             if include_binding_names {
                 hash_binding_pattern(&param.pattern, h);