perf(checks): add a reproducible cold camera evidence benchmark

[Galabavamsi]

Summary

• add a deterministic cold camera_frame_stats benchmark with default 1080p30, quick, and per-filter profiling modes
• time canonical transformation separately and use a fresh episode workdir for every cold check
• report FFmpeg/CPU provenance, decoded frames, and instrument-cache sizes
• document the measured bottleneck and why the shipped filter graph remains unchanged

Why

Issue #365 asked for a reproducible benchmark and a safe speedup if one could be demonstrated. Profiling shows signalstats=stat=tout+brng dominates the evidence pass. Thread-count, branched-graph, and CUDA controls did not produce a repeatable semantics-preserving improvement, so this keeps product behavior unchanged and contributes the durable measurement requested by the maintainer.

Closes #365

Validation

• uv run ruff check --fix — passed
• uv run ruff format --check — 208 files already formatted
• uv run ty check — passed
• uv run pytest -q — 1410 passed, 6 skipped
• uv run python benchmarks/camera_frame_stats_benchmark.py --quick --profile-filters — passed
• uv run python benchmarks/camera_frame_stats_benchmark.py --profile-filters — all three cold 1080p30 checks decoded 900 frames; 4.897 s median
• lychee --no-progress --include-fragments docs/BENCHMARKS.md — 3 links passed
• pre-commit ruff check and ruff format hooks — passed

Checklist

• I added or updated outcome-focused tests for changed business logic.
• I updated documentation for changed behavior, flags, formats, or requirements.
• I ran uv run ruff check --fix, uv run ruff format, and uv run ty check.
• I ran the relevant pytest suite.
• I did not add recordings, generated media, credentials, private URLs, or runtime artifacts.
• I preserved stored-data compatibility or documented an explicit version change.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Galabavamsi]

@kstonekuan need your review for this pr

[kstonekuan]

LGTM, merging. This is the resolution I said would be legitimate on #365, and it is worth more than a speedup would have been.

Reproduced the whole thing on different hardware and a different FFmpeg build (n8.1.2-44 against your n8.1.2-50, 22 logical CPUs against your 16):

                                        yours     mine
transform to canonical                  3.510 s   4.445 s
cold camera_frame_stats median          4.897 s   8.294 s
decode only                             0.422 s   0.695 s
decode + signalstats=stat=tout+brng     4.536 s   7.909 s
complete shipped graph                  4.711 s   8.145 s

Absolute numbers differ, as they should, and the finding does not: signalstats is essentially all of the cost above decode, 97% of the graph's margin over decode only on my machine against 96% on yours. Decode is under a tenth of it either way.

The stronger corroboration is accidental. When I accepted #365 I measured a synthetic 1080p30 cold check at 8.3 s with a throwaway script of my own; your benchmark reports 8.294 s on the same machine. Two independently written measurements of the same quantity agreeing to the noise is what makes this a baseline rather than a number.

The test is the part I would have asked for and did not have to. It runs the benchmark's machinery over a 160x90 one-second fixture in 1.36 s rather than importing 1080p into the suite, and this assertion is the one that matters:

assert len({run.instrument_cache_path.parent for run in result.check_runs}) == 2

A benchmark whose "cold" runs quietly share a workdir measures a cache hit and reports it as a decode. That line is what stops this baseline rotting into a lie, and it is why the docstring's "reusing one workdir breaks this result" is a claim rather than a hope.

Three smaller things I checked. The script writes only into a TemporaryDirectory, so a run leaves the tree clean. benchmarks/ is covered by ruff and ty like everything else. And the new table slots into the existing BENCHMARKS.md summary rather than starting a parallel document.

The negative result is written the right way round: what was tried, what it measured, and why a luma-only input is not a free win because BRNG deliberately reads all three planes. "Keep the measurement path unchanged" backed by controls is a finding, and the next person who wants to optimise this now has to beat a number instead of arguing with an impression.

Gate clean: ruff check, ruff format --check, ty check, 1410 passed / 6 skipped.

Closing #365 on this is right, and to be explicit about why: its DoD asked for a speedup, and I said when accepting it that a documented "no safe win available" would be a legitimate resolution. That was the maintainer position before you started, not a bar being moved afterwards.