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

43 KiB

c0 — contract package, v1

Branch p5/c0, seven commits, 41b4f8df..b4bbcc11, forked from feat/disaggregated @ a29807cc. Worktree ~/w7/p5-c0. Nothing pushed; nothing merged.

41b4f8df [Fix] (MG_Pipe, gen_pipe): export the per-opcode call flags and give GetCaps and
         CreateSamplerState the kHasBlob their payloads have always owned
ec20e700 [Feat] (Config, ConfigLoader): parse MOBILEGL_TRANSPORT and the MOBILEGL_IPC_* family
         entirely behind the disaggregated option, so the pull build's symbol set cannot move
1ee6c895 [Build] (CMake): add MOBILEGL_BUILD_DISAGGREGATED_INPROC, make DISAGGREGATED imply
         PIPE_PUSH, and list the new MG_Remote Wire/Client/Server sources
418e6f50 [Feat] (MG_Remote): land the P5 contract headers and their named-Fatal stubs so all
         seven parallel packages compile and link on day one
72a4cba5 [Fix, Test] (MG_Test): include the header that defines MOBILEGL_PIPE_POISON - seven
         emitter suites tested the macro without it, compiled the non-aborting arm, and turned
         eighteen expected refusals into aborts the moment a disaggregated build armed it
dd4afb0f [Docs, Test] (MG_Remote, Wire): state the five sequence watermarks, the
         late-never-early batching rule and the pad-does-not-count rule on RingControl, and pin
         all three with five cases
b4bbcc11 [Docs] (MG_Remote): CONTRACT-P5.md - the encoding, byte-carrier, field-ownership and
         role-ownership tables every P5 package is held to

1. What landed, against BRIEF §5's nine items

# item state
1 MG_Remote/CONTRACT-P5.md, tables 0/1/2/3 done. Table 1 is 23 rows, not 19 (see §3.5). Table 2 is the spec + the four class definitions + every known row; p1 generates the authoritative instance.
2 PipeCalls.def flag corrections + the ResourceRespecify initial-bytes ruling done. GetCaps → kReplySlot|kHasBlob; CreateSamplerState → kHasBlob. R-13.3 confirmed with evidence; R-13.2 overturned in a third direction (§3.2). No opcode moved; PipeCatalogueTest's last-four pins untouched.
3 gen_pipe.py per-opcode flags table done. kMGPipeCallFlags[kOpCount] + MGPipeCallFlagsFor() + six generator-authored static_asserts, in generated/PipeWire.inc. Plus a new gate: a flag token that is not an MGPipeCallFlags enumerator, or kNone OR'd with a real flag, stops the generator. Two new negative controls; --self-test went 7 → 9 controls, all trip. .inc regenerated and committed.
4 MG_Config::Transport + MOBILEGL_TRANSPORT + the MOBILEGL_IPC_* family done, all nine knobs plus MOBILEGL_IPC_SERVER_PATH. Runtime-verified on six arms (§2.5).
5 CMake done, plus one implication the brief did not ask for: DISAGGREGATED now implies PIPE_PUSH (§3.8).
6 headers and stubs done, 8 headers + 8 .cpp. Every stub is MGLOG_F + std::abort.
7 verb census done — and for OpenRA it is measured, not estimated: the fixture was already hydrated locally. ~/w7/notes/p5/verb-census.md.
8 Ring.h + five cases done. RingTest 16 → 21 cases; the Wire suites go 52 → 57 and are 57/57 green.
9 purity done. check_include_closure.py: 4 probes, 0 skipped, 0 problems. No new header is reachable from ITransport.h.

2. Acceptance numbers

All in ~/w7/p5-c0, GLIBC_TUNABLES=glibc.malloc.tcache_count=0.

2.1 Builds — four for four

build-linux (pull), build-push, build-verify, build-split (-DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON): configure rc=0, build rc=0, all four.

2.2 G1 — did not move

nm --defined-only build-linux/libMobileGL.so | grep -ic MG_Remote  ->  0
nm --defined-only build-split/libMobileGL.so | grep -ic MG_Remote  ->  188   (was 98 at a29807cc)
symbol-report vs ~/w7/p5-before-libMobileGL.so, --threshold 0:
  .text 10806323 -> 10806323 (+0, +0.000%)
  27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed

This is the gate the brief calls the easiest to break, and it held because every knob and the whole parser sit behind #if MOBILEGL_BUILD_DISAGGREGATED — including the parser. A FeaturesTable member would have resized MG_Config::Features; a warning in the unconditional part of ConfigLoader would have resized MG_ConfigLoader::Init.

2.3 Generators and purity

gen_pipe.py --check      : generated files are up to date
gen_pipe.py --self-test  : 9 negative-control trips, positive control OK   (was 7)
gen_pipe_dirty_surface.py --check / --self-test : green, 27 controls all trip
check_include_closure.py : 4 probes, 0 skipped, 0 problem(s)

2.4 Test lanes

lane result
ctest -L unit build-linux 1785 / 1785
ctest -L unit build-push 1785 / 1785
ctest -L unit build-verify 1785 / 1785
ctest -L unit build-split 1842 / 1842 — the 18 aborts are gone (§4)
the five MG_Test/Wire suites in build-split 57 / 57 (52 + my 5)
ctest -L integration-gpu build-push, MOBILEGL_TRANSPORT=monolith 1117 / 1117
ctest -L integration-gpu build-push, no MOBILEGL_TRANSPORT 1117 / 1117
ctest -L integration-gpu build-split, MOBILEGL_TRANSPORT=monolith 1117 / 1117

