perf(json): batch-materialize a lazy tape array by re-parsing its blob (#7478)

[proggeramlug]

Implements step 2 of #7478's roadmap. Unblocked by #7483.

What changed

force_materialize_lazy walked the tape element-by-element to build the
ArrayHeader tree. #7478's decomposition measured that walk at ~2.3x the direct
parser's batch tree build — 56 ms/iter vs 24 ms/iter on the 10k-record fixture —
and identified the fix: a lazy array only ever stands for a top-level array
(try_parse_via_tape builds one only when tape_entries[0].kind == KIND_ARR_START, always with root_idx = 0), so its retained blob_str is
exactly that array's source text. Re-parsing it with DirectParser produces the
identical tree in one linear pass.

"Identical" now includes the numbers: #7483 put the DirectParser's decimal fast
path on a single correctly-rounded division, so it agrees bit-for-bit with
str::parse::<f64> (what materialize_number uses) and with node. That
divergence (#7477) is what blocked this the first time.

The crash, root-caused

The earlier prototype SIGSEGV'd intermittently. DirectParser is only sound
inside a no-move window, in three independent ways — all three visible in
json/parser.rs:

1. it holds input: &'a [u8] derived from the blob's StringHeader payload for
   the whole parse and has no way to re-derive it;
2. it carries an unrooted raw-pointer shape cache (hot_shape_keys: [*const StringHeader; 8], hot_shape_array: *mut ArrayHeader) across every
   allocation — the "runtime-side cache of a raw heap pointer is a GC root, and
   the static checker cannot see it" shape from CLAUDE.md;
3. array_push_parse_fast fills fresh arrays through
   note_array_slot_layout_only, which deliberately skips the generational
   barrier for young arrays and says so in a comment that begins "GC is
   suppressed for the whole direct parse".

js_json_parse buys all three with its gc_suppress() window. The prototype
called the parser without one. The fix wraps the parse in a GcSuppressScope —
nesting-safe on purpose, because force_materialize_lazy is reachable from
inside try_stringify_lazy_array, and the flat gc_unsuppress() would end an
outer window early.

Around that window the ordering follows the #7341 discipline: every header
re-read is a RuntimeHandle::across_{mut,const} paired with the call that can
collect (no new bare get_raw_*_ptr — json_tape.rs stays at its ceiling of
22), the parsed tree is handed to PARSE_ROOTS before the suppression closes
and promoted to a handle-scope root before those are restored, and the function
returns the refreshed header on every exit including the declining ones.

Cache-merge semantics

The reparse rebuilds every element from source, so the sparse cache has to be
patched back over the fresh slots: a cached slot holds the JSValue user code
already has a reference to and may have mutated through it (parsed[2].id = 99), while the blob still says the old value. The patch loop preserves both the
value and the identity (parsed[i] === parsed[i]), and runs inside a suppression
window so the header, bitmap, cache and array pointers stay valid without a
per-element re-read.

It stores through store_array_slot, not a raw *elements.add(i) = bits: the
reparsed array is frequently in RawF64 numeric layout, and a raw store would
leave it flagged pointer-free with a live pointer inside — invisible to the
tracer.

When it fires

Only below the measured crossover (cached_count * 2 < cached_length). Once most
elements are already cached the element-wise merge is the cheaper producer — it
copies the cached JSValues and materializes only the remainder — so a reparse
there would rebuild subtrees it is about to throw away. From the 2.3x ratio the
crossover sits at ~43% uncached; the check is on the conservative side of it.

This is deliberately a no-op for bench_field_access, and that is not an
oversight. That benchmark touches every element before stringifying, so by the
time try_stringify_lazy_array force-materializes, the bitmap is full and the
merge walk is already the cheap path — all of its 2981 ms went into the 10k
lazy_get calls, not into materialization. Closing that gap is #7478's step 3
(a batch-flip trigger that materializes early, while the cache is still mostly
empty); this PR is what makes that trigger worth adding, since step 1 of the
issue measured it as neutral against the slow materializer. What benefits today
is any full-array operation on a lazy array whose elements have not been
individually walked: .map / .filter / spread / for…of / sort /
Object.keys on a fresh JSON.parse result (the 1_json_pipeline
"filter-all-records" shape), and the random-access cumulative_walk_steps
trigger, which fires after ~4 accesses on a 10k array — cache count 4 out of
10000, deep in reparse territory.

No timing claims in this PR: the host was at load average 27-40 throughout. Perf
belongs on a quiet host at review.

Validation

Unit — cargo test -p perry-runtime --lib: 1718 passed, 0 failed, 3
ignored. New/extended cases:

• test_json_tape_reparse_materialize_preserves_a_mutated_cache_entry (new,
  gc/tests/runtime_roots/callback_scanners.rs): plants a mutated cached element
  (parsed[2].id = 99), materializes via reparse, asserts the mutation survives
  and the array slot is the same JSValue, then asserts the stringified text is
  [{"id":0},{"id":1},{"id":99},{"id":3}].
• test_json_tape_force_materialize_sparse_cache_handles_survive_copied_minor_gc
  (existing sabotage test) keeps firing the ForceLazyArrayRooted safepoint —
  the hook forces a copying minor there and the test asserts the array handle was
  refreshed. It now runs against the reparse producer, and a new assertion pins
  that, so the instrument cannot silently change subject.
• force_materialize_majority_cached_uses_the_merge_walk_not_a_reparse (new):
  pins the crossover decision, not just the values — without it the test passes
  either way and the crossover could silently invert.
• force_materialize_declines_reparse_when_the_tape_root_is_not_the_blob_root
  (new): a lazy header whose tape root is not the blob's first value must decline
  and still materialize correctly through the walk.
• The two existing force_materialize_* tests gained assertions that they take
  the reparse path (one also pins the RawF64 -> pointer layout downgrade).

The witness for all of the above is a thread-local reparse counter, so a test can
assert which producer ran rather than only that nothing threw.

Sabotage — deleting the cache-patch loop turns 3 tests red, including the
existing sparse-cache sabotage test and the new mutation test ("the reparse must
patch the handed-out element back, not a fresh copy"). Restored.

Byte-for-byte vs node 26.5.1 — an 11-scenario probe (600 records x 13 fields
incl. floats, exponents, escapes, non-ASCII, nested arrays/objects; plus the
10k-element i * 3.14159 float array from the #7477 divergence class, edge
values -0.0 / 1e21 / 5e-324 / 1.797…e308 / 9007199254740993, a
whitespace-bearing blob, identity checks, sort, and repeated materialization).
Scenarios print whole JSON texts, so the diff is the byte check. All three
modes — PERRY_JSON_TAPE=1, =0, and auto — are byte-identical to node
(670,312 bytes each). An instrumented runtime confirmed the reparse path ran 10x
across that probe, and that the every-element-touched scenario correctly did
not take it.

json gap tests — all 12 test-files/test_gap_*json*.ts compile, run, and
match node 26.5.1 byte-for-byte, with matching exit codes, under both
PERRY_JSON_TAPE=1 and =0.

#7478's own benchmarks, correctness only — bench_field_access checksum is
2552985550 under PERRY_JSON_TAPE=1, under =0, and under node — the value
#7483 established as ground truth. benchmarks/json_polyglot/bench.ts (the
unmutated-blob memcpy roundtrip, the path this PR must not disturb) checksums
53735550 in auto mode, matching node.

GC instruments — the probes were compiled with PERRY_GC_MOVING_LOOP_POLLS=1
and run under PERRY_GC_ZEAL=1 PERRY_GC_PROTECT_FROMSPACE=1 PERRY_GC_PROTECT_FROMSPACE_DEPTH=800 PERRY_GC_DIAG=1. Instrument liveness
confirmed — [gc-fromspace-protect] mode=ProtectPages retired_set=#0…#5 with a
copying minor that moved 144,174 objects — 120 reparses inside that protected
run, exit 0, output still byte-identical to node.

cargo fmt --all -- --check clean. scripts/raw_handle_debt.py: 999 =
baseline, all modules within ceilings. scripts/check_file_size.sh: OK.

One pre-existing failure found (not from this PR)

PERRY_GC_VERIFY_EVACUATION=1 with PERRY_JSON_TAPE=1 trips the
old-young-edge-verifier:

old-young-edge-verifier failed: … missing_edges=8205 unmarked_parents=8205
  first_missing: parent=… type=lazy_array(9) old_arena=true marked=false
                 slot=… child=… child_type=object(2) slot_page_ever_dirty=false
  missing_by_parent_type: lazy_array(9)=8205

A/B'd against a runtime built from this branch's merge-base with only
json_tape.rs + the test file reverted, same binary pipeline, same probe: the
baseline fails identically (lazy_array(9) parents, object(2) children,
slot_page_ever_dirty=false; 8205 edges on the baseline vs 10095 with this
change — the same defect, differing only in how much lazy-cache traffic each arm
generates). So it is on main today, not introduced here. The slot is the lazy
header's sparse element cache (materialized_elements, a separate arena
allocation attributed to the lazy_array parent), written in lazy_get. Filed
as #7500 rather than folded in here.

#7478 stays open for step 3.

[coderabbitai]

Warning

Review limit reached

@proggeramlug, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 4 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e65cc9ce-69f2-44e5-b42f-69253a3a14b0

📥 Commits

Reviewing files that changed from the base of the PR and between 40214c5 and dc0383b.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• CLAUDE.md
• Cargo.toml
• changelog.d/7499-json-reparse-materialize.md
• crates/perry-runtime/src/gc/tests/runtime_roots/callback_scanners.rs
• crates/perry-runtime/src/json_tape.rs

---

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