feat: Iterator helpers 基建——Symbol.dispose 注册与 %IteratorHelperPrototype%

crates/oxide_vm/src/bindings/bind_iterator.rs

@@ -6,7 +6,8 @@ use oxide_types::object::JsObject;
 use oxide_types::value::JsValue;
 
 use crate::bindings::{
-    apply_binding_table, bind_global_value, bind_iterator_function_prototype, configure_native_constructor,
+    apply_binding_table, bind_global_value, bind_iterator_ctor_identity, bind_iterator_function_prototype,
+    configure_native_constructor,
 };
 
 /// 绑定 `Iterator` 全局构造器（`prototype` = %IteratorPrototype%、`from` 方法）。
@@ -23,6 +24,7 @@ pub fn bind_iterator(core: &Arc<KernelCore>, session: &KernelSession, global: &m
         oxide_builtins::iterator::iterator_constructor::<crate::vm::Vm> as *const (),
         0,
     );
+    bind_iterator_ctor_identity(core, &mut iterator);
     bind_iterator_function_prototype(core, session, &mut iterator);
 
     apply_binding_table(

crates/oxide_vm/src/bindings/bind_symbol.rs

@@ -90,6 +90,14 @@ pub fn bind_symbol(core: &Arc<KernelCore>, session: &KernelSession, global: &mut
             "species",
             JsValue::from_js_object(session.builtin_world().sym_species.as_ptr() as *mut JsObject),
         ),
+        (
+            "asyncDispose",
+            JsValue::from_js_object(session.builtin_world().sym_async_dispose.as_ptr() as *mut JsObject),
+        ),
+        (
+            "dispose",
+            JsValue::from_js_object(session.builtin_world().sym_dispose.as_ptr() as *mut JsObject),
+        ),
     ] {
         bind_well_known_symbol(core, ctor, name, val);
     }

crates/oxide_vm/src/bindings/mod.rs

@@ -165,6 +165,98 @@ pub(crate) fn bind_accessor_getter(
     proto.bump_generation();
 }
 