Name-for-name identity, integration-gpu in build-push, mine vs ~/w7/pipe/build-push at a29807cc: 1117 = 1117, diff lines 0. G2 (pull vs push ctest names, all labels): 0 diff lines. G14 (split vs push): 57 added, 0 removed — the added 57 are exactly the Wire suites.

2.5 The knobs, at runtime

Six arms through a binary that actually runs MG_ConfigLoader::Init() (ctest -R ClearThenReadPixels in build-split, 10/10 green on every arm):

arm observed
defaults silent — nothing logged, because Transport == Monolith
inproc + tuned IPC ring=4MiB stage=16MiB spin=10us persistent-block=64KiB adopt-tier=2 verb-barrier=1 strict=0 audit=0 affinity='auto'
inproc + both negative controls both warnings fire by name, and the line shows persistent-block=0KiB verb-barrier=0
spawn names a transport P6 implements and P5 does not; staying on monolith. This run is NOT a split run.
MOBILEGL_TRANSPORT=banana Ignoring invalid env variable MOBILEGL_TRANSPORT='banana'
MOBILEGL_IPC_RING_MB=0 Ignoring invalid env variable MOBILEGL_IPC_RING_MB='0', falls back to 8

2.6 The CMake implications actually fire

-- MOBILEGL_BUILD_DISAGGREGATED_INPROC=ON forces MOBILEGL_BUILD_DISAGGREGATED ON for this configure
-- MOBILEGL_BUILD_DISAGGREGATED=ON forces MOBILEGL_PIPE_PUSH ON for this configure: ...
-- PipeInputs push ON, appending the MGPipe fill sources
-- disaggregated transport ON, appending MG_Remote sources

Both are normal variables shadowing the cache for one configure, matching the house shape the flatbuffers guard's own comment argues for — so an operator's cached ON stays theirs.


3. Rulings I made that the brief did not

Every one is also in CONTRACT-P5.md §6, with what would overturn it. Here, only the ones a package will trip over.

3.1 CallMask bits 32..47 carry the consumer mask. R-8 says the client's liveness gates read the CallMask mirror instead of MGPipeGetResourceOps(). But CallMask as declared has only the nine MGPCapBit feature bits and no per-family bit, so R-8 was not implementable as written — c1 and b1 would each have invented one. Ruling: bits 0..8 stay MGPCapBit; bits 32..47 are (serverConsumedSubsystems & 0xFFFF) << 32. Constants and the fold/test helpers are in MG_Remote/CapsCodec.h; CapsCodec.cpp asserts the block does not collide with the cap bits and that P4a's 0x1fff fits. Overturned by a decision to carry a second schema field instead.

3.2 ResourceFlushRange carries no bytes at all — a third answer, not either of R-13.2's two. The ladder it drives rewrites its range "from the authoritative shadow" (Managers.cpp:1047-1076), and under R-11 the authoritative shadow is server-owned, so resource_subdata is already the only way bytes reach it. A blobref would be a second, forgeable way to say the same thing. Overturned by evidence that tier-1 INVALIDATE_RANGE needs bytes and range in one record — impossible while the verb barrier holds; revisit when the barrier retires for the buffer family.

3.3 ResourceRespecify has a SECOND uncarried companion and the brief does not mention it. const MGPRespecifiedLevel* level (PipeApply.h:792-795) is the scope of the redefinition and MGPResourceDesc cannot express it. Without a carrier, every per-level glTexImage2D in OpenRA silently takes the whole-resource arm and drops every pending upload — precisely the texel loss the server-side set exists to prevent. Ruling: two named fields in the existing pads — Pad1 (4 B) becomes {Uint16 RespecifiedUploadTarget; Uint16 RespecifiedLevel;} and one byte of Pad0 becomes Uint8 HasRespecifiedLevel. Zero size change, MGP_ASSERT_POD(MGPResourceDesc, 88) does not move. I ruled and specified it; I did not implement it — MGPipeTypes.h is not c0's file. It is coupled to PipeFields.def, which is mine (pads are excluded from field lists, so the two named members must be added there or --check fails). Integrator: land this before w1 encodes the record.

3.4 R-13.3 confirmed, with the cost that makes it obvious. MGPBlobRef is 24 bytes; MGPResourceDesc's two pads total 6. A blob member takes the struct 88 → 112 and moves the POD assertion. The recommended route reuses MGPipeForEachSubDataRecordRange, which is already chunked and already acceptance-gated, and the texture path already does exactly this — TextureEmit.h:1137 passes nullptr and relies on a following upload. So the ruling generalises today's texture behaviour to buffers rather than inventing anything.

3.5 Table 1 is 23 rows. The brief's 19 and scout-premortem:§3's 19 are different lists; the four only the premortem carries — MapPersistent, ResourceReadback, ReadPixels, GetTextureImage — are exactly the server → client ones. A phase that omits them discovers in week three that it never decided where readback pixels land. Ruling for ReadPixels: destination is always SEG_REPLY in P5, so MGPReadbackInfo gains no Seg field.

