DKR-R surgical performance qualification
======================================

This is a beta 10 qualification build, not a claim of measured FPS gains.
No game, replay, benchmark, or unit test was executed by the build pipeline.
Gameplay and visual acceptance remain with the owner.

Included
--------
* Flow interpolation reuses dense bounded sample storage instead of allocating
  hash-map nodes every source frame. Sample identity, UV maths, wrap handling,
  duplicate-view conflict checks and scene/rollback resets are preserved.
* Water material lookup uses a contiguous index for larger binding tables.
  Exact raw pointer comparison and FIRST-match semantics are preserved,
  including duplicate pointers and invalid texture IDs. Allocation failure
  falls back to the original scan. Small tables keep the original scan.
* DKR's existing CPU PNG mip generator reuses scratch storage. The same
  downsample loop, alpha weighting, odd-size partitioning and GPU upload code
  are retained. CPU payload retention is capped at 8 MiB per worker; larger
  images release their CPU scratch after upload preparation. Re-entry uses a
  separate local workspace. Native resource/fallback checks are unchanged.
* Custom Magic Code checkpoint serialization reserves its EXACT final size
  before writing. Field order, endianness, permissions and checkpoint padding
  are unchanged. It still returns an owned byte buffer; it does not share
  mutable checkpoint memory or skip captures, validation or hashes.
* Presentation-only waits use steady_clock with the accepted calibrated
  short-sleep/spin tail and the existing Windows kernel wait. The original
  source timestamp is used only to detect thread/owner changes, not to
  calculate elapsed pacing time. All GPU waits and queue capacities remain.

Unchanged
---------
Game/VI/audio/input/network clocks, user frame-rate targets, graphics quality,
water and lava shaders, memory safety checks, save formats and ownership,
mod APIs/permissions, rollback rules, snapshots and lease retirement. The
checked-out submodules and generated guest sources are untouched.

Optional diagnostics
--------------------
Windows: launch Record-Performance.cmd from the extracted package instead of
DKR-R.exe for a diagnostic session. It enables logging for that child process
only. Choose your normal scenes/settings, play, and close normally. Launch
DKR-R.exe for normal play. The build pipeline has NOT run this launcher.

Linux: run the AppImage with these temporary environment variables:
  DKR_SURGICAL_PROFILE=1 DKR_POWER_PROFILE=1 DKR_TRACK_PROFILE=1 DKR_ROLLBACK_PROFILE=1 ./DKR-R-1.0.7+beta.10-Linux-x86_64.AppImage

Compare the same short route with equivalent settings and a normal warm-up.
Capture the loading/resize case separately. New diagnostics also participate
in the existing performance_capture API where it is wired (Android); desktop
support buttons do not currently expose that API, hence the explicit launcher.
No environment or graphics settings are saved by these diagnostic launch flags.

[perf][surgical-present] reports 300 successful swapchain-return intervals,
p50/p95/p99/max and counts over 1.5/2 times the selected frame budget. It
excludes the first half second after a viewport/target/observed-scene change.
Producer-scene is the latest frontend observation, NOT an exact GPU scene tag.
These are NOT physical scanout timestamps. Scene/load/resize acceptance must
also examine the normal unsuppressed capture, not just the stable window.

[perf][surgical] reports bounded CPU WALL-time histograms for decoder, registry
and liquid warmup. Nested/concurrent times are not additive CPU utilisation.
Percentiles are labelled upper bounds; max-us is the actual observed maximum.

A/B and rollback switches
------------------------
Set any of these to 0 BEFORE launching to use that component's accepted path:
  DKR_PERF_FLOW_REUSE=0
  DKR_PERF_TEXTURE_INDEX=0
  DKR_PERF_MIP_SCRATCH=0
  DKR_PERF_MONOTONIC_PACER=0
No environment changes are persisted by the application. Existing settings,
saves, mod packages and texture packs are not rewritten by these switches.
The exact-size checkpoint reserve has no byte-level or gameplay effect; the
prior complete package remains the full rollback for this source-only change.

Owner acceptance matrix
-----------------------
Compare equivalent scenes/settings, with cold and warm visits separated:
* 60/120/180 FPS; windowed/fullscreen; resize, minimise and restore.
* 4:3, 16:9 and ultrawide; ordinary and high FOV.
* Hub, Whale Bay, Pirate Lagoon, Hot Top Volcano, waterfalls/rivers.
* Intro logos, start-menu text, complete credits and black fades.
* Stock content, HD textures, dkrmap/legacy tracks and SDK 1/2 code mods.
* Offline and Experimental Rollback; 2/3/4-player local views; ModernCamera++
  with and without camera replacement. Check shadows and interpolated UVs.
* Water effects off/on and each reflection mode; do not lower quality to
  manufacture a reported improvement.
* Confirm saves/audio/controller input and online determinism remain intact.

Compare frame-interval tails, missed deadlines, CPU/GPU timings, latency,
allocation reuse and memory high-water marks; average FPS alone is insufficient.
No performance claim should be accepted without repeated comparable captures.

Gated follow-up (not silently enabled in this build)
--------------------------------------------------
Persistent mip disk caching, upload batching, event-driven online loops, direct
checkpoint serialization, static/dynamic geometry separation, reduced optical
buffers, GPU pass elision, camera range copies, resource rings and compiler/LTO
experiments require owner capture evidence and acceptance of this baseline.
They are deliberately NOT implemented as speculative changes to the stable
renderer. No GPU fence is removed and no source-frame debt is accumulated.
