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

408 lines
33 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.
# v1-v1 — the server role, the apply thread, and the EGL context migration
Branch `p5/v1`, commits **`5e5bf7b9..571cbabb`** (six single-line commits; base = the integration head
`feat/disaggregated@5e5bf7b9` = wave 1 + `dev fff9d639`, merged first per ID-44). Resumed after the
Sep 11 outage from the uncommitted WIP the integrator preserved (ID-45); nothing was restarted.
Commits, oldest first:
| sha | what |
|---|---|
| `377356f8` | R-11: `MG_Remote/Server/StagedShadow.h` + the four `Managers.cpp` sites; `Fatal{StageSnapshotTooNarrow}` asserted BEFORE the flush drain |
| `8dbe230a` | `Server/PipeApplier.{h,cpp}`: `Attach` on the apply thread, stamp → apply → clear per record, `ServerVerbSink` for the five class-B verbs |
| `23c04687` | `Server/ServerLoop.{h,cpp}`: `mgl-srv-apply`, affinity mask, three-way park predicate, blocking control mailbox, bounded `Stop`, the twelve EGL forwarders |
| `d6231184` | `MG_Backend/Init.cpp` hook + `MobileGL/Init.cpp` `ShutdownSplitRoles()` at the top of `DestroyImpl` |
| `7ea3b1d1` | `MG_Test/Wire/ServerLoopTest.cpp` (11 cases) + its CMake registration (split-only) |
| `571cbabb` | G1 fix: `ShutdownSplitRoles` exists only under `MOBILEGL_BUILD_DISAGGREGATED` |
Files touched: `MobileGL/Init.cpp`, `MG_Backend/{Init.cpp,BackendObjects.h}`,
`MG_Backend/DirectGLES/Managers.cpp` (b1's; R-11 only, see §5), `MG_Remote/Server/{ServerLoop,PipeApplier}.{h,cpp}`,
`MG_Remote/Server/StagedShadow.h` (new), `MG_Test/Wire/{ServerLoopTest.cpp,CMakeLists.txt}`. No `.def`, no
generator, no c0/c1/s1/w1/p1/t1 file.
---
## 1. What landed
**The thread (charter 1).** `ServerLoop::Start` spawns `mgl-srv-apply`; the thread names itself, resolves
`MOBILEGL_IPC_SERVER_AFFINITY` (`auto` = `ShaderCompilePool`'s 85%-of-peak cpufreq rule re-derived as a
MASK, `off` = 0, or a number), applies it with `sched_setaffinity`, and **logs the RESOLVED mask** (0 on this
WSL box: no cpufreq tree, so "do not pin" rather than "pin to a guess"). It parks through
`Doorbell::Wait(control.consumerParked, ready, spinUs, kWaitForever)` and treats `Wait == false && Dead()` as
shutdown. The park predicate is THREE things - ring head moved, stop requested, control request pending -
not `SessionConsumer::WaitForWork`'s one: a `Notify` is consumed by one `Park`, so a predicate that cannot
see the control request re-parks for ever (that is red-check case `park-predicate-loses-control`, which
must TIME OUT). `Stop` = set stop, ring, wait for the exit flag with a **5 s bound**, then `join`; a bound
that expires is `Fatal{ApplyThreadJoinTimeout}` + abort, never detach (a detached apply thread still owns
the context and reads rings the client is about to unmap).
**The EGL migration (charter 2).** `ServerLoop::CreateBackend` builds the server's private
`BackendObject_DirectGLES` (or `_DirectVulkan`) on the app thread and runs its non-GL `Initialize()`; the
context is created and made current LATER, on the apply thread, when the client's `eglMakeCurrent`
crosses as a blocking control request (`RunOnApplyThread`: one-slot mailbox, caller-serialised, runs
INLINE when already on the apply thread - which the teardown path needs, and inline when no thread exists
yet). Twelve free-function forwarders `Server{InitializeEGLDisplay, CreateEGLWindowSurface,
ResizeEGLWindowSurface, CreateEGLPbufferSurface, MakeEGLCurrent, SwapEGLBuffers, SetEGLSwapInterval,
ReleaseEGLSurface, ReleaseEGLResources, InitCapabilities, InitWindowSurface, SetWindowHandle}` are the seam
c1 needs; `ServerMakeEGLCurrent` and `ServerInitCapabilities` also **re-publish the CapsSnapshot** on
success (R-12 arm (a): a second arrival IS the invalidation). The backend is **destroyed on the apply
thread, while it still owns the context**, by the thread itself on its way out - so `~BackendObject_DirectGLES`
→ `DestroyEGLContext` never runs on the app thread. Evidence it works: on the joint build the log shows
`GL_VENDOR: Mesa` / `GL_RENDERER: llvmpipe` written by thread `mgl-srv-apply`, `CapsMirror generation 2
adopted` on the client after make-current, and `destroying the server's BackendObject on mgl-srv-apply,
which is the context owner` at teardown (`~/w7/p5-v1-joint-preflight.log`).
**The hook (charter 3).** `MG_Backend::Init()` gains one `#if MOBILEGL_BUILD_DISAGGREGATED` block before the
`switch`: if `Transport != Monolith` → `InitSplitRoles()` = server backend → the two CallMask halves (§1
"caps") → `ClientSession::Start` (s1/c1's; it does the handshake and ends by calling `ServerLoop::Start`) →
the client's backend object into `pActiveBackendObject` → `InitSpecificBackendLibs()` (which fills
`gBackendFunctionsTable` from THAT object, i.e. c1's emit table) → `LogBackendInfo()`. c1-v1 §8.2's order,
exactly. A failed bring-up leaves `pActiveBackendObject` null and returns - **no fallback to the switch**.
The counterpart `ShutdownSplitRoles()` runs first in `DestroyImpl` (§1 "teardown").
**The applier (charter 4, 5).** `PipeApplier::Attach` builds w1's decoder ON the apply thread (its
constructor installs the process-wide apply hook) and points it at `ServerVerbSink`. `ApplyOne` =
`StampVerbBoundary(op)` → `DecodeAndApply` → `LeaveApplier()`; s1's `SessionConsumer::ApplyOne` advances
`appliedSeq` by exactly one after it returns, and nothing here touches `RingControl`. No batching. After each
drain batch: the decoder tally and the session watermark must agree (`Fatal{ProtocolCorruption,
"appliedSeq batched"}` otherwise) and `RetireThrough(AppliedSeq())` runs once. p1's rule verbatim:
`MGPipeVerbForWireOp(op)`, `kVerbCount` ⇒ nothing, else `MGPipeServerStampVerbBoundary(verb)` once before the
applier; `MGPipeServerClearVerbBoundary()` on leaving - **inside `ApplyOne`, before the watermark publishes**
(§6). `PipeApplier::m_residualPulls` is deleted; `ResidualPullCount()` forwards to `MGPipeResidualPullCount()`.
`ServerVerbSink` is the consumer for the five class-B verbs that have no `MGPipeApply*` entry point: `Clear`
(five kinds, three value classes, against the BOUND framebuffer - `MGPClear::Fbo` is null by c1's ruling),
`Blit`, `Present` (through the server's own `Present`, so `present ↔ eglSwapBuffers` stays 1:1;
`FrameSerial == 0` = stamp your own), `ReadPixels` (writes exactly `DstSize` bytes into the reply slot,
`DECLINED` when no table, `ERROR` on zero size - never a silent non-answer, because the client is parked on
that seq), `DrawVbo` (single non-instanced arrays / indexed draw; `NumDraws != 1`, instancing and any user-index
span are DECLINED BY NAME - P8's). Per-verb tallies exist for lanes to assert against.
**R-11 (charter 6).** `StagedShadowStore` (header-only, keyed by the resource twin's address) copies
`[offset, offset+size)` into server-owned storage and records the EXACT covered ranges (adjacent runs merge,
gapped ones do not). `Ops_H_SubData` / `Ops_H_FlushRange` / the respecify base go through
`MGL_SERVER_STAGED_ADOPT`, whose non-split expansion is the ORIGINAL expression character for character
(`raw - offset`), so push/verify compile what they compiled before. Drops at destroy, at a successful
`map_persistent`, and at context death. The integrator's M-6 ruling is enforced as
`Fatal{StageSnapshotTooNarrow, "<site>"}`: `UploadRangeFrom` and the tier-1 invalidating map in
`Ops_H_FlushRange` check their own range, and the three-tier drain's queue is checked at its two
server-shadow call sites (`Ops_H_Readback`, the handle-arm ensure path) by
`RequireStagedCoverageForPendingRanges` **before** `FlushPendingRangesFrom` is called - the pinned body is
untouched (§5). The store's copying arm is a constructor parameter, not a `MG_Config::Transport` read, so
`StagedShadowTest` builds one of each and asserts the DIFFERENCE.
**Caps defaults (charter 7).** `InitSplitRoles` sets both halves before `Accept`: `SetCapabilityBits(0)`
(explicit: `kCapNeedsHostIndexBytes`/`kCapNeedsHostUboBytes` are 0 for all of P5 by table 0) and
`SetConsumedSubsystems(ConsumedSubsystemsFor(type))` = `kMGPipeSubsystemsMigratedAtP4a` for DirectGLES,
the same minus `kMGPipeSubsystemResources` for DirectVulkan (which registers no resource ops) - stated from
what the backend IS, **not** derived from the process-wide `MGPipeGetResourceOps()`, which under inproc
answers with whatever the client half registered. `AssertConsumerMaskIsHonest` runs after `Initialize()` and
is `Fatal{ConsumerMaskLie}` if the mask claims the resource family while no op table is registered (ID-39's
shape, one level down). On the joint run the client adopted `callMask=0x1fff00000000`.
**Teardown (charter 8).** `ShutdownSplitRoles()` → `ClientSession::Stop()`, which IS table 3's order:
publish + bounded drain → `transport->Shutdown()` (= `Doorbell::Kill`, the only thing that wakes a
`kWaitForever` park) → `ServerLoop::Stop()` (bounded join; the thread applies whatever is still queued,
detaches the decoder, destroys the backend on itself) → only then the emitter-owned things → transport
closed. It runs at the TOP of `DestroyImpl`, so the apply thread is joined before `PipeStats::Shutdown()`
dumps and before `pActiveBackendObject.reset()`. **The sync/query registries keep today's order** (drained at
`MobileGL/Init.cpp:62/:67`, before `:68`); CONTRACT §4's known open item is recorded as "P5 keeps today's
order" in `BackendObjects.h`, and it is P10's to move. Under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`
(exported by the gate) every case, the shutdown case included, is green; `StopKillsTheDoorbellJoinsAndTheThreadReallyExits`
asserts the thread really PARKED first and that `Stop` returned inside the bound.
---
## 2. Acceptance
| charter line | status | evidence |
|---|---|---|
| `DirectGLES.Split.ClearThenReadPixelsScenario.*` green under `inproc` | **green on the joint preview**, not on `p5/v1` alone (needs c1) | `~/w7/p5-v1-joint-isplit.log`: 21 entries, **19 passed, 2 skipped by design** (`TheMapLandsInTheArmItsLaneDeclares` in the two non-counting lanes: "MGITEST_PMAP_LANE is set only by the *.PersistentMapArm.* entries"; the counting entry passed). All 5 `ClearThenReadPixels`, both `TriangleScenario`, both `SmallRing.*` families. The probe is t1's runtime one (`SplitLane.h:SkipReasonForSplitOnlyAssertions` → `SplitRuntimeSkipReason`), armed only by a live session, non-zero implemented verbs and a moved record ordinal - not by source text. |
| four self-tests, all four dirs + split; G1 must not move | **all green**, §3 | `~/w7/p5-v1-gaterun.log` |
| teardown clean under the tcache tunable, 5 s bounded join | green | gate exports it; `ServerLoopTest.StopKills…` + red-check `park-predicate-loses-control` (the case TIMES OUT when the predicate loses the control flag, i.e. a lost wakeup is red, not a wedge) |
| `MOBILEGL_IPC_AUDIT=1` on the reduced path, no 0xDD reaches a draw | **19/21 green under audit** on the joint | `~/w7/p5-v1-joint-isplit-audit.log`; plus unit-scope `TheAuditPoisonFillsExactlyTheStagedRunAfterTheApplierReturns` (asserts the bytes crossed, the poison ran, and it landed on the named run, read back through the CLIENT's mapping) |
**The first IPC frame renders on the reduced path** (`~/w7/p5-v1-joint-preflight.stdout`:
`[ OK ] ClearThenReadPixelsScenario.ClearWithNoDrawIsVisibleToDefaultFramebufferReadPixels (6 ms)` under
`MOBILEGL_TRANSPORT=inproc`, `MGITEST_SPLIT_LANE=1`, `MOBILEGL_ITEST_REQUIRE_GPU=1`), **after three seam
fixes that live on the scratch branch only** (§8). `p5/v1` by itself cannot arm the lane: there is no client
role without c1, and the weak placeholder aborts by name rather than pretending.
---
## 3. The four self-tests (final gate on `571cbabb`, `~/w7/p5-v1-gate.sh`, log `~/w7/p5-v1-gaterun.log`)
All four dirs rebuilt first (`CTestTestfile.cmake` checked before anything is reported, C-10).
| | pull | push | verify | split |
|---|---|---|---|---|
| build | rc=0 | rc=0 | rc=0 | rc=0 |
| `ctest -L unit` | **1813/1813** | **1813/1813** | **1813/1813** | **1985, 2 known reds** (`RingTest.TheTwoFlagSpacesAreDisjointByTranslation` = s1's ID-43, `PipeWireCodecTest.NoReplyIsWrittenForARowTheCatalogueGivesNoReplySlot` = c1's ID-31) = the charter's 1974 + v1's 11 |
**G1** (pull build vs `~/w7/p5-before-libMobileGL.so`, marker `4595163c`):
`.text 10806611 -> 10806611 (+0, +0.000%)`, `27814 -> 27814 defined symbols: 0 added, 0 removed, 0 resized,
0 renamed`; `nm pull MG_Remote = 0`, `nm split MG_Remote = 426`, `ServerLoop` symbols in split = 24.
**It was red on the first measurement** - `+32 .text, 1 added (MG_Backend::ShutdownSplitRoles()), 1 resized
(DestroyImpl)` - because the first version called `ShutdownSplitRoles()` unconditionally from
`MobileGL/Init.cpp` with an empty body in a pull build. "A no-op call" is still a call and a symbol. Fixed in
`571cbabb`: declaration, definition and call all under `#if MOBILEGL_BUILD_DISAGGREGATED`.
**Integration:** `build-push`, `MOBILEGL_TRANSPORT=monolith`, `ctest -L integration-gpu`: **1128/1128**.
`build-split`, monolith: **1149 with exactly the seven known reds**, all `PersistentCoherentMapScenario`
(b1's ID-42), none other.
**G2/G14**, in the integrator's exact shape (`wsl_p5_gate.sh:25,118-122`: every registered name, `comm`):
names pull 2941 / push 2941 / split 3134 / baseline 2902; G2 pull-vs-push **0** diff lines; G14 pull
**0 removed**, 39 added (wave 1's own, identical to c1's report); split vs push 0 removed, 193 added (182
wave-1/c0 split-only + v1's 11).
**Generators:** `gen_pipe --check`, `gen_pipe_field_ownership --check`, `gen_pipe_dirty_surface --check` all
up to date (v1 touched none); `check_include_closure`: 4 probes, 0 problems.
**G5 (`scripts/p3a_untouched_regions.sh` / `p4a_…`)** against `ff2994d9` and against `5e5bf7b9`: the ONLY
region that moves is `FlushPendingRangesFrom`, and its sha at my HEAD is **`172b0222…`, the integration
head's own body** (ID-41) - p3a reports "byte-identical between 5e5bf7b9 and HEAD" for all eleven; p4a stays
red on that one name because it consults the pin unconditionally (ID-41's D-N/2), which b1's re-pin closes.
My WIP had a line INSIDE that body; §5 says where it went.
**Flake sweep** (new gate part 2b): v1's suite ×100 under `-j 8`: 100% - the two ordering defects were
1-in-40 reds at that load, so a single green run is not a verdict for this suite.
---
## 4. The red-check (R-16): `python3 ~/w7/p5-v1-redcheck.py`, log `~/w7/p5-v1-redcheck.log`
Baseline green → each of TEN perturbations rebuilds `build-split`, runs the named case, and must go RED →
restore → baseline green again. Final line `P5_V1_REDCHECK_ALL_WENT_RED`. "I made it red once, by doing X":
| gate | X |
|---|---|
| `AClearRecordCrossesAndIsStampedAsAVerbBoundary` | `stamp-removed`: `StampVerbBoundary` answers `kVerbCount` → red at :366 |
| same, the M-5 half | `leave-applier-removed`: comment out `LeaveApplier()` → `ServerStampedVerb()` stays true, red at :373 |
| `TheSessionWatermarkAndTheDecoderTallyAgreeAfterEveryRecord` | `drained-tally-removed`: remove the per-record `m_drained` bump → red at :398 (deterministic control for the ordering defect, §6) |
| same, the retire half | `retire-removed`: comment out `RetireThrough` → the 2 s bounded poll of `retiredSeq` times out, red at :414 |
| `AControlRequestRunsOnTheApplyThreadAndUnparksIt` | `control-runs-on-caller`: `if (true) return work(user)` → "ran on the CALLER" at :250 |
| same, the un-park half | `park-predicate-loses-control`: drop `ControlIsPending()` from the predicate → the case **times out at 60 s** (the honest shape of a lost wakeup) |
| `TheAffinityStringResolvesToAMaskAndTheMaskIsLogged` | `resolved-mask-not-logged`: rename the log token → :335 |
| `TheAuditPoisonFillsExactlyTheStagedRunAfterTheApplierReturns` | `audit-poison-disarmed`: `SetAuditPoison(false)` after attach → :483/:491 |
| `StagedShadowTest.TheSplitArmCopiesAndSurvivesTheSourceBeingPoisoned` | `r11-copy-removed`: the split arm returns `raw - offset` → seven :529 reds (the copy reads 0xDD) |
| `StagedShadowTest.CoverageIsExactAndAGapIsNotCovered` | `coverage-widened`: merge ranges 16 bytes apart → :547-:552 |
Every control asserts its own string; no case constructs the state it observes (records go in through w1's
encoder over a real `ShmSegment` session and come out through the real apply thread; nothing calls
`PipeApplier::ApplyOne` directly, nothing writes a record field by hand); no probe arms against a stub (the
five class-B verbs DECLINE in the unit process because there is no GL context, and the case asserts the
decline - `Clears() == 0` - rather than skipping).
---
## 5. Charter/contract lines I did NOT do, or did differently - with evidence and what overturns the ruling
1. **`ClientSession::ScopedApplierEntry` does not bracket `ApplyOne` on `p5/v1`.** It cannot: the type
(and the two `Note*` statics) exist only on `p5/c1`; the integration head's `ClientSession.h` has the two
stubbed predicates and nothing to call. The bracket IS placed and verified on `p5/v1-joint`
(`0a02f94b`, in `~/w7/p5-v1-joint-seam.diff`): a `const Client::ClientSession::ScopedApplierEntry` at the
TOP of `ApplyOne`, covering the stamp and `LeaveApplier` too, not only `DecodeAndApply` - both are
`gPipeInputs` writes and the client asserts the flag is DOWN before it publishes, so a bracket around the
decode alone would leave two real writes outside the check. It drops before `ApplyOne` returns, i.e.
before s1 publishes `appliedSeq`, so the client can never observe it up. The 19 passing split entries ran
with it in. **Integrator: apply that hunk in the merge commit.** Overturned if c1's flag moves out of
`ClientSession.h` into something the server may include.
2. **My R-11 line inside `FlushPendingRangesFrom` is gone, deliberately.** The WIP asserted coverage INSIDE
the pinned body (`MGL_SERVER_STAGED_REQUIRE(..., "flush_pending_ranges")`). ID-41 admits the row's move
for b1's re-parameterisation and b1 re-pins to `172b0222…`; a second move by v1 would turn G5 red again
the moment my landing follows b1's. So the pinned body is byte-identical to the integration head and the
coverage Fatal moved to the instant BEFORE the drain takes the queue, at the two call sites whose base can
be a server shadow (`Ops_H_Readback`, the handle-arm ensure path), through
`RequireStagedCoverageForPendingRanges` - same clamp as the drain's, checked over `pendingRanges` under
`pendingMutex`, `RequireCoverage` no-ops for the legacy arm's `MappedData()`. Cost: the three clamp lines
are spelled twice. Overturned if a THIRD caller ever passes a server shadow (grep `FlushPendingRangesFrom(`:
the other two pass `MappedData()`). Also note for ID-41: my WIP never passed `hostBaseFrom/To`; it asserted
coverage instead. The two defaulted parameters are unused by v1.
3. **No `mgl-srv-io`** - by charter; inproc's control plane is in-process (`InProcessTransport`), P6 splits it.
4. **`ServerVerbSink::OnClear` implements all five kinds and three value classes**, where c1-v1 §3 says
`OnClear` "should Fatal on anything else" than `Whole`. The numbering is shared (`kMGPClearKind*` in
`PipeApplier.h` = c1's `MGRemoteClearKind`, Whole..DepthStencil = 0..4, same order, `ValueClass` reuses
`Core.h:39-41`'s three-way split), each arm is a distinct GL entry point rather than a guess, and an
out-of-range value IS `WireProtocolFatalAt`. c1 emits `Whole` only in P5, so the other arms are inert
until the eight `glClearBuffer*`/`glClearNamedFramebuffer*` migrate. FLAGGED FOR c0: both enums belong in
`MGPipeTypes.h`, which is c0's; two package headers now agree by discipline, not by construction.
5. **The `rsp` floor.** A record that is NOT a verb boundary applies with the stamp flag disarmed (p1
forbids re-stamping on a non-verb op), so a sticky forward pulled from inside such a record's applier is
not counted. Documented in `PipeApplier.cpp`; closing it needs an "enter the applier without stamping"
entry point in p1's `PipeInputs.cpp`. The number this phase reports is a floor, never an over-count.
6. **DirectVulkan under split is untested by me.** `CreateBackend` and the consumer mask handle it (bit 7
withheld), the inproc lane's DirectVulkan entries are in `~/w7/p5-v1-joint-inproc.log` (§8), but no
DirectVulkan split scenario exists to arm.
7. **OpenRA under split / audit** was not run: it needs t1's `SPLIT` trace-replay variant and c1's landing;
the audit was run over the 21 split entries only.
8. **`MOBILEGL_IPC_VERB_BARRIER=0` and `MOBILEGL_IPC_STRICT_ERRORS=1`** were run once each on the joint split
lane and the way they go red is recorded in §8 (they are lane matters, but the brief says "run once and
record", so they are).
---
## 6. The ordering defect - what it was, and its fix
My last words before the outage were "Found a real ordering defect via the red-check baseline". Re-derived
today by re-running that baseline under load (`ctest -R 'ServerLoopTest|StagedShadowTest' -j 8 --repeat
until-fail:40`): **red at run < 40** - `TheSessionWatermarkAndTheDecoderTallyAgreeAfterEveryRecord:398`
(`DrainedRecords()` 7, expected 8) and `AClearRecordCrossesAndIsStampedAsAVerbBoundary:365` (0, expected 1).
**The family is "server-side bookkeeping ordered AFTER the watermark that releases the client".** s1's
`SessionConsumer::ApplyOne` publishes `appliedSeq` the instant the apply callback returns, and publishing
`appliedSeq` is what makes the client runnable (R-1). Anything the apply thread records about a record AFTER
that publish is visible to the client only eventually. Two members:
- **(a) `LeaveApplier()` after the drain batch** - the stamp-clear ran while the client was already touching
`gPipeInputs`: a second writer, table 3's one forbidden thing. **Already fixed in the WIP** the integrator
preserved: the clear is inside `ApplyOne`, before the publish (`PipeApplier.cpp`'s block says so, and
`~/w7/p5-v1-patch3.py`'s timestamp shows the red-check anchor moved from `ServerLoop.cpp` to
`PipeApplier.cpp` at 16:32 on Sep 11 - that was the fix in flight).
- **(b) `m_drained` tallied once per batch, after the publish** - unfixed in the WIP, reproduced today,
**fixed in `23c04687`**: the tally moves inside the apply callback, before s1 publishes, so
`DrainedRecords()` can never lag `appliedSeq`. 200 consecutive `-j 8` runs of the two cases green after the
fix; the gate's 100× flake sweep is green; red-check `drained-tally-removed` is the deterministic control.
(A third, `retiredSeq`, is NOT a defect: R-9 lets every watermark but `appliedSeq` publish late, and the
case polls it with a 2 s bound instead of reading it once - the bound is what keeps it a check.)
Which of the two the sentence referred to I cannot know from the record; both were in the red-check
baseline's failure mode, (a) was fixed in the tree I inherited and (b) was not. Both are fixed now, and the
gate now sweeps for this family under load.
---
## 7. What I think the brief or contract got wrong
1. **A weak-symbol seam is unsafe under the static archive the tests link.** My own design, not the
contract's, but worth recording as a tenth-class finding: `MobileGLIntegrationTest` links `MobileGL_s`;
an archive member is pulled only to satisfy an UNDEFINED reference, and `ServerLoop.cpp.o`'s weak
`CreateRemoteBackendObject` already satisfied it, so c1's `BackendObject_Remote.cpp.o` was never linked and
the joint build aborted in the placeholder with c1's object fully present (`nm` shows the symbol `t`, local,
at the placeholder's address). Direct construction in the hook (c1-v1 §8.2's own wording) needs no
factory and no weak symbol; that is the merge-time form (§8).
2. **The preamble's G14 wording ("`ctest -L integration-gpu` … name-for-name equal to
`p5-before-ctest-names.txt`") does not describe the file.** The file is `ctest -N` over EVERY label (2902
names, unit suites included); the integrator's `wsl_p5_gate.sh:118-122` compares all names with `comm`.
Taken literally, the preamble's line produces a 1774-line diff on a correct tree (my first run printed 213
`AsyncCompileTest.*` "removals"). My gate now spells it the integrator's way.
3. **c1-v1 §8.4 says `TriangleScenario` "will not" render without the 37-entry `MGPipeApply*` routing.
It does** - both cases pass under inproc - because the P3a handle arm already DEFERS every GL touch made
on a non-owner thread (`CanTouchGLNow()` false → `pendingRanges` / lazy ensure) and the apply thread drains
them at the draw. That is "right by accident under inproc", the exact shape R-8 warns about: the same
records execute nothing under spawn. R-17's routing is still required; the green triangle must not be read
as its absence being harmless.
4. **Table 3's `pActiveBackendObject` row says the EGL lifecycle becomes "a blocking request onto the apply
thread" but not THROUGH WHAT.** c1 built its own trampolines over `RunOnApplyThread` + `Backend()` instead of
the twelve forwarders, and thereby skipped the R-12 republish that `ServerMakeEGLCurrent` carries - while
c1's own `InitCapabilities` comment assumes the republish happened. The contract should name the
forwarders as the seam (they are declared in `ServerLoop.h` for exactly that reason).
5. **ID-41 credits my WIP with "passing a real extent"**; it did not - it asserted coverage. Harmless to the
ruling (the re-pin target is still `172b0222…`), but the pin's justification should not cite a caller that
does not exist.
6. **BRIEF §5 says 19 `CanTouchGLNow()` sites; the contract's 16 is right** (c0-v1 §6.13) - already known,
restated because the charter text repeats 16+16 correctly.
---
## 8. The joint preview: `p5/v1-joint` = `p5/v1@7ea3b1d1` + `p5/c1@87c1e1be` (c1 round 1 + the same dev merge; c1 round 2 had landed no code yet)
Worktree `~/w7/p5-v1-joint`, links toggle `~/w7/p5-v1-joint-submodlinks.sh`, split build only. Merge
`c24cb5b7` had ONE conflict (`MG_Test/Wire/CMakeLists.txt`: both packages appended a test target; kept
both). Then three scratch commits, **none of which is on `p5/v1`** (`~/w7/p5-v1-joint-seam.diff`, 137
lines, `git diff c24cb5b7 f3ed2ed4`):
| scratch commit | edit | whose |
|---|---|---|
| `0a02f94b` | `ScopedApplierEntry` bracket at the top of `PipeApplier::ApplyOne` | **v1's** - the merge hunk (§5.1) |
| `0a02f94b` | c1's `RunMakeCurrent` → `Server::ServerMakeEGLCurrent(...)` (runs inline on the apply thread; carries the R-12 republish) | c1's file - **c1 must provide** (or call all twelve forwarders) |
| `97f8b8d2` | hook constructs `MakeUnique<MG_Remote::Client::BackendObject_Remote>()` directly (`#include <MG_Remote/Client/BackendObject_Remote.h>`); weak placeholder deleted from `ServerLoop.cpp` | **v1's two files - the merge-time form**, for the integrator's merge commit (§7.1) |
| `f3ed2ed4` | `m_started = true;` restored in `ClientSession::Start` step 7 | c1's file - **c1 must provide**: c1's rewrite of `Start` dropped s1's line (integration head `ClientSession.cpp:328`), so `EmitAndWait`'s `!m_started` guard aborted EVERY verb with `Fatal{NoClientSession, "Clear"}` on a fully-up session |
The three failures, in the order they were hit, each the first real failure of its run
(`~/w7/p5-v1-joint-preflight.log` is the last run's log):
1. `Fatal{UnimplementedRemoteBackendObject}` in the pre-flight child → every entry SKIPPED (harness: "the
EGL bring-up ABORTS … signal 6") - the static-archive link, §7.1.
2. `Fatal{NoClientSession, "Clear"}` at the first verb, after `CapsMirror generation 2 adopted` - c1's
missing `m_started = true`.
3. none: `[ OK ] ClearThenReadPixelsScenario.ClearWithNoDrawIsVisibleToDefaultFramebufferReadPixels (6 ms)`.
**`ctest -L integration-split` on the joint: 21 entries, 19 ran and passed, 2 skipped by design**
(`~/w7/p5-v1-joint-isplit.log`); **under `MOBILEGL_IPC_AUDIT=1`: identical, 19/21**
(`~/w7/p5-v1-joint-isplit-audit.log`) - no 0xDD reached a draw. Unit lanes `ServerLoopTest` + `StagedShadowTest`
+ c1's `RemoteClientTest`: 11/11 in the joint binaries (the bracket and c1's barrier check coexist).
**The `inproc` integration-gpu lane** (`MOBILEGL_TRANSPORT=inproc ctest -L integration-gpu`, 1149 entries,
`~/w7/p5-v1-joint-inproc.log`). Before the seam fixes: 1138 skipped + 11 failed, all "the EGL bring-up
ABORTS" (the placeholder). After them: **428 passed, 185 skipped, 506 subprocess-aborted, 28 failed**. The
aborts are R-4 working as ruled - a class-C slot by name, e.g. `CrossFrameBufferScenario.VertexBufferSubData`
→ `Fatal{UnmigratedVerb, "DrawElements"}` (probed directly with a log file; ctest's capture holds only the
gtest lines because `MGLOG_F` writes to the log file). What passes is what the six-verb reduced path plus
the deferred handle arm can serve: `OrientationScenario` (11/11 DirectGLES), `HandleRecycle.*`,
`AdvertisedLimitsScenario`, the `Split.*` families; what aborts is every suite that reaches a class-C verb
(`ImageTargetKindScenario` 29, `CrossFrameBufferScenario`, `VertexAttribBindingScenario`,
`UnboundImageDescriptorScenario` 13 each, both backends). This lane is judged on the reduced path only
(BRIEF §4); the 506 are the census's 65 `Fatal{UnmigratedVerb}` slots being reached, not a v1 defect.
**Negative controls, run once each on the joint split lane, and the way each goes red:**
- `MOBILEGL_IPC_VERB_BARRIER=0` (R-1's control, `~/w7/p5-v1-joint-isplit-barrier0.log`): **19 of 21 red**.
One assertion-red - `ClearThenReadPixelsScenario.cpp:290/:295`, `bottom.r`/`top.b` read back as `0`
where `> 200` was cleared (the readback overtook the clear); the other eighteen ABORT with
`Fatal{BarrierViolation, "DrawVbo"}` - c1's runtime form of R-1's invariant, which can only fire because
the `ScopedApplierEntry` bracket (§5.1) raised the apply-side flag. That is the bracket's own red-check.
- `MOBILEGL_IPC_STRICT_ERRORS=1` (R-7.3, `~/w7/p5-v1-joint-isplit-strict.log`): **19 of 21 abort** on the
APPLY THREAD with `Fatal{UnmigratedPipeInput, "GetTextureContextId@Clear"} [BARRIER-PULLED,
MOBILEGL_IPC_STRICT_ERRORS=1, retires in P3b/P4b]` - p1's instrumentation naming the first `rsp` read the
server makes on the reduced path, exactly table 2's row. The `rsp` count is the P3b/P4b debt; the number
itself is for the `PipeStats` line once the lane runs under the integrator's gate.
---
## 9. What c1 must provide (nothing of it is implemented on `p5/v1`)
1. `m_started = true;` before `g_active = this;` in `ClientSession::Start` step 7 (§8, `f3ed2ed4`).
2. The nine EGL virtuals of `BackendObject_Remote` should call v1's twelve `Server*` forwarders rather than
private trampolines - at minimum `MakeEGLCurrent` → `ServerMakeEGLCurrent` and `InitCapabilities` →
`ServerInitCapabilities`, which are the two that republish the caps snapshot (R-12 arm (a)). Without it the
client's mirror keeps the Accept-time snapshot, whose limits were read before any context existed, and
c1's own `InitCapabilities` comment ("whose ServerSession re-published the snapshot") is false.
3. Nothing else. `CreateRemoteBackendObject` is NOT needed: at the merge the hook constructs
`BackendObject_Remote` directly and v1's weak placeholder is deleted (`97f8b8d2`'s hunk is the exact edit,
both files v1's). `ClientSession::Active()` is set at step 7, before `ServerLoop::Start` - correct.
4. For c0 (via the integrator): `kMGPClearKind*` / `kMGPClearValueClass*` belong in `MGPipeTypes.h` (§5.4).
**Where the bracket belongs** (the integrator's question): in `PipeApplier::ApplyOne`, and at its TOP, for
the reason in §5.1 - one hunk in v1's file, applied at the merge, verified on the joint.
---
## 10. Debts left
- `rsp` is a floor for non-verb records (§5.5): needs p1's "enter without stamping" entry point.
- The clear-kind enums are duplicated across `PipeApplier.h` and c1's `EmitTables.h` until c0 hosts them.
- `ServerVerbSink::OnDrawVbo` declines instancing, multi-draw and indirect by name (P8); `OnReadPixels` has
no PBO destination (b1's, client-side); `OnBlit` uses the bound framebuffers only.
- `DetectBigCoreMask` reads `/sys/devices/system/cpu/*/cpufreq/cpuinfo_max_freq` on Linux/Android only;
every other platform resolves to "no affinity" and says so.
- The `SetVertexAttribDefaults` warning in the joint log ("does not reproduce the carried value … the client
is keeping `m_currentVertexAttribute` authoritative") is p1/w1's known one, visible now because the path
runs.
- `MOBILEGL_IPC_E2_DROP_CLEAR` (c1's `getenv` knob) was not exercised here.
- The sync/query release order stays today's (recorded, P10).
- `p5/v1` is based on `5e5bf7b9`; `feat/disaggregated` has since gained `4ba14fa4` (s1's ID-43, `RingTest.cpp`
only). It touches nothing of mine; merging it will retire one of the two known split reds.
---
## 11. Files and scripts (kept; everything else with the `p5-v1-` prefix was deleted)
`~/w7/p5-v1-gate.sh` (the four self-tests + flake sweep + split/monolith lane + G2/G14 in the integrator's
shape; log `~/w7/p5-v1-gaterun.log`), `~/w7/p5-v1-redcheck.py` (log `~/w7/p5-v1-redcheck.log`),
`~/w7/p5-v1-cfg.sh` / `-allbuilds.sh` / `-submodlinks.sh` / `-setup.sh`, `~/w7/p5-v1-joint-submodlinks.sh`,
`~/w7/p5-v1-symbols.md`, `~/w7/p5-v1-names-{linux,push,split}.txt`, `~/w7/p5-v1-igpu-push.log`,
`~/w7/p5-v1-igpu-split-monolith.log`, `~/w7/p5-v1-{pull,split}-unit.log`, `~/w7/p5-v1-flake.log`,
`~/w7/p5-v1-joint-{isplit,isplit-audit,isplit-barrier0,isplit-strict,inproc}.log`,
`~/w7/p5-v1-joint-preflight.{log,stdout}`, `~/w7/p5-v1-joint-seam.diff`. The six `p5-v1-patch*.py` one-off
edit scripts from Sep 11 are gone (their edits are the commits).