3.6 tableSlotMask is deleted, not renamed (R-8 allowed either). Decisive: GLFunctionsTable has 69 function-pointer slots and ulong is 64 bits — the field cannot address the table its own comment names, and never could. maxComputeWorkGroupCount/Size and prefersCpuXfbPrimitiveAccounting go with it.

3.7 The persistent-map census is 21 sites, not 20, and DirectGLES.cpp:361 (ResolveIndirectCommandBytes) is in the set. MEASUREMENTS.md:111 says 20 and Managers.cpp:5047-5048 says eleven Espryt; both are exactly one low and the missing one is Espryt's. A shared helper that reaches a persistently-mapped range can read stale bytes exactly as a draw site can. ARCHITECTURE.md:290's cited "§5.7" attribution table does not exist in the tree — b1 should not go looking. Correcting MEASUREMENTS.md:111 is b1's line.

3.8 MOBILEGL_BUILD_DISAGGREGATED implies MOBILEGL_PIPE_PUSH. The split path decodes into the MGPipe applier and PIPE_PUSH is what compiles the applier, so -DMOBILEGL_BUILD_DISAGGREGATED=ON alone used to configure cleanly and fail at link — a shape indistinguishable at the CMake level from a legitimate transport-only build.

3.9 The two doorbell accessors stay off ITransport. They are on InProcessTransport today (InProcessTransport.h:64-68). Ruling: the session owns the pair and hands out references, so ITransport stays the dumb control-plane interface its own header describes and SocketTransport does not grow two accessors with no natural home. Deciding this in P6 would mean re-laying one package's call sites.

3.10 gMGPipeSegmentResolver is installed by the SERVER role only. It is one process-wide non-atomic inline variable (MGPipeHostSpan.h:47), so it cannot be per-role — and under R-2 the client never resolves a span anyway, it only ever writes Ptr = nullptr. SegmentTable::InstallProcessResolver() asserts if one is already installed.

3.11 DrawVbo's host span stays in the variable tail. MGPipeTypes.h:1221-1224 defers the fixed-head-versus-tail question to P5. There are no per-draw byte histograms yet, so moving it would be a wire-format change with no measurement behind it. Keep.

3.12 Silent MOBILEGL_TRANSPORT in a non-disaggregated build is accepted and unfixable at runtime. A complaint would have to live in the unconditional part of ConfigLoader, which resizes a pull-build symbol and breaks G1. The guard is therefore t1's build-level nm check, and it is written into the contract so nobody re-litigates it.


4. The 18 split-build unit aborts — root cause and disposition

Disposition: FIXED here, by c0, in one test-local commit. Nothing is left red, and none of it is p1's.

The brief's leading hypothesis — a PipeInputs poison read hitting Fatal{UnmigratedPipeInput, "<Field>@<none>"} — is refuted. MG_Test/ScopedPipeVerb.h is not involved at all.

All 18 are Fatal{ProtocolCorruption} trip wires in PipeApply.cpp that the tests deliberately provoke and expect, e.g.

MGPipe: Fatal{ProtocolCorruption} create_vertex_elements {slot=5, gen=2}: the declared blob
length is not the byte length the two counts describe (attributes=3, bindingPoints=2, that
describes 104 bytes, blob declares 103)

MOBILEGL_PIPE_POISON is derived from MOBILEGL_BUILD_DISAGGREGATED (PipeInputs.h:20-26, exactly as the brief says) — but what it arms here is a second consumer, PipeApply.cpp:42-52, which flips 32 trip wires from MGLOG_E to MGLOG_F + abort. Each of the seven test files has a two-armed helper keyed on #if MOBILEGL_PIPE_POISON || MOBILEGL_PIPE_VERIFY that picks between "fork a child and expect it to die" and "run in process and read the log".

None of those seven TUs included <MG_Backend/MGPipe/PipeInputs.h>, the only header that defines the macro. So the token was undefined, the #if silently read 0, and they compiled the non-aborting arm while PipeApply.cpp — which does include the header — compiled the aborting one. Invisible in a push build (POISON really is 0) and in a verify build (-DMOBILEGL_PIPE_VERIFY=1 is on the command line); MOBILEGL_BUILD_DISAGGREGATED is the one arming condition that lives behind the header, so build-split is the first configuration that could ever expose it.

Fix: one include per file, matching what the two sibling files that get it right already do (RenderStateSpansTest.cpp:63, PipeInputsTest.cpp:34), each with the six-line note explaining why. Plus one latent guard correction that the same invisibility was masking: ResourceEmitTest.cpp's TheLiveHostWritesWireFiresOnTheCallAPersistentMapProducerWouldSetItOn guarded itself with #elif !(MOBILEGL_PIPE_POISON || MOBILEGL_PIPE_VERIFY) while PinNoLiveHostWrites is #if MOBILEGL_PIPE_VERIFY only (PipeApply.cpp:838-853) — so in a split build the wire genuinely is compiled out and the case must skip. Corrected to #elif !MOBILEGL_PIPE_VERIFY; verified SKIPPED in push, SKIPPED in split, OK in verify.

