memory(gc): heapUsed and major-GC pacing use block high-water, not live bytes #7879

Summary

Perry currently uses arena bump offsets as a proxy for live heap bytes in both public memory telemetry and major-GC pacing. That proxy includes tail slack and dead/reusable holes, and the two implementations do not even apply the same correction:

• js_arena_stats() sums committed block offsets and subtracts only old-generation free-list bytes.
• arena_in_use_bytes() sums block offsets without subtracting old-generation free-list bytes, despite its documentation and policy call sites describing the result as live/in-use bytes.

As a result, a tiny survivor can account for an entire 1 MiB block, process.memoryUsage().heapUsed can substantially overstate live memory, and full-GC pacing decisions can be driven by fragmentation/high-water placement rather than what a collection actually failed to reclaim.

Evidence

• js_arena_stats() sums block offsets and only subtracts old_free_bytes.
• arena_in_use_bytes() sums the same offsets without subtracting reusable old-generation holes.
• Major-GC policy treats the result as live/in-use bytes, including post-full measurements used to decide when another full collection is warranted.
• process.memoryUsage() exposes js_arena_stats().used_bytes as heapUsed; the same arena statistics also feed V8-compatible heap APIs and process reports.
• The ratchet documentation explicitly records the 1 MiB granularity artifact: one retained object can keep a full block represented in heap_used_bytes, producing a sawtooth even with a near-zero live set.
• The remaining amplification was acknowledged when gc: 05_closure_capture retains +16.44% with every collector counter at +0.00% — surfaced when the ratchet started measuring again #7559 was closed; that issue removed a conservative-scan trigger rather than fixing the accounting model.
• gc-ratchet: 7 gating rows red on main since 0.5.1451 — and 04_dead_after_deep_stack / 11_collect_at_depth are NOT among them #7843 currently reports several block-sized heap_used_bytes ratchet regressions. This issue does not assert the accounting model caused those regressions, but it makes the signal and the collector policy unusually sensitive to block-boundary changes.

Impact

1. Public Node/V8-compatible telemetry gives users a misleading measure of live JS heap usage.
2. Major/full collection pacing can compare block occupancy/fragmentation while naming and reasoning about it as live bytes.
3. Ratchet failures can be quantized by block placement, obscuring small real leaks and exaggerating boundary crossings.
4. The policy metric and public metric disagree about old-generation reusable holes, making diagnosis harder.

Proposed direction / acceptance criteria

• Define distinct, documented quantities for at least reserved/committed bytes, allocation high-water, reusable bytes, and live allocated bytes.
• Maintain exact or bounded live/reusable byte counters per generation, or perform a post-collection census where exactness is required.
• Make major-GC pacing compare one deliberately chosen semantic quantity before and after collection; rename it if occupancy rather than liveness is intentional.
• Make process.memoryUsage().heapUsed and compatible V8 APIs report a tested live-allocation quantity rather than whole-block high-water.
• Gate the ratchet on the precise live metric while retaining reserved/high-water metrics as separate fragmentation diagnostics.
• Add a regression test showing that retaining one tiny object does not add an otherwise empty 1 MiB block to reported heapUsed.
• Cross-check the new counters against a heap walk/snapshot in stress tests, including general free-list and old-generation free-list reuse.

Audit context

Found during the August 2026 GC/performance audit of the last 200 origin/main commits. This is a source/accounting finding; no heavy benchmark or compilation was run.