Module parity 

The cross-language parity gate (D26, docs/design/11-documentation-plan.md §6.2), and the runner that keeps every example executed.

What this proves

atune’s determinism contract says the parameters of trial n are a pure function of (study seed, n, space). That promise crosses the binding boundary too, because atune_py delegates to core’s optimize_with and the Python sampler factories ignore their seed argument in favour of the study seed (§1.3.6). So the strongest documentation gate available is: the Rust and Python versions of an example must agree on the answer — and not approximately, but bit for bit.

No other HPO framework can run this gate, because none of them promises bit-reproducibility across its bindings.

Why there are two halves

check-parity runs both arms and compares them, which needs a built wheel. check-parity --rust-golden compares only the Rust arm against a committed golden, which needs nothing but the workspace — so it belongs in the fast per-push gate, where a change in optimiser behaviour reddens CI immediately rather than waiting for the documentation job (§11).

The goldens are platform-pinned, and each file says so. A parity block carries float bits, and float bits from cos come from the platform libm, which is not required to be correctly rounded and may differ between platforms (§1.3.19b). Every rust.yml job is ubuntu-latest today (§1.3.23), so one golden per arm is correct and cheap. If the release gate ever gains a second OS, the choice is per-platform goldens or dropping the value line — never a tolerance.

Modules

block

The atune-parity/1 block: its grammar, its parser, and the comparison.

manifest

examples/parity.toml — the single source of what must agree.

Constants

BLESS 🔒

The environment variable that rewrites the goldens.

FACADE_MANIFEST 🔒

The facade’s manifest, where an example declares the features it needs.

GOLDEN_DIR 🔒

Where the committed Rust-arm goldens live, relative to the repository root.

Functions

capture 🔒

Runs a command, requiring exit 0 and returning its stdout.

cargo_example 🔒

Runs cargo run -q -p atune --example <name> and returns its stdout.

check

Runs the parity gate.

check_across_languages 🔒

Runs both arms of one pair and compares their blocks.

check_against_golden 🔒

Compares one Rust arm against its committed golden.

golden_text 🔒

Renders a golden file: the pinning comment, then the block.

libm_identity 🔒

The C library the float bits above came from, as far as it can be read cheaply.

python_origin 🔒

How a Python arm’s failure names itself.

python_program 🔒

The Python interpreter to drive the Python arms with.

required_features 🔒

The features an example declares through [[example]] required-features.

run_examples

Runs every example under examples/rust/.

run_python_arm 🔒

Runs a Python arm and returns its stdout.

run_rust_arm 🔒

Runs a Rust arm and returns its stdout.

rust_origin 🔒

How a Rust arm’s failure names itself.

strip_header_comments 🔒

Drops a golden’s leading # comment lines.