perf(gc): pace parse-boundary collection on JSON side-allocation bytes

changelog.d/gc-medium-parse-side-allocation-pacing.md

@@ -0,0 +1,68 @@
+### Fixed
+
+**GC: a `JSON.parse` loop over medium documents retained ~32 MB of dead tape per cycle.**
+
+`records_array_16k:parse` was the one row of the 50-cell JSON matrix still losing
+on peak RSS: **74.98 MiB against Node 26.5.1's 65 and Bun's 71** on the bench
+mini. It now peaks at **48.86 MiB** — 25 % under Node — with CPU 2.8 % *better*
+than before.
+
+**Where the bytes were.** A lazily-parsed document's memory is not in the arena.
+Parsing the 13 197-byte `records_array_16k` fixture puts ~1.1 KB in the nursery
+(the `LazyArrayHeader`, its sparse cache and bitmap) and ~24 KB of tape in a
+`json_tape_store` side allocation. Every pacing input a parse boundary reads is
+denominated in *arena* bytes, so the young generation saw 1/24th of what the
+process was holding. `PERRY_GC_DIAG=1` over the row's 11 284 iterations at
+`origin/main`: **eight collections, every one a full mark-sweep from
+`alloc_point_old_reclaim`**, each firing at `external_side=33.6 MB` with
+`arena_total` between 3 and 8 MB, `old_in_use=0`, and `from_space` never above
+6.9 MB against a 16 MB nursery cap. The row's only pacing was the old-reclaim
+growth band happening to read those side bytes — i.e. 32 MB of dead tape per
+cycle.
+
+**The fix, in two halves.**
+
+* A third arm on `tiny_parse_generational_collection_due`, keyed on
+  `external_side_live_bytes()` with the `max(floor, baseline)` growth band
+  old-gen reclaim already uses, based at the reading the last collection left
+  behind. A futile collection (an old-owned cluster whose tape survives)
+  re-bases the band at the surviving value, so repeats space out geometrically
+  instead of livelocking.
+* The band's counterweight: what a *non-full* collection releases stays in the
+  old-reclaim pressure term until the next full
+  (`external_side_old_reclaim_pressure_bytes`). Only a full returns arena
+  capacity, and on these rows the external term was paying for that too;
+  draining it with cheap minors alone took `records_array_1m:sparse` from seven
+  fulls to one, the arena's dirty pages from 29 MB to 55 MB, and peak RSS from
+  63.5 to 73.6 MiB *even though live external bytes had halved*. The sum is
+  bounded above by what `main` read at the same point, so it can never fire
+  old-reclaim earlier.
+
+**Measured** on the bench mini, 9 interleaved rounds, best of each, all 50 cells
+of the JSON matrix (peak RSS, MiB / CPU, ms):
+
+| row | main | this | ΔRSS | ΔCPU |
+|---|---|---|---|---|
+| `records_array_16k:parse` | 74.98 / 155.2 | 48.86 / 150.8 | **−34.8 %** | −2.8 % |
+| `records_array_16k:sparse` | 65.17 / 149.5 | 44.48 / 142.5 | −31.8 % | −4.7 % |
+| `records_array_8m:roundtrip` | 129.00 / 146.7 | 99.16 / 139.6 | −23.1 % | −4.8 % |
+| `records_array_16k:roundtrip` | 63.72 / 143.5 | 51.12 / 152.0 | −19.8 % | +5.9 % |
+| `records_array_8m:parse` | 97.84 / 134.2 | 85.44 / 131.7 | −12.7 % | −1.9 % |
+| `records_array_8m:sparse` | 98.39 / 132.7 | 86.00 / 129.2 | −12.6 % | −2.6 % |
+| `records_array_1m:roundtrip` | 61.36 / 162.9 | 58.23 / 165.5 | −5.1 % | +1.6 % |
+| `numbers_1m:parse` | 62.81 / 160.7 | 60.28 / 164.8 | −4.0 % | +2.6 % |
+| `records_array_1m:parse` | 65.78 / 157.7 | 64.75 / 158.9 | −1.6 % | +0.8 % |
+| `heterogeneous_1m:parse` | 59.05 / 160.3 | 62.52 / 159.4 | **+5.9 %** | −0.6 % |
+
+The remaining 40 rows move by less than 1 % on both axes. `heterogeneous_1m:parse`
+is the one row that grows: its arena capacity goes 5.24 → 8.39 MiB (one extra
+live non-general block plus one in-place promoted block) for a live-external
+reading that falls — the standing cost of running copying minors on a row that
+previously ran none — while its nine full collections are preserved exactly.
+
+`gc_ratchet` (14 probes, 7 repeats each, `main` vs this): correctness passes on
+all 14, and **`heap_used_bytes` and `heap_total_bytes` are bit-identical on every
+probe** — the gated retention counters do not move. Peak RSS (min of 7) stays
+within ±0.5 %, the largest being `03_cross_gen_writes` 25.25 → 25.38 MiB
+(+0.13 MiB) and `01_nursery_churn` 27.17 → 27.30 MiB; wall clock runs from
+`08_map_set_sidetables` −5.1 % to `06_string_retention` +1.2 %.

