daniel-lynch--ovrplugin-openxr-shim/docs/handoffs/HANDOFF-2026-06-26-skipblack.md

# RE4 VR Shim — Handoff (2026-06-26, skipblack instrument session)

Continuation of `HANDOFF-2026-06-26.md` (morning). Branch `latency-perffix-copyring`.
This session built + ran **Lever 2 step 1 (instrument-only black-frame detector)** and
validated the signal is real but coarse. Detailed finding in auto-memory
`skipblack-posthitch-signal-validated`. Design: `docs/research/lever2-detect-skip-black-handoff.md`.

## TL;DR — the post-hitch black signal is REAL but needs a tighter gate + frame-accurate proof
Added `debug.re4vr.skipblack 1` (instrument-only): after a HITCH (dt>20ms), flag the next
`skipblackn` frames as LIKELY-TRUNCATED and log them. NO behavior change at level 1. Ran on
device (standing, walk off bridge into house). 47 HITCHes / 89 flagged frames. Result:

- **The truncated/black frame has a signature: a SHORT (<12ms) frame right after a big hitch**
  — it finishes fast because UE rendered almost nothing into it (matches RenderDoc 28-vs-198
  draws → pure black).
- **Big hitches (≥40ms): 25, of which 52% have that <12ms truncated recovery frame.**
- **Mild hitches (20–40ms): 22, only 5%** — these recover to a full ~14ms frame = a 1-frame
  judder, NOT black. The current heuristic OVER-flags these.
- HITCH magnitudes span 20ms → 3.8s. The multi-hundred-ms / multi-second ones are
  **load/streaming stalls** (level transitions) — a different event from per-frame gameplay
  black drops. Must be separated from the gameplay black.
- Ground truth is still COARSE: user confirmed "black" happened, but not frame-accurate; the
  short-dt=black link rests on the single RenderDoc capture, not per-frame verified.

Raw frame/flag sequence persisted: `analysis/skipblack-2026-06-26/frame-sequence.log`.

## NEXT TASK — do BOTH (user decision this session):
### (3) Tighten the detector, then re-instrument
- **Gate the arm on hitch ≥40ms** (drops the 22 harmless mild hitches; ~halves false flags).
- **Add short-dt confirmation:** only treat a post-hitch frame as truncated if its own
  dt < ~12ms. Combines the two corroborating signals; cuts the ~48% of big hitches whose
  recovery wasn't short (those may be a different failure mode — investigate separately).
- **Handle sustained-overload clusters** (e.g. f=3162–3173: ~10 consecutive hitches). The
  fixed "next 2 frames" model is wrong there — the whole burst is bad. Consider: stay armed
  while consecutive frames keep hitching, not a fixed count.
- Re-run instrument-only and re-inspect (reuse the awk recipes from this session's analysis).
- Code is all in `shim/src/xr_runtime.c`: `skipblack_level()`/`skipblack_count()` (~205) and
  the flag block inside the FRAME/HITCH trace (~1186, look for `SKIPBLACK: LIKELY-TRUNCATED`).

### (2) Frame-accurate ground truth via Meta Cast (do alongside / before reproject)
- In-game recording is broken (empty mp4); display 0 is FLAG_SECURE so scrcpy/screenrecord
  can't see VR. Use **Meta Cast → desktop screen-record** while walking off the bridge.
- Run with `skipblack=1 skipblackn=2 trace=1`, capture logcat with timestamps in parallel.
- Align the video's visible black flashes to the `SKIPBLACK: LIKELY-TRUNCATED` log
  timestamps to PROVE (or refute) flag == perceived black, per frame. This is the
  `verify-before-theory` discipline — don't build the reproject on the coarse signal alone.

### THEN — Lever 2 step 2 (reproject, `debug.re4vr.skipblack 2`)
Only after (2)+(3). Re-present the **last-good** eye image with the current pose so the
OpenXR compositor timewarps it instead of showing black.
- **Use the COPY-ring, NOT a cross-frame swapchain hold** — holding across frames is what
  sank `pipeline=1` (see memory `deferred-flush-unstable-abandoned`). Copy last-good eye →
  shim VkImage (`xrr_vk_alloc_images`/`shimImages[]`, copy path in end_frame ~922), blit it
  into the acquired image on a flagged frame, submit the composition with the CURRENT pose.
- Low harm on false positives: reprojecting a stale frame ≈ what the compositor already does
  during the hitch, so over-flagging mild hitches is tolerable but wasteful — the ≥40ms gate
  keeps it clean.
- Success = black flashes replaced by (at worst) brief reprojection judder, not black.

## Build / deploy / test (unchanged)
```
./shim/build_android.sh && ./packaging/repack.sh      # repack bundles LAST build — check
                                                       # shim/build/arm64/libOVRPlugin.so timestamp
adb -s <redacted-serial> install -r packaging/out/re4vr-shim.apk
adb -s <redacted-serial> logcat | grep -iE "xrr|SKIPBLACK"
```
Launch is BLOCKED by the controllers-asleep system dialog
(`app_launch_blocked_controller_required`) — wake controllers + headset on before
`am start -n com.Armature.VR4/com.epicgames.ue4.GameActivity`.
Logcat is dominated by PerfMetrics polling — filter to `FRAME f=|HITCH|SKIPBLACK` for pacing.

## Props
- `debug.re4vr.skipblack 0|1|2` — 0 off / 1 instrument-only (built) / 2 reproject (TODO).
- `debug.re4vr.skipblackn N` — post-hitch frames to flag (default 2). Will change with the
  cluster-aware rewrite in (3).
- Reset to baseline now: skipblack=0, skipblackn=0, trace=0, ffr=2, resscale=100.

## State
- Code committed? **NO — `skipblack` detector is UNCOMMITTED** in the working tree
  (`shim/src/xr_runtime.c`). Commit it (instrument-only, gated off, safe) before further work.
- Branch `latency-perffix-copyring`, clean except the skipblack edit + the new analysis dir.