Files
MobileGL/docs/Disaggregated/notes/p3a/p3a-results/contract-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

412 lines
28 KiB
Markdown

# P3a package A, commit c0 — the contract (`contract-v1`)
**Commit** `397226873c2fe06ed57a5b78058ff68bc1716896` (`39722687`) on branch `p3a/contract`, worktree
`/home/swung/w7/p3a-contract`, parent `44c2b5cf` (ID-1's base ref, not the brief's `55d2af9b`).
**Tag** `p3a/contract` points at it. Not pushed.
Message, single line, no body:
```
[Feat] (Pipe): land the P3a contract - the handle-shaped resource op table, the applier's resource and vertex-elements records, the two vertex wire views, an explicit baseInstance on set_vertex_buffers, and the first kNeedsAck
```
`p3a/{wire, client, espryt, gates}` can branch from the tag now.
---
## 1. Per-file summary
21 files, +1049 / -23. Every one of them is in C.0's table; C.0 lists two files that were deliberately not
touched (§3 D1, D2).
| file | what changed |
|---|---|
| `MobileGL/MG_Pipe/MGPipeValueTypes.h` | **+`MGPVertexAttribWire` (24 B) and `MGPVertexBindingPointWire` (16 B)**, in `namespace MobileGL` immediately after the `MG_State::GLState` block that holds `VertexAttribute` / `VertexBufferBindingPoint`, with the blob-layout rule, the "stride 0 is meaningful" note, the reason `Divisor` and `LegacyStride`/`LegacyPointer` are absent, and the surviving reason the second view travels at all. Four `static_assert`s (trivially-copyable + exact size + standard layout) in the `:547` trip-wire block, spelled out rather than `MGP_ASSERT_POD` because that macro is `MGPipeTypes.h`'s and that header includes this one. |
| `MobileGL/MG_Pipe/MGPipeTypes.h` | **`MGPVertexBuffers` 16 → 24 B**: `Uint32 BaseInstance; Uint32 Pad0;`, `MGP_ASSERT_POD(..., 24)`, comment naming the `ContentHash` requirement, the `MGPDrawInfo::StartInstance` distinction and the once-per-set rule. **+`MGPipeResourceRespecifyNeedsAck(const MGPResourceDesc&)`** next to `MGPipeSetSubDataBufferRange`. **+`kMGPipeMaxVertexAttribs = 32`** (see §3 A1). `MGPVertexBuffer` (per entry, 32 B) untouched. |
| `MobileGL/MG_Pipe/PipeCalls.def` | `ResourceRespecify` flags `kNone` → **`kNeedsAck`**; the `:18` legend gains the "MAY require an ack; a per-record predicate decides" sentence naming the predicate. No row added, moved or reordered; `MGP_CALL_LIST_DOCUMENTED_COUNT` stays **71**. |
| `MobileGL/MG_Pipe/PipeFields.def` | `MGP_FIELDS_MGPVertexBuffers` gains `F(BaseInstance)`; new `MGP_FIELDS_MGPVertexAttribWire` (10 fields, `Pad0` excluded) and `MGP_FIELDS_MGPVertexBindingPointWire` (3); **both appended to `MGP_VERIFY_PAYLOAD_LIST`** (69 → 71 payloads). |
| `MobileGL/MG_Pipe/MGPipe.h` | `kMGPipeSubsystemResources` (bit 7), `kMGPipeSubsystemVertexInput` (bit 8), `kMGPipeSubsystemsMigratedAtP3a = 0x1ff`; the reserved-bit comment moves to "bits 9..62"; `kMGPipeSubsystemsMigratedAtP2` kept, with the note that each phase's constant survives as the next phase's A/B control. |
| `MobileGL/MG_Pipe/PipeApply.h` | `MGPipeResourceOps` (9 members) + `MGPipeSetResourceOps` / `MGPipeGetResourceOps`; `MGPipeResourceRecord`; `MGPipeVertexElementsRecord`; **11 new `MGPipeApplierState` members**; **14 new entry points**, complete signatures, in two commented sections. No `MG_State` token anywhere in the file (G13). |
| `MobileGL/MG_Pipe/PipeApply.cpp` | file-static `g_resourceOps` + the two accessors (real bodies); the 14 entry points as **no-op stubs** with the block comment saying why a no-op is unreachable here rather than merely empty; `MGPipeApplierReset` clears all 11 new members and deliberately does **not** clear the op table. |
| `MobileGL/MG_Pipe/Coverage.def` | `GetBufferBindingSlot`'s comment **rewritten**: the per-target split is now stated target by target (vertex / index / indirect / shader-buffers / still-pulled), sourced from the emission site rather than from a re-vendored inventory, plus why the row stays one row and why it is not in the emitted list. `MGP_COVERAGE_EMITTED_LIST` gains **`X(GetBoundVertexArray, BindVertexElements)`** with a note for the commit that wires it. The `Buffer ops delta → ResourceRespecify` delta row is untouched. |
| `MobileGL/MG_Impl/Pipe/PipeFill.cpp` | *(contract-commit-only, enum-coupled block)* `SubsystemForEmitter` gains the `BindVertexElements → kMGPipeSubsystemVertexInput` arm; four new `static_assert`s (one direct, three conditional pairings — §3 B1) plus the `kMGPipeMaxVertexAttribs` ↔ `VertexArrayObject::MAX_VERTEX_ATTRIBS` drift assert; `kMGPipeWiredSubsystems` **unchanged, with the reason recorded in place** (§3 B2); three **stub emitters** `Emit{VertexElements,VertexBuffers,IndexBuffer}` returning 0 and their three `wants()`-gated call sites in `MGPipeValidateForVerb` step 3, in the fixed order after the four P2 emitters. |
| `MobileGL/MG_Pipe/generated/PipeVerify.inc` | regenerated: two forward decls, two `MGPipeHasFieldVerifier` specialisations, two comparators, `kMGPipeVerifiedPayloadCount` 69 → 71. |
| `MobileGL/MG_Pipe/generated/PipeFilled.inc` | regenerated: `MGPipeFieldEmitter::BindVertexElements`, its name-table row, `kMGPipeFieldEmittedBy[GetBoundVertexArray]`, `kMGPipeEmittedFieldCount` 33 → 34. |
| *(the other six `.inc`)* | regenerated, byte-identical (§3 C1). |
| `MobileGL/MG_Backend/DirectGLES/SlotTables.h` | `BackendSlotTable::GetOrCreate(MGPipeHandle)` — never calls `MGPipeSlots()`, no `StatePtr`, arms the teardown sentinel, resets a twin whose `Gen` no longer matches. Header-only, uninstantiated, both arms compile. `FindByHandle(MGPipeHandle)` already existed and already met the requirement (§3 C2). |
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | `CallClass::MapPersistentRoundtrips` inside the existing `#if MOBILEGL_PIPE_PUSH` block, name `"map-persistent-roundtrips"`, `FormatWindowLine` prints ` mpr=<n>` beside `csom`/`csob`. |
| `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | `mpr=` pinned in `SummaryLineCarriesEveryClassAndGate`, the name pinned in `CounterNamesAreStable`, both inside the push guard. |
| `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | `kMGPipeVerifiedPayloadCount` 69 → **71** (a required consequence the brief does not mention); two `MGPipeHasFieldVerifier` static asserts; **3 new cases** — `VertexBufferSetCarriesAnExplicitBaseInstance` (size 24, `Pad0` is not a field, comparator names `BaseInstance`, per-entry struct unchanged), `VertexWireViewsAreFlatAndCarryIsLongSeparately` (both sizes, comparator names `IsLong` and `Divisor`), `ResourceRespecifyAcksOnlyImmutableStorage` (the flag is on the call, it is the **only** call carrying it, the predicate is true for `Immutable=1` and false for a `STATIC_DRAW` + defined-content mutable store, and opcode 3 did not move). |
| `MobileGL/MG_Test/Pipe/ResourceEmitTest.cpp` | **new**, suite `ResourceEmit`, own `main()`, one permanent case `TheResourceOpTableIsUnregisteredUntilABackendInstallsOne` (§3 D3). |
| `MobileGL/MG_Test/Pipe/VertexInputEmitTest.cpp` | **new**, suite `VertexInputEmit`, own `main()`, one permanent case `AResetApplierCarriesNoVertexInputStateOver`. |
| `MobileGL/MG_Test/Pipe/CMakeLists.txt` | both registered (`GTest::gtest`, own `main()`), `gtest_discover_tests(... PROPERTIES LABELS unit)`. Re-opened at `44c2b5cf` per ID-1: it already carried `MagmaPipeIdentityTest`. |
| `MobileGL/Config.h` | bit-list comment gains `0x80 resources` and `0x100 vertex input`; the default now names `kMGPipeSubsystemsMigratedAtP3a` and records `0x7f` as the phase-by-phase control. |
| `MobileGL/ConfigLoader.cpp` | push default `kMGPipeSubsystemsMigratedAtP2` → **`kMGPipeSubsystemsMigratedAtP3a`** (0x7f → 0x1ff). |
---
## 2. The contract, verbatim — what B, C and D compile against
### 2.1 The two wire structs (`MG_Pipe/MGPipeValueTypes.h`, `namespace MobileGL`)
```cpp
struct MGPVertexAttribWire {
Uint64 Offset; // 0
Int32 Stride; // 8
Uint32 Type; // 12 DataType
Uint8 Size; // 16 1..4; GL_BGRA keeps 4
Uint8 Enabled; // 17
Uint8 Normalized; // 18
Uint8 IsInteger; // 19
Uint8 IsLong; // 20 carried separately from Type == Float64
Uint8 IsBgra; // 21
Uint8 BindingIndex; // 22 < kMGPipeMaxVertexAttribs
Uint8 Pad0; // 23
}; // sizeof == 24
struct MGPVertexBindingPointWire {
Uint64 Offset; // 0
Int32 Stride; // 8 initial value is 16, not 0
Uint32 Divisor; // 12
}; // sizeof == 16
```
Blob layout on `CreateVertexElements`: `MGPVertexAttribWire[AttributeCount]` immediately followed by
`MGPVertexBindingPointWire[BindingPointCount]`, both ascending, both counts `<= kMGPipeMaxVertexAttribs`.
### 2.2 `MGPVertexBuffers` (`MG_Pipe/MGPipeTypes.h`)
```cpp
struct MGPVertexBuffers {
Uint32 Start, Count;
Uint32 BaseInstance; // NEW: the draw's raw vertex-FETCH base instance, one per set
Uint32 Pad0; // NEW
Uint64 ContentHash; // must include BaseInstance
}; // sizeof == 24 (was 16)
inline constexpr Uint32 kMGPipeMaxVertexAttribs = 32; // NEW
inline Bool MGPipeResourceRespecifyNeedsAck(const MGPResourceDesc& desc) { return desc.Immutable != 0; } // NEW
```
`MGPVertexBuffer` (per-entry, 32 B) is unchanged; its `Pad0` stays padding.
### 2.3 `MGPipeResourceOps` (`MG_Pipe/PipeApply.h`, inside the existing push guard)
```cpp
struct MGPipeResourceOps {
void (*Create) (MGPipeHandle res, const MGPResourceDesc& desc);
void (*Respecify) (MGPipeHandle res, const MGPResourceDesc& desc, const void* initialBytes);
void (*SubData) (MGPipeHandle res, const MGPSubData& record, const void* bytes);
void (*SubDataResident)(MGPipeHandle res, const MGPSubData& record, const void* bytes); // may be null
void (*FlushRange) (MGPipeHandle res, const MGPFlushRange& record, const void* bytes);
void (*Readback) (MGPipeHandle res, const MGPReadback& record);
void (*Destroy) (MGPipeHandle res);
void* (*MapPersistent) (MGPipeHandle res, Uint64 size, const void* seedBytes);
void (*UnmapPersistent)(MGPipeHandle res);
};
void MGPipeSetResourceOps(const MGPipeResourceOps* ops); // nullptr uninstalls
const MGPipeResourceOps* MGPipeGetResourceOps(); // nullptr until a backend installs one
```
### 2.4 The fourteen apply entry points
```cpp
void MGPipeApplyResourceCreate (const MGPResourceDesc& desc);
void MGPipeApplyResourceRespecify (const MGPResourceDesc& desc, const void* initialBytes);
void MGPipeApplyResourceSubData (const MGPSubData& record, const void* bytes);
void MGPipeApplyBufferSubDataResident(const MGPSubData& record, const void* bytes);
void MGPipeApplyResourceFlushRange (const MGPFlushRange& record, const void* bytes);
void MGPipeApplyResourceReadback (const MGPReadback& record);
void MGPipeApplyResourceDestroy (const MGPHandleOnly& handle);
void* MGPipeApplyMapPersistent (const MGPHandleOnly& handle, Uint64 size, const void* seedBytes);
void MGPipeApplyUnmapPersistent (const MGPHandleOnly& handle);
void MGPipeApplyCreateVertexElements (const MGPVertexElements& desc, const void* blobBytes);
void MGPipeApplyBindVertexElements (const MGPHandleOnly& handle);
void MGPipeApplyDeleteVertexElements (const MGPHandleOnly& handle);
void MGPipeApplySetVertexBuffers (const MGPVertexBuffers& hdr, const MGPVertexBuffer* tail);
void MGPipeApplySetIndexBuffer (const MGPIndexBuffer& record);
```
All fourteen are **no-op stubs** at `c0`; `MGPipeApplyMapPersistent` returns `nullptr` (a decline, which is a
supported answer).
### 2.5 The applier's records and state
```cpp
struct MGPipeResourceRecord { // indexed by MGPipeHandle::Slot, kind Buffer; slot 0 never live
Uint32 Gen = 0; Bool Live = false;
MGPResourceDesc Desc{};
Uint64 Serial = 0; // server-owned MGGen
Bool HasLiveHostWrites = false; // always false in P3a
};
struct MGPipeVertexElementsRecord { // indexed by MGPipeHandle::Slot, kind VertexElementsCso
Uint32 Gen = 0; Bool Live = false;
Uint32 AttributeCount = 0, BindingPointCount = 0;
Array<MGPVertexAttribWire, kMGPipeMaxVertexAttribs> Attributes{};
Array<MGPVertexBindingPointWire, kMGPipeMaxVertexAttribs> BindingPoints{};
Uint64 ContentSerial = 0; // server-owned MGGen
};
// appended to MGPipeApplierState:
Vector<MGPipeResourceRecord> Resources;
Vector<MGPipeVertexElementsRecord> VertexElementsCsos;
MGPipeHandle BoundVertexElements = kMGPipeNullHandle;
Array<MGPVertexBuffer, kMGPipeMaxVertexAttribs> VertexBuffers{};
Uint32 VertexBufferStart = 0;
Uint32 VertexBufferCount = 0;
Uint32 VertexFetchBaseInstance = 0;
Uint64 VertexBuffersSerial = 0;
MGPIndexBuffer IndexBuffer{};
Uint64 IndexBufferSerial = 0;
Uint64 MapPersistentRoundtrips = 0;
```
`MGPipeApplierReset()` clears all eleven. It does **not** clear the op table.
### 2.6 Everything else B / C / D can rely on
- `kMGPipeSubsystemResources = 1ull << 7`, `kMGPipeSubsystemVertexInput = 1ull << 8`,
`kMGPipeSubsystemsMigratedAtP3a = 0x1ffull`; push default is now `0x1ff`, `0x7f` is the P3a-off control.
- `BackendSlotTable::GetOrCreate(MG_Pipe::MGPipeHandle)` and the pre-existing `FindByHandle(MGPipeHandle)`.
- `PipeStats::CallClass::MapPersistentRoundtrips`, short name `mpr`, push-only.
- Stub emitters `EmitVertexElements/EmitVertexBuffers/EmitIndexBuffer(GLContext&) -> Uint64` in
`PipeFill.cpp`'s anonymous namespace, already called from step 3 in the fixed order. **B replaces the
bodies without moving a call site.**
- gtest suites `ResourceEmit` and `VertexInputEmit` (see D3).
---
## 3. Deviations from the brief, each with its reason
### A. Types
**A1 — `kMGPipeMaxVertexAttribs` was minted (not in the brief).** D-G4 writes the applier's arrays as
`Array<..., 32>`. A bare 32 in `MG_Pipe` that must equal `VertexArrayObject::MAX_VERTEX_ATTRIBS` is a
silent-drift hazard and `MG_Pipe` may not include a frontend header (purity gate A). So the constant is
declared once in `MGPipeTypes.h` and `PipeFill.cpp` — the one translation unit that sees both — carries
`static_assert(kMGPipeMaxVertexAttribs == VertexArrayObject::MAX_VERTEX_ATTRIBS)`.
**A2 — the wire structs use plain `static_assert`, not `MGP_ASSERT_POD`.** D-G2 writes `MGP_ASSERT_POD`, but
C.0 places the structs in `MGPipeValueTypes.h` and that macro is defined in `MGPipeTypes.h`, which *includes*
`MGPipeValueTypes.h`. The assertions are spelled out in the existing `:547` trip-wire block instead, in that
block's own style, and cover trivial copyability, exact size and standard layout.
**A3 — eleven new `MGPipeApplierState` members, not "ten".** C.0 says ten; D-G4's own code block declares
eleven (`VertexBufferStart` and `VertexBufferCount` are two members on one line, as are `IndexBuffer` and
`IndexBufferSerial`). D-G4's block is what landed, verbatim. No member was dropped or added.
### B. `PipeFill.cpp`'s enum-coupled block
**B1 — three of the four new pairing `static_assert`s are conditional, not equalities.** D-M asks for
`SubsystemForEmitter(...) == MGPipeSubsystemForDirty(...)` alongside three new `MGPipeSubsystemForDirty` arms
"all four in one commit". `MGPipeSubsystemForDirty` lives in `MG_Impl/Pipe/Tracker.h`, which **C.5 assigns to
package B**, and at `44c2b5cf` it returns 0 for bits 5/9/10. A direct equality would therefore fail to compile
at `c0` for a reason that is not a defect, and the only way to make it hold would be to edit B's file — which
hard rule (4) forbids and which would guarantee a rebase conflict. What landed:
- an unconditional `SubsystemForEmitter(BindVertexElements) == kMGPipeSubsystemVertexInput`;
- three of the form `MGPipeSubsystemForDirty(bit) == 0 || MGPipeSubsystemForDirty(bit) == kMGPipeSubsystemVertexInput`,
for `NewVertexElements`, `NewVertexBuffers`, `NewIndexBuffer`. The escape hatch is *only* the not-yet-mapped
case: the moment B maps a bit onto anything, the assertion becomes the equality D-M asks for. No later edit
is required, and none is invited.
This is recorded as a brief-internal contradiction (D-M vs C.0/C.5) rather than a design change; the integrator
should correct D-M.
**B2 — `kMGPipeWiredSubsystems` does NOT gain the two bits at `c0`.** D-M asks for it in the same commit. It
would be a live bug. Traced through `MGPipeValidateForVerb` step 4 with the new default push mask `0x1ff`:
`supplied` for `GetBoundVertexArray` would evaluate `subsystem != 0` ✓, `subsystem & wired` ✓,
`pushMask & subsystem` ✓, `EmittedCallSuppliesTheWholeField` ✓ (default arm), `applierDerives` ✓ — so
`CopyField` would be **skipped** while the emitters are stubs and the applier's entry points are stubs, leaving
`PipeInputs::m_boundVertexArray` unwritten in every push and verify build. That is precisely the failure the
constant's own comment says it exists to prevent ("a field whose emitter is not wired here keeps being
pulled"). The reason is written into the file beside the constant, and B adds the bits in the commit that gives
the emitters their bodies.
**B3 — stub emitters are wired into step 3 at `c0`, not only declared.** C.0 says "stub emitters that emit
nothing"; the call sites were added too, gated by `wants()`, so B's commit is a body replacement rather than a
body plus a call-site edit at the validate point. They are unreachable today (their dirty bits map to no
subsystem) and return 0 so the payload histogram gains no bucket for bytes nobody sent.
### C. Generators and `Coverage.def`
**C1 — `scripts/gen_pipe.py` needed no edit.** C.0 lists it as MODIFY, "whatever the two new payloads and the
flag-word change require". Verified by reading the generator: `MGPipeValueTypes.h` is already in
`FIELD_LIST_STRUCT_HEADERS`, `gen_verify` is driven entirely off `MGP_VERIFY_PAYLOAD_LIST`, and no generator
materialises a call's flag word (`Call.Flags` is only consulted for `kVarTail` / `kReplySlot` signatures). So
`gen_pipe.py` is unchanged and **only two** of the eight `.inc` files actually moved. Related: **D-A5's claim
that "a flag-word edit changes the generated tables" is false in this tree** — `git diff --exit-code --
MobileGL/MG_Pipe/generated` was still run and is clean, but it is not what catches a missing regeneration for
that edit; `PipeCatalogueTest.ResourceRespecifyAcksOnlyImmutableStorage` is.
**C2 — only `GetOrCreate(MGPipeHandle)` was added to `SlotTables.h`.** C.0 asks for
"`GetOrCreate(MGPipeHandle)` / `FindByHandle` overloads that never call `MGPipeSlots()`".
`BackendSlotTable::FindByHandle(MGPipeHandle)` already exists at `44c2b5cf` and already meets the requirement
verbatim, so adding a second one would be churn. No `const` overload was added either — nothing needs one yet
and `MG_Backend/DirectGLES/**` is package C's from the tag on.
**C3 — `GetBufferBindingSlot`'s accessor row could not literally "split per target".**
`MGP_COVERAGE_ACCESSOR_LIST` *is* the `MGPipeInputField` enum and the `PipeInputs` field set (one row → one
enumerator → one member of `PipeInputs`' X-macro list, which is `MG_Backend`'s file), and the field is a single
array `m_bufferBindingSlot[kBufferTargetCount]`. A duplicate row would be a duplicate enumerator. The split is
therefore stated exhaustively in the rewritten comment (target → call, including the five targets that are
still pulled) and lives in the emitters; the row stays one row naming `SetIndirectBuffers`, and the comment
says why. It is deliberately kept **out** of the emitted list, because five of its targets are still pulled and
a row there would be the same half-truth `GetPixelStoreParameters` is excluded for.
**C4 — the emitted list gained exactly one row, `GetBoundVertexArray → BindVertexElements`.** C.0 says
"emitted-list vertex-input fields", plural. The accessor list contains exactly three vertex-input accessors:
`GetCurrentVertexAttribute` (already emitted since P2), `GetBufferBindingSlot` (C3) and `GetBoundVertexArray`.
The row is inert until B wires the subsystem (B2), and a note in `Coverage.def` tells the wiring commit that
the field is a `SharedPtr` to the frontend VAO which the applier does not reproduce, so the
`EmittedCallSuppliesTheWholeField` decision must be taken deliberately in `PipeFill.cpp` (B's file from the tag
on) rather than inherited silently from the row's presence.
### D. Build files and tests
**D1 — root `CMakeLists.txt` was not touched.** C.0's row is "the new client sources inside
`if (MOBILEGL_PIPE_PUSH)`". D-N fixes that P3a's new client files are **headers**
(`MG_Impl/Pipe/{ResourceTracker.h, VertexInputEmit.h}`), and `SOURCE_FILES` lists no headers, so there is no
source to add. The two other halves of that row — the push default and the bit-list comment — landed in
`ConfigLoader.cpp` and `Config.h`. If B later needs a `.cpp`, the root `CMakeLists.txt` is still A's file and
the contract would have to be re-opened; B was told the new files are headers for exactly this reason.
**D2 — `PipeCatalogueTest.cpp` also needed `kMGPipeVerifiedPayloadCount` 69 → 71.** Not in C.0's row, but a
mandatory consequence of appending to `MGP_VERIFY_PAYLOAD_LIST`; without it the suite fails.
**D3 — the two new gtest suites are `ResourceEmit` and `VertexInputEmit`, not `…Test`.** The brief names cases
as `VertexInputEmitTest.X` / `ResourceEmitTest.X` in prose (D-H2.3, C.1's list, E's risk table) but spells the
gates as `ctest -R 'VertexInputEmit\.'` (G6, G7) and `-R '…|VertexInputEmit\.|ResourceEmit\.'` (line 1488).
A suite named `VertexInputEmitTest` does not match `VertexInputEmit\.`, so with `--no-tests=error` G6 and G7
could never run. The suite names follow the gates and this directory's own convention
(`RenderStateSpansTest.cpp` → suite `RenderStateSpans`). **The prose case names in the brief must be read with
the `Test` dropped**: `VertexInputEmit.ABaseInstanceChangeAloneStillEmitsTheVertexBufferSet`, and so on.
**D4 — the two stubs link `GTest::gtest` and carry their own `main()`.** C.0 only asks for "one placeholder
`TEST`". The point of A owning the registration is that no later package edits
`MG_Test/Pipe/CMakeLists.txt`; a `gtest_main` target would force exactly that edit the first time a case needs
to read a trip wire's line back out of a log file (which both suites will: the applier's blob-bounds gate and
its protocol refusal report that way, and abort under poison/verify). The `main()` shape is copied from
`RenderStateSpansTest`/`PipeInputsTest`.
**D5 — the placeholders are permanent contract assertions, not throwaways.** G14 forbids removing a test name,
so a placeholder that B deletes would itself be a gate break. `ResourceEmit.TheResourceOpTableIsUnregisteredUntilABackendInstallsOne`
pins the fact the whole family's landability rests on (nothing is registered ⇒ every dispatch falls through)
plus the set/get round trip and that `MGPipeApplierReset` does not clear the table;
`VertexInputEmit.AResetApplierCarriesNoVertexInputStateOver` pins that a fresh context carries no handle, no
window and no serial over. Both skip visibly in a pull build.
---
## 4. Verification transcript
All commands in `/home/swung/w7/p3a-contract`, `CCACHE_BASEDIR=/home/swung/w7`, at the tagged commit.
**G1 — pull build symbol identity** (`symbol_report.py --before ~/w7/p3a-before-libMobileGL.so --after
build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0`), rc **0**:
```
symbol-report: Total 17209979 -> 17209979 (+0)
symbol-report: 27799 -> 27799 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
`.text` 10792739 -> 10792739 (+0, +0.000%). ... 27060 unchanged.
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (same size) (0)
```
P3a's admitted-resize set is empty, as §A.2 G1 requires.
**Generators**
```
python3 scripts/gen_pipe.py --check rc 0 "gen_pipe: generated files are up to date"
"71 calls (11 screen, 60 context), 71 verify payloads,
63 PipeInputs fields (7 sticky, 34 emitted), 69 verbs, 9 classes"
"inventory 477 rows: ... 0 UNMAPPED"
python3 scripts/gen_pipe.py --self-test rc 0 "7 negative-control trip(s), positive control OK"
git diff --exit-code -- MobileGL/MG_Pipe/generated rc 0
```
**Include closure** — the brief's form names `clang++-20`, which does not exist on this host (`clang++` is
22.1.6); both forms were run:
```
python3 scripts/check_include_closure.py rc 0
value-header OK 66 headers, 0 forbidden; artifacts-header OK 65; mutation-header OK 84; wire-header OK 2
include-closure: 4 probes, 0 skipped, 0 problem(s)
python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all rc 0
include-closure: self-test: 6 negative-control trip(s), parser checks OK
include-closure: 4 probes, 0 skipped, 0 problem(s)
```
**Three builds** — `cmake --build <dir> -j 24`
| build | rc |
|---|---|
| `build-linux` (pull) | 0 (339/339) |
| `build-push` | 0 (349/349) |
| `build-verify` | 0 (349/349) |
**Three unit runs** — `ctest --test-dir <dir> -L unit -j 12 --no-tests=error`, rc 0 in all three:
```
build-linux 100% tests passed, 0 tests failed out of 1571 (9.71 s)
build-push 100% tests passed, 0 tests failed out of 1571 (9.76 s)
build-verify 100% tests passed, 0 tests failed out of 1571 (9.72 s)
```
**Name-set checks (G2's name half, G14)**
```
ctest -N names: build-linux 2487, build-push 2487, build-verify 3315
diff <build-linux names> <build-push names> -> empty
comm -23 ~/w7/p3a-before-ctest-names.txt <build-linux names> -> empty (nothing removed)
comm -13 ... -> 5 added:
PipeCatalogue.ResourceRespecifyAcksOnlyImmutableStorage
PipeCatalogue.VertexBufferSetCarriesAnExplicitBaseInstance
PipeCatalogue.VertexWireViewsAreFlatAndCarryIsLongSeparately
ResourceEmit.TheResourceOpTableIsUnregisteredUntilABackendInstallsOne
VertexInputEmit.AResetApplierCarriesNoVertexInputStateOver
ctest --test-dir build-push -N -R 'VertexInputEmit\.|ResourceEmit\.' -> Total Tests: 2
```
(The baseline was 2482 names; 2487 = 2482 + 5.)
**G13's two greps**
```
grep -c 'MG_State' MobileGL/MG_Pipe/PipeApply.h -> 0
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' -> empty
```
**Not run here, and why**: G2's execution half, G3/G3b/G4's retrace, G5 (`p3a_untouched_regions.sh` is package
D's and does not exist yet), G6-G12, G15. `c0` touches no `Managers.cpp` region and changes no behaviour, and
those gates belong to the integrator's D.1 merges.
---
## 5. Left undone / handed on
1. **`p3a/wire`'s `c1`, `c2`, `c3`** — the fourteen bodies and `ResourceEmitTest`'s applier cases. Not started;
this task was `c0` only.
2. **`kMGPipeWiredSubsystems`** must gain `kMGPipeSubsystemResources | kMGPipeSubsystemVertexInput` in the
commit that gives the emitters bodies (B2). Until then no vertex-input field is skipped by the residual
fill — which is correct, but it also means the subsystem A/B (G12) cannot show a *fill-loop* difference yet.
3. **`Tracker.h`'s three `MGPipeSubsystemForDirty` arms** (bits 5, 9, 10 → `kMGPipeSubsystemVertexInput`) are
package B's; the three conditional pairing asserts in `PipeFill.cpp` become equalities the moment they land,
with no edit needed.
4. **`EmittedCallSuppliesTheWholeField(GetBoundVertexArray)`** — C4's note; B must decide it explicitly.
5. **Doc corrections owed to the integrator**, beyond the ones the brief already lists: D-M's "all four in one
commit" is not achievable under C.5's ownership split (B1/B2); D-A5's "a flag-word edit changes the
generated tables" is not true in this tree (C1); C.0's "ten new `MGPipeApplierState` members" is eleven
(A3); the brief's `VertexInputEmitTest.`/`ResourceEmitTest.` case names must lose the `Test` (D3);
`check_include_closure.py --compiler clang++-20` does not exist on this host (§4).
6. **Not pushed**, per the task. The tag is local to `/home/swung/w7/p3a-contract`; the other three trees must
be created from it with `wsl_p3a_tree.sh <slug> p3a/contract`.
Intermediate logs this package created — `~/w7/p3a-contract-{sym,closure,closure2}.log` and
`~/w7/p3a-contract-names-build-*.txt` — were deleted. `~/w7/p3a-contract-tree.log` is kept, as instructed.
Six further files match the same glob and were **left alone because they are not this package's**: the tree
script's own `p3a-contract-{submodule,build-linux-configure,build-linux-build,build-push-configure,
build-push-build,build-verify-configure,build-verify-build}.log`. The integrator should delete them if the
tree-creation transcript is no longer wanted.