feat(perf): v1.19.0 "Afterburner" - PGO/BOLT pipeline

[doublegate]

Summary

• New scripts/pgo/run.sh: instrument → train against the committed permissive ROM corpus (via
  a new crates/rustysnes-test-harness/src/bin/pgo_trainer.rs binary — the gilyon
  CPU-instruction suite plus a handful of undisbeliever HDMA-glitch/INIDISP-hammer ROMs for
  control-flow breadth beyond the single steady-state headless_frame bench ROM) → optimized
  rebuild of the shipping rustysnes binary.
• New .github/workflows/pgo.yml: workflow_dispatch + release-tag push only — never the PR
  gate, since an instrument+train+rebuild cycle is far too slow for that. Promotion requires
  both: a measured >3% Criterion speedup over the plain release build on the same runner,
  and a byte-identical re-run of the full --features test-roms oracle under the PGO-merged
  profile (cites docs/adr/0004's determinism contract — never promotes on speed alone). An
  optional Linux-only BOLT post-link stage chains onto an already-promoted PGO binary,
  best-effort.
• Found and fixed a real, latent CI gap while building this: rust-toolchain.toml didn't
  list llvm-tools-preview, and dtolnay/rust-toolchain silently ignores the rust-setup
  composite action's own components: input whenever a rust-toolchain.toml file exists (the
  same class of bug already found and fixed for ios.yml in v1.16.0) — without this fix,
  cargo-pgo's .profraw/.profdata merging would have silently failed to find the component
  on a fresh CI runner.

Test plan

• cargo test --workspace --exclude rustysnes-android — all green
• cargo clippy --workspace --exclude rustysnes-android --all-targets -- -D warnings — clean
• cargo fmt --check — clean
• RUSTDOCFLAGS="-D warnings" cargo doc --workspace --exclude rustysnes-android --no-deps — clean
• cargo build -p rustysnes-core --target thumbv7em-none-eabihf --no-default-features — no_std gate green
• cargo deny check / cargo audit — clean
• actionlint .github/workflows/pgo.yml — clean
• Real, full local pipeline run: scripts/pgo/run.sh 60 produces a genuine, running
  PGO-optimized rustysnes binary (instrument build → pgo_trainer over all 5 committed ROMs →
  optimized rebuild).
• Real determinism-gate run: cargo pgo optimize test -- -p rustysnes-test-harness --release --features test-roms passes cleanly under the PGO-merged profile (golden
  framebuffers, SA-1/Super FX on-cart boots, save-state determinism/backward-compat, SPC700
  oracle all pass).
• Real A/B Criterion comparison: plain vs PGO headless_frame_steady_state — documented
  honestly in docs/performance.md (short local training run did not clear the >3% bar; this
  is expected, not a bug — CI's real 3600-frame sweep is what the promotion gate actually
  decides on).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a Profile-Guided Optimization (PGO) and BOLT pipeline for the shipping rustysnes binary, adding a new training-workload binary (pgo_trainer.rs), a runner script (scripts/pgo/run.sh), documentation updates, and adding llvm-tools-preview to rust-toolchain.toml. The review feedback correctly points out that on standard Rust setups, cargo build compiles binaries directly into target/release/ rather than target//release/, which would cause the runner script to fail with a 'No such file or directory' error. The reviewer provides robust fallback suggestions to dynamically resolve these paths.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

Adds an opt-in Profile-Guided Optimization (PGO) + optional BOLT pipeline for the shipping rustysnes binary, including a dedicated CI workflow to build, benchmark (A/B), and enforce the project’s byte-identical determinism contract before any optimized artifact is considered promotable.

Changes:

• Introduces a local PGO driver script (scripts/pgo/run.sh) and a committed-ROM training binary (pgo_trainer) to generate representative profiles deterministically from the permissive ROM corpus.
• Adds a dedicated GitHub Actions workflow (pgo.yml) that runs only on manual dispatch or release tags and gates promotion on both speedup (>3%) and a full --features test-roms byte-identical oracle.
• Updates toolchain/docs/changelog to document and support the pipeline (including adding llvm-tools-preview to the pinned toolchain components).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
scripts/pgo/run.sh	Local instrument → train → optimized rebuild recipe for rustysnes using committed ROMs.
rust-toolchain.toml	Adds llvm-tools-preview to the pinned toolchain components for profiling tooling support.
docs/performance.md	Documents the new PGO/BOLT pipeline and the CI promotion criteria (speed + determinism).
crates/rustysnes-test-harness/src/bin/pgo_trainer.rs	Adds a training workload binary that runs multiple committed permissive ROMs for profile breadth.
CHANGELOG.md	Records the new pipeline and the CI/toolchain gap fix under Unreleased.
.github/workflows/pgo.yml	Adds the non-PR-gated CI workflow implementing the PGO promotion gate and optional BOLT stage.