fix(runtime): observe class iterator prototype replacements

[proggeramlug]

Class generator iterators exposed a synthetic string key in Object.getOwnPropertyNames, and later Symbol.iterator replacements could be bypassed by the class vtable, direct symbol calls, and for...of new C() lowering. For example, replacing Range.prototype[Symbol.iterator] now changes spread, direct calls, Array.from, and module/function loops consistently.

Keep the computed-symbol registration, whose runtime registration already installs the dispatch alias. Resolve current prototype properties before that alias, preserving subclass shadowing and accessor receivers. Data descriptors also replace old symbol accessors correctly, and presence checks do not invoke getters a second time.

Closes #9788.

Validation on macOS arm64 with the pinned Node 26.5.1:

• Both new regression fixtures pass the canonical parity runner with its default timeout and no skips.
• Existing class sync/async iterator, Class with *[Symbol.iterator]() generator method hangs in for...of (and growing RSS to OOM) #448, for-of / spread over a non-generator class [Symbol.iterator] doesn't iterate #1840, and ToPrimitive fixtures pass (6 additional cases).
• HIR iterator tests: 3 passed. Runtime symbol tests: 11 passed; object tests: 316 passed, single threaded.
• Coherent perry-dev compiler/runtime/stdlib build and Node-version consistency check passed.

No version bump.

Summary by CodeRabbit

• New Features

  • Iterator behavior now respects runtime replacements and overrides of Symbol.iterator across for...of, spread syntax, and Array.from.
  • Prototype accessors are invoked with the correct instance and iterator methods are resolved at loop entry.
  • Explicit undefined iterator replacements now correctly shadow existing methods.

• Bug Fixes

  • Prevented synthetic string properties from appearing during prototype key enumeration.
  • Improved iterator handling across inherited and instance-level overrides.

• Tests

  • Added coverage for iterator mutation, inheritance, accessors, enumeration, and iterator cleanup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: b6c36e31-6436-43ef-bb9b-5308bac29d89

📥 Commits

Reviewing files that changed from the base of the PR and between c7361c8 and 74e32d8.

📒 Files selected for processing (9)

• changelog.d/9788-iterator-prototype-symbols.md
• crates/perry-hir/src/lower/stmt_loops.rs
• crates/perry-hir/src/lower_decl/body_stmt.rs
• crates/perry-hir/src/lower_decl/class_decl.rs
• crates/perry-runtime/src/object/native_call_method.rs
• crates/perry-runtime/src/object/object_ops/define_property.rs
• crates/perry-runtime/src/symbol/get.rs
• test-files/test_gap_9788_iterator_protocol_mutation.ts
• test-files/test_gap_9788_iterator_prototype_overrides.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Class-based iteration now resolves the current Symbol.iterator at runtime. Synthetic iterator wrappers no longer expose "@@iterator" string keys. Runtime lookup handles instance, prototype, accessor, inherited, and undefined replacements with expanded tests.

Changes

Iterator protocol mutation

Layer / File(s)	Summary
Dynamic iterator lowering and symbol-only registration crates/perry-hir/src/lower/stmt_loops.rs, crates/perry-hir/src/lower_decl/body_stmt.rs, crates/perry-hir/src/lower_decl/class_decl.rs	Class-based for...of paths use GetIterator at loop entry. Synthetic iterator wrappers register only as computed symbol members.
Runtime Symbol.iterator resolution crates/perry-runtime/src/object/native_call_method.rs, crates/perry-runtime/src/object/object_ops/define_property.rs, crates/perry-runtime/src/symbol/get.rs	Well-known symbols use property lookup. Prototype overrides, accessors, own properties, and descriptor writes are resolved through the runtime symbol path.
Iterator mutation coverage test-files/test_gap_9788_iterator_protocol_mutation.ts, test-files/test_gap_9788_iterator_prototype_overrides.ts, changelog.d/9788-iterator-prototype-symbols.md	Tests cover iterator replacements, inheritance, accessors, enumeration, non-generator methods, undefined, and IteratorClose. The changelog records the behavior.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 74e32

Class iterator methods now remain symbol-only while current Symbol.iterator replacements are honored by direct calls and iteration. The targeted mutation and protocol coverage supports merge readiness with no outstanding risk.

Sequence Diagram(s)

sequenceDiagram
  participant ForOfLoop
  participant GetIterator
  participant SymbolPropertyLookup
  participant PrototypeOverrideResolver
  participant Iterator
  ForOfLoop->>GetIterator: request iterator for class instance
  GetIterator->>SymbolPropertyLookup: read Symbol.iterator
  SymbolPropertyLookup->>PrototypeOverrideResolver: inspect own and prototype replacements
  PrototypeOverrideResolver-->>SymbolPropertyLookup: return current iterator method
  SymbolPropertyLookup-->>GetIterator: return bound iterator method
  GetIterator->>Iterator: invoke method once at loop entry
  Iterator-->>ForOfLoop: produce iterator values

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: runtime support for class iterator prototype replacements.
Description check	✅ Passed	The description provides a clear summary, links issue #9788, documents the implementation scope, and reports extensive validation. It does not reproduce the template headings and checklist, but the re…
Linked Issues check	✅ Passed	The changes satisfy issue #9788. They remove the synthetic "@@iterator" string key, honor prototype-level Symbol.iterator replacements, preserve instance overrides and subclass shadowing, and add regr…
Out of Scope Changes check	✅ Passed	The implementation changes, changelog entry, and regression tests are directly related to the iterator defects described in issue #9788. No unrelated code changes are evident.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 8 files. (1 skipped: 1 …

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Landed on main via merge train #9817 (rebase-merged, so your commits keep their authorship). Thanks!