MobileGL/docs/archive/notes/p5e/FLIP-CHECKLIST.md

# P5e wave 3 — integration and the flip, as an executable checklist

Base `7c6f6886`. Integration tree `~/w7/p5e-int` (branch `p5e-wave2-landed`, fetched to the Windows
worktree `MobileGL-disagg` via remote `wslpipe`, pushed to `origin/feat/disaggregated`).
`G` below = `bash /home/swung/w7/notes/tools/p5e_gate.sh int <step>`.

Rulings this implements: ID-111 … ID-123.

## Phase A — land the three packages

| package | tree | scope | brief |
|---|---|---|---|
| `pa` | `~/w7/p5e-pa` | the program family, 69 of 109 red entries, the per-draw pull | `TASK-pa.md` |
| `mv` | `~/w7/p5e-mv` | `MultiDraw.cpp`'s bound-VAO read, 9 entries (ID-113) | `TASK-mv.md` |
| `gl` | `~/w7/p5e-gl` | the gate mechanism + two latent crashes (ID-111/112/115/116/117/118/119/120) | `TASK-gl.md` |

Merge order: `gl` first (it changes the strict knob and the generator, so the other two want to be
measured under it), then `pa`, then `mv`. Expect conflicts only where `pa` and `gl` both touch
`PipeInputs.*`; `gl` was told to stay out of `DirectGLES.cpp` and `MultiDraw.cpp`.

After each merge: `G build`, `G unit`, `G isplit`, `G gpu`, `G gens`. **`gpu` is not optional** —
it is the push-monolith runtime arm and the only thing that would catch an ID-81 violation
(ID-107/109; the last one cost 137 SEGFAULTs across 38 scenarios).

## Phase B — make the lane's claim evaluable, then measure it

1. **Re-take the census on the corrected harness.** The current census re-runs each entry under a
   FIXED environment, which is wrong for 14 of 109 (the `PersistentMapArm.` and `SmallRing.` and
   `NamedBlit.` prefixes carry extra `ENVIRONMENT`). Drive the environment from
   `ctest -L integration-split -N -V` per entry. Until that is done, any marker table is provisional.
2. **The census is a first-fault histogram, not an inventory.** The 62 entries that abort on
   `GetProgramForDraw@DrawArrays` will not go green when that row lands; they will advance to their
   next pull. Budget a second census immediately after `pa` merges, before claiming any distance to
   hard green.
3. Baselines to record BEFORE the flip so the deltas are attributable (all measured green at
   `7c6f6886` by the controls scout, re-confirm after the merges):
   - `MOBILEGL_IPC_RUN_AHEAD=0 ctest --test-dir build-split -L integration-split -j 4` → 116/116
   - `MOBILEGL_IPC_AUDIT=1 ctest --test-dir build-split -L integration-split -j 4` → 116/116
   - `MOBILEGL_IPC_STRICT_ERRORS=1 ctest -L unit` → 2250/2250
   - the default arm's split logs carrying "run-ahead requested … running lockstep"

## Phase C — the things BRIEF §3 asks for that do not exist or are broken

| BRIEF item | real state | action |
|---|---|---|
| §3.4(a) `RUN_AHEAD=0` identical picture | control exists and is green; SSIM harness does not | host-side pixel equality on the lane's readback scenarios is cheaper and stronger than SSIM; write that |
| §3.4(b) `VERB_BARRIER=0` red at a barriered row | `scripts/ci/split_negative_controls.sh` **fails its own check** and demands a `Fatal{BarrierViolation}` that cannot fire at `BATCH_WAITS=1` | ID-122: fix, re-specify, or delete with a named reason. Do not leave it |
| §3.4(c) Magma logs once and runs lockstep | already true and already in every split entry's private log | assert it, no new fixture |
| §3.5 per-package red-once | **not executable** — every candidate is red before the revert (ID-121) | re-sequence after the lane is green; evidence form becomes "the table gains exactly this one pair" |
| §3.6 G1 | the gate configures only `build-split`; no pull flavour exists (ID-123) | integrator runs one `-DMOBILEGL_PIPE_PUSH=OFF` configure+build; packages must write "not verified locally", never "G1 green" |
| §3.7 `MOBILEGL_IPC_AUDIT=1` clean | measured 116/116 today | re-run post-flip, when a present-ahead client is the new consumer of retired staging |

## Phase D — the flip, in one commit

Flip together, never separately:

- `kMGPipeP5eRunAheadReady` — `MG_Backend/Init.cpp:98`
- `kMGPipeP5eClientWaitRuleLanded` — `MG_Pipe/PipeApply.h:969`

and in the SAME commit, ID-111's one-line fix to the barriered stamp
(`MG_Remote/Server/PipeApplier.cpp:1180-1182`), if `gl` has not already landed it. Without it the
Vulkan backend stamps every draw unbarriered while its client is still lockstep and dies on the first
draw.

## Phase E — the device matrix

Four arms, interleaved, 30 s windows, GPU pinned per arm (the pin is lost across app restarts), fan
on, and the core each thread landed on recorded:

| arm | what it answers |
|---|---|
| monolith | the parity target |
| inproc, `MOBILEGL_IPC_RUN_AHEAD=0` | the paired A/B control: identical server code, identical records, the only difference is whether the client waits |
| inproc, run-ahead, `PRESENT_CREDIT=1` | the shipping configuration |
| inproc, run-ahead, `PRESENT_CREDIT=2` | ID-92's measurement arm |

**Do not use `MOBILEGL_IPC_VERB_BARRIER=0` as the control** (ID-114): it is the first conjunct of
`RunAheadArmed()`, so it turns run-ahead off as a side effect, and it aborts within seconds with
`Fatal{UnmigratedPipeInput, "IsCapabilityEnabled@ClientWaitSync"}`.

Acceptance, in order of what actually decides it:

1. `cli` per frame falls from ~916 to the handful of records that stay barriered by ID-84.
2. `rsp` stops scaling with `draws` (it was exactly the draw count under inproc, 0 under monolith).
3. client thread CPU ms/frame falls from 6.1 toward the projected ~3.0 (`PERF-PROFILE-7c6f6886.md` §5).
4. fps, last, and only compared within one interleaved session.

## Phase F — docs

`CURRENT_STAGE_PROGRESS.md` §2.5, `MEASUREMENTS.md` §10, `ROADMAP.md`'s P5e row, and a P5e report.
The perf story belongs in the report, not scattered: `PERF-BASELINE-7c6f6886.md` and
`PERF-PROFILE-7c6f6886.md` are its raw material.