psxrecomp/docs/HOST_OPTIMIZATION_CONTRACT.md

Host optimization contract

This document is the acceptance contract for changes intended to make psxrecomp run faster on the host. It applies to generated code, the runtime, the flat CPS trampoline, overlay dispatch and validation, graphics and audio support code, and host-side caches or fast paths.

Correctness fixes and deliberate guest-visible enhancements still need focused verification, but the 5% performance retention gate below applies specifically to optimizations.

Non-negotiable rules

1. Measure on a quiet host with zero compiler processes. Finish all AOT, overlay, shader, and helper compilation before the timed region. Confirm that no compiler, linker, build driver, or autocompile worker is alive while sampling. A run in which one appears is contaminated and is discarded, not explained away.
2. Interleave A and B. Never measure all baseline runs and then all candidate runs. The minimum acceptable order for three pairs is A1 B1 A2 B2 A3 B3; reversing the first member of alternate campaigns is encouraged. Keep the same binary and use a forced runtime selector when practical.
3. Report every raw run, the min-of-N for A and B, the percentage change between those minima, both medians, and the percentage change between the medians. N is at least three. State whether lower or higher is better.
4. Discard a pair when either member is contaminated. Reasons include a compiler process, overlay compilation, shader-cache construction, a changed power or thermal state, unexpected foreground load, a different overlay population, or a different pacing owner. Record the discarded pair and its reason in the experiment ledger.
5. A candidate that adds complexity, persistent state, generated-code ABI, configuration or debug ABI, or another maintained fast path is retained only when the agreed primary metric improves by at least 5%. A pure simplification may be retained at flat cost, but its measured numbers must still be recorded. Correctness fixes are judged on correctness, not this speed threshold; do not disguise an optimization as a correctness fix.
6. With the optimization forced on for every eligible operation, guest-visible state must be byte-identical to the faithful path at deterministic checkpoints. An automatic fallback is not proof: it can hide the exact case the fast path mishandles.
7. The faithful reference computation remains linked and selectable. A fast path is an implementation of that same computation, not a replacement model that merely looks plausible for one title.
8. Do not copy another console project's opcode handlers. It is valid to reuse its experimental process, evidence format, test structure, or review checklist. Implement R3000A behavior from PlayStation evidence and psxrecomp's own faithful path.

Preparing comparable psxrecomp runs

Prefer one executable containing both paths and an explicit selector with three states: faithful, candidate forced on, and normal policy. Record the selector and assert in telemetry that the requested state took effect. If two binaries are unavoidable, build both before the campaign and record their commits, toolchains, options, and artifact hashes.

Static recompilation makes build quietness part of the benchmark definition. Pre-generate the game and BIOS images, warm every overlay needed by the workload, and prevent runtime autocompile during the measured interval. Record the static image identity and the exact overlay inventory. A benchmark is not comparable if A interprets an overlay while B uses a compiled shard.

Content-verified overlay variants require an additional check. A and B must use the same captured bytes, identity ranges, flavor, cache generation, and selected variant at each checkpoint. Pin and report the overlay flavor. A fast identity check may avoid a CRC or range scan, but the faithful verifier must remain callable and both must select the same content-verified variant.

The flat CPS trampoline is part of observable execution semantics. Compare the published continuation PC, dispatch result, exception redirect, dispatch depth, and same-site resume consumption at block and function boundaries. A host function returning with cpu->pc == 0 is not equivalent to tail-publishing the next guest PC, even if common images never cross that boundary.

Use a deterministic workload with fixed inputs and a fixed capture or replay when possible. Keep renderer, audio backend, window state, display refresh, vsync/pacer ownership, guest cycle scale, CRTC multiplier, mods, RAM size, and instrumentation identical. Warm caches outside the timed region unless cold behavior is the stated metric.

Correctness proof

The forced-candidate run must exercise the candidate, and its checkpoints must match a run forced through the faithful reference. Hash or serialize all state that can affect later guest execution, including:

• GPR, HI/LO, PC, COP0, GTE registers and completion timestamps;
• main RAM, scratchpad, VRAM, SPU RAM, and relevant device registers;
• the R3000A cycle counter, deferred cycle charges, event deadlines, IRQ state, load-delay state, and pending exception continuation;
• dispatch and overlay identity state that changes which guest bytes execute;
• deterministic mod-owned guest state and savestate-visible sections.

Host-only counters may be excluded only when they cannot influence selection, timing, invalidation, or later guest state. Document every exclusion.