crates/perry-runtime/src/gc/diag_sites.rs

@@ -45,6 +45,7 @@ pub(super) fn trigger_decision(site: &'static str, kind: &'static str) {
     let nursery_cap = tenuring::scavenge_nursery_cap_effective_bytes();
     let old_reclaimable = policy::old_gen_reclaimable_pressure_bytes();
     let external = policy::external_side_live_bytes();
+    let external_drained = policy::GC_EXTERNAL_SIDE_DRAINED_SINCE_FULL.with(Cell::get);
     let old_baseline = policy::GC_LAST_OLD_RECLAIM_IN_USE_BYTES.with(Cell::get);
     let old_band = policy::gc_old_reclaim_growth_band_bytes(old_baseline);
     let old_threshold = gc_old_gen_reclaim_threshold_dyn_bytes();
@@ -57,7 +58,8 @@ pub(super) fn trigger_decision(site: &'static str, kind: &'static str) {
     eprintln!(
         "[gc-trigger] site={site} kind={kind} arena_total={arena_total} next_base={next_base} armed={armed} \
          from_space={from_space} nursery_cap={nursery_cap} old_in_use={old_in_use} old_free={old_free} \
-         old_reclaimable={old_reclaimable} external_side={external} old_baseline={old_baseline} \
+         old_reclaimable={old_reclaimable} external_side={external} \
+         external_drained={external_drained} old_baseline={old_baseline} \
          old_band={old_band} old_threshold={old_threshold} old_pending={old_pending} retaining={retaining} \
          malloc={malloc} next_malloc={next_malloc}"
     );

crates/perry-runtime/src/gc/policy.rs

@@ -478,8 +478,16 @@ pub(super) fn tiny_parse_pressure_due_with(
 /// is safe to consult where the absolute in-use guard was not: a minor lowers
 /// the quantity it tests to the survivors, so it cannot fire again until the
 /// cap has been refilled.
+///
+/// Medium-parse pacing (2026-09-14) adds the third arm for the same reason the
+/// second one exists, one currency over: both of the first two are denominated
+/// in ARENA bytes, and a lazily-parsed document's bytes are not in the arena at
+/// all. See
+/// [`external_side_parse_pressure_due`].
 pub(super) fn tiny_parse_generational_collection_due(in_use: usize, in_use_trigger: usize) -> bool {
-    tiny_parse_pressure_due(in_use, in_use_trigger) || young_scavenge_cap_due()
+    tiny_parse_pressure_due(in_use, in_use_trigger)
+        || young_scavenge_cap_due()
+        || external_side_parse_pressure_due()
 }
 
 /// The live [`tiny_parse_pressure_due_with`]: current base and step.
@@ -522,13 +530,22 @@ fn diag_tiny_parse_forced_collection(site: &str, in_use: usize) {
     }
     let base = GC_TINY_PARSE_PRESSURE_BASE_BYTES.with(Cell::get);
     let step = GC_STEP_BYTES.with(Cell::get);
+    // Medium-parse pacing (2026-09-14): the side-allocation arm's own inputs,
+    // so a diag reader can tell which of the three arms priced this collection
+    // rather than re-deriving it — the same "assert the subject was live" rule.
+    let external = external_side_live_bytes();
+    let external_base = GC_LAST_COLLECTION_EXTERNAL_SIDE_BYTES.with(Cell::get);
     eprintln!(
-        "[gc-tiny-parse] forced collection site={} in_use={} base={} headroom={} step={}",
+        "[gc-tiny-parse] forced collection site={} in_use={} base={} headroom={} step={} \
+         external_side={} external_base={} external_band={}",
         site,
         in_use,
         base,
         tiny_parse_pressure_headroom_bytes(step),
-        step
+        step,
+        external,
+        external_base,
+        external_side_parse_band_bytes(external_base)
     );
 }
 
@@ -631,6 +648,18 @@ const GC_EXTERNAL_SIDE_ALLOC_STEP: usize = 16 * 1024 * 1024;
 crate::perry_thread_local! {
     static GC_EXTERNAL_SIDE_ALLOC_PENDING: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
     static GC_EXTERNAL_SIDE_LIVE_BYTES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
+    /// Medium-parse pacing (2026-09-14): [`external_side_live_bytes`] as the
+    /// last collection ended — the base of the parse-boundary growth band
+    /// ([`external_side_parse_pressure_due_with`]). A byte COUNT, never an
+    /// address; written only from `note_collection_finished_arena_occupancy`.
+    pub(super) static GC_LAST_COLLECTION_EXTERNAL_SIDE_BYTES: std::cell::Cell<usize> =
+        const { std::cell::Cell::new(0) };
+    /// Medium-parse pacing (2026-09-14): external side bytes that a
+    /// NON-full collection has released since the last full — see
+    /// [`external_side_old_reclaim_pressure_bytes`]. A byte COUNT, never an
+    /// address.
+    pub(super) static GC_EXTERNAL_SIDE_DRAINED_SINCE_FULL: std::cell::Cell<usize> =
+        const { std::cell::Cell::new(0) };
 }
 
 /// Live bytes currently held by external Map/Set side buffers on this thread.
@@ -639,6 +668,54 @@ pub(super) fn external_side_live_bytes() -> usize {
     GC_EXTERNAL_SIDE_LIVE_BYTES.with(Cell::get)
 }
 
+/// Medium-parse pacing (2026-09-14): how many bytes of external side allocation
+/// may accumulate past the last collection before a `JSON.parse` boundary is
+/// due.
+///
+/// Deliberately the `max(floor, proportional)` shape of
+/// [`gc_old_reclaim_growth_band_bytes`], for the two reasons that shape exists:
+///
+/// * a program whose live side set is genuinely large (a retained multi-MB
+///   `Map`) must not collect once per parse, so the band grows with it; and
+/// * a collection that CANNOT lower the number this band watches re-baselines
+///   it at the surviving value, so futile repeats space out geometrically
+///   instead of firing at a constant step. That is what keeps this arm off the
+///   #7437/#7592 livelock: a lazy array whose cluster was born OLD
+///   (`json_tape::lazy_cluster_is_old`) keeps its tape through the nursery
+///   collection this arm schedules, and the next band is then twice as far
+///   away rather than due again at the next parse.
+pub(super) fn external_side_parse_band_bytes(baseline: usize) -> usize {
+    gc_trigger_headroom_floor_bytes().max(baseline)
+}
+
+/// [`external_side_parse_pressure_due`] with both readings supplied.
+pub(super) fn external_side_parse_pressure_due_with(live: usize, baseline: usize) -> bool {
+    live >= baseline.saturating_add(external_side_parse_band_bytes(baseline))
+}
+
+/// Medium-parse pacing (2026-09-14): has external side-allocation churn earned
+/// a parse-boundary collection?
+///
+/// Every other pacing input a parse boundary reads is denominated in ARENA
+/// bytes, and a lazily-parsed document's memory is not in the arena: a 13 KB
+/// `records_array_16k` parse puts ~1.1 KB (header + sparse cache + bitmap) in
+/// the nursery and ~24 KB of tape in a `json_tape_store` side allocation. So
+/// the young generation reads 1/24th of what the process is actually holding,
+/// and a parse loop reaches its nursery cap 24x later than the memory says it
+/// should. Measured on `records_array_16k:parse` at `origin/main`
+/// (`PERRY_GC_DIAG=1`, 11 284 iterations): EIGHT collections, every one of them
+/// a full mark-sweep from `alloc_point_old_reclaim`, each firing at
+/// `external_side=33.6 MB` with `arena_total` between 3 and 8 MB,
+/// `old_in_use=0` and `from_space` never above 7 MB against a 16 MB nursery
+/// cap. The only pacing this workload had was the old-reclaim growth band
+/// reading those side bytes, i.e. 32 MB of dead tape per cycle.
+pub(super) fn external_side_parse_pressure_due() -> bool {
+    external_side_parse_pressure_due_with(
+        external_side_live_bytes(),
+        GC_LAST_COLLECTION_EXTERNAL_SIDE_BYTES.with(Cell::get),
+    )
+}
+
 /// Record `bytes` of fresh external side-buffer allocation (Map entries /
 /// Set elements — creation or growth delta) and poke the trigger check when
 /// the accumulated churn window fills. Callers must invoke this only when
@@ -666,6 +743,34 @@ pub(crate) fn gc_note_external_side_alloc(bytes: usize) {
 /// Record that a Map/Set side buffer of `bytes` was freed (GC finalizer).
 pub(crate) fn gc_note_external_side_free(bytes: usize) {
     GC_EXTERNAL_SIDE_LIVE_BYTES.with(|c| c.set(c.get().saturating_sub(bytes)));
+    GC_EXTERNAL_SIDE_DRAINED_SINCE_FULL.with(|c| c.set(c.get().saturating_add(bytes)));
+}
+
+/// The external side-buffer term of OLD-RECLAIM pressure.
+///
+/// Live bytes PLUS whatever a non-full collection has already released since
+/// the last full. The sum is deliberately what `external_side_live_bytes()`
+/// alone read before the parse-boundary band existed, so old-reclaim keeps
+/// firing at exactly the program point it always did.
+///
+/// It has to. Only a FULL collection returns arena capacity — general blocks
+/// are released after two full observations (`gc::arena_right_size`) — and on a
+/// lazily-parsed record loop the external term was what pushed old-reclaim over
+/// its band, i.e. the side allocations were paying for the arena's block
+/// release as well as their own. Draining that term with cheap nursery
+/// collections and leaving the pressure test on the live reading removed those
+/// fulls: measured on `records_array_1m:sparse` (161 parses of a 7 600-record
+/// document), 12 minors and ONE full against `origin/main`'s seven, the arena's
+/// dirty pages 29 MB -> 55 MB, and peak RSS 63.5 -> 73.6 MiB even though live
+/// external bytes had HALVED. Keeping the drained bytes in the pressure term
+/// pins the full cadence to main's while the band holds the live reading down.
+///
+/// It can never make old-reclaim fire EARLIER than main: every drained byte is
+/// a byte main would still have been counting as live at the same point, so the
+/// sum is bounded above by main's reading and equals it when the same objects
+/// die.
+pub(super) fn external_side_old_reclaim_pressure_bytes() -> usize {
+    external_side_live_bytes().saturating_add(GC_EXTERNAL_SIDE_DRAINED_SINCE_FULL.with(Cell::get))
 }
 
 #[inline]
@@ -1931,8 +2036,8 @@ pub(super) fn copied_minor_promotion_handoff_due(trigger_kind: GcTriggerKind) ->
         return false;
     }
     let promotable = copied_minor_promotable_active_survivor_bytes();
-    let old_in_use =
-        old_gen_reclaimable_pressure_bytes().saturating_add(external_side_live_bytes());
+    let old_in_use = old_gen_reclaimable_pressure_bytes()
+        .saturating_add(external_side_old_reclaim_pressure_bytes());
     let baseline = GC_LAST_OLD_RECLAIM_IN_USE_BYTES.with(|bytes| bytes.get());
     copied_minor_promotion_handoff_pressure_due(promotable, old_in_use, baseline)
 }
@@ -2040,8 +2145,8 @@ pub(super) fn maybe_schedule_old_reclaim_after_copied_minor() {
     // a tenured-then-dead Map holds its multi-MB buffer until a full
     // reclaim's old-gen sweep finalizes it, so the buffer bytes must be
     // able to escalate that reclaim.
-    let old_in_use =
-        old_gen_reclaimable_pressure_bytes().saturating_add(external_side_live_bytes());
+    let old_in_use = old_gen_reclaimable_pressure_bytes()
+        .saturating_add(external_side_old_reclaim_pressure_bytes());
     let baseline = GC_LAST_OLD_RECLAIM_IN_USE_BYTES.with(|bytes| bytes.get());
     if old_reclaim_pressure_due(old_in_use, baseline) {
         GC_OLD_RECLAIM_PENDING.with(|pending| pending.set(true));
@@ -2065,10 +2170,15 @@ pub(super) fn request_old_reclaim_for_untraced_promotions(bytes: usize) {
 }
 
 pub(super) fn finish_full_old_reclaim_baseline() {
+    // Medium-parse pacing (2026-09-14): the full this baseline records is the
+    // collection the drained bytes were being held for, so the debt is paid
+    // here — before the baseline is read, or the baseline would carry it into
+    // the next band and the following full would fire a band too early.
+    GC_EXTERNAL_SIDE_DRAINED_SINCE_FULL.with(|c| c.set(0));
     // Baseline includes external side-buffer bytes (#6010) so the growth
     // delta in `old_reclaim_pressure_due` stays unit-consistent.
-    let old_in_use =
-        old_gen_reclaimable_pressure_bytes().saturating_add(external_side_live_bytes());
+    let old_in_use = old_gen_reclaimable_pressure_bytes()
+        .saturating_add(external_side_old_reclaim_pressure_bytes());
     GC_LAST_OLD_RECLAIM_IN_USE_BYTES.with(|bytes| bytes.set(old_in_use));
     // Record the TOTAL post-full live set for major-GC pacing (young+old): the
     // full sweep is the only collection that frees forwarding stubs, so this is
@@ -2235,6 +2345,12 @@ pub(super) fn note_collection_finished_arena_occupancy(full: bool) {
     GC_LAST_COLLECTION_POST_IN_USE_BYTES.with(|cell| cell.set(bytes));
     // #9831: the same moment, in the units the tiny-parse guard reads.
     GC_TINY_PARSE_PRESSURE_BASE_BYTES.with(|cell| cell.set(crate::arena::arena_in_use_bytes()));
+    // Medium-parse pacing (2026-09-14): and in the units the parse-boundary
+    // side-allocation band reads. This is the site that makes the band self-correcting: whatever the sweep
+    // and the from-space pass just released has already been subtracted from
+    // `external_side_live_bytes`, so a collection that freed the tapes
+    // re-bases at ~0 and one that could not re-bases at the surviving value.
+    GC_LAST_COLLECTION_EXTERNAL_SIDE_BYTES.with(|cell| cell.set(external_side_live_bytes()));
     super::arena_right_size::note_collection_finished(bytes, full);
 }
 
@@ -3373,7 +3489,7 @@ pub(super) fn gc_budgeted_due_trigger_eval() -> (Option<BudgetedGcTrigger>, bool
     let old_pending = GC_OLD_RECLAIM_PENDING.with(Cell::get);
     // #6010: external Map/Set side-buffer bytes escalate to OldReclaim too.
     let old_reclaimable = old_gen_reclaimable_pressure_bytes();
-    let old_in_use = old_reclaimable.saturating_add(external_side_live_bytes());
+    let old_in_use = old_reclaimable.saturating_add(external_side_old_reclaim_pressure_bytes());
     let old_baseline = GC_LAST_OLD_RECLAIM_IN_USE_BYTES.with(|bytes| bytes.get());
     if old_pending || old_reclaim_pressure_due(old_in_use, old_baseline) {
         return (Some(BudgetedGcTrigger::OldReclaim), true);