Why it is c0's and not p1's: p1's artefacts are all correct as they stand. PipeInputs.h derives the macro the way its own comment says it must; PipeApply.cpp consumes it correctly; PipeFill.cpp and gen_pipe_dirty_surface.py are not in the path. The defect is entirely consumer-side visibility in seven files under MG_Test/Pipe/, which are not p1's (t1 owns only MG_IntegrationTest/**), and the fix introduces no new convention — that MG_Test → MG_Backend/MGPipe/PipeInputs.h edge already exists twice in the same directory.

One hardening left on p1's account, deliberately not taken: if the integrator wants MOBILEGL_PIPE_POISON to be unmissable, the derivation could move into a header every push TU already sees (MG_Pipe/MGPipe.h), or PipeInputs.h could grow a tripwire for TUs that test the macro without it. That changes a p1-owned header and touches every push TU's macro surface — a much larger blast radius than a seven-line include for a defect the include closes completely. Filed as a p1 note; not done here.

(One caveat inherited, not introduced: running a whole fixed binary by hand — all cases in one process — leaves some FramebufferEmit/TextureEmit fork cases red, because the parent has already opened the log file and the child inherits a handle to the unlinked inode. That is the limitation RenderStateSpansTest.cpp:1034-1040 names; under ctest every case is its own process and it does not arise.)


5. Every stub signature, with one line each

MG_Remote/Wire/PipeWireCodec.h — owner w1

signature why this shape
enum SegmentId { kSegNone=0 … kSegAdopt=6 } one id space with Protocol::SegmentKind, tied by static_assert in the .cpp, which is the only place the flatbuffers header and the codec meet.
struct SegmentView { void* Base; Uint64 Size; } a role's view of one segment; two roles in one process hold two different tables over the same memory on purpose.
SegmentTable::{Install, Get, Resolve, InstallProcessResolver, UninstallProcessResolver} Resolve returns nullptr rather than Fatal-ing so a unit test can exercise the arithmetic without dying; the caller escalates.
WireProtocolFatal(what, detail) / WireProtocolFatalAt(what, got, expected) not stubs — worded once so encoder, decoder and every package's own check emit the same line.
CheckBlobIsHonest(op, blob, segments) / CheckHostSpanIsHonest(span) R-2.3's arms as functions, so "honest" means one thing.
PipeWireEncoder::StageBytes(bytes, size) -> MGPBlobRef returns the ref; a zero-size call Fatals rather than returning an empty ref, because "declared no blob" and "declared an empty blob" must not be spelled the same way.
PipeWireEncoder::EncodeRecord(op, payload, payloadBytes, varTail, varTailBytes) -> Uint64 seq returns the seq, which is also the reply-slot id (R-3). One function for fixed payload + tail so no package invents a second framing.
PipeWireEncoder::{Publish, EmitSeq, MaxRecordBytesSeen} MaxRecordBytesSeen is R-10's proof obligation, on the encoder because that is where the number exists.
class ReplySink { PostReply(seq, status, bytes, size) } declared in Wire, not Server, so the codec does not depend on the session: the decoder's job ends at "produce the answer bytes".
PipeWireDecoder::DecodeAndApply(const RingRecordView&) -> Bool one record in; false = "this build does not implement it", malformed never returns. A kRecPad reaching it Fatals — the caller skips pads before counting.
PipeWireDecoder::AppliedSeq() separate from the control page so the batching ban (R-9) has something to be checked against.

MG_Remote/CapsCodec.h — owner w1 (codecs) / s1 (handshake)

signature why
kMGCapsConsumerBitShift, kMGCapsConsumerMask, MGCapsConsumerBits(mask), MGCapsServerConsumes(callMask, bit) the ruling of §3.1 as four constexprs, so neither side hand-shifts.
Encode/DecodeFormatCapabilities, Encode/DecodeRendererInfo the two serializers MGPipeTypes.h:134-136 defers to this phase. Decoders return false on truncation; these bytes arrive over a wire.
CapsAbiFingerprint() -> Uint64 mixes the three sizeofs and the build fingerprint; compared in Hello/Welcome, Fatal{AbiMismatch} and never a downgrade.

MG_Remote/Client/CapsMirror.h — owner c1

signature why
Adopt(caps, formats, renderer, apiVersion, backend) one call, whole snapshot; re-arrival is the invalidation (R-12), so there is no separate Invalidate().
Generation() ++ per Adopt. The only thing on the client that can see a server context death; a client memo must key on it.
Renderer() returns a reference GetRendererInfo() is const RendererInfo& (BackendObject.h:590), so the mirror must own an instance — including a placeholder before the first snapshot, because LogBackendInfo reads it at Init.cpp:21.
Dynamic(), Formats(), ApiVersion(), Backend() the other 55 read points. Backend() returns the server's type, never a new "Remote" enumerator.
ServerConsumes(subsystemBit) R-8's only legal client-side spelling.
PrefersCpuXfbPrimitiveAccounting() it is a GLFunctionsTable member (:274), not a Dynamic one, so under split it has to come from the cap bit.

MG_Remote/Client/EmitTables.h — owner c1

signature why
RemoteEmitTable() -> const GlobalBackendFunctionsTable& 71 function pointers, not 69 (§3 of the contract): 69 GL.* + Present + SetSwapInterval.
UnmigratedVerbFatal(slot) [[noreturn]] not a stub — same shape as MGPipeInputPoisonFatal, live at every log level, so the wording lives in one place and a death test can filter on it.
ImplementedVerbCount() / kRemoteEmitSlotCount = 71 a table that silently loses an emitter must not look like one that never had it; EmitTables.cpp asserts the 71 against the struct.

MG_Remote/Client/ClientSession.h — owner s1 (construction) / c1 (barrier)

signature why
Active() returns nullptr, not a Fatal MG_Backend::Init() legitimately asks "is there a session" and the monolith answer is no.
Start(mode, endpoint) returns a named error rather than falling back to monolith.
Stop() publish → Kill → join → only then free emitter-owned memory.
EmitAndWait(op, payload, bytes, tail, tailBytes, replyOut, replyBytes, statusOut) -> seq one call, because the barrier's wait and the reply's wait are the same wait (R-3/R-5). Separating them is how a package re-derives an acceptance answer locally.
BarrierArmed(), InBarrierWait(), ApplyThreadIsInsideApplier() R-1's mutual-exclusion invariant as a checkable pair rather than a sentence. Both return false in the stub — an assertion helper that aborts when asked is worse than useless.

MG_Remote/Server/PipeApplier.h — owner v1 (with p1 for the stamp)

signature why
ReplyPool(base, size, slotCount, slotBytes) + PostReply override addressed seq % slots, seq stamped back into the header for self-check.
ReplyPool::SlotBytes() a reply bigger than a slot is Fatal, not chunked: P5's only big answer is ReadPixels, whose size the client knows before it emits.
PipeApplier::ApplyOne(record) decode → stamp → apply → reply → advance appliedSeq by one.
PipeApplier::StampVerbBoundary(op) the prerequisite nobody else owns (§3 of the contract). p1 defines what; v1 calls it.
PipeApplier::ResidualPullCount() rsp; its end-of-P5 value is the P6/P7/P8 debt.
PipeApplier::PoisonRetiredStageBytes(offset, size) R-2.5's 0xDD, the only mechanical control on rule C.

MG_Remote/Server/ServerSession.h — owner s1

signature why
Accept(ITransport&) the ABI assertion happens here, before a single record is decoded.
PublishCapsSnapshot() callable more than once; the second call is the invalidation.
ConsumerDoorbell() / ProducerDoorbell() §3.9: the pair lives on the session, not on ITransport.

MG_Remote/Server/ServerLoop.h — owner v1

signature why
Start(session) names the thread mgl-srv-apply, applies the affinity and logs the resolved mask.
Stop() / Running() Running() is not a stub: teardown asks it before deciding to Kill and join, and a helper that aborts when the thread never started is a hang.
Backend() the server's private BackendObject_DirectGLES, not pActiveBackendObject.
RunOnApplyThread(ControlWork, void*) a raw function pointer plus a user pointer, not std::function: this runs on the teardown path and the teardown path may not allocate (ID-8).

6. Everything in the brief I believe is wrong or incomplete

Ordered by how much it would cost a package to discover it.

  1. R-13.3 covers only one of ResourceRespecify's two uncarried companions. §3.3. The MGPRespecifiedLevel* scope needs a carrier or OpenRA's per-level uploads are silently lost. This is the one I most want the integrator to act on before w1 starts.
  2. R-4's "69 slots" is GLFunctionsTable's count; the table the client installs is 71. Present is on the reduced path and Present/SetSwapInterval have zero MG_Impl call sites — they are reached through the EGL path, so an emit table built by mirroring GLImpl covers neither.
  3. R-4's predicted minimum set names Flush. There is no Flush slot, and glFlush/glFinish are literally empty bodies (Definitions.cpp:111-112). A TriangleScenario that uses glFlush to order its readback is ordering nothing.
  4. The census's real surprise: GetIntegeri_v is reached by the first glCompileShader of a context, via CaptureCompileEnv (CompileEnv.cpp:134-138), not by any verb. An all-Fatal emit table aborts on the first shader compile of every scenario. It needs a real emitter or a caps-mirror answer.
  5. R-8 is not implementable as written — CallMask had no per-family bit. §3.1.
  6. Table 1's 19 rows are the wrong 19 (§3.5), and one of them, SetResidualValueState, is a fourth typed companion nobody named: MGPipeApplySetResidualValueState takes const ResidualValueBlock& and MGPResidualValueState is never instantiated on the live path. Budget it as w1's hardest row, not one of the easy eight.
  7. Three of the 19 have no applier entry point at all — SetShaderBuffers, SetStreamOutputTargets, DrawVbo. scout-premortem:§3 cites five entry points for a six-call row and those five belong to other calls.
  8. The brief's diagnosis of the 18 aborts is wrong (§4). It cost nothing here because it was checked rather than assumed, but a package that had taken it at face value would have gone looking in ScopedPipeVerb and p1's poison machinery, both of which are innocent.
  9. CanTouchGLNow() guards 16 sites, not 19 (19 = 1 definition + 2 comments + 16 calls), and ScopedDefaultUnpackState has six value shadows, not five.
  10. DirectGLES.cpp:12446 is not ClampSamplesToBackendSupport — it is Present()'s fence poll, and DirectGLES.cpp contains no pActiveBackendObject reference at all. The real function is BackendObject_DirectGLES.cpp:807-828, and there are seven backend-internal reads across six functions, not one. Table 3's conclusion survives; the diff does not.
  11. MGPipeApply* is 37 entry points / 41 call sites, not "~45".
  12. The persistent-map census is 21, not 20, and the attribution table ARCHITECTURE.md:290 cites does not exist (§3.7).
  13. Doc corrections carried into the contract: ARCHITECTURE.md:83 says 61 PipeInputs fields (it is 63); :492 cites PipeStats.h:126 for mpr (it is :141); :19 says eight EGL lifecycle virtuals (there are nine — ResizeEGLWindowSurface); ROADMAP's P4a row says six MGPipeUnmigratedEmulation sites (five calls + one comment).
  14. MGHostSpan, not MGPHostSpan — the latter does not exist.

7. Notes for the integrator

  • The worktree's submodules are symlinks to ~/w7/pipe's. git worktree add populates no submodule content and a recursive init needs the network (apitrace's brotli tree is not in the local object store), so ~/w7/p5-c0-setup.sh links every .gitmodules path — include/ska included, which is what Includes.h:53 reaches for. git refuses to run at all while they are symlinks ("expected submodule path X not to be a symbolic link"), so ~/w7/p5-c0-submodlinks.sh off|on toggles them: off before any git command, on before any build. Every parallel package will hit this on day one. It is worth telling them once rather than seven times.
  • An earlier bring-up script reported four green builds that never happened — it dropped $COMMON and its build loop passed no directory, so cmake --build -j 24 only printed usage and $? was 0. If any P5 script reports a build result, check that a CTestTestfile.cmake exists before believing it.
  • ~/w7/p5-c0-gate.sh is c0's own gate (four dirs, generators, purity, G1, the four unit lanes) and is a reasonable skeleton for t1's wsl_p5_gate.sh part 1/3/5.
  • Retained logs this report cites: ~/w7/p5-c0-gaterun.log, ~/w7/p5-c0-acceptrun.log, ~/w7/p5-c0-symbols.md, ~/w7/p5-c0-names-push-{mine,base}.txt. Everything else under ~/w7/p5-c0-* is a re-runnable script. The diagnosis scratch (~/w7/p5-c0-diag-*) is deleted.
  • Not run here, and not c0's: ctest -L integration-verify, the retrace sweeps, and the device lane. integration-gpu was run on both build-push and build-split and is name-for-name identical to a29807cc on both.

8. Follow-up round — integrator rulings A and B, and the respecify-scope carrier

Two more commits. Range is now 41b4f8df..5175f9cc, nine commits.

45b759e7 [Feat] (MG_Pipe): give resource_respecify's redefinition scope a wire carrier in the
         descriptor's two existing pad fields, so a per-level glTexImage cannot cross as a
         whole-resource redefinition and eat every other level's pending upload
5175f9cc [Docs] (MG_Remote): record R-15 and split the emit table's 71 slots into
         answered-locally, emitted and Fatal, with the forty-one null checks that are really
         capability probes

8.1 Ruling A — MGPipeTypes.h is c0's

Recorded in CONTRACT-P5.md §8. Worth keeping the causal note: that file being unowned is precisely why the row-19b gap had nobody to close it, and the same is true of anything else that falls between the .def files and a package's own directory. Ownership now reads: the three .def files, gen_pipe.py, MGPipeTypes.h, Config.h, ConfigLoader.cpp, the root CMakeLists.txt, CONTRACT-P5.md, the MG_Remote stub headers, Ring.h/RingTest.cpp.

8.2 Work item 1 — the carrier, landed

MGPResourceDesc (MGPipeTypes.h), exactly the §3.3 spec and nothing more:

  • Uint8 HasRespecifiedLevel takes the high byte of the old Pad0 (Uint16 Pad0 → Uint8 HasRespecifiedLevel; Uint8 Pad0;);
  • Uint16 RespecifiedUploadTarget; Uint16 RespecifiedLevel; take all of the old Pad1, in that order, so they are MGPRespecifiedLevel (PipeApply.h:792-795) byte for byte. Spelled as two Uint16s rather than as that type because PipeApply.h includes this header, not the reverse;
  • MGP_ASSERT_POD(MGPResourceDesc, 88) did not move, and a new offsetof assertion pins the pair adjacent and in that order — the layout is the contract, not the field names.

Five helpers, because three fields are one value. MGPipeRespecifyIsWholeResource, MGPipeRespecifiedUploadTargetOf, MGPipeRespecifiedLevelOf, MGPipeSetRespecifiedLevel, MGPipeClearRespecifiedLevel. The two readers return 0 for a whole-resource descriptor rather than whatever the pad held, so a misuse is deterministic; the writers set or clear the presence byte with the pair so it cannot be left behind. An open-coded reader that forgets the presence byte reads level 0 of upload target 0 as a real scope, which is the one wrong answer that looks plausible — hence the helpers rather than a comment.

No emitter or applier behaviour changed. The producer is a later package's. What did change:

  • PipeFields.def gains the three rows — required, not optional: the generator's cover check only excludes members literally named Pad*, so omitting them fails --check. Both directions verified as negative controls: dropping F(HasRespecifiedLevel) → "member(s) with no F(...) in PipeFields.def: HasRespecifiedLevel"; adding a name the struct lacks → "F(...) name(s) that are not members: RespecifiedNothing". They are also real G4 comparands now, which matters: a verify build that let the scope differ silently would be blind to the one field deciding whether a respecify drops one pending upload or all of them.
  • PipeApply.cpp gains PinWholeResourceRespecifyScope, the PinNoLiveHostWrites shape (:839-850), called from MGPipeApplyResourceRespecify beside it. Verify-build only, and verified so: the Fatal{PipeRespecifyScope} string appears in build-verify/libMobileGL.so once and in build-push and build-split zero times. It pins that P5 builds only whole-resource descriptors, so the phase that wires the carrier cannot arrive unannounced — and in particular cannot land a descriptor saying "whole resource" while the still-live trailing MGPRespecifiedLevel* says "level 1".
  • A standalone round-trip compile (value-init → whole-resource; set a cube face + level 3; read both back; clear; read 0 not the pad) returns 0.

8.3 Ruling B — R-15, and the three-class split

CONTRACT-P5.md §7, cross-referenced from MG_Remote/Client/EmitTables.h and from verb-census.md so c1 meets it wherever it starts reading.

  • Class A, answered locally from the caps mirror, never emitted and never Fatal — 2 slots: GetIntegeri_v (from MGPCaps::Dynamic.MaxComputeWorkGroupCount/Size) and IsTimerQuerySupported (from kCapTimerQuery), plus the non-slot Bool PrefersCpuXfbPrimitiveAccounting (from kCapCpuXfbPrimitiveAccounting).
  • Class B, emitted — 5 slots: Clear, DrawArrays, ReadPixels, BlitFramebuffer, Present.
  • Class C, Fatal{UnmigratedVerb} — 64 slots, including SetSwapInterval and GetGpuTimestampNs (a live GPU timestamp, not a static device property, so deliberately not class A).

One thing R-15 surfaced that is bigger than R-15. R-4 forbids a null slot — and 41 of the 69 slots are null-checked at their call site, with several of those checks being capability probes rather than safety checks. In an emit table with no null slots every one of them answers "supported" and the fallback behind it silently disappears. Named in the contract: BeginOcclusionQuery (GL_Query.cpp:481, :785) → kCapOcclusionQuery; BeginXfbPrimitivesQuery's ternary (:534) → kCapXfbPrimitivesQuery; SubDataResident → kCapResidentSubData. The rule generalises: a null check on a slot may not survive into the client under split — it becomes a caps-mirror read. This is ARCHITECTURE.md:114's "CallMask replaces 'is this table slot null'" with a concrete list attached, and it is c1's to carry.

8.4 Work item 2 — the gate, re-run in full

G1 is the one this edit could plausibly have moved (a PipeFields.def row can widen a generated array, and the descriptor's pads became named members). It did not move:

.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
nm pull MG_Remote 0   /   nm split MG_Remote 188
check result
four build dirs, configure + build rc=0, all four
gen_pipe.py --check up to date
gen_pipe.py --self-test 9 / 9 controls trip, positive control OK
gen_pipe_dirty_surface.py --check / --self-test green, 27 controls all trip
check_include_closure.py 4 probes, 0 skipped, 0 problems
ctest -L unit build-linux / push / verify 1785 / 1785 each
ctest -L unit build-split 1842 / 1842
Wire suites, build-split 57 / 57
integration-gpu names, build-push vs a29807cc 1117 = 1117, diff 0
integration-gpu build-push, MOBILEGL_TRANSPORT=monolith 1117 / 1117

All four lanes held.


9. Wave-1 round — the acceptance rows' reply slot, and the two flag spaces

Three commits on p5/c0, b5b6cef2..225819ab, on top of feat/disaggregated @ 5175f9cc.

b5b6cef2 [Fix] (MG_Pipe): give the four acceptance calls the kReplySlot their applier entry
         points have always answered through, so the flags table is the single thing that sizes
         the reply pool and the decoder posts against
c2273df1 [Fix, Test] (gen_pipe, Wire): stop the generated header comment inviting a stamp of the
         call flags into the ring's framing flags - three of the six bits mean something else
         there, and only one of the three is masked on one path
225819ab [Docs] (MG_Remote): record R-16 and R-17 - the fourteen reply-slot rows and why the
         barrier makes them cost no block, and the two flag spaces being disjoint by translation

9.1 Item 1 — the four acceptance rows, verified before editing

The set is exactly the one the ruling names. Verified by enumerating every MGPipeApply* entry point that returns a value, not by taking the brief's word:

Bool  MGPipeApplyResourceCreate      PipeApply.h:820
Bool  MGPipeApplyResourceRespecify   PipeApply.h:868
Bool  MGPipeApplyResourceSubData     PipeApply.h:897
Bool  MGPipeApplySetTextureParams    PipeApply.h:1023
void* MGPipeApplyMapPersistent       PipeApply.h:917   (already kReplySlot)

No others return anything. So: ResourceCreate kNone → kReplySlot; ResourceRespecify kNeedsAck → kNeedsAck|kReplySlot; SetTextureParams kNone → kReplySlot; ResourceSubData kHasBlob|kVarTail → +kReplySlot. kReplySlot rows 10 → 14. No opcode moved.

One correction to the ruling's expectation, and it changes the work rather than the outcome: PipeCatalogueTest had no kReplySlot count to update. grep -rn kReplySlot MobileGL/MG_Test/ returns nothing at this base, and none of the five wave-1 branches adds one. Rather than leave the number unpinned now that it is load-bearing, I added the pin, in the house shape the neighbouring kNeedsAck count already uses (MGP_COUNT_ACKING_CALLS): a count assertion (== 14) and a by-name assertion that all four acceptance rows carry the flag (== 4). A count alone would let one row lose the flag while another gained it.

The "never blocks" contradiction is resolved in the contract rather than papered over. MGPipe.h:49 says a reply-slot call never blocks; R-5 says these four answers are read synchronously. Both hold, because under the verb barrier the client is already waiting for appliedSeq >= mySeq at that verb boundary and the reply is read inside that wait. A kReplySlot row therefore adds no block — it adds a read to a wait that was already happening. The flag keeps its literal meaning; the barrier blocks, and the barrier retires per family, at which point these four become genuinely asynchronous and the acceptance answer becomes a real latency question. That is P9's account.

9.2 Item 2 — and the part of w1's finding that the tree contradicts

The generated comment said Flags was "MGPipeCallFlags of the call, for asserts and tracing", which invited exactly the stamp w1 found. It now says what the field is: ring framing flags, and the two spaces are disjoint by translation, not shared.

But the finding as relayed is stronger than the tree supports, and I would rather correct it than pin something false. RingProducer::Reserve masks kRecPad out of a caller's flags (Ring.cpp: flags & ~kRecPad). So:

collision status
kVarTail → kRecPad defended, one bit wide, one path wide. A stamp through Reserve does not delete the record. A producer that writes the header itself — which is what a codec with its own header struct does, since these are the same eight bytes — loses the mask, and then Pop skips the record as a wrap filler.
kHostSpan → kRecBorrowSlot undefended. The consumer believes the record borrowed a slot into the GPU timeline and retires it on completedFrameSerial instead of on apply.
kReplySlot → kRecVarTail undefended — and after item 1 this now fires on fourteen rows rather than ten.

So the real failure is not one dramatic disappearance: it is a lifetime lie and a phantom tail on every affected record, plus a disappearance only on the path that bypasses Reserve. My first version of the test asserted the dramatic version, and it failed — which is the system working. The landed test pins all three shapes including the masking, so the one defence that exists cannot quietly go away either.

Enforcement, split by what each file can see. MG_Pipe is below MG_Remote and may not include Ring.h, so no generated .inc can hold a cross-enum assertion:

  • gen_pipe.py now reads enum MGPipeCallFlags out of MGPipe.h rather than hard-coding it, and emits a value assertion per flag plus kMGPipeCallFlagsAllBits == 0x3F. A renumbering or a seventh flag is a build break, and — because the parse also feeds the existing unknown-flag gate — a flag added to the header no longer has to be added to the generator by hand, which is the copy that would have gone stale in exactly the case that matters.
  • MG_Test/Wire/RingTest.cpp holds the cross-enum table: the one place in the tree that sees both enums, and built only under MOBILEGL_BUILD_DISAGGREGATED. Six correspondences, both totals (0x3F and 0x1F), and a runtime half that demonstrates each of the three shapes.

9.3 Acceptance — re-run in full, against this rebuilt tree

.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
nm pull MG_Remote 0   /   nm split MG_Remote 188
check result
four build dirs rc=0, all four
gen_pipe.py --check / --self-test up to date; 9 / 9 controls trip
gen_pipe_dirty_surface.py --check / --self-test green, 27 controls
check_include_closure.py 4 probes, 0 problems
ctest -L unit build-linux / push / verify 1785 / 1785 each
ctest -L unit build-split 1843 / 1843 (1842 + the new cross-enum case)
Wire suites, build-split 58 / 58
integration-gpu names, build-push vs base 1117 = 1117, diff 0
integration-gpu build-push, MOBILEGL_TRANSPORT=monolith 1117 / 1117

9.4 Three things for the integrator

  1. The unit baselines have not moved, because nothing has landed. ~/w7/pipe's feat/disaggregated is still at 5175f9cc — my own tip. The five wave-1 branches (p5/w1, p5/s1, p5/p1, p5/t1, p5/b1) exist and are ahead, but none is merged. My numbers above are therefore directly comparable to §8's, and the only unit delta is the one case I added.
  2. Two wave-1 branches have edited c0-exclusive files. p5/w1 → scripts/gen_pipe.py (the decoder hook in gen_wire); p5/b1 → MGPipeTypes.h (a HasLiveHostWrites byte out of MGPSubData's pad), PipeFields.def, CMakeLists.txt. Both look like good work and both may well have been authorised the way my own PipeApply.cpp edit was — I raise it only so the ownership table means something. Their regions are disjoint from mine, so the merge is clean except for generated/*.inc, which both sides regenerate: the integrator should take either side and re-run gen_pipe.py, never hand-merge a generated file.
  3. The submodule-symlink trap bit me once and will bit others. A git command needs them off, a build needs them on, and the failure mode when they are left off is four CMake "source directory does not exist" errors that look nothing like the cause. ~/w7/p5-c0-gate.sh now restores them itself and refuses to run if they are unpopulated; worth copying into wsl_p5_gate.sh.