Compare at more than the final frame. Include checkpoints before the candidate first fires, immediately after it fires, at overlay or exception boundaries it touches, and after a long soak. For caches and memos, force hits, misses, invalidation, wrap or saturation, and savestate/rewind restore. For generated code, cover the game emitter, BIOS full-function emitter, compiled overlays, static overlay bakes, and the dirty interpreter wherever the contract crosses execution tiers.

For cycle-affecting work, use tools/cycle_testrom/measure.py as the existing measurement seam. Run the same test-ROM anchors against the native compiled path, PSX_FORCE_INTERP=1, and the Beetle oracle as applicable. The script's per-iteration deltas establish guest-cycle correctness; they do not replace a separate interleaved wall-time or throughput campaign for host performance. The faithful per-instruction R3000A cycle model remains authoritative: an optimization may reduce host work but may not remove base charges, wait states, interlocks, GTE completion timing, I-cache behavior, or peripheral deadlines.

Performance campaign and evidence

Choose the primary metric before running the campaign. Frame or workload time is preferred when the work is bounded; throughput is acceptable for a fixed steady-state loop. Report secondary metrics, but do not change the retention decision after seeing the results.

The evidence block for every candidate contains:

Candidate: <short name>
Commits/artifacts: A=<hash> B=<hash> selector=<setting>
Workload: <capture, interval, overlay inventory, backend and host>
Primary metric: <name and unit; lower/higher is better>
Run order: A1 B1 A2 B2 A3 B3
Raw A: <a1>, <a2>, <a3>
Raw B: <b1>, <b2>, <b3>
Min-of-3: A=<min-a> B=<min-b> change=<percent>
Medians: A=<median-a> B=<median-b> change=<percent>
Correctness: faithful=<hashes> forced-on=<hashes> result=<identical/not identical>
Contamination: <none, or discarded pairs and reasons>
Complexity/ABI: <none, or exact added surface>
Decision: ACCEPT/REJECT - <reason>

Worked example, using workload time in milliseconds where lower is better:

Run order: A1 B1 A2 B2 A3 B3
Raw A: 12.000, 11.000, 13.000 ms
Raw B: 9.744, 9.493, 10.100 ms
Min-of-3: A=11.000 B=9.493; improves 13.7%
Medians: A=12.000 B=9.744; improves 18.8%
Correctness: faithful=7a... forced-on=7a...; byte-identical
Complexity/ABI: two per-variant words plus one generated helper call
Decision: ACCEPT - both summaries exceed the 5% retention gate

Do not report only a profiler share, a best screenshot, an FPS range, or a sequential before/after observation. Those are useful for finding candidates, not for accepting them.

Experiment ledger

Every investigated candidate gets a ledger row, including rejected, superseded, reverted, and flat candidates. The ledger is append-only evidence, not a highlights page. Keep it beside the optimization or campaign notes and include links to raw data when available.

Required fields are:

Field	Required contents
ID and date	Stable candidate ID and campaign date
Change	Commit(s), artifact hashes, selector, and concise hypothesis
Scope	Workload, renderer/audio backend, host, toolchain, config, overlay inventory and flavor
Correctness	Faithful and forced-on checkpoint hashes; exact exclusions
Runs	Interleaved order, all raw accepted runs, and every discarded pair with reason
Summary	A/B min-of-N and medians with percentage changes
Cost	Added code, state, ABI, configuration, maintenance burden, or simplification
Verdict	Accepted or rejected, threshold used, and reason

Accepted and rejected results are equally visible. A compact ledger index may look like this, with each row linking to its full evidence block:

ID	Min-of-N change	Median change	State result	Cost	Verdict
EX-A	improves 13.7%	improves 18.8%	byte-identical	two per-variant words and one helper call	ACCEPT - clears 5%
EX-R	improves 3.0%	improves 1.0%	byte-identical	new cache and invalidation path	REJECT - below 5%

Use an explicit rejected entry even when the candidate was reverted before a formal campaign. Record the numbers that motivated the experiment and state which required evidence is missing. Do not silently delete failed ideas: the ledger prevents the same attractive but invalid optimization from being tried again without new evidence.

Review checklist

• Host was quiet and had zero compiler processes during every retained run.
• A/B was interleaved; contaminated pairs were discarded and recorded.
• Raw runs, min-of-N, and medians are present.
• The forced candidate and faithful reference produced byte-identical guest-visible state.
• The faithful path remains linked and selectable.
• Overlay identities and execution tiers were held constant and reported.
• Cycle-model changes were checked through the cycle-test-ROM seam.
• Added complexity or ABI clears 5%; flat pure simplifications have numbers.
• Accepted and rejected candidates are both in the experiment ledger.
• R3000A implementation was derived independently; no other console's opcode handlers were copied.