+/// 在原型上绑定一个原生访问器属性（getter + setter 成对），键可为字符串 intern 键
+/// 或 well-known symbol 键（shape 键直接传入，不要求字符串 intern）。
+///
+/// # 步骤
+/// 1. 构造 getter 函数对象（name = `getter_name`，length 0）与 setter 函数对象
+///    （name = `setter_name`，length 1）。
+/// 2. 为键开 shape 槽位并写入访问器 meta（enumerable=false, configurable=true）。
+///
+/// # 注意事项
+/// getter/setter 函数对象经 `Box::into_raw` 持有，与 `bind_accessor_getter` 的
+/// 方法 wrapper 同一生命周期约定（内置对象在 session 生命周期内不被回收）。
+#[expect(clippy::too_many_arguments)]
+pub(crate) fn bind_accessor_getset(
+    core: &Arc<KernelCore>, session: &KernelSession, proto: &mut JsObject, key: u32, getter_name: &str,
+    setter_name: &str, getter_fn: *const (), setter_fn: *const (),
+) {
+    let shape_forge = core.shape_forge().as_ref();
+    let string_forge = core.perm_interner().as_ref();
+    let fn_proto_val = JsValue::from_js_object(session.builtin_world().function_proto.as_ptr() as *mut JsObject);
+
+    let mut getter = Box::new(JsObject::new_empty(EMPTY_SHAPE_ID, fn_proto_val));
+    getter.set_function(true);
+    // SAFETY: getter_fn 是转成 *const () 的 NativeFn 函数项指针。
+    getter.set_native_fn(Some(unsafe { oxide_types::object::NativeFnPtr::from_raw(getter_fn) }));
+    getter.set_native_arg_count(0);
+    // 给函数对象开 name/length 槽位（描述符均 { writable:false, enumerable:false, configurable:true }）。
+    let si_name = string_forge.intern("name").0;
+    let name_shape = shape_forge.make_shape(getter.shape_id(), si_name);
+    getter.set_shape_id(name_shape);
+    getter
+        .ensure_hash_props()
+        .push(JsValue::perm_string(string_forge.string_ptr(string_forge.intern(getter_name).0)));
+    let name_pos = getter.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    getter.set_data_meta(name_pos, PropAttributes::new(false, false, true));
+    let si_length = string_forge.intern("length").0;
+    let length_shape = shape_forge.make_shape(getter.shape_id(), si_length);
+    getter.set_shape_id(length_shape);
+    getter.ensure_hash_props().push(JsValue::int(0));
+    let length_pos = getter.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    getter.set_data_meta(length_pos, PropAttributes::new(false, false, true));
+    let getter_val = JsValue::from_js_object(Box::into_raw(getter));
+
+    let mut setter = Box::new(JsObject::new_empty(EMPTY_SHAPE_ID, fn_proto_val));
+    setter.set_function(true);
+    // SAFETY: setter_fn 是转成 *const () 的 NativeFn 函数项指针。
+    setter.set_native_fn(Some(unsafe { oxide_types::object::NativeFnPtr::from_raw(setter_fn) }));
+    setter.set_native_arg_count(1);
+    let name_shape = shape_forge.make_shape(setter.shape_id(), si_name);
+    setter.set_shape_id(name_shape);
+    setter
+        .ensure_hash_props()
+        .push(JsValue::perm_string(string_forge.string_ptr(string_forge.intern(setter_name).0)));
+    let name_pos = setter.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    setter.set_data_meta(name_pos, PropAttributes::new(false, false, true));
+    let length_shape = shape_forge.make_shape(setter.shape_id(), si_length);
+    setter.set_shape_id(length_shape);
+    setter.ensure_hash_props().push(JsValue::int(1));
+    let length_pos = setter.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    setter.set_data_meta(length_pos, PropAttributes::new(false, false, true));
+    let setter_val = JsValue::from_js_object(Box::into_raw(setter));
+
+    // 访问器属性槽：enumerable=false、configurable=true（get/set 函数对象已持有）。
+    let new_shape = shape_forge.make_shape(proto.shape_id(), key);
+    proto.set_shape_id(new_shape);
+    let pos = proto.push_prop(JsValue::undefined());
+    proto.set_accessor_meta(pos, getter_val, setter_val, PropAttributes::new(true, false, true));
+    proto.bump_generation();
+}
+
+/// 为 `Iterator` 构造器绑定 `length`=0 与 `name`="Iterator" 属性（规范描述符均
+/// { writable:false, enumerable:false, configurable:true }）。
+///
+/// `bind_iterator`（初始化路径）与 `bind_iterator_global`（dirty reset 路径）共用，
+/// 防两处漂移导致 dirty reset 后 `Iterator.length`/`Iterator.name` 消失。
+pub(crate) fn bind_iterator_ctor_identity(core: &Arc<KernelCore>, ctor: &mut JsObject) {
+    let shape_forge = core.shape_forge().as_ref();
+    let string_forge = core.perm_interner().as_ref();
+    let si_length = string_forge.intern("length").0;
+    let length_shape = shape_forge.make_shape(ctor.shape_id(), si_length);
+    ctor.set_shape_id(length_shape);
+    ctor.ensure_hash_props().push(JsValue::int(0));
+    let length_pos = ctor.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    ctor.set_data_meta(length_pos, PropAttributes::new(false, false, true));
+    let si_name = string_forge.intern("name").0;
+    let name_shape = shape_forge.make_shape(ctor.shape_id(), si_name);
+    ctor.set_shape_id(name_shape);
+    ctor.ensure_hash_props()
+        .push(JsValue::perm_string(string_forge.string_ptr(string_forge.intern("Iterator").0)));
+    let name_pos = ctor.hash_props_vec().map_or(0, |v| v.len() as u32).saturating_sub(1);
+    ctor.set_data_meta(name_pos, PropAttributes::new(false, false, true));
+}
+
 /// 把原型上 `source` 属性已绑定的函数值复制到 `alias` 名下（共享同一函数对象）。
 ///
 /// 用于规范要求的方法别名（如 Set 的 `keys`/`@@iterator` 与 `values` 同一函数对象）。
@@ -294,6 +386,58 @@ fn bind_iterator_protos(core: &Arc<KernelCore>, session: &KernelSession) {
         );
     }
 
