# 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_assert`s, 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, "@"}` — 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 ``, 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 `constexpr`s, 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 `sizeof`s 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 `Uint16`s 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`.