an.bench.environment

The environment tuple — the fields that decide whether two rows may be compared.

Split into two halves with different comparison rules, because the two sides of the pipeline were measured and their answers are opposite:

Render side — comparable on any machine. Both render paths, four machines (local arm64 macOS, macos-latest, ubuntu-latest x86-64, ubuntu-24.04-arm), 132 frames each: zero differing pixels and zero differing PNG bytes, across two different SwiftShader JIT backends. So the render-side metrics need no cross-machine band column, and the golden corpus can be a CI gate. Record the Chromium build and the **launch argv verbatim** — all four rasteriser configurations report a byte-identical UNMASKED_RENDERER_WEBGL string, so the renderer string is demonstrably blind to the choice it was proposed to guard.

Encode side — machine-scoped, not bandable. Same ISA + same x264 build is byte-identical; a different ISA moves the decoded stream a little (luma <=2.66% of samples); a different x264 build moves it by two orders of magnitude (up to 99.2% of samples, mean |d| 3.94, max 36). A band that wide would swallow flat_field_deviation’s entire crf18->23 signal. So --compare (an#40) must refuse rows whose x264_sei or isa differ, in the same way it refuses rows with a different scene_contract_sha256 — the number is uninterpretable, not good or bad.

Module Attributes

RUNTIME_DIGEST_SUFFIXES	_stage_job's shutil.copytree is a bare copy that DOES deliver everything under the runtime dir into the staged tree, so "what gets staged" cannot be the reason to exclude anything — the real reason is "what the page loads": index.html/preview.html pull in .js (including vendor/), .css and .json, and nothing else under the tree is read by the browser (an#141).
RUNTIME_IGNORED_SUFFIXES	Suffixes under the runtime dir that are known to be non-runtime — excluded from the digest on purpose, not by omission.

Functions

environment_record(*, pix_fmt[, x264_sei, ...])	Everything about this machine that could plausibly move a number.
ffmpeg_identity()	The ffmpeg build banner.
home_relative(path, *[, home])	path with the user's home directory spelled ~.
probe_browser()	Launch Chromium with the render path's own flags and read back its identity.
runtime_sha256()	A digest of the JS runtime the renderer will stage, files and names.
tool_version(name)
x264_sei(mp4)	The encoder build + thread count, read straight out of the file.

an.bench.environment.RUNTIME_DIGEST_SUFFIXES = ('.js', '.html', '.css', '.json')

_stage_job’s shutil.copytree is a bare copy that DOES deliver everything under the runtime dir into the staged tree, so “what gets staged” cannot be the reason to exclude anything — the real reason is “what the page loads”: index.html/preview.html pull in .js (including vendor/), .css and .json, and nothing else under the tree is read by the browser (an#141). Package metadata (__init__.py), docs (README.md), vendor licence text can change — a stray .DS_Store included — without the page the renderer loads changing at all, and hashing them anyway made the digest answer “did the runtime change” wrong.

Type:

Suffixes runtime_sha256 hashes. Deliberately narrow

an.bench.environment.RUNTIME_IGNORED_SUFFIXES = ('', '.py', '.pyc', '.md', '.txt')

Suffixes under the runtime dir that are known to be non-runtime — excluded from the digest on purpose, not by omission. "" covers extension-less dotfiles (.DS_Store, the one this issue was filed over); .pyc covers a stray __pycache__/*.pyc from __init__.py (the issue’s other named example — reproducible on this very tree). test_bench_environment.py fails on any suffix that lands in neither this set nor RUNTIME_DIGEST_SUFFIXES, so a future runtime asset (an .svg, .woff, .wasm, .mjs) cannot silently fall outside what the digest sees (an#141).

an.bench.environment.environment_record(*, pix_fmt, x264_sei=None, browser=None)

Everything about this machine that could plausibly move a number.

browser lets the caller supply an already-taken probe. The golden gate needs the Chromium build before the run-level provenance is assembled — the path keys on it — and probing twice would launch a second browser and could, in principle, report a different build from the one that rendered.

pix_fmt is required and has no default, because it is a **comparability key** and the caller is the only one who can measure it. It must be the format the delivered files actually are — imageio.delivered_pix_fmt — and not a re-derivation, for the reason an#72 records: the delivered encode resolves its format from RenderContext.pix_fmt or the module global, so reading either one is a second source of truth that can disagree with the file, and this field is what bench-compare uses to decide whether two encode-side rows may be compared at all.

Return type:

dict[str, Any]

an.bench.environment.ffmpeg_identity()

The ffmpeg build banner. Informational — the x264_sei is the key.

Return type:

dict[str, Any]

an.bench.environment.home_relative(path, *, home=None)

path with the user’s home directory spelled ~.

Ledger rows are committed to a public repository, so a row must not carry the absolute path of the machine that wrote it. Provenance only: nothing compares on this field. POSIX-spelled on every platform.

Return type:

str

>>> home_relative("/home/u/.cache/ms-playwright/chrome", home=Path("/home/u"))
'~/.cache/ms-playwright/chrome'
>>> home_relative("/opt/chrome", home=Path("/home/u"))
'/opt/chrome'

an.bench.environment.probe_browser()

Launch Chromium with the render path’s own flags and read back its identity.

Never raises: a probe that crashes must not cost a caller a completed capture, and a recorded error is more honest than a missing field that reads as “nothing to report”.

Return type:

dict[str, Any]

an.bench.environment.runtime_sha256()

A digest of the JS runtime the renderer will stage, files and names.

Provenance, NOT a comparability key: the runtime is the code under test, and two rows rendered by different runtimes are exactly what an bench --compare exists to compare. What it buys is that a render-side mutation leaves a fingerprint in the row — before this, the disabled_aa lever had no way to prove it applied, and assert not report["mutation_may_not_have_applied"] asserted nothing for it (an#41 review).

Only files whose suffix is in RUNTIME_DIGEST_SUFFIXES are hashed, so a file that is not staged as a runtime asset — a stray .DS_Store, a __pycache__ entry, package metadata — cannot move the digest (an#141).

Return type:

str

an.bench.environment.x264_sei(mp4)

The encoder build + thread count, read straight out of the file.

Return type:

str | None