+    // %IteratorPrototype% 的 constructor / @@toStringTag 访问器：getter 动态读
+    // global（dirty reset 后 global 重建，不能缓存指针），setter 实现
+    // SetterThatIgnoresPrototypeProperties（home 赋值抛 TypeError）。
+    let si_constructor = core.perm_interner().intern("constructor").0;
+    if core
+        .shape_forge()
+        .lookup_position(iter_proto.shape_id(), si_constructor)
+        .is_none()
+    {
+        bind_accessor_getset(
+            core,
+            session,
+            iter_proto,
+            si_constructor,
+            "get constructor",
+            "set constructor",
+            oxide_builtins::iterator::iterator_constructor_getter::<crate::vm::Vm> as *const (),
+            oxide_builtins::iterator::iterator_constructor_setter::<crate::vm::Vm> as *const (),
+        );
+    }
+    let sym_to_string_tag = oxide_types::private_key::make_well_known_symbol_key(9);
+    if core
+        .shape_forge()
+        .lookup_position(iter_proto.shape_id(), sym_to_string_tag)
+        .is_none()
+    {
+        bind_accessor_getset(
+            core,
+            session,
+            iter_proto,
+            sym_to_string_tag,
+            "get [Symbol.toStringTag]",
+            "set [Symbol.toStringTag]",
+            oxide_builtins::iterator::iterator_to_string_tag_getter::<crate::vm::Vm> as *const (),
+            oxide_builtins::iterator::iterator_to_string_tag_setter::<crate::vm::Vm> as *const (),
+        );
+    }
+
+    // %IteratorPrototype% 的 @@dispose：显式资源管理下用 return 关闭迭代器。
+    let sym_dispose = oxide_types::private_key::make_well_known_symbol_key(12);
+    if core.shape_forge().lookup_position(iter_proto.shape_id(), sym_dispose).is_none() {
+        bind_well_known_method(
+            world,
+            core,
+            iter_proto,
+            12,
+            "[Symbol.dispose]",
+            oxide_builtins::iterator::iterator_dispose::<crate::vm::Vm> as *const (),
+            0,
+        );
+    }
+
     // %ArrayIteratorPrototype% 服务 Array/TA 两族；Map/Set 共用按 `__mode__`
     // 分发的实现；%RegExpStringIteratorPrototype% 供 matchAll。
     bind_iterator_proto_next(
@@ -488,6 +632,7 @@ fn bind_iterator_global(core: &Arc<KernelCore>, session: &KernelSession, global:
         oxide_builtins::iterator::iterator_constructor::<crate::vm::Vm> as *const (),
         0,
     );
+    bind_iterator_ctor_identity(core, &mut iterator);
     bind_iterator_function_prototype(core, session, &mut iterator);
     apply_binding_table(
         session.builtin_world(),

crates/oxide_vm/tests/builtins_iterator_tests.rs

@@ -1,4 +1,5 @@
 use oxide_compiler::compiler::Compiler;
+use oxide_types::object::JsObject;
 use oxide_types::value::JsValue;
 use oxide_vm::vm::Vm;
 
@@ -289,3 +290,263 @@ fn iterator_proto_next_consumption_unchanged() {
     let done = eval(&mut vm, "var it = new Uint8Array([1]).values(); it.next(); it.next().done").unwrap();
     assert!(done.as_bool());
 }
+
+#[test]
+fn iterator_function_name_length() {
+    let mut vm = Vm::new();
+    let bool_cases = [
+        ("Iterator.name === 'Iterator'", true),
+        ("Iterator.length === 0", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'name').writable === false", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'name').enumerable === false", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'name').configurable === true", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'length').writable === false", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'length').enumerable === false", true),
+        ("Object.getOwnPropertyDescriptor(Iterator, 'length').configurable === true", true),
+    ];
+    for (src, expected) in bool_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+}
+
+#[test]
+fn iterator_prototype_constructor_accessor() {
+    let mut vm = Vm::new();
+    let bool_cases = [
+        // getter 动态读 global 上的 Iterator 构造器。
+        ("Iterator.prototype.constructor === Iterator", true),
+        (
+            "typeof Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor').get === 'function'",
+            true,
+        ),
+        (
+            "typeof Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor').set === 'function'",
+            true,
+        ),
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor').enumerable === false",
+            true,
+        ),
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor').configurable === true",
+            true,
+        ),
+        // getter 无参调用（this=undefined）仍返回 Iterator。
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor').get.call() === Iterator",
+            true,
+        ),
+    ];
+    for (src, expected) in bool_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+}
+
+#[test]
+fn iterator_prototype_constructor_setter_semantics() {
+    let mut vm = Vm::new();
+    // home 对象赋值与原始值 this 抛 TypeError（SetterThatIgnoresPrototypeProperties）。
+    let throws = [
+        (
+            "try { Iterator.prototype.constructor = 'x'; false } catch (e) { e instanceof TypeError }",
+            true,
+        ),
+        (
+            "try { var d = Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor'); \
+             d.set.call(undefined, 'x'); false } catch (e) { e instanceof TypeError }",
+            true,
+        ),
+        (
+            "try { var d = Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor'); \
+             d.set.call(null, 'x'); false } catch (e) { e instanceof TypeError }",
+            true,
+        ),
+        (
+            "try { var d = Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor'); \
+             d.set.call(true, 'x'); false } catch (e) { e instanceof TypeError }",
+            true,
+        ),
+    ];
+    for (src, expected) in throws {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+    // 非 home 对象：无 own 属性建 own，有 own 属性走 Set 覆盖。
+    let ok_cases = [
+        (
+            "var o = {}; var d = Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor'); \
+             d.set.call(o, 42); o.constructor === 42 && o.hasOwnProperty('constructor')",
+            true,
+        ),
+        (
+            "var o = { constructor: 1 }; var d = Object.getOwnPropertyDescriptor(Iterator.prototype, 'constructor'); \
+             d.set.call(o, 2); o.constructor === 2",
+            true,
+        ),
+        // home 不受污染。
+        ("Iterator.prototype.constructor === Iterator", true),
+    ];
+    for (src, expected) in ok_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+}
+
+#[test]
+fn iterator_prototype_to_string_tag_accessor() {
+    let mut vm = Vm::new();
+    let bool_cases = [
+        ("Iterator.prototype[Symbol.toStringTag] === 'Iterator'", true),
+        (
+            "typeof Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag).get === 'function'",
+            true,
+        ),
+        (
+            "typeof Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag).set === 'function'",
+            true,
+        ),
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag).enumerable === false",
+            true,
+        ),
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag).configurable === true",
+            true,
+        ),
+        (
+            "Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag).get.call() === 'Iterator'",
+            true,
+        ),
+        // home 赋值抛 TypeError。
+        (
+            "try { Iterator.prototype[Symbol.toStringTag] = 'x'; false } catch (e) { e instanceof TypeError }",
+            true,
+        ),
+        // 普通对象 setter 建 own Symbol.toStringTag。
+        (
+            "var o = {}; var d = Object.getOwnPropertyDescriptor(Iterator.prototype, Symbol.toStringTag); \
+             d.set.call(o, 'tag'); o[Symbol.toStringTag] === 'tag'",
+            true,
+        ),
+        // 原型继承场景：非 home 子对象赋值落到自身 own 属性（不污染祖先）。
+        (
+            "var p = Object.create(Iterator.prototype); p[Symbol.toStringTag] = 'sub'; \
+             p[Symbol.toStringTag] === 'sub' && Iterator.prototype[Symbol.toStringTag] === 'Iterator'",
+            true,
+        ),
+    ];
+    for (src, expected) in bool_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+}
+
+#[test]
+fn symbol_dispose_and_async_dispose_registered() {
+    let mut vm = Vm::new();
+    // well-known symbol 以空对象表示，typeof 为 object；两符号互不相同。
+    let bool_cases = [
+        ("typeof Symbol.dispose === 'object'", true),
+        ("typeof Symbol.asyncDispose === 'object'", true),
+        ("Symbol.dispose !== Symbol.asyncDispose", true),
+        ("Symbol.dispose !== Symbol.iterator", true),
+        // 键可作属性名使用（well-known 键映射一致）。
+        ("({ [Symbol.dispose]: 1 })[Symbol.dispose] === 1", true),
+        // getOwnPropertySymbols 能反解出同一符号对象。
+        ("Object.getOwnPropertySymbols({ [Symbol.dispose]: 1 })[0] === Symbol.dispose", true),
+    ];
+    for (src, expected) in bool_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+    // 描述性名称经 String 构造器反射（well_known_symbol_name 表）。
+    let desc = eval(&mut vm, "String(Symbol.dispose)").unwrap();
+    assert_eq!(to_str(&vm, desc), "Symbol(Symbol.dispose)");
+}
+
+#[test]
+fn iterator_prototype_symbol_dispose() {
+    let mut vm = Vm::new();
+    // @@dispose 调用 this 的 return 方法并返回 undefined。
+    let bool_cases = [
+        ("typeof Iterator.prototype[Symbol.dispose] === 'function'", true),
+        ("Iterator.prototype[Symbol.dispose].length === 0", true),
+        ("Iterator.prototype[Symbol.dispose].name === '[Symbol.dispose]'", true),
+        (
+            "var called = false; var it = { return: function() { called = true; return { done: true }; } }; \
+             var r = Iterator.prototype[Symbol.dispose].call(it); r === undefined && called === true",
+            true,
+        ),
+        // 无 return 方法：GetMethod 返回 undefined，跳过调用。
+        ("Iterator.prototype[Symbol.dispose].call({ next: function() {} }) === undefined", true),
+        // return 返回任意值不影响 @@dispose 的 undefined 返回值。
+        (
+            "var it = { return: function() { return 42; } }; \
+             Iterator.prototype[Symbol.dispose].call(it) === undefined",
+            true,
+        ),
+    ];
+    for (src, expected) in bool_cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+    // return 抛错经 @@dispose 透传（原值，不二次包装）。
+    let thrown = eval(
+        &mut vm,
+        "try { var it = { return: function() { throw new RangeError('boom'); } }; \
+         Iterator.prototype[Symbol.dispose].call(it); false } catch (e) { e instanceof RangeError }",
+    )
+    .unwrap();
+    assert!(thrown.as_bool());
+}
+
+#[test]
+fn iterator_helper_prototype_links_to_iterator_proto() {
+    let vm = Vm::new();
+    // %IteratorHelperPrototype% 已建且链到 %IteratorPrototype%（链：
+    // helper → %IteratorPrototype% → Object.prototype）。
+    let helper_ptr = vm.session().builtin_world().iterator_helper_proto.as_ptr() as *mut JsObject;
+    let helper_proto_val = unsafe { &*helper_ptr }.proto();
+    let iter_ptr = vm.session().builtin_world().iterator_proto.as_ptr() as *mut JsObject;
+    assert!(helper_proto_val.is_object());
+    assert!(std::ptr::eq(helper_proto_val.as_js_object_ptr(), iter_ptr));
+}
+
+#[test]
+fn iterator_prototype_rebound_after_full_reset() {
+    let mut vm = Vm::new();
+    // 用户改写 %IteratorPrototype%：object 家族世代递增（global 未动）。
+    let old_iter_proto = vm.session().builtin_world().iterator_proto.as_ptr();
+    unsafe { &mut *(old_iter_proto as *mut JsObject) }.bump_generation();
+
+    vm.full_reset();
+
+    // %IteratorPrototype% 重建后访问器 / @@dispose 重绑正确，构造器 identity 保留。
+    let cases = [
+        ("Iterator.prototype.constructor === Iterator", true),
+        ("Iterator.prototype[Symbol.toStringTag] === 'Iterator'", true),
+        ("typeof Iterator.prototype[Symbol.dispose] === 'function'", true),
+        ("Iterator.name === 'Iterator'", true),
+        ("Iterator.length === 0", true),
+        ("typeof Symbol.dispose === 'object'", true),
+        ("typeof Symbol.asyncDispose === 'object'", true),
+    ];
+    for (src, expected) in cases {
+        let result = eval(&mut vm, src).unwrap();
+        assert_eq!(result.as_bool(), expected, "for {}", src);
+    }
+    // helper 原型随 object 家族重建并链到新 %IteratorPrototype%。
+    let helper_ptr = vm.session().builtin_world().iterator_helper_proto.as_ptr() as *mut JsObject;
+    let helper_proto_val = unsafe { &*helper_ptr }.proto();
+    let new_iter_ptr = vm.session().builtin_world().iterator_proto.as_ptr() as *mut JsObject;
+    assert!(std::ptr::eq(helper_proto_val.as_js_object_ptr(), new_iter_ptr));
+    // 迭代器家族整体功能完好。
+    let r = eval(
+        &mut vm,
+        "Iterator.prototype[Symbol.dispose].call({return: function(){return {done:true}}})",
+    )
+    .unwrap();
+    assert!(r.is_undefined());
+}