test(scripts): retarget the Bun 1.4 memory stack onto dev with blockers closed

[lidge-jun]

Summary

Retargets the Bun 1.4 memory stack (#2301, #2303, #2304) onto dev with the recorded review blockers closed. Two commits: the devlog roadmap, then the harness scripts.

Deliberately excludes the #2302 runtime commit. Merging the stack as-is would have done two bad things: dragged in the extraMemorySize: 0 fabrication #2302 still carries, and reverted the coordinator work that landed on src/cli/doctor.ts after the stack was cut (git diff origin/dev cac21afb -- src/cli/doctor.ts is -94/+6).

Blockers closed

#2301 — git diff --check was red on all six added markdown files (extra blank line at EOF); now clean. The future-date objection is moot rather than fixed: the review was written 2026-08-21 objecting to a 2026-08-22 date, and today is 2026-08-22, so it is correct now and was not backdated.

Two plan defects also fixed: 010 specified the unavailable extraMemorySize case as 0 (unavailable is not a measured zero, and it contradicted the watchdog/doctor layers that type the field optional), and 040 step 3 described concurrent-stream GC pairs that contradict 020's split into idle RSS cells and separate latency cells.

#2303 — the harness recorded rssAfterLoad/rssPlus5s/rssPlus60s but no pre-load baseline, so it could not express the controlling gate ("at least 50% of post-load RSS growth is gone"). It now records rssBeforeLoad and derives postLoadGrowth and recoveryFraction, with null when growth was not measurable so an inconclusive cell doesn't read as 0% recovery. A child-side gc-error now rejects the cell instead of expiring into a 10s timeout that hid the cause.

The SIGUSR2 collector in the retention child is now gated on OCX_GC_EVAL=1. It was gated by a comment saying the 7h protocol never sends that signal — a claim about one sender, not a property of the process.

#2304 — payloadMb and runs are validated as bounded integers. Reproduced before fixing:

bun scripts/smol-worker-ab.ts <dir> 100 0
  {"completionSuccess":true, ...}      # zero runs, median fields silently absent

Both invalid inputs now refuse. Medians are computed only after both arms complete. The header claimed to measure the audited shapes of the history/restore/policy workers while importing none of them; it now says what it is — a synthetic screening of the shared array+JSON burst shape.

What is NOT claimed

Both experiments' FAIL verdicts stand. No production Bun.gc(true) and no smol: true flag is landed.

The GC harness needs a live upstream fixture to produce new numbers, so the recorded RSS cells are not regenerated here and the 020 table still carries the old denominator. Re-running the cells and rewriting that table around recoveryFraction is the next measurement pass, not something this PR pretends to have done.

Verification

bun x tsc --noEmit                  exit 0
git diff --check origin/dev...HEAD  exit 0
bun run privacy:scan                Privacy scan passed
bun test tests/repo-hygiene.test.ts 11 pass / 0 fail
smol-worker-ab.ts <dir> 100 0       refuses (runs must be an integer in 1..20)
smol-worker-ab.ts <dir> -5 1        refuses (payloadMb must be an integer in 1..512)
smol-worker-ab.ts <dir> 1 1         exit 0, verdict recorded

Checklist

• Scripts and devlog only; no runtime/src change
• privacy:scan green
• Full suite + exact-head CI run against the merged head

Summary by CodeRabbit

• Documentation

  • Added planning and research documentation for memory diagnostics, garbage-collection evaluation, worker memory optimization, and live Mac mini measurements.
  • Documented measurement protocols, acceptance criteria, platform considerations, and validation requirements.

• Tools

  • Added opt-in Bun garbage-collection evaluation tooling with RSS and latency reporting.
  • Added a worker memory A/B benchmark measuring completion, runtime, and peak memory usage.
  • Added optional JSC memory diagnostics and structured collection results for evaluation runs.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 59b5be2c-14c1-4d69-8511-54ea7a52103d

📥 Commits

Reviewing files that changed from the base of the PR and between d179fa4 and 1ab34dc.

📒 Files selected for processing (9)

• devlog/_plan/260822_260822-bun14-followup-memory/000_plan.md
• devlog/_plan/260822_260822-bun14-followup-memory/000_research.md
• devlog/_plan/260822_260822-bun14-followup-memory/010_memory_diagnostics.md
• devlog/_plan/260822_260822-bun14-followup-memory/020_watchdog_gc_relief.md
• devlog/_plan/260822_260822-bun14-followup-memory/030_smol_workers.md
• devlog/_plan/260822_260822-bun14-followup-memory/040_macmini_measurement.md
• scripts/bun-gc-relief-eval.ts
• scripts/macos-rss-retention-harness-child.ts
• scripts/smol-worker-ab.ts

---

📝 Walkthrough

Walkthrough

The PR adds plans and executable harnesses for Bun 1.4 memory diagnostics, GC-relief evaluation, smol-worker A/B testing, and macmini measurements. It defines fresh-process gates, guarded GC control, optional JSC fields, latency and RSS criteria, and JSON evidence reports.

Changes

Bun 1.4 memory follow-up

Layer / File(s)	Summary
Research and rollout plan devlog/_plan/260822_260822-bun14-followup-memory/000_research.md:1-70, devlog/_plan/260822_260822-bun14-followup-memory/000_plan.md:1-17	Defines verified Bun memory claims, research gaps, phase sequencing, A/B requirements, rollout gates, and explicit non-goals.
JSC memory diagnostics plan devlog/_plan/260822_260822-bun14-followup-memory/010_memory_diagnostics.md:1-80	Plans optional jscHeap.extraMemorySize, guarded bun:jsc watchdog sampling, doctor output, unchanged thresholding, and related tests.
GC relief evaluation harness devlog/_plan/260822_260822-bun14-followup-memory/020_watchdog_gc_relief.md:1-98, scripts/bun-gc-relief-eval.ts:1-322, scripts/macos-rss-retention-harness-child.ts:68-97	Adds isolated RSS and latency evaluation cells, an SSE fixture, child-process SIGUSR2 GC control, cleanup handling, quantile calculations, and metadata-rich JSON reports. The plan keeps production GC disabled until the stated evidence gates pass.
Smol worker A/B benchmark devlog/_plan/260822_260822-bun14-followup-memory/030_smol_workers.md:1-44, scripts/smol-worker-ab.ts:1-142	Runs baseline and { smol: true } worker workloads in fresh child processes. It records completion, elapsed time, peak RSS, medians, environment metadata, and gate results.
macmini measurement protocol devlog/_plan/260822_260822-bun14-followup-memory/040_macmini_measurement.md:1-33	Defines Bun installation, 30-minute baseline sampling, matched GC cells, optional smol A/B testing, runtime metadata capture, and scalar-counter JSON evidence collection.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: ingwannu

Sequence Diagram(s)

sequenceDiagram
  participant Evaluator
  participant SSE fixture
  participant Retention harness
  participant Report
  Evaluator->>SSE fixture: Run load and probe streams
  Evaluator->>Retention harness: Send SIGUSR2
  Retention harness-->>Evaluator: Return GC timing or error JSONL
  Evaluator->>Evaluator: Sample RSS and calculate latency quantiles
  Evaluator->>Report: Write cell results and runtime metadata

Loading

✨ 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 codex/wp7-bun14-docs

---

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