Files
MobileGL/docs/Disaggregated/notes/p5/p5-results/t1-v1.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

518 lines
40 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.
# t1-v1 — test and CI plumbing for the SPLIT arm
Branch `p5/t1`, worktree `~/w7/p5-t1`, base `feat/disaggregated @ 5175f9cc`.
Commit range **`5175f9cc..8d0850bd`** (four commits):
| commit | what |
|---|---|
| `5a52150a` | `Scenarios/TriangleScenario.cpp`, `Scenarios/PersistentCoherentMapScenario.cpp`, `Harness/SplitLane.h`, the `DirectGLES.Split.` + `PersistentMapArm.` lanes, `PipeStatsWindow::CounterAsDoubleOrAbsent`, the split skip guard in `ScenarioFixture.h` |
| `6a29d9b7` | `add_trace_replay_test`'s `VARIANT`/`TRANSPORT`/`IPC_SERVER_PATH`, `add_trace_replay_split_test`, `run_trace_case.cmake`'s transport block and refusal census, `trace_cases.py`'s `split` flag + `github-split-matrix`, `trace_cases.json`'s `"split": true` on OpenRA |
| `bb14c639` | `build-linux-split`, `integration-split`, `retrace-split` in `.github/workflows/test.yml`, and `trace-cases`' `split-matrix` output |
| `8d0850bd` | `Harness/PersistentMapPeek.{h,cpp}` and the arm / membership assertions b1-v1.md §4.1 asks for |
Not in git (tooling): `~/w7/notes/tools/wsl_p5_gate.sh`, `~/w7/notes/tools/wsl_p5_rss.sh`.
---
## 1. The four self-tests, with numbers
Run by `MGL_P5_TREE=~/w7/p5-t1 wsl_p5_gate.sh` at `bb14c639`. All four build dirs configured and
built clean, each confirmed against the presence of `CTestTestfile.cmake` (C-10).
**G1 — the gate P5 is most likely to break.** Clean.
```
symbol-report: .text 10806323 -> 10806323 (+0, +0.000%)
symbol-report: 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
```
**G1's split half** (new in P5, CONTRACT-P5 §5):
```
nm --defined-only build-linux/libMobileGL.so | grep -ic MG_Remote = 0 (must be 0)
nm --defined-only build-split/libMobileGL.so | grep -ic MG_Remote = 188 (must be > 0)
```
**`ctest -L unit`, four dirs.** Exactly the preamble's baselines.
| dir | result |
|---|---|
| build-linux | 1785 / 1785 |
| build-push | 1785 / 1785 |
| build-verify | 1785 / 1785 |
| build-split | **1842 / 1842** |
| build-split, the five `MG_Test/Wire` suites alone | **57 / 57** |
The Wire suites had never been compiled or run by any lane before P5 configured this directory
(scout-test-ci §5.2). They are green on `5175f9cc` + t1.
**`ctest -L integration-gpu`.** Baseline 1117 + t1's 11 new names = 1128.
| arm | result |
|---|---|
| build-linux (pull) | 1128 / 1128 |
| build-push | 1128 / 1128 |
| build-split, `MOBILEGL_TRANSPORT=monolith` | 1139 / 1139 |
| build-split, `MOBILEGL_TRANSPORT=inproc` | 1139 / 1139 |
| the two split arms, diffed **name AND status** | **0 differing lines** |
1139 = 1128 + the 11 `integration-split` entries, which carry `integration-gpu` too.
**G2** pull-vs-push name diff: **0 lines**.
**G14** vs `~/w7/p5-before-ctest-names.txt`: **0 removed, 11 added** —
```
DirectGLES.PersistentCoherentMapScenario.AWriteAfterAFrameBoundaryReachesTheNextFramesDraw
DirectGLES.PersistentCoherentMapScenario.TheMapLandsInTheArmItsLaneDeclares
DirectGLES.PersistentCoherentMapScenario.TwoWritesThroughTheCoherentPointerEachReachTheirOwnDraw
DirectGLES.PersistentMapArm.PersistentCoherentMapScenario.TheMapLandsInTheArmItsLaneDeclares
DirectGLES.TriangleScenario.AVboBackedTriangleReachesReadPixels
DirectGLES.TriangleScenario.TheSameVboAndVaoRedrawAcrossAFrameBoundary
DirectVulkan.PersistentCoherentMapScenario.AWriteAfterAFrameBoundaryReachesTheNextFramesDraw
DirectVulkan.PersistentCoherentMapScenario.TheMapLandsInTheArmItsLaneDeclares
DirectVulkan.PersistentCoherentMapScenario.TwoWritesThroughTheCoherentPointerEachReachTheirOwnDraw
DirectVulkan.TriangleScenario.AVboBackedTriangleReachesReadPixels
DirectVulkan.TriangleScenario.TheSameVboAndVaoRedrawAcrossAFrameBoundary
```
plus, in `build-split` only (inside `if (MOBILEGL_BUILD_DISAGGREGATED)`, so G2 is untouched):
5 × `DirectGLES.Split.ClearThenReadPixelsScenario.*`, 2 × `DirectGLES.Split.TriangleScenario.*`,
3 × `DirectGLES.Split.PersistentCoherentMapScenario.*`,
1 × `DirectGLES.Split.PersistentMapArm.PersistentCoherentMapScenario.TheMapLandsInTheArmItsLaneDeclares`,
and in a trace-replay build with the option, `MobileGLTraceReplay.OpenRA.DirectGLES.SPLIT`.
**`gen_pipe.py --check/--self-test`** and **`gen_pipe_dirty_surface.py --check/--self-test`**: green,
untouched by this package (no `.def` and no generator was edited).
`scripts/gen_pipe_field_ownership.py` does not exist yet; the gate names its absence rather than
passing silently over it.
## 2. The acceptance rows
| row | result |
|---|---|
| both new scenarios green under monolith on `DirectGLES.` | **yes** — and on `DirectVulkan.` too; they are ordinary GL scenarios and run in every lane |
| the `Split.` lanes registered and either green or skipping **by name** | **11 registered, 11 skipping by name.** The skip names `MG_Remote/Client` and the three packages, verbatim |
| `ctest -L integration-split` matches something in `build-split` | **yes, 11 / 11** |
| ... and goes red in a build without the option | **yes** — `-L integration-split --no-tests=error` in `build-push` exits non-zero |
| `wsl_p5_gate.sh` runs end to end, numbers match the preamble | **yes**, table above |
| G14 0 removed, added names listed | **yes**, above |
| G1 unmoved | **yes**, 0/0/0/0, `.text` +0 |
Part 2 (semantic): `integration-verify` **930 / 930, 0 `Fatal{` lines**.
79-case push retrace sweep **79 / 79**; 79-case verify sweep **79 / 79, armed 79 of 79, logs with
`Fatal{`: 0**.
Exit gate **E2**, the OpenRA inproc arm: **2 / 2** (DirectGLES and DirectVulkan), ssim 1.000, and
`MGPipe split: ... Fatal{ lines in .../output/mobilegl.log: 0` on both.
All of the above re-confirmed at `8d0850bd`: G1 `.text +0`, 0/0/0/0; G2 0; G14 0 removed / 11
added; pull `integration-gpu` 1128 / 1128.
---
## 2b. Which lanes are SKIPPING BY NAME today, and what re-arms them (superseded by §7.1 M-1: the arming condition is now a runtime fact, not a source probe)
Integration should re-run these on the commit that lands the last of c1 / s1 / v1, and again after
b1 merges into the integration tree.
| entries | state | what arms them |
|---|---|---|
| the 11 `DirectGLES.Split.*` (5 ClearThenReadPixels, 2 Triangle, 3 PersistentCoherentMap, 1 `Split.PersistentMapArm.`) | **registered, skipping by name** | the last `Fatal{Unimplemented...}` stub disappearing from `MG_Remote/{Client,Server}` — the probe is a conjunction, see §3(a). `ctest -L integration-split` is 11/11 green-as-skips today |
| `PersistentCoherentMapScenario`'s membership assertion (b1 §4.1 item 2) | **compiled out**, recorded as `persistent_map_membership=unavailable` | a source under `MG_Remote/Client` naming `IsLivePersistentMap` **and** a `MOBILEGL_BUILD_DISAGGREGATED` build. b1's tracker is on `p5/b1`, not yet in the integration tree |
| the `pmap > 0` assertion | **not asserted** in any lane that runs today | it fires only in a lane that declares `MGITEST_PERSISTENT_MAP_ARM=emulated`, which is only the split counting lane, which skips. So no lane's green depends on `pmap` being non-zero yet |
| negative controls **E1** (`MOBILEGL_IPC_VERB_BARRIER=0`) and **E3(a)** (`MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0`) | **inert**, and they say so | the same probe. They are two-state and derive the expected state from `MGITEST_REMOTE_CLIENT_PRESENT` in the shipped ctest include files, so they become gates with no edit |
| `MGITEST_SPLIT_EXPECT_TRANSPORT` | carried, not asserted by any case | a scenario-level arming case, once c1 lands (§6.3) |
Nothing else skips. The two new scenarios' five cases run and assert in every ambient lane on both
backends today.
---
## 2c. Reconciliation with b1-v1.md §4.1 — all seven items
| b1 item | in this package |
|---|---|
| 1. assert which arm: `IsBackendPersistentMapped()` **false** immediately after the map | **yes, exactly that spelling.** `Harness/PersistentMapPeek.cpp` reads `pGLContext->GetBufferObject(name)->IsBackendPersistentMapped()`; `AssertOrRecordArm()` is called immediately after the map in `SetUp` and again after the counted window's map. A lane that DECLARES an arm asserts it; a lane that declares none records it — see D-3, and the measurement below |
| 2. `IsLivePersistentMap` membership | **yes**, `AssertMembership()`, compiled in only when CMake's probe finds the symbol under `MG_Remote/Client` **and** the build compiled MG_Remote. Records `unavailable` otherwise. `__has_include` alone is wrong here: the header is in the source tree of the pull build too, which would turn a healthy pull build into a link error |
| 3. E3(b), a write announced by nothing | **yes**, and it is the file's headline. `WriteThroughTheMapThenDraw` is `std::memcpy` + `glDrawArrays` with nothing between; the sequence is map, write, draw, write, draw, read back, plus a second case across a `Present` |
| 4. E3(c), `pmap > 0` split-side and `mpr` equal between arms | **yes**, with one change of shape: `mpr` equality is asserted as **the same constant in both lanes** (`kExpectedRoundtrips = 1`) rather than as a cross-lane comparison, because one test process can only see its own log. `pmap > 0` fires only in the lane that declares `emulated` |
| 5. E3(d), `IsBackendPersistentMapped()` staying false across the whole scenario | **yes** — re-asserted after the draws in both behavioural cases, not only at the map. A late adoption would leave item 1 true and this one false and would be invisible in every pixel |
| 6. E3(a), red under `MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0` | **yes**, as a two-state negative control in the `integration-split` CI job and in `wsl_p5_gate.sh` — not as a registered ctest entry, because an entry expected to be red cannot carry a label that must be green (the verify lane's precedent: the controls are always-on STEPS that pass when ctest fails) |
| 7. `PERSISTENT|WRITE|COHERENT` without `FLUSH_EXPLICIT` | **yes**, and it is now a `static_assert` on the flag constant rather than a comment |
**One difference worth naming.** b1 §4.1 item 4 and item 5 both reduce to `pmap` in b1's wording;
this scenario keeps them **separate**, with the arm read from the peek and `pmap` only as a
cross-check. Deriving the arm from `pmap` makes "the push was never wired" and "the store was
adopted" the same reading, and they are different defects with different owners — the first is c1's
missing call sites, the second is R-6 not holding. The first spelling of this scenario did derive
the arm from `pmap` and it reported `adopted` on a tree where the push simply is not wired yet.
**And one measurement b1 will want.** With the peek, on llvmpipe / Espryt, in `build-split` under
`MOBILEGL_TRANSPORT` unset: `persistent_map_arm = adopted`, `mpr=1`, `pmap=0.00`. So the monolith
arm of this scenario is the **adopted** arm on this driver, and R-6 pins the split arm at emulated —
the two arms of exit gate E3 therefore run different buffer code paths, not the same path over a
different transport. `mpr` is the only counter equal by construction. Details in §3(c).
---
## 3. The three things the other packages most need to know
### (a) The naive "does MG_Remote/Client exist" probe ARMS AGAINST c0's STUBS, and it went green against monolith
This is measured, not predicted. The brief tells t1 to copy `mgl_itest_probe_for_symbol` and probe
for a **symbol**. That is necessary and it is **not sufficient on this tree**: package c0 already
landed `MG_Remote/Client/{CapsMirror,ClientSession,EmitTables}.{h,cpp}` and
`MG_Remote/Server/{PipeApplier,ServerLoop,ServerSession}.cpp` as SIGNATURE STUBS - every entry
point is `MGLOG_F("MGPipe: Fatal{Unimplemented..., \"...\"} - P5 package <x> has not landed this
yet; c0 shipped the signature only")` + `std::abort()`, `RemoteEmitTable()` aborts on sight and
`ImplementedVerbCount()` returns 0. A probe for `kRemoteEmitSlotCount|BackendObject_Remote|CapsMirror`
answered YES, the Split lanes armed, and eleven entries named `DirectGLES.Split.*` went **green
having run the monolith path end to end**.
The arming condition is now a conjunction with a **negative** half: the client names its own
symbols **and** no source under `MG_Remote/Client` or `MG_Remote/Server` still matches
`Fatal.Unimplemented`. That is layout-independent in the way the house rule demands - c1, s1 and
v1 have to delete those aborts to implement anything - and it arms itself on the commit that
removes the last one. **Whoever lands the last stub arms eleven ctest entries and two negative
controls in the same commit.** Configure prints which file still carries a stub.
### (b) SSIM cannot be the split retrace gate. A PULL library under `MOBILEGL_TRANSPORT=inproc` replays OpenRA at ssim=1.000
Measured twice, on both threading paths into `run_trace_case.cmake`. In a build without
`-DMOBILEGL_BUILD_DISAGGREGATED=ON` the whole `MOBILEGL_TRANSPORT` parser is compiled out
(CONTRACT-P5 §5), so the variable is accepted by the environment, steers nothing, and every frame
still matches its golden. There are now two guards and neither is the picture:
* **build-level** — `nm --defined-only libMobileGL.so | grep -i MG_Remote` non-empty, asserted in
`build-linux-split`, in `retrace-split`'s library swap and in the gate's part 1;
* **run-level** — `run_trace_case.cmake` demands the library's own log carry
`ConfigLoader`'s `MOBILEGL_TRANSPORT=inproc` INFO line, which exists only in a disaggregated
build. Negative control: a pull library under `inproc` is **RED**, and the failure message names
the transport rather than the picture. This is in the gate as a standing control.
Corollary for everyone: `MOBILEGL_LOG_ACTIVE_LEVEL` must admit INFO in every split lane, because
that one line is the only runtime evidence the transport resolved.
### (c) On llvmpipe the MONOLITH arm of `PersistentCoherentMapScenario` is the ADOPTED arm — so R-6 makes the split A/B a two-path comparison for buffers
Measured in `build-split` with the transport unset, in the window covering exactly the workload:
```
MGPipe stats: ... bytes/f[... pmap=0.00 ...] cso[csom=1 csob=1 mpr=1] ...
```
`mpr=1` (one acquisition attempt for one storage definition, as ARCHITECTURE.md:492 prices it) and
`pmap=0.00` → `MGPipeEmitMapPersistent` **minted**, the store is GPU-resident, the CPU shadow was
released. R-6 pins the split arm at T2 = declined = emulated. So on this driver the two arms of
exit gate E3 run **different buffer code paths**, not the same path over a different transport,
and `mpr` is the only counter that is equal by construction. That is exactly why the counting
lanes are a PAIR that each assert the same constant rather than a cross-lane comparison.
**For b1 specifically** (all seven of your §4.1 items are reconciled in §2c above):
1. `mpr == 1` for one `glBufferStorage(PERSISTENT|WRITE|COHERENT)` + one `glMapBufferRange` + four
writes and four draws. Asserted in both lanes. **Live today**, and `mpr=1` measured.
2. the arm is read from `IsBackendPersistentMapped()` through `Harness/PersistentMapPeek`, your
spelling, **not** inferred from `pmap`. Live today in every lane; the split lane additionally
asserts it equals `emulated`.
3. **`pmap` is printed as a fixed-point PER-FRAME figure** in the `bytes/f[...]` bracket, not an
integer. `PipeStatsWindow::CounterOrAbsent`'s `strtoll` reads `"0.37"` as `0`, which would turn
"the push happened" into "the push moved at least one whole byte per frame" silently. Use the
new `CounterAsDoubleOrAbsent` for any byte class.
4. **Your report and the integrator's message disagree about whether `pmap` is non-zero without
c1.** b1-v1.md §4.2 says "the push is already live at the 21 `SyncPersistentMappedRange` sites
(they route into `PushBlocksFor`), so `pmap` is non-zero without c1"; the integrator's note says
`MarkGpuWritesForDraw` / `MarkGpuWritesForDispatch` / `PushPersistentMapsBeforeVerb` are unwired
and not to expect a non-zero `pmap`. This package is neutral on the question: no lane that RUNS
today asserts `pmap > 0`, so either reading is safe, and the assertion arms with the split lane.
Worth settling before integration, because it decides whether E3(c) is satisfiable by b1 alone.
---
## 4. Decisions this package made that the brief and the contract did not
**D-1. `TriangleScenario`'s first case ends with `EndFrame()`, so `Present` is in target B's slot
set.** verb-census §B flags this as a choice to be made deliberately: the spec as written never
swaps, which would make B a strict subset of A minus `Present`. BRIEF §4.B lists `Present`(67)
among the catalogue rows B needs, so the frame boundary is in. Overturned by: a decision that B
should be the minimal draw and nothing else, in which case delete the trailing `EndFrame()` and B
drops to four slots.
**D-2. The split-lane skip guard lives in `ScenarioFixture.h`, not in the two new scenarios.** The
`Split.` family also points at `ClearThenReadPixelsScenario`, which is target A and predates P5 and
has no guard of its own; without this its five entries were the false greens of §3(a). One place
also means any later Split lane inherits it. The guard fires only when `MGITEST_SPLIT_LANE=1`,
which only the Split entries set, so the other ~1128 entries are untouched.
**D-3. The monolith lanes declare NO arm and RECORD it; only the split lane declares one.** Which
arm `AcquireMemoryRange` takes for a sub-16-MiB map is a property of the driver (llvmpipe mints; a
device may decline), so a monolith lane that pinned one would be red on hardware for a reason that
is not a defect. The value lands in the gtest XML as `persistent_map_arm`, so the recording is
machine-readable rather than a log line. The counting case also `SUCCEED()`s rather than skipping
when no arm is declared, because its `mpr` assertion is that lane's real claim and a skip would
have thrown it away with the arm.
Overturned by: a measurement showing every target device declines, in which case the monolith lanes
can declare `emulated` too and the A/B becomes a pure transport A/B.
**D-4. The trace-replay transport is threaded BOTH ways and asserted once.** `-DTRACE_TRANSPORT=`
(what the SPLIT variant passes) does `set(ENV{MOBILEGL_TRANSPORT})` at the top of
`run_trace_case.cmake`; the assertions at the bottom read `$ENV{MOBILEGL_TRANSPORT}`, so they fire
for the `-D` path and for a process-environment export alike. ARCHITECTURE.md:16 asks for the
former and BRIEF §5 for the latter; they are the same mechanism.
**D-5. `TRACE_OUTPUT_DIR` and `TRACE_ARTIFACT_DIR` carry the variant** (`OpenRA/DirectGLES-SPLIT`,
`OpenRA/actual-images-SPLIT`). `run_trace_case.cmake` `file(REMOVE_RECURSE)`s the output dir before
every run, so shared directories would mean the second arm erases the first arm's
`output/mobilegl.log` - and that log is the only valid refusal census, because the console sink is
compiled out of these configurations and `ctest -V`'s transcript is a false zero.
**D-6. `retrace-split` runs the UNCHANGED ctest names with the transport in the job environment,
not the `SPLIT` names.** `build-retrace` configures without `-DMOBILEGL_BUILD_DISAGGREGATED`, so
the variant entries are deliberately not registered there - a name that says SPLIT in a build that
cannot be one is worse than no name. The `SPLIT` name is registered, and verified to register and
to run, in a build that DOES have the option. See the debt in §6.
**D-7. The E1 and E3(a) negative controls are TWO-STATE, derived rather than assumed.** While the
Split entries skip, a "this step passes when ctest FAILS" control would be red for the whole of P5
for a reason that is not a defect. The expected state is read from the same fact the lanes read:
`MGITEST_REMOTE_CLIENT_PRESENT` appears in the generated ctest include files the artifact ships.
Armed → the knob must turn entries red; disarmed → the step says so loudly (`::warning` in CI, a
named line in the gate) and asserts nothing. It becomes a gate on the commit that lands the last
stub, with no edit.
**D-8. The gate hydrates fixtures from `~/w7/pipe` and never from GitHub.** A `git worktree add`
leaves 40 of the 41 fixtures as 130-byte LFS pointers (only `openra.tgz`'s object is in the local
cache), and a naive sweep then reports **"passed 2 / 79"**, which reads exactly like a
catastrophic regression. After copying from the integration tree - same commit, no network, files
marked `assume-unchanged` - the push sweep is **79 / 79**.
## 5. Where I think the brief or the contract is wrong or incomplete
**W-1 (the important one).** BRIEF §5 t1: *"copy `mgl_itest_probe_for_symbol` (`:402-414`), which
probes for a **symbol**, never a filename"*. Correct as far as it goes and **insufficient here**,
for the measured reason in §3(a). The brief was written before c0 landed the stubs. Amendment
proposed: the house rule should read *"probe for the symbol AND for the absence of the owning
package's own not-implemented marker"* whenever a contract package has already shipped signatures.
**W-2.** BRIEF §5 t1 lists `MOBILEGL_IPC_SERVER_PATH` as something the lanes must carry
(ARCHITECTURE.md:543), which they now do — but **there is no `MobileGLServer` target on Linux at
all**. The only one in the tree is `if (ANDROID AND MOBILEGL_BUILD_SERVER_SPIKE)`
(`CMakeLists.txt:901`), pointing at `tools/spikes/server_stub/main.cpp`. The value the lanes carry
is therefore a path to a file that is never built. That is correct for P5 (inproc consumes none of
it) and it is a **P6 prerequisite nobody currently owns**: someone has to add the desktop
executable with `RUNTIME_OUTPUT_DIRECTORY` = `$<TARGET_FILE_DIR:MobileGL>` before the path means
anything.
**W-3.** ARCHITECTURE.md:521's "`ctest -L integration-gpu` 逐名相同 between the arms" is, taken
literally, trivially true - it is one build directory, so `ctest -N` cannot differ. The failure
worth catching is an inproc arm that SKIPPED forty entries the monolith arm ran, so the gate
compares **name and status**, out of ctest's JUnit output. Suggest the wording be tightened.
**W-4.** BRIEF §6 part 2 says the 79 retrace cases must stay 79/79 on the push and verify arms. In a
package worktree that is impossible without W-1's fixture copy; see D-8. Worth adding to the
preamble's "first day" list beside the submodule symlinks.
**W-5 (small).** verb-census §B says `Flush` is not a slot and `glFlush`/`glFinish` are empty
bodies. Confirmed and acted on: `TriangleScenario` has no `glFlush` and its header says why. But
BRIEF §4.B still lists `Flush`(66) among the catalogue rows target B needs. §12 C-3 retires it;
the §4 list was not updated to match.
## 6. Debts left for later rounds and phases
1. **The `SPLIT` ctest name is not exercised by CI.** `build-retrace` has no
`-DMOBILEGL_BUILD_DISAGGREGATED`, so `retrace-split` uses the unchanged names. Registering and
running it is verified locally (`build-tracesplit`, and the entry's own argv driven through
`run_trace_case.cmake` by hand: ssim 1.000, census 0, and RED against a pull library). If the
phase wants `ctest -L retrace-split` green in CI, `build-retrace` needs a second configure.
2. **RSS slope needs a long case.** `wsl_p5_rss.sh` works (`VmHWM` 475.8 MiB, deciles and a
least-squares slope over the second half), but OpenRA replays to call 31249 in ~1.1 s on
llvmpipe, so its slope is the allocation ramp. The script says so rather than reporting a
number that looks like a leak. Use `minecraft-1.21.4-startup` / `rd12-odinlite` or a device run.
Under inproc the two roles are two threads of one process, so `/proc` cannot separate them: the
script reports the process total plus the shm segment ledger and waits for s1's hooks.
3. **`MGITEST_SPLIT_EXPECT_TRANSPORT` is carried and not yet asserted by any case.** The
transport-resolution check lives in CI and in `run_trace_case.cmake`; a scenario-level arming
case - the `PipeVerifyArmingScenario.Armed` analogue - is the obvious follow-up once c1 lands,
and the marker is already in the split lane's environment for it.
4. **E5 (the five inproc-honesty controls) and E4 (the field-ownership gate) are not in
`wsl_p5_gate.sh`.** They belong to p1 and v1; the gate names p1's generator's absence rather
than skipping over it.
5. **`DirectVulkan.Split.` does not exist**, deliberately: the split shape's first backend is
Espryt. The three `gtest_discover_tests` blocks take a backend the day Magma's server lands.
---
# §7. Fix round 1 — answers to t1-review-v1
Commits `8d0850bd..1abe716f` on `p5/t1` (two more; the package is now `5175f9cc..1abe716f`, six
commits). Every mutation below was applied, observed and reverted by
`~/w7/p5-t1-mutate.py`, whose restores are in `finally` blocks, and the tree was rebuilt after
each. Working tree clean at the end.
## 7.1 The MAJORs
### M-1 — the arming condition is now a RUNTIME fact. FIXED, and re-tested with the reviewer's own mutation.
The review did not argue with the source-text probe, it performed it, and it was right. The
replacement is not a better grep; it is a different kind of statement. `Harness/SplitRuntimePeek.{h,cpp}`
reads three values out of the running process, none of which exists in a monolith build and none
of which a message edit can move:
| fact | why it cannot be faked by editing text | owner when false |
|---|---|---|
| `MG_Config::Transport != Monolith` | in a build without `MOBILEGL_BUILD_DISAGGREGATED` it is a `constexpr Monolith` and this whole TU is compiled out | the build configuration |
| `ClientSession::Active() != nullptr` | c0 made this the ONE non-aborting accessor precisely because "does a session exist" has a legitimate no (`ClientSession.cpp:31`). A null pointer does not become non-null because a string changed | s1 (construction, handshake) |
| `ImplementedVerbCount() > 0` | c0's stub returns 0; the contract gives this function the job of separating "lost an emitter" from "never had one" | c1 |
The whole CMake conjunction is **deleted** - there is no longer a probe, a marker variable, or an
`MGITEST_REMOTE_CLIENT_PRESENT` anywhere in the tree. CMake decides only whether the peek can be
COMPILED, which is exactly the build option. That also closes M-2 and M-3 by construction: there is
no string left for a comment to match or for a stub file outside a probed directory to miss.
**Observed (the reviewer's mutation, verbatim, widened to all eight stub files including the two
M-3 named):** `Fatal{Unimplemented` → `Fatal{NotYetImplemented` in 8 files under `MG_Remote`,
rebuild, `ctest -L integration-split` →
```
100% tests passed, 0 tests failed out of 21
entries skipped: 21 (was: 8 of 11 GREEN before this fix)
```
### M-2 — a comment can no longer keep the lanes dark. FIXED (by the same deletion).
**Observed:** prepending `// NOTE: this file used to raise Fatal{Unimplemented...} before c1 landed.`
to `Client/CapsMirror.cpp`, rebuilding, →
`100% tests passed, 0 tests failed out of 21; entries skipped: 21` — unchanged, because nothing
reads that text any more. Before the fix this line would have disarmed all eleven entries forever.
### M-3 — the two unwatched stub files are irrelevant now. FIXED (same).
`MG_Remote/CapsCodec.cpp` and `MG_Remote/Wire/PipeWireCodec.cpp` were outside the probed
directories; the stub-rename mutation above touched all eight files and the arming condition did
not move, because it no longer depends on any of them. **What it does now depend on, stated so it
is not rediscovered:** if c1/s1/v1 land while w1 has not, the lanes ARM and the entries go red on
w1's codec abort. That is loud and correctly attributed (the abort names `UnimplementedCapsCodec`
and package w1), which is the outcome the review asked for over a tautological green.
### M-4 — the gate's E1/E3(a) controls count their selection first. FIXED.
`wsl_p5_gate.sh` now mirrors CI: `ctest -N … | grep -c` before the control, `*** FAIL` on `< 1`.
**Observed:** `ctest -N -L integration-split -R 'ThisMatchesNothingAtAll'` matches **0**, and the
bare `ctest … --no-tests=error` exits **8** — which is exactly what the old code read as "RED, as
it must be". The armed/disarmed decision in the same loop also moved off the marker string and
onto behaviour (how many entries actually RAN, from the JUnit output), for M-1's reason.
### M-5 — the transport guard matches ConfigLoader's whole sentence. FIXED in both readers.
`run_trace_case.cmake` and the `integration-split` CI step now search for
`MOBILEGL_TRANSPORT=inproc - the MGPipe record stream`, which exists only in
`InitTransport`'s InProcess arm. **Observed** against a crafted DEBUG-level pull log carrying
`Config: Accepted env variable: MOBILEGL_TRANSPORT=inproc`: the old bare-substring grep **PASSES**,
the new one **REFUSES**, and the full `cmake -P` harness returns rc=1 with "never reported
resolving it". The related half is fixed too: a run that asked for `spawn`/`unix:`/`pipe:` now gets
a message saying ConfigLoader REFUSES those by name, instead of one that talks about `inproc`.
### M-6 — `retrace-split` has its negative control. FIXED, and E2's charter control is now a named debt.
The job gains `build-linux` to its `needs`, downloads the **pull** runtime, and ends with an
always-on step that swaps the pull library over the frozen path and requires the same replay to
**fail** — with an `nm` assertion that the control's own library really has no `MG_Remote` in it,
so the control cannot pass for the wrong reason either. Same shape and same sentence as
`retrace-verify`'s.
**What it is not:** BRIEF §7 E2's control ("patch the `Clear` emitter to drop one emission; SSIM
must fall below threshold"). That needs an emitter, i.e. c1. It is now carried as debt §7.4 item 1
rather than silently substituted, which is the part of M-6 that was a reporting failure rather
than a code one.
**Observed locally** (the same assertion the CI step makes): pull library under
`MOBILEGL_TRANSPORT=inproc` → `FAIL … rc=1 ssim=1.0`, log carries `never reported resolving it`;
split library → `passed 1 / 1` with `Fatal{ lines: 0`.
### M-7 — exit gate E3(e) exists. FIXED as a lane, with its remaining gap stated.
`DirectGLES.Split.SmallRing.` — the same three split scenarios with `MOBILEGL_IPC_RING_MB=1` and
`MOBILEGL_IPC_STAGE_MB=1`, ConfigLoader's floor for both (a ring caps one record at half its size,
so 1 MiB caps a record at 512 KiB, far above anything on the reduced path: small, not unusable).
Ten new entries, `integration-split` is now **21**.
**What this lane does not yet assert, said out loud rather than implied:** that a back-pressure
wait actually happened. That needs a producer-parked / ring-full counter only **s1** can publish.
Until then the lane proves the five checks survive a small ring, not that the small ring bit. In
the debts, and in the lane's own comment block.
## 7.2 The MINORs and QUESTIONs
| # | disposition |
|---|---|
| **N-1** stale skip reason | **FIXED.** The message now comes from `SplitRuntimeSkipReason()` and names the first fact that is false. Observed verbatim: *"MG_Remote::Client::ClientSession::Active() is null: no client session exists in this process… packages s1 and c1 have not landed…"* |
| **N-2** three spellings of the symbol list | **FIXED by deletion** — there is no symbol list any more |
| **N-3** the dead names file in CI | **FIXED.** The step now writes two JUnit files and diffs them by name **and status** in-line, with `::error` per differing entry. Observed on two deliberately different JUnit blobs: `diff entries: ['Y'] -> RED` |
| **N-4** a manifest key typo empties a CI matrix | **FIXED twice.** `trace_cases.py` rejects any key outside `KNOWN_CASE_KEYS`; the `trace-cases` job additionally refuses an empty `include`. Observed: `"splitt": true` → `rc=1 ValueError: unknown key(s) for OpenRA: splitt` |
| **N-5** ten of eleven entries had no runtime evidence | **FIXED**, and this is the second half of M-1's answer: `ScenarioTest`'s **destructor** requires the client encoder's record ordinal to have MOVED during any case that ran in an armed split lane. In the fixture destructor rather than `TearDown()` because gtest calls only the most-derived `TearDown`. See gate 14 below — it is the only gate in the package that can catch an emit table that resolves the transport and then falls through to the driver |
| **N-6** the "monolith" counting lane was not pinned | **FIXED.** `MOBILEGL_TRANSPORT=monolith` is now in its `ENVIRONMENT` property, which overrides a job- or gate-level export. `MGITEST_SPLIT_EXPECT_TRANSPORT` is deleted — the peek makes it redundant |
| **N-7** implicit attribute locations | **FIXED.** Both scenarios' vertex inputs are `layout(location = 0/1)`; `CompileProgram`'s `glBindAttribLocation` still agrees with them |
| **N-8** `RESOURCE_LOCK` guards nothing today | **KEPT, not removed.** Each counting lane's filter selects one case today, so the lock has no second holder — but the lock is what lets a second case join the lane later without renaming an entry (G14 forbids the rename that would otherwise be the fix). Cost is zero; the "4/0/2 spurious failures" measurement is inherited from the pre-existing UnlocatedIoBlocks lanes and I have re-attributed it in §1 rather than claiming it for these |
| **Q-1** what can the E3 A/B still claim | **Integrator's call, and I agree with the framing.** With llvmpipe adopting and R-6 pinning split at emulated, the A/B is not a transport A/B for buffers. `mpr` equality is by construction. My recommendation: keep D-3 (the monolith lane records rather than declares) until someone measures the two campaign devices; if both decline, pin both lanes at `emulated` and the A/B becomes real. The measurement belongs to the device round, not to t1 |
| **Q-2** the gate read the union of window and teardown lines | **FIXED.** `wsl_p5_gate.sh` now takes the last `MGPipe stats:` line that is NOT `window=0`. The scenario was already correct (it reads before teardown); only the gate's echo was wrong |
| **Q-3** INFO is a load-bearing, unenforced precondition | **Made a build fact.** `MG_IntegrationTest/CMakeLists.txt` now `message(WARNING)`s when a disaggregated build is configured at a level that is neither INFO nor DEBUG. A WARNING and not an error because the integration lanes no longer depend on the log level at all — they read `MG_Config::Transport` — so the only casualty is the trace-replay assertion |
## 7.3 The 13 gates, with the observed-red column filled in (R-16)
Re-numbered to include the two gates this round added. **11 of 15 observed red**; the four that are
not each name the package that will arm them.
| # | gate | how I made it red | observed |
|---|---|---|---|
| 1 | `ctest -L integration-split --no-tests=error` matches something | ran it in `build-push` and `build-linux`, which never register the label | **RED** (rc=8 both) |
| 2 | `build-split/libMobileGL.so` defines `MG_Remote` | pointed the check at the pull library | **RED** (0 vs 188) |
| 3 | the PULL library defines **no** `MG_Remote` (G1's split half) | pointed the gate's pull-side check at `build-split/libMobileGL.so` | **RED** (`*** FAIL: the pull build defines MG_Remote symbols`) |
| 4 | `run_trace_case.cmake`'s transport-resolution assertion | replayed OpenRA with the pull library under `MOBILEGL_TRANSPORT=inproc` | **RED** — ssim 1.000000 and then `never reported resolving it`. The SSIM is green; only this assertion is not |
| 4b | …the same assertion against a DEBUG-level PULL log | hand-wrote a log carrying ConfigLoader's env-dump line | **RED (was GREEN before M-5's fix)** |
| 5 | `integration-split`'s "the split lane really resolved the transport" | same crafted log against the step's grep | **RED**; the old bare-substring grep accepted it |
| 6 | **the arming condition** | the reviewer's mutation, widened: renamed the stub message in all 8 `MG_Remote` files | **REFUSES TO ARM** — 21/21 still skip (was 8 of 11 green) |
| 6b | …and the comment-only disarm | prepended a comment carrying the old marker | **NO EFFECT** — 21/21 still skip, correctly |
| 7 | negative control E1 `MOBILEGL_IPC_VERB_BARRIER=0` | **not yet** — needs an armed lane | **unverified**; arms with c1/s1/v1. The control's own failure branch was observed by the reviewer in a fake-armed tree |
| 8 | negative control E3(a) `MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0` | same | **unverified**; arms with c1 + b1 |
| 8b | the same two controls' zero-selection hole | gave them a filter matching nothing | **RED** (`matched=0` → `*** FAIL`); the old code printed "RED, as it must be" |
| 9 | the persistent-map arm assertion | declared `MGITEST_PERSISTENT_MAP_ARM=emulated` against a driver that adopts | **RED** — `Which is: "emulated"` / `Which is: "adopted"` |
| 10 | `add_trace_replay_test(… TRANSPORT x)` without `VARIANT` | called it that way through a `cmake -P` harness | **RED** (`CMake Error … with no VARIANT`) |
| 11 | `trace_cases.py` manifest validation | `"splitt": true` | **RED** (`ValueError: unknown key(s)`); the three value-shaped mistakes already raised |
| 12 | G1 / G2 / G14 | not mutated — they are the phase's standing gates and `symbol_report.py --self-test` owns their falsifiability | **unverified here**, reproduced clean |
| 13 | three-arm name+status identity (now in CI as well) | fed the step's own comparator two JUnit blobs differing by one skip | **RED** (`diff entries: ['Y']`) |
| 14 | **NEW — the wire actually moved** (`EmitSeq` advanced) | patched `ClientSession::Active()` to return a static instance and `ImplementedVerbCount()` to return 5: a client that EXISTS and emits nothing | **RED — 19 of 21 entries failed** with *"the client encoder's record ordinal did not move: EmitSeq was 0 at SetUp and is 0 now"*. This is the gate that catches an emit table which resolves the transport and then falls through to the driver, and nothing else in the package can |
| 15 | **NEW — E3(e)'s small-ring lane** exists and runs the five checks at the ring floor | **not yet** — arms with the rest, and asserting that a back-pressure wait HAPPENED needs a counter from **s1** | **unverified**, named |
## 7.4 Debts, updated
1. **E2's charter negative control** — "patch the `Clear` emitter to drop one emission, SSIM must
fall below threshold" (BRIEF §7). Needs an emitter. **Owner: c1**, on the commit that lands it.
The pull-library control now in `retrace-split` is a different statement and is labelled as one.
2. **E3(e) needs a back-pressure counter.** The lane exists; proving the ring actually blocked
needs a producer-parked / ring-full tally on `RingControl`. **Owner: s1.**
3. **Gates 7, 8 and 15 are unverified until the lanes arm.** They are wired, their failure
branches are written, and the reviewer observed 7 and 8 working in a fake-armed tree. Integration
should re-run `integration-split` and `wsl_p5_gate.sh` on the commit that lands the last of
c1/s1/v1 — that single commit turns 21 skips into 21 runs and three unverified gates into three
verdicts, with no edit anywhere in this package.
4. **The `SPLIT` ctest name still is not exercised by CI** (unchanged from §6.1): `build-retrace`
configures without `-DMOBILEGL_BUILD_DISAGGREGATED`, so `retrace-split` uses the unchanged names
with the transport in the job environment. The variant entry is verified to register and to run
locally, including through its own `-D` path.
5. **RSS slope still needs a long case** (unchanged from §6.2).
## 7.5 Acceptance, re-run at `1abe716f`
| | |
|---|---|
| G1 | `.text 10806323 -> 10806323 (+0)`; `27811 -> 27811` defined symbols, **0 added / 0 removed / 0 resized / 0 renamed** |
| G1 split half | `nm … grep -ic MG_Remote` = **0 / 0 / 0 / 188** (linux / push / verify / split) |
| G2 | pull-vs-push name diff **0** |
| G14 | **0 removed, 11 added** (the same 11; the 10 new `SmallRing` entries are inside `if (MOBILEGL_BUILD_DISAGGREGATED)` and so are in neither compared build) |
| `ctest -L unit` | 1785 / 1785 / 1785 / **1842** |
| `ctest -L integration-gpu` | pull **1128/1128**, push **1128/1128** |
| split `integration-gpu` | monolith **1149/1149**, inproc **1149/1149**, **name+status diff 0** |
| `ctest -L integration-split` | **21 / 21**, all skipping by name, naming `ClientSession::Active()` |
| ... in a build without the option | **red** (rc=8) |
| OpenRA inproc retrace | **1/1**, ssim 1.000000, `Fatal{` lines **0** |
| OpenRA inproc retrace, pull library | **red**, and red for the transport, not the picture |