fix(runtime): js_get_iterator must reject a handle-band near-null pointer as non-iterable

[proggeramlug]

Problem

for…of (and other iteration) over a pointer-tagged value whose payload is a small handle-band address (e.g. POINTER_TAG | 1 → a "pointer" to address 1) did not throw. js_get_iterator read [Symbol.iterator] off the near-null address, found nothing, and returned the bogus value as its own iterator; .next() then yielded undefined, producing a misleading, far-removed TypeError: Iterator result is not an object instead of a correct "is not iterable" at the point of iteration.

js_get_iterator(undefined) already throws correctly; the gap was specifically the non-dereferenceable handle-band pointer.

Fix

In js_get_iterator (after the primitive check, before the [Symbol.iterator] lookup), reject a pointer-tagged value whose raw address is in the handle band (addr_class::is_handle_band) with the normal "is not iterable" TypeError. This stops the runtime manufacturing an iterator from a near-null pointer and surfaces the error at the correct location.

Verification

cargo test -p perry-runtime --lib: 1072 passed. Found while driving a large bundle whose deep config path produced such a value through an upstream binding-wiring defect; with this guard the iteration throws cleanly at the right place instead of much later. (No isolated TS repro: the trigger is an internal mis-tagged value, not something source code can directly construct; the guard is defensive and spec-aligned regardless.)

Summary by CodeRabbit

• Bug Fixes
  • Improved runtime iterator handling by adding an early validation to immediately reject certain invalid pointer-tagged inputs that are not truly iterable. This ensures they fail fast with the standard “not iterable” TypeError, avoiding misleading attempts to treat near-null or handle-like values as iterators.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c52e6cdf-a48e-4410-9a24-6c8793769ff0

📥 Commits

Reviewing files that changed from the base of the PR and between 245de5e and b63032c.

📒 Files selected for processing (1)

• crates/perry-runtime/src/symbol.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/perry-runtime/src/symbol.rs

---

📝 Walkthrough

Walkthrough

In js_get_iterator within symbol.rs, an early guard is added that detects pointer-tagged input values whose raw pointer payload falls within the small-handle "handle band." When detected, the function now immediately throws a throw_value_not_iterable TypeError instead of proceeding into the [Symbol.iterator] lookup path.

Changes

Iterator Handle-Band Guard

Layer / File(s)	Summary
Early handle-band check in js_get_iterator crates/perry-runtime/src/symbol.rs	Adds 20 lines of guard logic: when the input value is pointer-tagged and its underlying raw pointer lies in the handle band, throw_value_not_iterable is called immediately, bypassing the normal [Symbol.iterator] resolution path that previously returned the input unchanged as a bogus iterator.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• PerryTS/perry#5543: Adds a parallel handle-band guard in js_error_get_errors to prevent corrupted handle-band values from being returned when the receiver is not an Error object — the same class of defensive fix applied to a different runtime function.

Poem

🐇 A handle-band pointer crept into my iterator stew,
But now I catch it early and throw it right on through!
No bogus iterators lurking, no corruption in the night,
not iterable TypeError — I set those bad pointers right.
Hoppity-hop, the runtime stays tight! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description covers the problem, fix, and verification, but is missing explicit checkboxes confirmation and doesn't clearly reference which files were changed or include a formal test plan checklist.	Complete the test plan checklist (cargo build, cargo test, etc.) and explicitly confirm all items in the Checklist section to match the template requirements.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a guard in js_get_iterator to reject handle-band near-null pointers as non-iterable, which aligns with the summary and description.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/iterator-reject-near-null

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/perry-runtime/src/symbol.rs`:
- Around line 2263-2267: The guard that checks is_handle_band(raw) and calls
throw_value_not_iterable() is incorrectly blocking iteration dispatch for
handle-backed iterable values like fetch Headers. Remove the entire if statement
that checks is_handle_band(raw) and calls throw_value_not_iterable(), allowing
the code to continue to the iterator resolver path. This will permit
Symbol.iterator dispatch to work correctly for small handles as intended by the
code at lines 1724-1730.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 711406a6-0113-4fd4-9ef9-b072086d9970

📥 Commits

Reviewing files that changed from the base of the PR and between f392dba and 245de5e.

📒 Files selected for processing (1)

• crates/perry-runtime/src/symbol.rs