Files
MobileGL/docs/Disaggregated/notes/recovered/wf5/.partD.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

252 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
## D. Integration order, and what the integrator runs
### D.0 Preconditions
- The baseline captures of §A (`~/w7/p2-before-libMobileGL.so`, `~/w7/p2-before-ctest-names.txt`, `~/w7/p2-before-syncrenderstate.sha`, `~/w7/p2-before-dirty-surface.txt`), taken in `~/w7/pipe` at `48268068` **before any package lands**.
- `~/w7/pipe` clean at `48268068`; fixture binaries hidden the way `wsl_p2_tree.sh` does it (`git update-index --assume-unchanged` on `tools/trace_replay/fixtures`).
- `~/w7/retrace_gate.py` copied from `scratchpad/wf2/retrace_gate.py`.
- Both devices reachable and **not** locked by the GL4.6 Wave-7 campaign (`ls .../8ab6b3cb-.../scratchpad/w7/locks/`).
### D.1 Order: **contract → tracker → magma → espryt → gates**
Reason for that order, and it is not P1's by default:
- `contract` first because everything else compiles against it.
- `tracker` second because it is the only package that changes semantics; after it, both backends are still reading the same bytes they read before, through unmodified code. If `tracker` is wrong, the verify lane says so before any backend has been touched.
- `magma` third rather than last, because D's `m1`/`m2` (the render-state re-key) is the deliverable the day-43 number depends on and it is the one most likely to need iteration; `m3`/`m4` (subsystem 4) then land against a Magma that is already CSO-keyed.
- `espryt` fourth: Espryt needs **zero** render-state change by construction (G5), so C is purely Track H and is independent of everything except the contract.
- `gates` last, so its lanes assert against the finished tree — except `HandleRecycleScenario`, whose `AbaControl` red is recorded on the contract tree at D.2.
Copy `scratchpad/wf2/wsl_integrate_p05.sh` → `wsl_integrate_p2.sh` (`p05`→`p2`). Per slug: rebase `p2/<slug>` onto `feat/disaggregated` in its own worktree, `git merge --ff-only` in `~/w7/pipe`, then:
```sh
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
python3 scripts/gen_pipe_dirty_surface.py --check # from `tracker` onward
python3 scripts/check_include_closure.py
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so \
--threshold 0 --markdown ~/w7/p2-symbol-<slug>.md
# 0 added / 0 removed / 0 renamed after every merge; resized ⊆ the three RenderState symbols of D15
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty
awk '/namespace RenderStateImpl \{/,/\} \/\/ namespace RenderStateImpl/' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum
# equal to ~/w7/p2-before-syncrenderstate.sha after EVERY merge (G5)
ctest --test-dir build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort | comm -23 ~/w7/p2-before-ctest-names.txt - # empty
```
### D.2 On the contract tree, before `tracker`: record the "red before" evidence
```sh
cd ~/w7/p2-gates && cmake --build build-verify --parallel 28
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure | tee ~/w7/p2-handlerecycle-before.log
# .AbaControl PASSES (it asserts the corrupted pixels), .Legacy PASSES, .Handles SKIPs
```
That log is the artefact `ROADMAP.md:18`'s "重键前红" asks for. Keep it; it goes into `MEASUREMENTS.md`.
### D.3 After every package has landed: the five-part gate on `~/w7/pipe`
**Part 1 — interface purity.**
```sh
python3 scripts/check_include_closure.py # gate A
nm --undefined-only build-linux/libMobileGL.so | grep -E 'MG_State::GLState::|glslang' ; echo rc=$? # gate B (n/a in monolith; recorded)
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # gate C: empty
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure # the {slot,gen} memo-key assertion (G8)
```
**Part 2 — the semantic shadow comparison (the decisive one).**
```sh
cmake --build build-verify --parallel 28
ctest --test-dir build-verify -L unit --no-tests=error --output-on-failure
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4 --output-on-failure
MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-verify/libMobileGL.so \
--out ~/w7/retrace-out/p2-verify -j 4
grep -L 'MGPipe verify:' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty: every case armed
grep -l 'Fatal{' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty
```
A `Fatal{UnmigratedPipeInput, "F@V"}` is a missing `FillPoints.def` row — add the row (never a sticky flag, `FillPoints.def:24-27`), regenerate, rerun. A `Fatal{PipeVerifyDiffer, …, where=read}` is a real push/pull divergence — most likely a D5 derivation transcribed wrongly; it names the field, and it is fixed, never silenced. A `Fatal{PipeResidualDiverged}` means a capability lost its carrier (D9).
**Part 3 — behavioural A/B.**
```sh
# {pull, push} name-for-name on both backends (G2)
for d in build-linux build-push; do ctest --test-dir $d -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > ~/w7/p2-names-$d.txt; done
diff ~/w7/p2-names-build-linux.txt ~/w7/p2-names-build-push.txt # empty
ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 4
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
# 40 traces (79 desktop cases) under push, both backends, SSIM >= 0.99 (G3)
python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-push/libMobileGL.so --out ~/w7/retrace-out/p2-push -j 4 --ssim 0.99
# the render-state-sensitive integration scenarios, called out by name because they are the ones a
# chunk-table mistake shows up in first:
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 \
-R 'ClipDistance|SampleMaskScope|SampleVariables|DualSourceBlend|ViewportArray|PrimitiveRestart'
# the negative controls, always-on entries (G7, G8, G12)
bash scripts/g7_negative_control.sh build-push
ctest --test-dir build-push -R CsoContentAddressing --no-tests=error --output-on-failure
ctest --test-dir build-verify -R 'PoisonOmitted\.|VerifyCorrupted\.|HandleRecycle' --no-tests=error
```
**CTS**: P2 is **not** one of the five architecture boundaries that need the full `gl44to46` caselist (`ROADMAP.md:34`) and no named block is assigned to it. The full 56,271-case run happens once, on both devices, when P2 merges to `dev` — scheduled off the critical path.
**Part 4 — performance non-regression.** D.4 below.
**Part 5 — coverage, poison, handle discipline.**
```sh
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test # G6 regenerates, 0 UNMAPPED
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test # G9
ctest --test-dir build-push -R 'RenderStateSpans\.|Residual' --no-tests=error --output-on-failure # G6, G10
```
**CI.** `gh workflow run test.yml --ref feat/disaggregated`, then once green `gh workflow run test.yml --ref feat/disaggregated -f baseline_sha=48268068` for `monolith-symbol-report`. Record both run URLs. Expected green: `pipe-gates`, `include-graph-check`, `test`, `integration`, `benchmark`, `build-linux-verify`, `integration-verify`, `retrace`, `retrace-verify`, `monolith-symbol-report`. **Note for the schedule**: the three verify lanes have never yet produced a green CI run — they were added at `0fe7bf82` / `97b997d5` and the only run whose head contained them was still in progress when the scouts were written, so their CI wall time is unknown. The only cost datum is local (`MEASUREMENTS.md:142`): 818 `integration-verify` entries at `-j 4` are about the same order as `integration-gpu`, and 79 retrace cases at `-j 4` take ~20 minutes on a 28-core WSL box. Budget accordingly and do not put the device runs behind them.
**A P2 decision the CI file forces**: `test.yml:520-526` records that `integration`'s second, `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` filtered pass (186 entries) is not run under the comparator and says "P2 can take it once the comparator's cost is known". **Decision: P2 does not take it.** The comparator's cost is now known to be 5–10× and the 186 entries are a buffer/readback filter that P2 changes nothing in; revisit at P3b, and the integrator records that decision in `MEASUREMENTS.md` rather than leaving the note dangling.
### D.4 The measurement runs P2 owes the day-43 GO/NO-GO
Four numbers, in the order they must be produced. Items 2–7 of `ROADMAP.md:46-52` are all here; item 1 is P1's and is already recorded at `MEASUREMENTS.md:126-142`.
#### D.4.1 Prerequisite: a per-thread CPU series in the retrace harness (package E)
**There is no per-thread CPU-time instrumentation anywhere in the tree** — greps for `CLOCK_THREAD_CPUTIME_ID`, `CLOCK_PROCESS_CPUTIME_ID`, `getrusage`, `RUSAGE_THREAD` and `/proc/self/task` across `MobileGL/`, `tools/`, `android-plugin/` and `scripts/` return nothing. The metric the whole GO/NO-GO hangs on (`ROADMAP.md:56`) therefore has no first-party collector today, and the cheapest way to get one is inside the retrace benchmark itself: retrace runs `--singlethread` (`trace_replay_core.cpp:459`) and `trace_benchmark.hpp:12-13` states that `Begin` / `OnFrameBoundary` / `End` are only ever reached from that one thread, so **that thread's CPU time is the client-side CPU cost** — no sampling, no root, no debuggable build, no profiler.
E's four edits (D.4's cost is one afternoon, and it is pre-flighted on the desktop CLI, which shares the same core):
`trace_benchmark.cpp:74-76` takes `clock_gettime(CLOCK_THREAD_CPUTIME_ID, …)` beside `Clock::now()`; `trace_benchmark.hpp:32-39`'s `Report` gains `frameCpuMs`; `SummarizeBenchmark` (`trace_replay_core.cpp:832-865`) is reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) emits `meanFrameCpuMs` / `medianFrameCpuMs` / `p95FrameCpuMs` and the full `frameCpuTimesMs[]` array beside `frameTimesMs[]`. **p99 needs no device change even today** — the full per-frame array is dumped, so any percentile is computed host-side from `benchmark.json`; only the headline fields stop at p95.
**Do not** put a timer inside `MGPipeValidateForVerb`. `ROADMAP.md:7` forbids committing hot-path instrumentation, and D17 explains where the ns number comes from instead.
#### D.4.2 The paired two-device A/B (GO/NO-GO items 4 and 3)
Protocol, per device, one lock hold per arm, `scratchpad/wf2/stats_baseline.sh:16-29` as the template:
- **reboot-clean**: `adb -s $SER reboot`, wait for boot completion, wake and unlock (`input keyevent KEYCODE_WAKEUP; input keyevent 82`), let the device settle to the thermal floor before the first arm, and run the two arms **back to back in the same session** so they share a thermal window (`tools/device_bench/README.md:45-58`).
- **CPU/GPU pinned** per the project protocol (big 1.96 GHz / little 1.55 GHz, GPU maxed, 40 °C gate), the pin re-checked at the end of each window and the window discarded if it drifted off-pin.
- **serially from one tree**: `run_android_retrace_local.py` shares one `.trace-work/android-retrace-result` root per tree and `rmtree`s it per invocation (`:14`, `:354-356`), so the two devices **must not** be driven concurrently from one worktree (`MEASUREMENTS.md:93`).
- **device lock** held ≤ 25 min per acquisition, `owner` file written, `rm -rf` on the way out; a lock held > 60 min is not to be broken — report "blocked by device lock".
- **ColorOS traps** on `3B159D009VZ00000`: the first install of a not-yet-installed package blocks on `com.oplus.appdetail InstallGuideActivity` until "继续安装" is tapped (`input tap 353 2349` on the 1272×2772 panel); a foreign-signed APK must be uninstalled first.
- `MSYS_NO_PATHCONV=1` on every invocation, because a `/data/...` inside an `--env` value is path-converted otherwise.
Arms: **{pull APK, push APK} × {`--benchmark-no-finish`, finish} × 4 cases × 2 backends**, per device.
```sh
LOCKS=.../8ab6b3cb-.../scratchpad/w7/locks
for SER in 35d0befa 3B159D009VZ00000; do
for c in minecraft-1.21.4-in-world minecraft-1.21.4-fabric-iris-bsl-in-world improved-transparency-minecraft-26.3 minecraft-1.21.4-startup; do
for b in DirectGLES DirectVulkan; do
for arm in pull push; do
until mkdir "$LOCKS/$SER" 2>/dev/null; do sleep 20; done; echo "p2-ab $(date)" > "$LOCKS/$SER/owner"
ANDROID_SERIAL=$SER MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
--case "$c" --backend "$b" --benchmark --benchmark-no-finish --benchmark-repeats 3 --benchmark-tail-frames 200 \
--env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
# the same invocation yields BOTH artefacts: benchmark.json (frameCpuTimesMs[]) and
# mobilegl.log (the 'MGPipe stats:' windows) - trace-replay-ci.sh:489,491 copies both
rm -rf "$LOCKS/$SER"
done; done; done; done
```
Then, host-side, reduce `frameCpuTimesMs[]` over the trailing 200 frames to **p50 and p99** per arm and publish the delta `push − pull` per (device, case, backend). `--benchmark-no-finish` is the **primary** arm because P2's question is CPU cost (`trace_benchmark.hpp:16-24`); the finish-ON arm is the sanity check that GPU time did not move.
Also read out of the same runs, because they survive the accessor-tally relocation problem (D17): the six memo gate hit/miss pairs (`ers etl eub mfp mpm mdt`) from the **last complete window** of `grep 'MGPipe stats:' mobilegl.log`, the `resid=` byte class (G10), and the two new `csom` / `csob` call classes.
**Excluded**: `minecraft-1.21.1-neoforge-create-indirect-in-world` — it fails on both devices on the `dev@81b17c0b` baseline APK itself (Espryt black frame after ~4.5 min on Adreno 830, Magma `VK_ERROR_DEVICE_LOST` during a texture-upload submit; Mali SSIM 0.85 / 0.45), so it is not this branch's regression (`MEASUREMENTS.md:96`, open question 17). It stays in the 40-trace desktop SSIM corpus and out of the device A/B.
**Trap**: `MOBILEGL_PIPE_STATS_FILE` never produces a file on device — the JSON is written from `PipeStats::Shutdown()` (`PipeStats.cpp:271-278`) which runs from `MobileGL::Destroy` (`Init.cpp:50`), and the trace app never reaches that teardown. Only the periodic `mobilegl.log` lines exist, and a run shorter than one period yields nothing at all; hence `MOBILEGL_PIPE_STATS_PERIOD=120` (or lower for a short fixture).
#### D.4.3 The tracker's absolute ns per draw (GO/NO-GO item 5)
From `DriverBench`'s `ns_per_op` (`MobileGL/MG_Benchmark/Driver/DriverBench.c:31-32`, printed at `:288-289`), on the desktop, against the same library built three ways. `DriverBench` is a headless EGL client that is **not** linked against MobileGL: it `dlopen`s exactly one provider from `$DRIVERBENCH_EGL_LIB` (`DriverBench.c:9-18`), so the same binary measures the native driver and both MobileGL backends. It loops 30 warmup + 120 timed frames, each closed with a real fence wait rather than `glFinish` (MobileGL implements `glFinish` as a no-op, `DriverBench.c:245-266`).
```sh
cd ~/w7/pipe && cmake --build build-bench --parallel 28
for lib in build-linux build-push; do # pull vs push, same tree, same flags
for be in espryt magma; do
DRIVERBENCH_EGL_LIB=$PWD/$lib/libMobileGL.so \
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be $PWD/$lib/libMobileGL.so
done
done
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh native # the control
```
Two deltas, both published, on `mc_vanilla_draw` (5495 draws/frame — the per-draw denominator):
- **T1, the gate number** = `ns_per_op(push, default bitmask) − ns_per_op(pull)`. This is the whole boundary cost per draw.
- **T2** = `ns_per_op(push, MOBILEGL_PIPE_PUSH=0) − ns_per_op(pull)`. This is P1's residual fill alone, so **T1 − T2** isolates exactly what P2 added and what it removed.
**The ceiling, and it is pinned in `MEASUREMENTS.md` before the run** (`ARCHITECTURE.md:504` demands an absolute threshold precisely because a relative one would pass trivially). Derivation: the pull baseline is **6.5–9.3 accessor calls plus memo probes per draw** (`MEASUREMENTS.md:64`, table `:50-58`: MC 1.21.4 in-world Espryt 9.28 / Magma 8.56 at 91.6 draws/frame; improved-transparency 26.3 Espryt 8.44 / Magma 6.53 at 1320 draws/frame). Priced at a non-inlined accessor call plus a load — 6–10 cycles, ~4 ns at 1.96 GHz — plus six memo probes at ~2 ns, that is **~44 ns/draw of work push has to be no worse than**. So:
> **T1 ≤ 45 ns/draw on Adreno 830 (`35d0befa`) and ≤ 60 ns/draw on the Mali device (`3B159D009VZ00000`)**, pinned before the A/B is run. If the pre-run calibration (one DriverBench run of the pull library, reporting `ns_per_op` for `mc_vanilla_draw`, minus the `native` control) says the per-accessor price on these devices is different, the *measured* price replaces the estimate and the ceiling is re-derived by the same arithmetic — but it is pinned before the push arm is measured, not after.
`DriverBench` is Linux-desktop only (`Driver/CMakeLists.txt:7-9`) and the whole benchmark tree is force-disabled on Android (`CMakeLists.txt:33-35`). That is acceptable: P2's ns question is a client-side CPU question and the desktop run answers it, while the two-device requirement (`ROADMAP.md:49`) applies to the per-thread CPU deltas, which come from D.4.2. **Do not** enable the google-benchmark tree on Android to change this; if an on-device blend-toggle is ever wanted the cheap route is a new Android-only target modelled on `DriverBench.c`, which already `dlopen`s EGL and falls back to surfaceless (`DriverBench.c:294-300, 417`).
#### D.4.4 The Blaze3D blend-toggle microbenchmark (GO/NO-GO item 6)
**The case already exists**: `case_mc_state_toggle` (`DriverBenchCases.inc:558-570`) is `glEnable(GL_BLEND); glBlendFuncSeparate(...); glDrawElements(...); glDisable(GL_BLEND); glDrawElements(...)` × 46, registered as `{"mc_state_toggle", case_mc_state_toggle, 46, 0, 46}` (`:627`) at exactly the vanilla-frame rate (46 toggle pairs and 28 `glBlendFuncSeparate` per frame). Note the case is `enable/draw/disable/draw`, which is what `ROADMAP.md:51` writes verbatim.
```sh
for be in native espryt magma; do
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be ... | grep '^mc_state_toggle'
done
```
Published as a table of `ns_per_op` for `{native, espryt-pull, espryt-push, magma-pull, magma-push}`, alongside `mc_vanilla_draw` and `mc_pass_switch` so the toggle number is read against a non-toggling baseline. This is the workload the whole "push at validate, not in the setter" decision (`ARCHITECTURE.md:151`) was made for, and it is where a per-setter design would have shown up as a loss.
#### D.4.5 The CSO negative control (GO/NO-GO item 7)
The knob is `kMGPipeBehaviourNoCsoContentAddressing` (bit 63 of the runtime `MOBILEGL_PIPE_PUSH` bitmask, D14). **It disables the map probe and the handle reuse, not the CSO records** — otherwise it measures a different thing: with it set, every pipeline-version change mints a fresh CSO, binds it and evicts, which is precisely "whole-block content addressing" and reproduces the regression `RenderState.h:165-170` records.
```sh
# desktop: the microbenchmark and the per-draw case, with and without
MOBILEGL_PIPE_PUSH=0x800000000000007f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
MOBILEGL_PIPE_PUSH=0x7f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
# device: one extra arm of D.4.2 on minecraft-1.21.4-in-world only, both backends, one device
ANDROID_SERIAL=35d0befa MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
--case minecraft-1.21.4-in-world --backend DirectGLES --benchmark --benchmark-no-finish \
--env 'MOBILEGL_PIPE_PUSH=0x800000000000007f' --env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
```
The point of the control is to separate **"push is slower"** from **"the CSO design is slower"**: if T1 is over the ceiling *and* the control is not, the cost is in the tracker; if both are over, the cost is in the wire shape. And because a dead switch would pass silently, `CsoContentAddressingScenario` (E) is an always-on ctest pair asserting that `csom` / `csob` move in opposite directions with and without the bit while the pixels do not move at all.
#### D.4.6 The Track H unit costs (GO/NO-GO item 3)
`ROADMAP.md:56`'s criterion is "Track H 单位成本不超出估计的 50%", against the deleted `PLAN.md`'s estimates of **Espryt 0b = 5–7 days** and **Magma subsystem 4 = 2–3 days**. So the measurement is calendar, not nanoseconds: record the actual elapsed days for packages C and D, the diff sizes, and the count of memos actually retired against `ARCHITECTURE.md:363`'s census (11 direct deletions, 2 moved to client debounce, 7 re-keyed, 1 unchanged). P2 pays into that census: **11 of the 11 direct deletions and 2 of the 7 re-keys**. The remaining slices are P3a/P3b/P4a/P4b/P7 and their unit cost is extrapolated from these two.
### D.5 Docs, and the merge to `dev` (integrator, one commit)
`scripts/check_doc_citations.py docs/Disaggregated/*.md` must stay clean — every `file:line` a doc edit adds has to be true.
- `README.md:3` — status → P2 landed with the hash.
- `ROADMAP.md:18` — ✅, with the real numbers: 7 pipeline chunks / 396 B and 8 dynamic chunks / 772 B; CsoCache 64; the residual ratchet 1248 → 8; 11 memos deleted and 2 re-keyed.
- `ROADMAP.md:74` (open question 1) — answered with T1/T2 and the two-device p50/p99 table; `:77` (Q4) — answered with the chunk granularity and the note that 64 is retuned at P13 with the counters live; `:78` (Q5) — answered, and **corrected to three capabilities** (the preamble's correction 1).
- `ARCHITECTURE.md:153` — eight validate entries → nine, named (D1).
- `ARCHITECTURE.md:172` and `:568` — "P1 起成为门" → P2, matching what `test.yml` actually runs.
- `ARCHITECTURE.md:186` — the split's one place is now real; `:189` — the "~25-30 字" estimate → 396 B / 49.5 words; `:190` — the `FramebufferSrgb`/`DepthClamp` open question is closed, and `TextureCubeMapSeamless` is added.
- `ARCHITECTURE.md:504` — `tools/bench.sh` → `tools/device_bench/bench.sh`.
- `ARCHITECTURE.md:580`, `:588` — `MOBILEGL_PIPE_LEGACY_MEMOS` gains its CMake row; the `MOBILEGL_PIPE_PUSH` bitmask row gains the bit list and the new default.
- `MEASUREMENTS.md` — a new §8 with: the D.4.2 two-device p50/p99 table, T1/T2 and the pinned ceiling with its derivation, the blend-toggle table, the CSO negative control, the D.2 "red before" log, the six gate hit/miss pairs before and after, the `resid=` and `csom`/`csob` numbers, the per-dirty-bit fire rates, the payload histogram, the verdict on the 8 over-approximated fill rows, and the `integration-verify` filtered-pass decision of D.3.
Then `[Merge]` to `dev` per the milestone flow, and schedule the full `gl44to46` caselist on both devices off the critical path (`ROADMAP.md:34`).
---
## E. Risks and mitigations
| risk | mitigation |
|---|---|
| **The `[581,584)` padding hole is not where this brief computes it**, so the three new capability bools grow `RenderStateParameters` past 1168 — which breaks the `static_assert` at `MGPipeValueTypes.h:541`, `MGL_RESIDUAL_BLOCK_SIZE`, and every offset in D6's table. | It is a **compile error on the first build of `c0`**, not a silent drift, and it is the very first thing the contract package builds. If it fires, find the real hole with a temporary `static_assert(offsetof(...))` — do **not** grow the struct: the residual ratchet only goes down and a growth is a deliberate build break by design (`MGPipeTypes.h:527-535`). |
| **The hand-derived chunk offsets in D6 are wrong.** They were computed from declarations, not compiled. | `MGPipeRenderStateSpans.cpp` computes every boundary with `offsetof`/`sizeof` and `static_assert`s that the chunks are sorted, non-overlapping and cover exactly `[0, sizeof(RenderStateParameters))`. A mistake in this brief is a build break in that file, and the file is right. |
| **The pipeline subset is now a superset of what Magma hashes, so more state mints CSOs** — a scissor or sample-coverage toggle that used to cost nothing now costs a hash and a probe. | Hashing runs only when `m_pipelineStateVersion` moves, which is exactly when Magma recomputes `ComputePipelineStateHash` today, so the work is moved, not added. `TrackerTest.BlendToggleReusesTwoCsos` pins that a two-state ping-pong mints two CSOs and then reuses them forever, and D.4.4's blend-toggle table is the measurement. If the number disappoints, the escape hatch is demoting the offending setters to `++m_version` — but that is a **pull-build** semantic change and therefore a P3 decision with its own gate, not an in-flight P2 fix. |
| **A D5 derivation is transcribed wrongly**, so a backend reads a value that is subtly not what `GLContext` would have returned. `GetViewport`'s float→int rounding and the 35-way `IsCapabilityEnabled` switch are the two candidates. | This is exactly what the P1 verify comparator was built for and why the entry compare stops being tautological here: the compare-at-read re-reads every one of those fields from the live context at every backend read, field-wise, across 79 retraces and 818 integration-verify entries. On top of it, `RenderStateSpansTest.DerivationMatchesTheFrontendGetters` drives every setter and compares all 29. |
| **A dirty bit fires too rarely** — the dangerous direction (`ARCHITECTURE.md:502`), and one the current harness is blind to for object-class state, because the verify comparator compares O-class fields **by identity only** (`PipeInputs.h:248-249`). | P2 emits for value-class bits 0–4 only; bits 5–17 are computed and *counted* but nothing depends on them yet, so an under-firing object-class bit cannot render anything stale in P2. `TrackerTest.AggregateGenerationCatchesABoundTextureMoving` is the first real test of the direction, and the per-bit fire rates go into `MEASUREMENTS.md` so P3a starts from data. The verify "保留模式" extension for consume-and-clear groups is P3b work and is recorded as such. |
| **A slot table has no garbage collector, so an object nobody destroys leaks its twin forever** — worse than today's lazy `weak_ptr` sweep. | C's `e2` lands the explicit `delete_*` notification **before** `e3` switches the tables over, and `e3` is not merged without it. `SanityTest.cpp:2575-2596` (deleted-texture scrub) and the ~100 CTS cases `Managers.h:306-314` describes are the existing coverage; a leak check on the 79-case retrace (peak RSS, push vs pull) goes into `MEASUREMENTS.md`. |
| **`EnsureProcessTeardownSentinel()` stops being armed** because the arming site moved off `GetOrCreate`, and a twin then `glDelete*`s a recycled name during process teardown. | The arming moves onto the slot table's first insertion in the same commit, and `Managers.h:52-57` documents why a destructor hook is the wrong answer. `SanityTest.cpp:2650-2665, 2765-2790` pin the context-generation guards that back it up. |
| **The `g_fbSlotCache` rewrite reintroduces `pGLContext` in `MG_Backend/`** (it is the one place tempted to, since it caches a pointer into frontend storage). | Purity gate C (`grep -rc pGLContext MobileGL/MG_Backend`) runs after every merge, and the replacement is a plain `MGB_CTX->` read, which is also what closes the P1 poison bypass at those five sites. |
| **`HandleRecycleScenario` is green for the wrong reason** — the allocator never actually reproduces the address, so the scenario proves nothing. | The `AbaControl` arm exists precisely to prove the reproducer reproduces: it defeats the two guards and asserts the *wrong* pixels. If the ABA stops happening, that arm fails. `ObjectLifetimeIdTest.cpp:120-121,130` shows the precedent of skipping rather than passing when the allocator refuses to repeat — the scenario does the same, with a visible skip. |
| **P2 changes `glEnable(GL_FRAMEBUFFER_SRGB)` behaviour**: Espryt now issues a real `glEnable(GL_FRAMEBUFFER_SRGB)` where it previously always disabled. | `MEASUREMENTS.md:84` records that none of the 41 fixtures enables it, so G3's SSIM ≥ 0.99 over 40 traces on both backends is the gate, plus the full `gl44to46` caselist at the `dev` merge. The change is recorded in `MEASUREMENTS.md` as a deliberate conformance fix (it was a silently-swallowed `glEnable` and a lying `glIsEnabled`), not as a side effect. |
| **The pull build's `.text` moves more than the three named symbols.** | `symbol_report.py --threshold 0` after every merge (D.1). Anything outside the named set is a defect. If a compiler schedules the `{}` differently than expected, the delta is attributed line by line in the commit message; the gate admits an attributed delta, never an unexplained one. |
| **`acc/draw` improves for the wrong reason.** `CallClass::AccessorCalls` is a static tally at ~10 hot entry points (`PipeStats.cpp:76-88`), so a tracker that merely *relocates* reads out of `SyncRenderState` / `GetOrCreatePipeline` / `ApplyDynamicDrawStateTail` scores a lower number without removing work. | The report leads with the **gate hit/miss pairs** (which survive relocation, `PipeStats.cpp:93-99`) and the **CPU-time series**, and quotes `acc/draw` only alongside a re-audit of the tally constants at `DirectGLES.cpp:1421,1524,2043,2053,2977` and `VulkanRenderer.cpp:5009,5016,5274,5927,5934,6416,6449,6462`. This caveat is written into `MEASUREMENTS.md` above the numbers, not below them. |
| **Device time is the schedule's long pole**, and both devices are shared with the GL4.6 Wave-7 campaign under the mkdir lock. | The desktop numbers (T1/T2, blend toggle, CSO control, all of the correctness gates) come first and can NO-GO the phase without touching a device. The device A/B is 2 devices × 4 cases × 2 backends × 2 arms ≈ 32 lock holds of ~10 min; budget two days and hold ≤ 25 min per acquisition. A lock held > 60 min is not broken — report "blocked by device lock". |
| **The three verify CI lanes have never produced a green run**, so their wall time is unknown and could dominate. | The P2 exit does not depend on them: the local WSL verify run (D.3 part 2) is the evidence, exactly as it was for P1 (`MEASUREMENTS.md:129-142` is local `~/w7/pipe` evidence, not CI evidence). CI green is required before the `dev` merge, not before the GO/NO-GO. |
| **`MOBILEGL_PIPE_LEGACY_MEMOS` doubles the Espryt and Magma sync code and rots.** `ARCHITECTURE.md:367` budgets +1 day per phase for it. | Both arms sit behind the same `PipeInputs` interface, and every A/B command in §C runs the suite twice (`MOBILEGL_PIPE_PUSH=0` and default) so the legacy arm cannot silently stop compiling or stop passing. It retires with the pull path at P13. |
| **A collision in the 64-bit CSO key aliases two render states.** | The cache `memcmp`s the 396 pipeline bytes on a hash hit before reusing the handle (D7), and `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` forces a collision through a test seam. The memcmp only runs when the pipeline version moved. |
| **The patch trio travels twice** (pipeline chunk P0 and `set_patch_state`), so the two carriers could disagree. | The applier asserts under verify that they agree, which turns the redundancy into a trip wire (D6). The bytes are 28 and the state changes about once per program, so the cost is nil. |
| **`gen_pipe_dirty_surface.py`'s three blind spots** (a mutator inside a lambda is attributed to the enclosing function; a mutation published through a helper reads as deferred; the scan root is `MG_Impl/GLImpl` only, so the four `MGP_NOTE_MUTATION` sites in `TextureState.h` are outside it) let an unmapped mutation slip past a green gate. | The gaps are written into `DirtySurface.def`'s header comment rather than left implicit, and the gate is a *completeness* gate over what the scanner does see — the semantic proof stays the verify lane, which is blind to none of them. Widening the scan root is recorded as a P3a item. |
| **A test that drives a backend helper directly aborts on the poison** because no verb filled the block — the P1 F3 class of failure. | `MG_Test/ScopedPipeVerb.h` already exists for exactly this and eleven tests already use it (`ef6227e1`). Any new test C or D writes that calls a backend helper directly declares its verb the same way; the poison is never weakened and no test name changes. |
| **A/B/C/D/E land against an outdated contract.** | The contract is one commit, tagged `p2/contract`. A must not change any signature in `MGPipeRenderStateSpans.h`, `PipeApply.h`, `SlotAllocator.h`, the subsystem bit constants or `RenderStateParameters` after the tag without telling the other four; a rebase-time compile error is the backstop. |