perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script

[vanceingalls]

Summary

Make the existing benchmark harness genuinely useful for HDR perf work: positive --tags filter, peak heap/RSS sampling, a bench:hdr script, and a perf README documenting the captured April-2026 baseline. Lands first in the Chunk 8 sub-stack so subsequent perf PRs can be measured against a known starting point.

Why

Chunk 8A of plans/hdr-followups.md. Wall-clock timing alone can't catch slow memory regressions like an unbounded image cache — peak RSS does. And the existing harness only had --exclude-tags, so HDR runs had to wait for unrelated SDR fixtures.

What changed

1. Positive --tags filter in benchmark.ts. Adds --tags hdr so HDR runs don't have to wait for unrelated fixtures. Filters compose: a fixture must match --tags (if provided) AND must not match --exclude-tags.

2. Peak heap + RSS tracking in executeRenderJob. A 250 ms periodic process.memoryUsage() sampler runs alongside every render and reports peakRssMb / peakHeapUsedMb in RenderPerfSummary. Sampler is unref'd and always cleared in finally so it never keeps the event loop alive or leaks across jobs. Both fields are optional on the interface for back-compat with serialized older summaries.

3. bench:hdr convenience script plus a perf README at tests/perf/README.md documenting the harness, the new flags, and the captured April-2026 HDR baseline (PQ regression: 34.5 s / 272 MiB RSS, HLG regression: 11.5 s / 227 MiB RSS, both 1080p / 1 worker / 1 run).

The benchmark output table is widened and gains PeakRSS / PeakHeap columns. A new avgOrNull helper preserves null in the JSON when no run reported memory (avoids silently coercing missing data to 0 in older snapshots).

No behavior change for non-benchmark renders — the sampler runs in every executeRenderJob but its overhead is a single process.memoryUsage() call every 250 ms, well below noise.

Test plan

• bunx tsc --noEmit -p packages/producer — clean.
• bunx oxlint / bunx oxfmt --check on changed files — clean.
• bun test src/services/ — 60/60 pass (frameDirCache, orchestrator, etc.).
• bunx tsx src/benchmark.ts --tags hdr --runs 1 — both HDR fixtures render successfully, summary table prints PeakRSS/PeakHeap columns, per-run output shows new memory line.
• bunx tsx src/benchmark.ts --tags nonexistent — exits 1 with a helpful message naming the active filters.

Stack

Chunk 8A of plans/hdr-followups.md. First PR in the Chunk 8 perf sub-stack; subsequent PRs (image cache, logger gating) measured against this baseline.

[vanceingalls]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382 👈 (View in Graphite)
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.