Parity-to-95% roadmap: remaining clusters mapped (TypedArray branded methods = top lever)

[proggeramlug]

Parity-to-95% roadmap (data-driven, 2026-06-04)

Tracking the path from current parity to the 95% goal, based on uncapped
per-category test262 sweeps. Companion to the scripts/parity_gap_report.py
radar and .gapwork/PARITY_TRACKER.md trend.

Current state

• Sampled (60/cat) raw parity: 66.3%, plateaued (the sample is noise-heavy
  and insensitive to fixes in partially-passing categories).
• Real parity ≈ 73% after excluding ~349 http/net/https link artifacts
  (radar runs without --auto-optimize, mis-bucketing ext-crate APIs) and
  ~84 timeout/(no output) cases.

Cleared this cycle (single-root-cause clusters — DONE)

Array array-like receivers (−457), Set instance brand-check (−77), DataView
prototype (−44), iterator prototypes, BigInt.asIntN/asUintN, ToNumber(object)
valueOf, isPrototypeOf/Reflect coercion, uncurry-this dispatch (#4279).

Remaining work to 95% (uncapped counts, by tractability)

A. Multi-layer "branded prototype method" cluster (~1000+ cases, HIGH value)

• built-ins/TypedArray + TypedArrayConstructors: 962. %TypedArray%.prototype.*
  methods route to the regular Array helpers, so they (a) don't brand-check the
  receiver (Int8Array.prototype.map.call([1,2]) should throw TypeError) and
  (b) miss TA-specific DefineOwnProperty/length-immutability + precision cases.
  Fix shape = give %TypedArray%.prototype real branded methods (like the
  iterator-prototype work). Largest single lever left.

B. Deep runtime semantics (fragmented, MEDIUM value, many small fixes)

• GeneratorPrototype/AsyncGeneratorPrototype (~68): iterator-result
  {value,done} values wrong, yield sequencing, async resumption.
• Promise (~?): async-test-failures (microtask/then ordering).
• Proxy/Reflect (~30 each): remaining trap edges.

C. node-API behavioral (~340, fleet-owned)

• fs/stream/zlib/buffer/child_process: arg-validation throws (stdlib doesn't throw Node arg-validation errors (ERR_INVALID_ARG_TYPE/EBADF/...) on bad input — ~85 tests across fs/buffer/net/http/crypto/zlib/process #2013/Spec-mandated TypeErrors / argument-validation throws (Test262 'no exception was thrown') #3146),
  actively worked by the contributor fleet.

D. Categorical hard-gaps (may STRUCTURALLY cap parity, per CLAUDE.md)

• Lookbehind regex (Rust regex crate limitation), console.dir/group*
  formatting, lone-surrogate / WTF-8 handling. These need library-level work and
  may not all be reachable.

Honest assessment

95% is reachable but requires (A) the TypedArray branded-prototype rewrite, (B)
sustained generator/promise semantics grinding, (C) the fleet finishing node-API,
and (D) resolving or explicitly excepting the categorical gaps. The clean
mechanical wins are exhausted; the curve from here is slower and deeper.

[andrewtdiz]

Opened draft PR #4318 for the TypedArray branded prototype-method cluster:

#4318

This adds an internal receiver brand for noop-backed %TypedArray%.prototype method closures, so extracted calls like Uint16Array.prototype.map.call([1, 2], cb) now throw TypeError instead of redispatching as generic Array helpers. The new parity fixture also keeps Array.prototype.map generic borrowing covered as a control.

Validation passed:

• Node 26 oracle for test-parity/node-suite/globals/typedarray-prototype-method-brand.ts
• direct Perry release run of the same fixture
• ./run_parity_tests.sh --suite node-suite --module globals --filter typedarray-prototype-method-brand
• ./run_parity_tests.sh --suite node-suite --module globals --filter typedarray
• cargo fmt --all --check
• cargo check -p perry-runtime
• cargo build --release -p perry -p perry-runtime -p perry-stdlib
• git diff --check
• ./scripts/check_file_size.sh

[andrewtdiz]

Opened draft PR #4322 to close the dynamic TypedArray callback-result indexing gap.

This routes registered TypedArrays through the per-kind dynamic index accessor/setter instead of falling through to raw ArrayHeader slot reads, so Uint16Array#map(...) and Int8Array#filter(...) results keep correct indexed reads even after static type erasure, and dynamic Uint8ClampedArray writes preserve clamp/coercion behavior.

Validation passed:

• Node 26 oracle for test-parity/node-suite/globals/typedarray-callback-result-indexes.ts
• direct Perry release run of the same fixture
• ./run_parity_tests.sh --suite node-suite --module globals --filter typedarray-callback-result-indexes
• ./run_parity_tests.sh --suite node-suite --module globals --filter typedarray
• cargo fmt --all --check
• cargo check -p perry-runtime
• cargo build --release -p perry -p perry-runtime -p perry-stdlib
• git diff --check
• ./scripts/check_file_size.sh

[andrewtdiz]

I am taking a narrow TypedArray / SharedArrayBuffer constructor slice under this roadmap.

Planned PR cut: align new <TypedArray>(ArrayBuffer|SharedArrayBuffer, byteOffset?) default length derivation with Node, so a missing length argument creates a view over the remaining backing buffer instead of a mis-sized view. The immediate current-main symptom is the Atomics wait/notify fixture needing explicit new Int32Array(sab, 0, 2) to avoid an adjacent constructor gap.

Non-goals: Atomics wait scheduling semantics, the separate Atomics.waitAsync surface, TypedArray prototype-method branding/callback-result indexing already covered by earlier slices, detached/resizable buffers, and broader Test262 TypedArray semantics.

[andrewtdiz]

Continuing the narrow TypedArray / SharedArrayBuffer constructor slice called out above.

Planned PR cut: align new <TypedArray>(ArrayBuffer|SharedArrayBuffer, byteOffset?) default length derivation with Node, so omitting length creates a view over the remaining backing buffer instead of a mis-sized view. I will cover ArrayBuffer and SharedArrayBuffer, explicit-length controls, offset validation, and the Atomics wait/notify shape that currently needs an explicit length workaround.

Non-goals: Atomics scheduling semantics, Atomics.waitAsync, detached/resizable buffers, TypedArray prototype-method behavior, and broader TypedArray constructor validation not needed for this default-length path.

[andrewtdiz]

Opened draft PR: #4409

Scope covered:

• new <TypedArray>(ArrayBuffer|SharedArrayBuffer) for non-Uint8Array typed arrays now routes through the existing buffer-view constructor path when the single argument is ArrayBuffer-like.
• Omitted length derives from the remaining backing bytes and validates byte-length alignment / offset bounds with Node-shaped RangeError behavior.
• Added focused parity coverage in node-suite/globals/typedarray-buffer-default-length.

Validation on the rebased branch (331c6435f):

• Node 26 oracle for typedarray-buffer-default-length.ts
• direct Perry run of the same fixture
• focused parity globals --filter typedarray-buffer-default-length: PASS, report test-parity/reports/parity_report_20260604_150142.json
• broader typedarray globals sweep: 5 pass / 0 fail, report test-parity/reports/parity_report_20260604_145223.json
• adjacent atomics-basic: PASS, report test-parity/reports/parity_report_20260604_145018.json
• cargo check --release -p perry-runtime (existing warnings)
• rustfmt --check, git diff --check, and ./scripts/check_file_size.sh

Scope note: byte-offset aliasing/view identity remains out of scope here. The broader atomics-wait-notify fixture still has a separate Atomics receiver/shared-view behavior tail beyond this constructor-length fix.

[andrewtdiz]

Opened PR #4409 for this: #4409

Implemented the one-argument non-Uint8 TypedArray buffer constructor path so ArrayBuffer/SharedArrayBuffer sources route through the existing view validation/default-length logic. The patch also pointer-tags TypedArrayNew results so runtime consumers like Atomics.wait/Atomics.notify recognize the constructed Int32Array.

Validated with:

• Node oracle and direct Perry output for test-parity/node-suite/globals/typedarray-buffer-default-length.ts
• cargo check -p perry-codegen -p perry-runtime
• cargo build -p perry-runtime -p perry-stdlib -p perry --release
• parity globals --filter typedarray-buffer-default-length PASS 1/0
• parity globals --filter atomics-wait-notify PASS 1/0
• parity globals --filter typedarray PASS 5/0
• cargo fmt -p perry-runtime -p perry-codegen -- --check
• git diff --check HEAD^ HEAD
• git diff --cached --check
• jq empty test-parity/known_failures.json
• ./scripts/check_file_size.sh

[andrewtdiz]

I am taking a narrow TypedArray branded-method slice under this roadmap.

Planned PR cut: align borrowed %TypedArray%.prototype method dispatch/brand checks for the existing runtime-backed methods that commonly fall through generic array paths, starting with map, filter, slice, subarray, copyWithin, fill, reverse, and sort. The focused behavior is that calls on non-TypedArray receivers throw Node-shaped TypeError, while calls borrowed onto another TypedArray preserve the actual receiver kind and element storage.

Non-goals: detached/resizable buffers, Atomics scheduling, constructor/default-length behavior already covered by #4409, BYOB/Web Streams, and the full ~1000-case TypedArray Test262 sweep.

[andrewtdiz]

Opened draft PR for the typed-array borrowed-method slice: #4427

Scope covered:

• non-TypedArray receivers still throw TypeError for the focused %TypedArray%.prototype methods
• borrowed methods on Uint8Array preserve Uint8Array results/mutation behavior
• Buffer-backed Uint8Array receivers preserve Buffer result/mutation behavior for the covered borrowed methods
• fill/copyWithin thunks keep their optional trailing args so start/end defaults match Node

Validation:

• Node 26 vs Perry parity diff is empty for test-parity/node-suite/globals/typedarray-branded-methods.ts
• cargo check -q -p perry-runtime --lib
• cargo build --release -q -p perry-runtime with RUSTFLAGS=-Awarnings
• cargo fmt --all -- --check
• git diff --check
• ./scripts/check_file_size.sh