fix(array): resolve a Buffer-backed Uint8Array receiver in the fused callback helpers (#8137)

[proggeramlug]

Closes #8137.

Nine fused js_array_* callback/reduce entry points returned garbage values
— not empty, not a throw — when the receiver was a Buffer-backed Uint8Array
and codegen could not statically prove the receiver type.

Root cause

Perry's new Uint8Array([…]) is a BufferHeader (buffer::js_uint8array_new),
not a TypedArrayHeader. It is therefore absent from the typed-array registry,
and the lookup_typed_array_kind re-dispatch each of these helpers performs
never answers for it. There is no Buffer arm, so the helper falls through and
reads the BufferHeader as an ArrayHeader.

BufferHeader and ArrayHeader share the {length: u32, capacity: u32}
prefix. So length reads correctly while the elements — decoded as
NaN-boxed f64 slots at base + 8 + i*8 over a payload that is one byte per
element — are raw bytes reinterpreted, and the read runs length * 7 bytes past
the real payload. Correct length, garbage values. That is why the symptom is not
an empty result, and why any probe that only asks "did we return []?" is blind
to it.

normalize_array_receiver is permissive here (it returns the raw address for a
registered Buffer rather than null), so this is a standing gap, not the
#8041 funnel-ordering regression that #8090 / #8109 / #8119 / #8130 / #8140 have
been closing. The receiver-kind question is nevertheless asked above the
funnel, because the sibling funnel clean_arr_ptr does return NULL for the same
receiver and every caller reads that as "empty" — keeping the question above
means the ordering cannot rot back.

The design call

The issue laid out three options. This takes (c): delegate to
dispatch_uint8_buffer_method, the shared uint8 %TypedArray%.prototype
dispatcher a statically typed receiver already reaches via
dispatch_buffer_method's catch-all.

It is the only option that keeps callback-argument identity. These nine pass the
receiver to the callback as the 3rd/4th argument, and the dispatcher passes the
original Buffer. Option (b)'s alternative —
buffer_receiver_as_uint8_typed_array — hands back a copy, so

u.forEach((v, i, arr) => { arr[0] = 9 });   // node mutates u

would silently lose the write. That is not hypothetical: it is pinned by a test
that fails when the implementation is swapped to a copy (sabotage E below).

Delegating also closes the statically-typed holes for free, exactly as the issue
predicted:

• reduceRight was wrong even for const u = new Uint8Array([3,1,2]),
  because codegen folds that call straight to js_array_reduce_right rather
  than routing it through dispatch_buffer_method. Measured
  z|6.36e-314|5.09e-313|6.49e-319 against node's z|2|1|3.
• findLast had no arm in the uint8 dispatcher at all, so it threw
  TypeError: (Buffer).findLast is not a function on both paths. Its
  sibling findLastIndex was already served, which is why the hole survived —
  the two are always cited together. One arm added.

What is fixed

Measured with { u: new Uint8Array([3, 1, 2]) } against node v26.5.1
(.node-version), --profile perry-dev, pinned PERRY_RUNTIME_DIR,
PERRY_NO_AUTO_OPTIMIZE=1:

entry point	node	before	after
js_array_map	[6,2,4]	[1.297723e-318,0,0]	[6,2,4]
js_array_filter	[3,2]	[]	[3,2]
js_array_find	1	undefined	1
js_array_findIndex	1	-1	1
js_array_some	true	false	true
js_array_every	true	false	true
js_array_reduce	6	6.4886e-319	6
js_array_reduce_right	z|2|1|3	z|0|0|6.4886e-319	z|2|1|3
js_array_forEach	3;1;2;	6.4886e-319;0;0;	3;1;2;

Two more of the same defect, found by the sweep and fixed here:

entry point	node	before	after
js_array_map_discard (.map() result unused)	3;1;2;	6.4886e-319;0;0;	3;1;2;
findLast (both dispatch paths)	2	TypeError	2

reduce/reduceRight are covered with and without a seed: an absent
initial value must stay absent through the delegation, because the dispatcher
keys on args.len() >= 2 and forwarding initial unconditionally would turn
every seedless reduce into a seeded one — and the empty-receiver TypeError
into a silent undefined.

What is deliberately NOT changed

• flatMap is not a %TypedArray%.prototype method (node throws). The gate
  answers None for it, so the caller keeps today's behaviour. Pinned by a test.
• ArrayBuffer / SharedArrayBuffer / DataView are declined by
  is_typed_array_buffer — the same gate dispatch_buffer_method's catch-all
  uses, so the two receiver populations cannot drift apart. Perry answers
  ab.map(cb) => [0,0,0,0] where node throws TypeError; that divergence is
  pre-existing and byte-identical before and after this change, and is a
  separate issue. Serving them here would have invented iteration node does
  not have.
• js_array_find_last / js_array_find_last_index (the generic helpers)
  are not gated. Measured: a Buffer receiver never reaches them — findLastIndex
  already answers correctly through the dynamic tower, and findLast was the
  missing dispatcher arm, not a missing helper gate. A guard there would be
  untestable.

Cost on the ordinary path

buffer_receiver_dispatch opens with
typedarray::arena_payload_has_gc_type(addr, GC_TYPE_ARRAY): a receiver that is
provably an arena-backed GC_TYPE_ARRAY cannot be a registered Buffer, so
[1,2,3].map(…) reaches neither registry.

That predicate rather than a bare header-byte read is deliberate, and it is the
correction #8142 wrote into array_receiver_gc_tag's doc: a Buffer comes in
both backings, and an external one (EXTERNAL_BUFFER_REGISTRY,
shared_sab::alloc_shared_sab) has no GcHeader at all — the eight bytes below
its payload are allocator bookkeeping that can read as any obj_type,
GC_TYPE_ARRAY included. A bare tag read would skip the probe for exactly the
receiver this function exists to catch, silently and only sometimes.
arena_payload_has_gc_type range-checks, rejects HeapSpace::Unknown for the
header address, and validates through gc_type_info first; it answers false
for an external buffer, which then falls through to the registry — the
authoritative answer.

The gate is asserted, not assumed: a_plain_array_never_reaches_the_buffer_gate
measures a #[cfg(test)] probe counter on is_typed_array_buffer and fails if
the fast path is deleted, even though every answer stays correct.

Testing — and the vacuity this family invites

18 tests in array/typed_array_receiver_tests.rs. Every one asserts the
observed element values, never a predicate. The issue names the trap
explicitly, and it has already been shipped here once:
u.every(x => x > 0) answers true under node and under the bug, because
1.297723e-318 > 0. The callbacks record what they actually saw, so a garbage
read fails the assertion whatever the predicate says.

Sabotage results — each mutation applied, tests re-run, then reverted:

sabotage	expected to fail	result
A buffer_receiver_dispatch always returns None (pre-fix)	the 12 subject tests	12/12 FAILED, 4 controls correctly passed
B delete the arena_payload_has_gc_type gate	a_plain_array_never_reaches_the_buffer_gate	FAILED
C remove the findLast arm	find_last_is_served_for_a_buffer_receiver	FAILED
D over-reach: accept every registered buffer	an_array_buffer_or_data_view_receiver_is_not_given_element_semantics	FAILED (aborts)
E delegate through a COPY (option (b)'s shape)	the_callbacks_third_argument_is_the_receiver_itself_not_a_copy	FAILED — values stayed correct, identity did not

Sabotage A caught a vacuous test of my own: the 3rd-argument test passed
under it, because the pre-fix helper already passed the raw buffer as the 3rd
argument while reading garbage elements. It now carries an element assertion
too, so it fails under A as well as E; its comment says which mutation each
assertion is there for.

Controls that fail on over-reach: a plain array and a generic array-like object
(Array.prototype.map.call({length: 3, 0: 3, …})) must still work through the
same helpers, and Int32Array (a real registry typed array) is checked
end-to-end.

Verification

• cargo test -p perry-runtime --lib — 2436 passed, 0 failed, 4 ignored
  (2418 on main + 18 new).
• Byte-compared against node v26.5.1 for all 36 probe cases; the only
  remaining diff is the pre-existing ArrayBuffer/DataView one described above,
  identical before and after.
• Runtime-only change — no codegen touched, so cargo test -p perry-codegen is
  not implicated.
• All lint-job gates generated from .github/workflows/test.yml (32 commands)
  plus scripts/check_gc_env_knobs.py: all pass.

Summary by CodeRabbit

• Bug Fixes
  • Fixed incorrect or corrupted values when using array iteration and reduction methods on Buffer-backed Uint8Array data.
  • Corrected callback behavior, including receiver identity, indices, mutations, and reductions with or without an initial value.
  • Added reliable support for findLast on Buffer-backed Uint8Array data.
  • Preserved existing behavior for ordinary arrays, generic array-like objects, ArrayBuffer, DataView, and unsupported cases.

[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: d867ec0c-acde-41be-9018-e2e2dd6b94cf

📥 Commits

Reviewing files that changed from the base of the PR and between 499e296 and ed75577.

📒 Files selected for processing (9)

• changelog.d/8173-buffer-receiver-fused-array-callbacks.md
• crates/perry-runtime/src/array/buffer_receiver.rs
• crates/perry-runtime/src/array/iter_methods.rs
• crates/perry-runtime/src/array/mod.rs
• crates/perry-runtime/src/array/reduce_right.rs
• crates/perry-runtime/src/array/typed_array_receiver_tests.rs
• crates/perry-runtime/src/object/mod.rs
• crates/perry-runtime/src/object/typed_array_proto_thunks.rs
• crates/perry-runtime/src/typedarray/mod.rs

---

📝 Walkthrough

Walkthrough

Changes

Buffer-backed Uint8Array receivers now use dedicated dispatch for nine fused array callback and reduction entry points. The dispatch preserves the original Buffer for callbacks, supports findLast and reduceRight, excludes unsupported receiver types, and adds regression coverage.

Buffer-backed Uint8Array callbacks

Layer / File(s)	Summary
Uint8 buffer dispatch bridge crates/perry-runtime/src/array/buffer_receiver.rs, crates/perry-runtime/src/object/typed_array_proto_thunks.rs, crates/perry-runtime/src/array/mod.rs, crates/perry-runtime/src/object/mod.rs, crates/perry-runtime/src/typedarray/mod.rs	The runtime validates Buffer-backed receivers, roots callback values and receivers, delegates to the Uint8 dispatcher, converts results, and adds reverse findLast traversal.
Array method integration crates/perry-runtime/src/array/iter_methods.rs, crates/perry-runtime/src/array/reduce_right.rs	The callback and reduction entry points dispatch Buffer-backed Uint8Array receivers before generic normalization. They preserve return types and initial-value handling.
Regression coverage and changelog crates/perry-runtime/src/array/typed_array_receiver_tests.rs, changelog.d/8173-buffer-receiver-fused-array-callbacks.md	Tests verify byte values, indices, receiver identity, mutation, reductions, reverse traversal, dispatch gating, and fallback behavior for other receiver types and methods.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to ed755

The PR corrects Buffer-backed Uint8Array callback behavior while preserving existing behavior for other receiver types, with the described tests and checks passing. No actionable merge-blocking risk remains beyond normal review.

Sequence Diagram(s)

sequenceDiagram
  participant ArrayMethod
  participant BufferReceiver
  participant Uint8Dispatcher
  participant Callback
  ArrayMethod->>BufferReceiver: dispatch Buffer-backed Uint8Array method
  BufferReceiver->>Uint8Dispatcher: pass callback and original Buffer
  Uint8Dispatcher->>Callback: invoke with byte value and index
  Callback-->>Uint8Dispatcher: return callback result
  Uint8Dispatcher-->>ArrayMethod: return converted method result

Loading

Possibly related PRs

• PerryTS/perry#8119: Both PRs modify typed-array and Buffer receiver dispatch and shared receiver tests.
• PerryTS/perry#8090: Both PRs add early typed-array or Buffer receiver detection in array methods.
• PerryTS/perry#8130: Both PRs modify fused array forEach receiver dispatch for different receiver types.

Suggested labels: bug

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the Buffer-backed Uint8Array receiver fix in the fused callback helpers.
Description check	✅ Passed	The description thoroughly explains the problem, implementation, scope, linked issue, tests, verification, and preserved behavior.
Linked Issues check	✅ Passed	The changes satisfy issue #8137 by fixing the affected helpers, preserving receiver identity, adding findLast support, and adding comprehensive regression tests.
Out of Scope Changes check	✅ Passed	All changes support the linked issue objectives, including dispatcher visibility, findLast handling, receiver gating, and focused regression tests.
Docstring Coverage	✅ Passed	Docstring coverage is 85.37% which is sufficient. The required threshold is 80.00%.

✨ 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/8137-fused-array-buffer-receiver

---

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.}