# P5 scout — test/CI plumbing a SPLIT arm needs Read-only survey of `/home/swung/w7/pipe` @ a29807cc (P4a landed). Nothing built, nothing run, nothing edited. Paths are tree-relative unless they start with `~`. **The three headline facts** (also the return summary): 1. **Nothing in CI or in the phase gate ever configures `MOBILEGL_BUILD_DISAGGREGATED=ON`.** Not one `cmake` invocation in `.github/workflows/test.yml` passes it, and `wsl_p4a_gate.sh` does not either — so every line of `MG_Remote/Transport/` and all five `MG_Test/Wire` suites are compiled by nothing today. P5 is the phase that must create the first `ON` configuration. 2. **`ClearThenReadPixelsScenario` exists; `TriangleScenario` and `PersistentCoherentMapScenario` do not exist in any form.** Two new scenario files plus three `gtest_discover_tests` blocks. 3. **`~/w7/retrace_gate.py` structurally cannot see a `SPLIT`-suffixed ctest name**, because it parses a *foreign* reference `CTestTestfile.cmake` from `~/mgl/MobileGL/build-retrace/` rather than the tree under test, and its name regex rejects the suffix. --- ## 1. The integration test harness (`MobileGL/MG_IntegrationTest`) ### 1.1 How a scenario is registered Three layers, all explicit — no globbing anywhere: * **One executable**: `MobileGLIntegrationTest`, `MG_IntegrationTest/CMakeLists.txt:51-144`. The source list is hand-written: `Main.cpp`, five `Harness/*.cpp`, then 85 `Scenarios/*.cpp` lines (52-143). A new scenario file is invisible until a line is added here. * **One gtest fixture per scenario file**: `class XxxScenario : public ScenarioTest {}` and then `TEST_F(XxxScenario, CaseName)`. `ScenarioTest` is `Harness/ScenarioFixture.h:67-125`; its `SetUp` brings up the shared headless context, skips (or, under `MOBILEGL_ITEST_REQUIRE_GPU`, fails — `ScenarioFixture.h:73-84`) when there is no GPU, and exposes `Ready()` as the *only* legal gate a derived `SetUp` may use (`:106-109`). `Main.cpp:61-65` installs only a banner `::testing::Environment`, so `--gtest_list_tests` (what CMake discovery runs) never touches EGL. * **ctest names = `TEST_PREFIX` + gtest name.** The backend is latched from `MOBILEGL_BACKEND_TYPE` at init, i.e. one process = one backend, so the *same binary* is registered many times with different prefixes and environments. ### 1.2 How `DirectGLES.` / `DirectVulkan.` are built Two ambient registrations: ``` gtest_discover_tests(MobileGLIntegrationTest TEST_PREFIX "DirectGLES." ... ENVIRONMENT "${MGL_ITEST_GLES_ENVIRONMENT}") # :738-745 gtest_discover_tests(MobileGLIntegrationTest TEST_PREFIX "DirectVulkan." ... ENVIRONMENT "${MGL_ITEST_VULKAN_ENVIRONMENT}") # :747-754 ``` and then **23 further "lane" registrations**, each = `TEST_PREFIX` + `TEST_FILTER` + `PROPERTIES {LABELS, TIMEOUT, [RESOURCE_LOCK], ENVIRONMENT}`. Representative shapes P5 should copy: | lane | line | shape | |---|---|---| | `DirectVulkan.AsyncCompile.` | 767-775 | whole scenario, one env knob pinned | | `DirectGLES.ForcedDepthStencilEmulation.` | 785-793 | wildcard filter `DepthStencilReadback*Scenario.*` | | `DirectGLES.UnlocatedIoBlocks.` | 816-825 | adds `RESOURCE_LOCK ` because the case reads the library log | | `DirectGLES.MallocPerturb.` | 838-846 | single case by full name in `TEST_FILTER` | | `DirectGLES.MapPersistentRoundtrips.` | 1377-1394 | **two registrations sharing one prefix**, different `TEST_FILTER` each | | `DirectGLES.ObjectSubsystemControl.{On,Off,Refused,...}` | 1512-1565 | one lane per bitmask arm | Environment strings are *never* written inline. They are assembled by `mgl_itest_join_environment()` (`:321-331`), which escapes the `;` separators — without it only the first entry survives `gtest_discover_tests`' flat `PROPERTIES` forwarding (`:315-320`). And every list **must append `${MGL_ITEST_COMMON_ENV}` / `${MGL_ITEST_VULKAN_ENV}`**, because a ctest `ENVIRONMENT` property *replaces* rather than adds, so an entry naming only its own knobs silently loses the EGL-vendor / Vulkan-ICD pinning (`:678-682`, restated at `:1036-1039` and `:1064-1066`). ### 1.3 What it takes to add `DirectGLES.Split.*` **`ClearThenReadPixels` exists.** `Scenarios/ClearThenReadPixelsScenario.cpp`; fixture declared at `:60`; five cases at `:80, :143, :191, :241, :308`; already in the source list at `CMakeLists.txt:76`. So `DirectGLES.Split.ClearThenReadPixelsScenario.*` needs **only** a registration block. **`Triangle` does not exist.** There is no `TriangleScenario` anywhere in the tree. A whole-tree grep for `Triangle` under `MobileGL/` returns only helper functions inside other scenarios: `PostLinkAttachScenario.cpp:204` `DrawFullViewportTriangle`, `RelinkStageSetScenario.cpp:212` `DrawTriangle`, `ClipDistanceScenario.cpp:134` `DrawClippedTriangle`, `PipelineFailureScenario.cpp:86` `FullscreenTriangleStrip`. Two readings of the gate row: (a) P5 authors a new minimal `Scenarios/TriangleScenario.cpp` (one VBO, one program, one `glDrawArrays`, one `glReadPixels`) — this is what `ROADMAP.md:21`'s literal `DirectGLES.Split.*(ClearThenReadPixels|Triangle)` reads as; or (b) the gate is satisfied by pointing the Split prefix at an existing draw scenario. **Evidence that settles it**: the same ROADMAP row also demands `PersistentCoherentMapScenario`, which likewise exists nowhere but in `ARCHITECTURE.md:500` — a phase that is expected to author one new scenario file is being asked for two. I read the gate as (a). **`PersistentCoherentMapScenario` does not exist.** Only citations: `docs/Disaggregated/ARCHITECTURE.md:500` (map `PERSISTENT|WRITE|COHERENT`, write, no other GL call, draw, readback) and `ROADMAP.md:21`. New file + new source-list line + registration. So the P5 integration-test package is, concretely: 1. `Scenarios/TriangleScenario.cpp` and `Scenarios/PersistentCoherentMapScenario.cpp`, added to `CMakeLists.txt`'s source list around line 143. 2. `mgl_itest_join_environment(MGL_ITEST_GLES_SPLIT_ENVIRONMENT "MOBILEGL_BACKEND_TYPE=DirectGLES" "MOBILEGL_TRANSPORT=inproc" "MOBILEGL_IPC_SERVER_PATH=..." ${MGL_ITEST_CAPABILITY_ENV} ${MGL_ITEST_COMMON_ENV})`. The `MOBILEGL_IPC_SERVER_PATH` entry is required by `ARCHITECTURE.md:543`: "每条新 ctest `ENVIRONMENT` 与 `add_trace_replay_test` 的 `SPLIT` 分支带 `MOBILEGL_IPC_SERVER_PATH`" — because the integration test links `MobileGL_s` statically and `dladdr` fallback cannot find the server. 3. Two (or three) `gtest_discover_tests(... TEST_PREFIX "DirectGLES.Split." TEST_FILTER ".*" ...)` blocks. **Use one block per scenario**, following the `DirectGLES.MapPersistentRoundtrips.` precedent at `:1377-1394`: a `:`-separated multi-pattern `TEST_FILTER` is not used anywhere in this file today, so its CMake/list escaping is unproven (guess: it would work, since `TEST_FILTER` is forwarded to `--gtest_filter`, but two blocks cost nothing and are already proven). 4. Gate it on the build option, or not — see §2. **Two standing rules the lane must not break.** (i) *G2*: `ctest -L integration-gpu` must be name-for-name identical between the pull build and the push build (`:366-369`, and `wsl_p4a_gate.sh:50` measures it). A Split family registered inside `if (MOBILEGL_BUILD_DISAGGREGATED)` is absent from *both* of those builds, so G2 is untouched. Registered unconditionally, it is present in both, so G2 is *also* untouched — but then the lane either skips (if it reports "this build has no transport") or goes red. The house answer for a capability a build may lack is a SKIP that names the missing thing, never a deleted registration (`:341-345`). (ii) *G14*: an existing ctest name may never disappear (`:813-815`); `wsl_p4a_gate.sh:51` counts removed/added against `~/w7/p4a-before-ctest-names.txt`. Adding names is fine; P5 will want a fresh `~/w7/p5-before-ctest-names.txt` snapshot. --- ## 2. ctest labels Five labels exist in the tree (plus one stray). Full inventory from a `LABELS` grep over all `CMakeLists.txt`/`*.cmake` outside `build*` and `3rdparty`: | label | where | count | |---|---|---| | `unit` | every `MG_Test/**/CMakeLists.txt`; `MG_Test/CMakeLists.txt:65`; **`MG_Test/Wire/CMakeLists.txt:35`** | ~45 registrations | | `integration-gpu` | `MG_IntegrationTest/CMakeLists.txt` — 25 registrations (`:742` … `:1755`) | 25 | | `integration-verify` | only inside `if (MOBILEGL_PIPE_VERIFY)` (`:1614-1759`), always paired: `LABELS "integration-gpu\;integration-verify"` at `:1684, :1692, :1706, :1715, :1728, :1737, :1746, :1755` | 8 | | `retrace` | `tools/trace_replay/CMakeLists.txt:376, :380` | all trace cases | | `benchmark` | `MG_Benchmark/**` (`CMakeLists.txt:41`, `Driver/CMakeLists.txt:35,60`, …) | 6 | | `integration` (stray) | `MG_Test/Backend/DirectVulkan/CMakeLists.txt:52` — `DirectVulkanSanityTest` | 1; **nothing in CI selects it** | How the phase gates select them: * `test.yml:204/206` — `ctest -L unit --no-tests=error` * `test.yml:293-298` — `ctest -L integration-gpu --no-tests=error`, then the *same whole label* again with `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` exported in the **job** environment (deliberately not a ctest property, `:290-292`) * `test.yml:547/549` — `ctest -L integration-verify --no-tests=error` * `test.yml:633` — a filtered `-L integration-gpu` run for the handle-ABA/CSO/subsystem controls * `test.yml:850` — `ctest -L benchmark` * the retrace jobs do **not** use the `retrace` label at all; they select by anchored name regex (`test.yml:1187`, `:1338`) * `wsl_p4a_gate.sh:52-63` — `-L unit` in all three build dirs, `-L integration-gpu` in build-linux and build-push (plus re-runs at `MOBILEGL_PIPE_PUSH=0 / 0x1ff / 0x7f`), `-L integration-verify` in build-verify (`:66`) **What label a Split arm should carry.** Copy the verify precedent exactly: `LABELS "integration-gpu\;integration-split"`. Both halves matter and are argued in-file: * the **second, private label** is what makes the lane falsifiable — `ctest -L integration-split --no-tests=error` in a build that forgot `-DMOBILEGL_BUILD_DISAGGREGATED=ON` matches nothing and *fails*, instead of reporting a green run of nothing (`:1025-1028`, the verify block's own argument for this); * keeping **`integration-gpu`** too is why "a verify build's `ctest -L integration-gpu` still describes the whole registration set" (`:1676-1679`) — the same sentence will want to be true of a split build. Note the escaping: a two-label list is written `"a\;b"`, not `"a;b"` (`:1684`). --- ## 3. The trace-replay harness ### 3.1 How a backend is chosen today ``` add_trace_replay_test(CASE_NAME BACKEND ...) tools/trace_replay/CMakeLists.txt:311 add_test(NAME MobileGLTraceReplay.${CASE_NAME}.${BACKEND} :350-351 COMMAND cmake -DTRACE_BACKEND=${BACKEND} ... -P run_trace_case.cmake) :352-372 set_tests_properties(... ENVIRONMENT "EGL_PLATFORM=surfaceless;LIBGL_ALWAYS_SOFTWARE=1;..." LABELS retrace) :373-381 add_trace_replay_test_for_backends(CASE ...) = the same twice :384-387 ``` Cases come from `trace_cases.json` through `trace_cases.py --format cmake` (`CMakeLists.txt:389-397`; emitter at `trace_cases.py:143-172`). `OpenRA` is `trace_cases.json:14-28` — `verify: true`, target call 31249, 640x480, crop 1,1,638,478, default `ssim_threshold` 0.99 (`defaults` block `trace_cases.json:2-12`, and the CMake default at `CMakeLists.txt:335-337`). The backend reaches the library as: `-DTRACE_BACKEND=` → `run_trace_case.cmake:61` `--backend` → `trace_replay_cli.cpp:130` → `android-plugin/app/src/trace/cpp/trace_replay_core.cpp:161` `setenv("MOBILEGL_BACKEND_TYPE", ...)`. That `setenv` block (`trace_replay_core.cpp:136-260`) runs immediately before `libMobileGL.so` is loaded, and ends with `ApplyEnvOverrides(request.envOverrides)` (`:237`) — the generic `K=V;K=V` passthrough. **That passthrough is reachable only from the Android path**: `trace_replay_core.hpp:70` `envOverrides`, filled by `trace_replay_jni.cpp:158` and driven by `android-plugin/trace-replay-ci.sh:174 --env` / `run_android_retrace_local.py:197,374`. The desktop CLI has **no `--env` option** (`trace_replay_cli.cpp:116-179` — the full option list, no env entry). ### 3.2 Where `SPLIT` and `-DTRACE_TRANSPORT=` have to be threaded Four edits, in order of increasing cost: 1. **`run_trace_case.cmake` consumes the transport.** Two possible spellings. *(a) environment* — add `TRACE_TRANSPORT` to the required/optional list at `:1-29` and `set(ENV{MOBILEGL_TRANSPORT} "${TRACE_TRANSPORT}")` before the `execute_process` at `:54`. This has exact precedent: the file already reads `$ENV{MOBILEGL_PIPE_VERIFY}` at `:153` and turns it into three assertions (`:153-190`). Zero C++ change, and `cmake -P`'s child inherits it. *(b) CLI flag* — a new `--transport` in `trace_replay_cli.cpp`, a new `request` field, a new `setenv` in `trace_replay_core.cpp` beside `:161`. Matches how `--backend` works. **Which is right is settled by** whether the split lane also needs the *Android* replay path (`trace_replay_jni.cpp`) to carry the transport: the Android path already has `--env`, so (a) covers desktop and Android both and (b) buys nothing. I'd brief (a). 2. **`add_trace_replay_test` grows a variant/suffix parameter.** `ARCHITECTURE.md:584` is explicit: the `SPLIT` suffix exists because otherwise the entry collides with the same case+backend (`add_test` with a duplicate NAME is a hard CMake error). The name line to change is `CMakeLists.txt:351`; the `-D` block to extend is `:352-372`; the `set_tests_properties` at `:373-381` must also carry `MOBILEGL_IPC_SERVER_PATH` (`ARCHITECTURE.md:543`). 3. **`trace_cases.py` has no notion of a variant.** `github_test_matrix` (`:111-118`) emits `{backend, case}` only; `emit_cmake` (`:143-172`) emits one `add_trace_replay_test_for_backends(...)` per case. A split subset would mirror the existing `verify` flag exactly — `verify` is validated at `:29-38`, filtered at `:85-92`, and surfaced as `github-verify-matrix` at `:121-122` and `--format` at `:180-192`. A `split: true` flag plus a `github-split-matrix` format is a four-hunk change of the same shape. 4. **`test.yml`'s retrace job cannot match a suffixed name.** `test.yml:1187` is `ctest -V --no-tests=error -R '^MobileGLTraceReplay\.${{ matrix.case }}\.${{ matrix.backend }}$'` — anchored at both ends, so `...DirectGLES.SPLIT` never matches. A split arm needs its own job (or a third matrix key folded into the regex). ### 3.3 What the retrace gate would need to run an inproc arm `~/w7/retrace_gate.py` (109 lines). It does **not** read the tree's CMake: * `REF = ~/mgl/MobileGL/build-retrace/tools/trace_replay/CTestTestfile.cmake` (`:14`) — a *foreign* reference build. New tests added to `~/w7/pipe`'s CMakeLists will simply not be in this file. * `parse()` (`:18-31`) lifts each `add_test` argv and its `ENVIRONMENT` property. * `wanted()` (`:47-50`) requires the name to match `r'MobileGLTraceReplay\.(.+)\.(DirectGLES|DirectVulkan)$'` **and** `group(2)` to be in the tree's `ci_backends` for `group(1)`. A trailing `.SPLIT` fails the regex outright; an infix `.SPLIT.` makes `group(1)` = `"OpenRA.SPLIT"`, which misses the `ci_backends` dict (`:46`) and is **silently dropped** — the gate would report "39 of 39 passed" having never run the split arm. * `run()` (`:54-92`) rewrites exactly five argv shapes — `-DMOBILEGL_LIBRARY=`, `-DTRACE_OUTPUT_DIR=`, `-DTRACE_ARTIFACT_DIR=`, the three fixture paths, and the `run_trace_case.cmake` path (`:59-68`). A `-DTRACE_TRANSPORT=` would pass through unchanged — but the reference file emits none. * `env = dict(os.environ)` at `:70`, then the per-test `ENVIRONMENT` on top (`:71-72`). **So there are two P5 paths, and they cost very different amounts:** * **Cheap, works today, zero code change**: run the *existing* names with the transport exported in the process environment — `MOBILEGL_TRANSPORT=inproc python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-split/libMobileGL.so --out ... --only OpenRA`. Line `:70` inherits it. This is character-for-character what `wsl_p4a_gate.sh:69` already does for `MOBILEGL_PIPE_VERIFY=1`, and what `test.yml:1334` does for the same knob in CI. The OpenRA SSIM ≥ 0.99 gate is satisfied by the case's own default threshold, unchanged. *Caveat*: the per-test `ENVIRONMENT` from the reference file is applied **after** `os.environ` (`:71-72`), so this works only because no reference entry names `MOBILEGL_TRANSPORT`. * **Full, needed for the `SPLIT` ctest name to mean anything**: point `REF` at a `build-retrace` configured from `~/w7/pipe` itself, and relax `wanted()`/the `ci_backends` lookup to tolerate a variant segment. Note `REF_FIX`/`REF_ROOT` (`:15-16`) also hard-code `/home/swung/mgl/MobileGL/`. A split retrace arm in CI has an exact template: **`retrace-verify`** (`test.yml:1246-1400`). It reuses the *unchanged* ctest names, swaps the library into the frozen `build-linux/libMobileGL.so` path (`:1303-1322`, with an `nm` check that makes the swap falsifiable), exports the mode knob in the job env (`:1334`), and carries a one-case negative control (`:1356-1385`). A `retrace-split` job is that file, with `MOBILEGL_PIPE_VERIFY=1` → `MOBILEGL_TRANSPORT=inproc` and `MGPipeVerifyInputs` → an `MG_Remote` symbol. --- ## 4. `.github/workflows/test.yml` ### 4.1 Triggers, and the TEMPORARY one ``` on: push: branches: - dev :6 - Feat/Backend-Direct-GLES :7 - Feat/Backend-Direct-Vulkan :8 # TEMPORARY, remove before merging the MGPipe work into dev: ... - feat/disaggregated :9-12 workflow_dispatch: :13-21 (input: baseline_sha, default 087685d1) ``` The trigger is `test.yml:9-12`. It is not alone — **four job steps carry the same branch guard** and are documented as retiring with it: * `pipe-gates` → "The buffer pool, the deferred-release drain and the rings did not move (G5)" and its self-test, `if: github.ref == 'refs/heads/feat/disaggregated' || github.event_name == 'workflow_dispatch'` (`:1694`, `:1698`; rationale `:1684-1689`); * the P4a twin of the same pair (`:1727`, `:1731`; rationale `:1714-1717`). `~/w7/notes/p4a/INTEGRATOR-DECISIONS.md:730` and `:792` already carry it as an open cleanup item ("TEMPORARY test.yml:9-12 trigger still present (remove before dev)", "the TEMPORARY CI trigger branch in test.yml/apk.yml (must be ...)"). **P5 must not build anything that only runs on that branch**: new split steps should use `workflow_dispatch` or run unconditionally, so that the day the four lines are deleted nothing of P5's goes dark. ### 4.2 The job matrix (18 jobs) | job | line | needs | what it does | |---|---|---|---| | `build-linux` | 24 | — | the ordinary library + tests + integration + benchmark; artifact `mobilegl-linux-runtime` | | `test` | 161 | build-linux | `ctest -L unit` | | `integration` | 217 | build-linux | `ctest -L integration-gpu` twice (ambient + `DISABLE_INVALIDATE_FLUSH=1`) | | `build-linux-verify` | 315 | — | `-DMOBILEGL_PIPE_VERIFY=ON`; artifact `mobilegl-linux-runtime-verify`; `nm` proof the comparator is in (`:415`) | | `integration-verify` | 484 | build-linux-verify | `-L integration-verify`, `-L unit`, the control lanes, and two "this step passes when ctest FAILS" negative controls (`:676`, `:705`) | | `flatc-check` | 745 | — | regenerates `protocol_generated.h` with an out-of-tree flatc and diffs; **compiles no MG_Remote code** | | `include-graph-check` | 773 | — | include-closure purity gate | | `benchmark` | 804 | build-linux | `-L benchmark` | | `build-retrace` | 860 | build-linux(+) | builds `mobilegl_trace_replay`; artifact carries `build-retrace/tools/trace_replay/CTestTestfile.cmake` | | `trace-cases` | 1005 | test, benchmark, integration | emits `matrix`, `names`, `verify-matrix` from `trace_cases.py` | | `trace-fixtures` | 1029 | trace-cases | per-case fixture cache / LFS fetch / upload | | `retrace` | 1094 | build-linux, build-retrace, trace-cases, trace-fixtures | one job per {case, backend}, `ctest -R '^…$'` | | `retrace-summary` | 1200 | | | | `retrace-verify` | 1246 | build-linux-verify, build-retrace, trace-cases, trace-fixtures | `verify-matrix` subset under `MOBILEGL_PIPE_VERIFY=1` | | `monolith-symbol-report` | 1403 | — | **workflow_dispatch only**; builds the library twice with `-DMOBILEGL_BUILD_DISAGGREGATED=OFF` (`:1467`, `:1484`) and asserts `nm --defined-only … \| grep MG_Remote` is empty (`:1491-1500`) | | `remove-artifact-clutter` | 1522 | | | | `pipe-gates` | 1582 | — (deliberately independent of build-linux) | `gen_pipe.py` + self-test, `symbol_report.py --self-test`, the stdio-instrumentation grep, `gen_pipe_dirty_surface.py --check/--self-test`, the two untouched-region gates, the citation lint | **Where a split arm slots.** The verify pair is a ready-made template and P5 should clone it: * `build-linux-split` — clone `build-linux-verify` (`:315-482`) with `-DMOBILEGL_BUILD_DISAGGREGATED=ON` (plus `-DMOBILEGL_PIPE_PUSH=ON`, since a remote backend needs the pushed block) and its own artifact name. Copy the "the library really carries it" `nm` step at `:415-437`, asserting an `MG_Remote` symbol instead of the comparator's. That step is what makes the lane falsifiable, and its absence is precisely what would let a split lane pass having run monolith. * `integration-split` — clone `integration-verify` (`:484-743`), running `ctest -L integration-split --no-tests=error` plus a whole-label `-L integration-gpu` run under `MOBILEGL_TRANSPORT=inproc` in the **job** env (the `DISABLE_INVALIDATE_FLUSH` precedent at `:290-298` is exactly this: a knob that must not be a ctest property so it reaches every entry). * `retrace-split` — clone `retrace-verify` (`:1246-1400`), see §3.3. * `trace-cases` gains a `split-matrix` output beside `verify-matrix` (`:1012-1027`) if the split retrace arm is a subset (recommended: `OpenRA` only, which the gate names). Note `build-linux` itself passes **no** `-DMOBILEGL_PIPE_PUSH` (`:91-105`), so it is a *pull* build; the only push build in CI is the verify one (`MOBILEGL_PIPE_VERIFY=ON` forces `MOBILEGL_PIPE_PUSH` ON, `CMakeLists.txt:467-473`). A split arm therefore cannot ride on `build-linux`'s artifact. --- ## 5. `MOBILEGL_BUILD_DISAGGREGATED` ### 5.1 What the option gates Declared `CMakeLists.txt:23`, default **OFF**, with the contract written at `:17-22`: with it OFF "nothing under `MobileGL/MG_Remote/` is compiled, no include path is added, and no library is linked, so `nm --defined-only libMobileGL.so | grep -i MG_Remote` is empty". Four gated blocks, all in the root `CMakeLists.txt`: | line | effect | |---|---| | `453-465` | if the flatbuffers submodule headers are missing, shadow the option OFF **as a normal variable, not a cache force** (`:460-463` explains why) | | `503-520` | append 8 sources to `SOURCE_FILES`: `Transport/{Ring,Doorbell,ShmSegment,ShmSegmentPosix,ShmSegmentWin32,FdPassing,InProcessTransport,WireLog}.cpp` | | `572-574` | append `-DMOBILEGL_BUILD_DISAGGREGATED=1` to `MOBILEGL_COMPILE_DEF` | | `605-610` | append `3rdparty/flatbuffers/include` to the include path (header-only; no `add_subdirectory`, no flatc in the graph) | Both library targets get the same `SOURCE_FILES`: `add_library(MobileGL SHARED ${SOURCE_FILES})` at `:612-614` and `add_library(MobileGL_s STATIC ${SOURCE_FILES})` at `:681-684`. `MobileGL_s` is what the desktop integration test links (`MG_IntegrationTest/CMakeLists.txt:29-37`), so a split integration lane gets `MG_Remote` for free once the option is on. One more thing the macro arms outside `MG_Remote`: the poison `#if` in `MG_Backend/MGPipe/PipeInputs.h:19-21` has `MOBILEGL_BUILD_DISAGGREGATED` as its third arm. `MG_Test/Wire` is registered **only** under the option: `MG_Test/CMakeLists.txt:105-106` (`if (MOBILEGL_BUILD_DISAGGREGATED) add_subdirectory(Wire)`). Its five suites are `Framing, Ring, InProcessTransport, ProtocolSmoke` + `FdPassing` on non-Windows (`Wire/CMakeLists.txt:7-17`), all labelled `unit` (`:35`). ### 5.2 Is MG_Remote built in the normal CI configuration? **No.** Every `cmake -S . -B` in `test.yml`, checked one by one: * `build-linux` `:91-105` — no `-DMOBILEGL_BUILD_DISAGGREGATED` * `build-linux-verify` `:384-397` — no, and the comment at `:375-382` says so explicitly: "this job needs neither a Debug log level nor `MOBILEGL_BUILD_DISAGGREGATED`" * `build-retrace` `:944-955` — no * `monolith-symbol-report` `:1461-1472` and `:1477-1489` — passes **`=OFF`** twice, on purpose, as the G1 control, then asserts at `:1491-1500` that the pull build defines no `MG_Remote` symbol `flatc-check` (`:745-771`) only runs `scripts/gen_protocol.py` against an out-of-tree flatc build and diffs the committed header; it compiles nothing of `MG_Remote`. Local evidence agrees: `build-linux/CMakeCache.txt:437`, `build-push/CMakeCache.txt:437`, `build-verify/CMakeCache.txt:437`, `build-bench/CMakeCache.txt:489` and all three `.cxx/*/arm64-v8a/CMakeCache.txt` read `MOBILEGL_BUILD_DISAGGREGATED:BOOL=OFF`. `wsl_p4a_gate.sh:12` (`$COMMON`) and its three configures (`:19-23`) never set it either. **Consequence to put in the P5 brief in bold**: `MG_Remote/Transport/*.cpp` and all five `MG_Test/Wire` suites — written in P0 and never touched since — have **never been compiled or run by any lane**. The first `-DMOBILEGL_BUILD_DISAGGREGATED=ON` configure in P5 may well be the first time those files see a compiler on this branch's current HEAD. Budget for it. ### 5.3 What does not exist yet * `MOBILEGL_BUILD_DISAGGREGATED_INPROC` — not in `CMakeLists.txt`; `ARCHITECTURE.md:581` and the switch table at `:595` list it as "计划(P5)". * `MG_Config::Transport` — a grep of `MobileGL/Config.h` and `MobileGL/ConfigLoader.cpp` for `Transport` returns **nothing**. `MOBILEGL_TRANSPORT` parsing is P5 work (`ARCHITECTURE.md:583`). * The `Init.cpp` hook — `MG_Backend/Init.cpp:49-63` is a plain `switch (MG_Config::ActiveBackendType)` with `DirectGLES` / `DirectVulkan` / `Unknown` arms and **no `#if`**. `ARCHITECTURE.md:29`: "分支在 P5 落地;P0 的 `Init.cpp` 尚未含它". * `MG_Remote/Client/` and `MG_Remote/Server/` directories — do not exist. The tree has only `MG_Remote/Protocol/` (3 files) and `MG_Remote/Transport/` (16 files). --- ## 6. `~/w7/notes/tools/wsl_p4a_gate.sh` — the five parts 77 lines; `wsl_p4a_gate.sh quick` skips the three retrace sweeps (`:3`, `:67`). `BASE=37da3c3a` (`:7`). It runs the parts in the order 1, 5, 3, 2 (fast source-level answers first). **Preamble (`:5-25`)** — three build directories, all failure-fast so a stale binary can never produce a verdict (`:25`): * `build-linux` — pull, reconfigured in place (`:19`) * `build-push` — `$COMMON -DMOBILEGL_PIPE_PUSH=ON` (`:20-21`) * `build-verify` — `$COMMON -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON` (`:22-23`) `$COMMON` (`:12`) pins clang + ccache + Release + INFO + TEST/INTEGRATION ON + BENCHMARK OFF + the mesa EGL vendor + the lavapipe ICD. `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` (`:16`) makes an exit-order UAF reproduce natively (ID-18/21). **Part 1 — interface purity (`:27-38`)** `check_include_closure.py`; gate C (`grep -rc pGLContext MobileGL/MG_Backend` must be empty); G13 (`MG_State` must not be inside `MG_Pipe/PipeApply.h`'s ops block); G13b (`MGPipeUnmigratedEmulation` site count in DirectGLES); G1 `symbol_report.py` against `~/w7/p4a-before-libMobileGL.so` with `--threshold 0`; G5 `p3a_untouched_regions.sh` (eleven regions) and `p4a_untouched_regions.sh` (seventeen) against `$BASE`; the `RenderStateImpl` sha vs `~/w7/p4a-before-syncrenderstate.sha`; `ctest -R HandleRecycle` in build-verify. **Part 5 — coverage, poison, handle discipline (`:40-46`)** `gen_pipe.py --check` + `--self-test`; `gen_pipe_dirty_surface.py --check` + `--self-test`; the emitter/CSO unit suites in build-push via `$UNIT_RE` (`:15`); both untouched-region `--self-test`s; `PoisonOmitted.|VerifyCorrupted.` in build-verify. **Part 3 — behavioural A/B (`:48-63`)** G2 (`ctest -N` name diff, pull vs push, must be 0 lines — `:49-50`); G14 (removed/added vs `~/w7/p4a-before-ctest-names.txt` — `:51`); `ctest -L unit` in all three dirs (`:52`); `-L integration-gpu` in build-linux and build-push with `--rerun-failed` (`:53-54`); the same whole label three more times at `MOBILEGL_PIPE_PUSH=0 / 0x1ff / 0x7f` (`:55`); once more under `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` (`:56`); the 41-scenario `$FAMILY` regex (`:13`, `:57`); G9 `TextureParamsWithoutASamplerView` (`:58`); `TextureUploadShape` (recorded, not gated — `:59`); three negative-control scripts (`:60`); the CSO/Resource/Object subsystem controls plus the `0x9ff` dependency-refusal arm (`:61-62`); the verify controls (`:63`). **Part 2 — semantic shadow comparison (`:65-76`)** `ctest -L integration-verify -j 4` in build-verify, counting and classifying `Fatal{` lines (`:66`); then unless `quick`, three `retrace_gate.py` sweeps (`:68-75`): verify (`MOBILEGL_PIPE_VERIFY=1`, build-verify's lib, then a check that every log carries "MGPipe verify:" and none carries `Fatal{`), push (build-push's lib), and the `$NAMED` subset (`:14` — `create-indirect|create-instancing|rd12-odinlite|improved-transparency-minecraft-26.3|fabric-sodium|photon-v1.3b`). **Part 4 (device performance) is not in this script** — it lives in `~/w7/notes/tools/wsl_p4a_bench.sh` and the A/B reducers beside it. ### P5's gate delta against this (proposal for the brief) 1. **A fourth build dir** `build-split`: `$COMMON -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON` (and `-DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` once it exists). Same fail-fast rule as `:25`. 2. **Part 1 gains the surviving byte equality** `ARCHITECTURE.md:524`: `nm --defined-only build-linux/libMobileGL.so | grep MG_Remote` must be **empty**, and `nm -D build-split/libMobileGLServer.so | grep mobilegl_server_main` must **hit** in RelWithDebInfo. Neither is asserted anywhere today outside `test.yml:1491-1500` (workflow_dispatch-only). 3. **Part 3 gains the split A/B**: `ctest -L unit` in `build-split` — **this is the first run of the five `MG_Test/Wire` suites** — plus `ctest -L integration-gpu` there under `MOBILEGL_TRANSPORT=monolith` and again under `=inproc`, diffed name-for-name (the G2 shape, extended to a third arm, which `ARCHITECTURE.md:521` asks for verbatim: "`ctest -L integration-gpu` 在 `DirectGLES.` 与 `DirectGLES.Pipe.`/`DirectGLES.Split.` 之间逐名相同"). Plus `ctest -L integration-split` (falsifiability: it must match something). 4. **Part 2 gains an inproc retrace arm**: the zero-code-change form is `MOBILEGL_TRANSPORT=inproc python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-split/libMobileGL.so --out ~/w7/retrace-out/p5-split -j 4 --only 'OpenRA'` (§3.3). The gate row asks only for OpenRA ≥ 0.99. 5. **Peak RSS for both roles is a brand-new measurement.** Nothing in the tree or in `~/w7/notes/tools/` measures RSS: a grep for `maxrss|VmHWM|peak rss|peakRss` across all `*.py/*.sh/*.cpp/*.h/*.yml/*.cmake` outside `build*`/`3rdparty` returns three **comments** only (`MG_State/GLState/ProgramState/ProgramLinkTask.h:105`, `MG_Util/Async/ShaderCompilePool.h:79`, `MG_Util/Async/ShaderCompilePool.cpp:20`) and zero hits under `~/w7/notes/tools/*.sh`. `--benchmark`'s JSON carries frame times only (`trace_replay_cli.cpp:32-40`). So "两个角色峰值 RSS 在案" needs a new mechanism — cheapest is `/usr/bin/time -v` or `/proc//status:VmHWM` sampling around the inproc retrace, recorded into MEASUREMENTS rather than gated. 6. **`persistent-map-push` 出数** likewise needs a counter published through `PipeStats`, the way `mpr=` is (`MG_Util/Metrics/PipeStats.h:126`, emitter `MG_Impl/Pipe/PipeFill.cpp:736`), and a scenario that reads the summary line back from a **per-lane** `MOBILEGL_LOG_FILE_PATH` with a `RESOURCE_LOCK` — the rule at `MG_IntegrationTest/CMakeLists.txt:802-815` and `:1318-1322` (the library opens its log `fopen(path,"w")`, so every process in a lane truncates it; a log-reading case needs a lane whose `TEST_FILTER` selects it alone). --- ## 7. Traps worth repeating in the brief * ctest `ENVIRONMENT` **replaces**, never appends; a property entry **overrides the job env** (`MG_IntegrationTest/CMakeLists.txt:678-682`, `:1036-1043`). That last point is load-bearing in the other direction too: the ambient `Verify.` lanes deliberately name *neither* `MOBILEGL_PIPE_VERIFY_CORRUPT` nor `MOBILEGL_PIPE_POISON_OMIT`, precisely so CI's job-level exports can reach them (`:1040-1043`). A split lane that wants a job-level `MOBILEGL_TRANSPORT` override must likewise not name it in its property. * `;` inside an `ENVIRONMENT` or `LABELS` value must be escaped `\;` (`:321-331`, `:1684`). * A log-reading case needs its own lane, its own `MOBILEGL_LOG_FILE_PATH`, and a `RESOURCE_LOCK` named after that log (`:802-815`) — measured: 3 runs of the full label at `-j 8` produced 4 / 0 / 2 spurious failures without it. * An existing ctest name may never disappear (G14); renaming to fix a race is not allowed, which is why `RESOURCE_LOCK` exists (`:813-815`). * `gtest_discover_tests` runs `--gtest_list_tests` at build time; it must not need a GPU, a transport, or a server process. A Split registration that made discovery spawn anything would break every build. * The P4a-era capability markers (`MGL_ITEST_CAPABILITY_ENV`, `:358-655`) are the house pattern for "this arm only asserts once the owning package landed": a `file(GLOB_RECURSE … CONFIGURE_DEPENDS)` content probe for a **symbol**, never a filename (`:389-398` argues this at length). If P5's Split lanes need to skip before `MG_Remote/Client` exists, copy `mgl_itest_probe_for_symbol` (`:402-414`) rather than inventing a guard.