Files
MobileGL/docs/Disaggregated/notes/p4a/p4a-results/wire-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

492 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P4a package A — `w1`..`w4`, the applier bodies. Result, v1
Branch `refs/heads/p4a/wire`, worktree `/home/swung/w7/p4a-wire`, on top of the tag
`refs/tags/p4a/contract` = `08192d72`. **Four commits, two production files and seven test
files, +3147 / −49. Not pushed. Nothing else touched.**
| commit | message (single line, empty body, no attribution) |
|---|---|
| `86835b50` | `[Feat] (Pipe): apply the framebuffer record per bound target and the texture and renderbuffer resource calls into their own slot-indexed records` |
| `bc9abfbd` | `[Feat] (Pipe): apply sampler states, sampler views and the three unit sets into the server's own working state` |
| `0f990633` | `[Feat] (Pipe): apply the shader CSO's artefacts and the default uniform block without ever re-linking on the server` |
| `3c07c8c3` | `[Test] (Pipe): pin every P4a record's lifecycle, its bounds gate and what a make-current does and does not clear` |
```
MobileGL/MG_Pipe/PipeApply.cpp | 1016 ++++++++++++++++++--
MobileGL/MG_Pipe/PipeApply.h | 46 +-
MobileGL/MG_Test/Pipe/CompositeResolverTest.cpp | 237 +++++
MobileGL/MG_Test/Pipe/FramebufferEmitTest.cpp | 249 +++++
MobileGL/MG_Test/Pipe/ImageEmitTest.cpp | 248 +++++
MobileGL/MG_Test/Pipe/ProgramEmitTest.cpp | 397 ++++++++
MobileGL/MG_Test/Pipe/ResourceEmitTest.cpp | 148 +++
MobileGL/MG_Test/Pipe/SamplerEmitTest.cpp | 444 +++++++++
MobileGL/MG_Test/Pipe/TextureEmitTest.cpp | 411 ++++++++
```
**Behaviour neutrality holds and is structural.** Nothing in this package registers a consumer
of any record: the four subsystem bits are absent from `kMGPipeWiredSubsystems`, every client
emitter beside them is still a stub, `MGPipeResourceOps` is unchanged at nine members, and no
backend reads the new state. `grep` over `MobileGL/` for the fifteen entry points returns hits
only in `MG_Pipe/PipeApply.{h,cpp}` and in `MG_Test/Pipe/*EmitTest.cpp`. The pull build is
byte-identical to `$BASE`'s (G1 0/0/0/0).
---
## 1. Verdict on the hard rules (after `3c07c8c3`; re-run unchanged after every commit)
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | rc 0, **0 added / 0 removed / 0 renamed / 0 resized** after each of the four commits |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 controls tripped) |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0, 27 negative controls, all tripped |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds compile (pull / push / verify) | all three, after every commit |
| `ctest -L unit` in all three | **1668 / 1668 in each**, 0 failed (1635 at the tag, +33) |
| ctest names pull == push | `diff` empty |
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | empty; 46 added (the contract's 13 + this package's 33) |
| only A's files | yes — `MG_Pipe/PipeApply.{h,cpp}` and the seven `MG_Test/Pipe/*Test.cpp` C.7 gives A |
| four commits, exact messages, no attribution, not pushed, no other worktree | yes |
| `grep -rc 'pGLContext' MG_Backend` | only `MGPipe/PipeInputs.h:1`, pre-existing |
---
## 2. Per-entry-point behaviour: record, serial, bounds, refusal
The two verdicts are P3a's and the difference between them is the whole discipline:
* **a call naming a record this applier does not have is a DEFINED NO-OP that is COUNTED.**
One legal sequence produces it (teardown → `MGPipeApplierReleaseObjectRecords` → `~Object` →
death notices naming records already dropped), so it cannot be a wire; `MOBILEGL_ASSERT` is
inert at INFO, so it cannot be only an assertion. `RefusedResourceCalls` takes the resource
family (buffers, textures **and** renderbuffers — they are resource calls);
`RefusedObjectCalls` takes the five object families (framebuffer, sampler, sampler view,
program, texture params).
* **a record that would make the server index or allocate outside its own storage is
`Fatal{ProtocolCorruption}`** with the record's identity in the line, and it is **not**
counted as a refusal.
### 2.1 `set_framebuffer_state`
| | |
|---|---|
| storage | `DrawFramebuffer` / `ReadFramebuffer`, working state. `Target != Read` writes the draw record, `Target != Draw` writes the read record, so `Both` writes both. |
| serial | `FramebufferSerial`, one for the pair, `++` once per applied record (**a `Both` record is one record and bumps once**). |
| bounds | `Target >= MGPipeFramebufferTarget::Count` → Fatal. Every `DrawBuffers[i]` outside `[-1, kMGPipeMaxColorAttachments)` → Fatal (an index into the record's own `Color[]`). |
| refusal | **none, ever.** A framebuffer has a handle but no wire lifetime (D-I2), so there is no record to resolve; and the surfaces' `Res` handles are deliberately **not** resolved, because an attachment pins its texture through the frontend's own `SharedPtr` in monolith and a refusal here would enforce a lifetime rule monolith cannot need (D-I3). This entry point never touches `RefusedObjectCalls`. |
### 2.2 `resource_create` / `resource_respecify` / `resource_subdata` / `resource_destroy`
The four P3a entry points now **branch on the descriptor's `Target`** (on the handle's `Kind`
for the destroy, which carries no descriptor). The three tables are `Resources`,
`TextureResources`, `RenderbufferResources`; the record **type** is shared and the bound
(`kMGPipeMaxResourceSlots`) is shared, only the table is per kind.
| | |
|---|---|
| table selection | `Target == Buffer` → `Resources`; `Target == Renderbuffer` → `RenderbufferResources`; every other enumerator below `Count` → `TextureResources`; `>= Count` → Fatal. Destroy: `Kind` ∈ {Buffer, Texture, Renderbuffer}, anything else → Fatal. |
| create | starts the record over, `Gen` from the handle, `Live = true`, `Serial` stays **0**. Dispatches to `MGPipeResourceOps::Create` **only for a buffer**. |
| respecify | replaces `Desc` whole, `++Serial`, **clears `PendingUploads`** (§2.4), dispatches **only for a buffer**. |
| destroy | drops the record whole, keeps `Gen`, dispatches **only for a buffer** (the op table is the buffer family's). |
| bounds | `slot >= kMGPipeMaxResourceSlots` → Fatal naming the bound; the table is never grown by a corrupt slot. |
| refusal | `RefusedResourceCalls`, through `ResolveResourceIn`. |
### 2.3 `set_texture_params`
| | |
|---|---|
| storage | `MGPipeResourceRecord::Params` on the **texture** record, addressed by resource and independent of any binding. |
| serial | `ParamsSerial`, `++` per applied call. `Serial` (the storage serial) does **not** move — a parameter push is not a storage mutation. |
| bounds | `params.BuiltinSampler == kMGPipeNullHandle` → **Fatal** (§5, hazard H1). |
| not checked | the CSO the record names is **not resolved**: the sampler bit may legitimately be clear while the texture bit is set, so an unresolvable `BuiltinSampler` is an ordering fact, not a corrupt one. |
| refusal | `RefusedObjectCalls`. |
### 2.4 The sub-data validator, per target
`SubDataBoxFault` was **split in two** rather than widened; every statement it made is a
statement about the buffer convention and every one of them is false for a texture.
**Buffer half (`Target == kMGPipeResourceTargetBuffer`, unchanged from P3a):** offset above
`0x7FFFFFFF` → Fatal; `Level != 0` → Fatal; `RegionCount != 0` → Fatal; `Blob.Size != 0 &&
Blob.Size != MGPipeSubDataBufferSize(record)` → Fatal; then `BufferRangeFault` against
`Desc.Width`; then a non-empty write with `bytes == nullptr` → Fatal. Dispatches to
`MGPipeResourceOps::SubData` / `SubDataResident`.
**Texture half (every other `Target`):**
| rule | verdict |
|---|---|
| `Level >= kMGPipeMaxTextureLevels` (32) | Fatal |
| the union box has a negative origin, or `origin + extent > 0x7FFFFFFF` on any axis | Fatal |
| `RegionCount > kMGPipeMaxPendingUploadRegions` (256) | Fatal |
| `RegionCount != 0 && regions == nullptr` | Fatal |
| a region with a negative origin or an unencodable extent | Fatal |
| **a region not inside the union box** | Fatal |
| an empty box **and** zero regions ("no texels at all") | Fatal |
| `bytes == nullptr` | Fatal |
| more distinct `(UploadTarget, Level)` keys than `kMGPipeMaxPendingUploads` (256) | Fatal |
The region-containment rule is the one that matters: the union box **is** the union of the
regions, the server picks the upload shape from the pair, so a region outside the box means the
box misses its texels and the region writes where the box never said it would.
**Deliberately NOT checked, so a later reader does not add them back as an oversight:** (a) the
level against `Desc.Levels` — a mutable texture defines its levels one `glTexImage2D` at a
time, so the descriptor's level count is not an upper bound at every instant and a gate on it
would refuse a legal upload; (b) the box against the descriptor's extents — the record
addresses the **level's** coordinate system and a view remaps that space, so the arithmetic is
the storage owner's; (c) the blob — **no field of a texture record describes its own byte
length**, so the one Blob rule has nothing to cross-check and is inert here by construction.
**Pending-upload accumulation (D-D5).** Keyed `(UploadTarget, Level)` on the texture's record.
Boxes union; rect lists concatenate; and the moment either side says "box only", or the list
would outgrow `kMGPipeMaxPendingUploadRegions`, the entry becomes **box only** — never a
dropped region, because the box still covers every texel the dropped list named. That is the
frontend's own model one level up (`MipmapStorage` answers "0 rects" for everything it cannot
describe that way). An entry is never created empty, which is why an empty `Regions` after the
first contribution unambiguously means box-only. `++Serial` on acceptance, and the acceptance
is what the client reads before clearing its own dirty flag.
### 2.5 `create_sampler_state` / `delete_sampler_state`
| | |
|---|---|
| storage | `SamplerCsos[slot]`, `Params` by value **including `borderColorForm`**. |
| serial | a **fresh or recycled identity** starts over with `Serial = 0` (a create is not a mutation, and a fresh twin starting at 0 agrees without either side publishing); a **re-issue on a live identity** keeps the record and `++Serial`. |
| bounds | `Parameters.Size != 0 && != sizeof(SamplerParameters)` → Fatal; `parameters == nullptr` → Fatal; `slot >= kMGPipeMaxSamplerCsoSlots` → Fatal. |
| delete | drops the record whole, keeps `Gen`. **Does not sweep `BoundSamplerStates`** — that window is "the last set as received" and the client re-emits it at the next verb. |
| refusal | `RefusedObjectCalls`. |
### 2.6 `create_sampler_view` / `delete_sampler_view`
| | |
|---|---|
| storage | `SamplerViewCsos[slot]`, `View` verbatim, plus **the texture's `ViewCso` back-pointer**. |
| serial | the same fresh-vs-re-issue rule as the sampler CSO. A re-issue **does not rebind** anything. |
| bounds | `slot >= kMGPipeMaxSamplerViewSlots` → Fatal. `View.Target`, `MinLevel`/`NumLevels`/`MinLayer`/`NumLayers` are **not policed** (`MGPVertexBuffer::BindingIndex`'s precedent: the applier cannot justify that contract). |
| back-pointer | written through a **silent** `FindIn` (no refusal counted) — a view arriving before or without its texture record is legal in a mixed-bit lane. The delete clears it **only if the texture still names this view**. |
| refusal | `RefusedObjectCalls` on the delete. |
### 2.7 The three `kVarTail` unit sets
One shared body (`ApplyUnitWindow`), because they differ only in what an entry is.
| | |
|---|---|
| bounds | `Start + Count > 192` → **Fatal** (`kMGPipeMaxTextureUnits` for the two sampler sets, `kMGPipeMaxImageUnits` for the images; the two constants are equal and a case pins that). `Count != 0 && tail == nullptr` → Fatal. |
| storage | entries land at `Start + i` and **nowhere else**; `Start`/`Count` stored; **entries outside the window are not cleared** — the record is "the last set as received", and a set that names four units has said nothing about the other 188. |
| serials | `SamplerViewsSerial` / `SamplerStatesSerial` / `ShaderImagesSerial`, `++` per applied set, independently. |
| refusal | **none** — a set is working state and resolves no record. A **null handle in any tail entry is legal** everywhere (a unit the program does not resolve, a unit with no sampler object, an unbound unit) and the entry's own `Unit` field is deliberately unpoliced: the destination is `Start + i`, which the window already bounds. |
| empty set | applied, not refused, and it still moves the serial — a program with no images publishes one. |
### 2.8 `create_shader_state`, the two bindings, `bind_shader_state`, `set_global_constants`
| | |
|---|---|
| table | `MGPipeIsCompositeShaderSlot(slot)` routes to `CompositeShaderCsos[slot − base]`, bounded by the band's width; every other slot to `ShaderCsos[slot]`, bounded by **the band's base** (an ordinary program can never be handed a band slot, so a non-composite slot at or above the base is out of range by definition). A slot at or above `kMGPipeShaderCsoSlotLimit` → Fatal naming `kMGPipeMaxShaderCsoSlots`. **The server never learns a handle is a composite**; the split is two functions and nothing else branches on it. |
| create | fresh/recycled → record starts over, `Serial = 0`; re-issue on a live identity → `++Serial` **and the default uniform block is dropped** (image cleared, version back to the `~0u` sentinel, `++GlobalConstantsSerial`), because a relink replaces the layout the block was sized to. `Desc` stored; the artefacts are **not** stored (in monolith the backend reads the frontend's own archive). |
| create bounds | `link == nullptr || spirv == nullptr` → Fatal ("declares no blobs and carries no artefacts"); `GlobalUboSize > kMGPipeMaxGlobalConstantsBytes` (16 MiB) → Fatal. |
| bind / draw / dispatch | one `ProgramBindingSerial` for the three, `++` per applied call. A **null** handle is legal in all three and means "nothing bound" (and still bumps); a **dead** handle leaves the previous binding untouched and is counted. |
| delete | drops the record whole, keeps `Gen`, and **clears every one of the three bindings that named it** (unlike the unit sets: these are single handles resolved against the record just dropped), bumping `ProgramBindingSerial` only if one was actually cleared. The **second** delete — a composite's other release path — is a counted refusal and moves nothing. |
| `set_global_constants` | on the **program's** record. `Version == ~0u` → Fatal (the backends' never-uploaded sentinel); `Blob.Size != 0 && != Desc.GlobalUboSize` → Fatal; `GlobalUboSize != 0 && bytes == nullptr` → Fatal. Stores `GlobalUboSize` bytes, sets `GlobalConstantsVersion`, `++GlobalConstantsSerial`. `Serial` does not move — a block upload is not a relink. The allocation is bounded **at the create**, so this call can only ever allocate what the create already declared. |
### 2.9 `MGPipeApplierReset` / `MGPipeApplierReleaseObjectRecords`
Unchanged from the contract commit and re-pinned by four cases: the reset clears the two
framebuffer records, the three unit sets and the three program handles and **advances** all five
P4a serials; it does **not** touch texture/renderbuffer resources, sampler CSOs, sampler views
or shader CSOs — nor the `Params`, `ParamsSerial`, `ViewCso` and `PendingUploads` that ride on a
resource record. `ReleaseObjectRecords` is the only teardown scope and advances the serials
again for the same reason.
---
## 3. The verify-only codec round trip (D-H3)
`PipeApply.cpp` includes `<MG_State/GLState/ProgramState/ProgramArtifactsCodec.h>` **inside
`#if MOBILEGL_PIPE_VERIFY`** — the only place the codec is called, and the coupling the
contract header already anticipated ("the verify build is the only place the codec runs, and it
runs from `PipeApply.cpp`"). `PipeApply.h` keeps its two forward declarations and reaches no
frontend header; the include-closure gate's four probes are unaffected (none of them names
`PipeApply.*`).
`PinProgramArchiveRoundTrip(desc, link, spirv)` runs **before the record is stored**, so a lane
that aborts aborts on the record that was wrong:
1. `EncodeProgramArtifacts(link, spirv, encoded)` — empty output for a program that has
artefacts is a fault;
2. `DecodeProgramArtifacts(...)` returning false is a fault;
3. re-encoding the decoded pair and comparing the bytes — a mismatch is a fault (the codec's own
suite reads the members back explicitly; what this adds is that it runs over **every real
program the verify lane links** rather than over one hand-built instance);
4. `decodedLink.program != nullptr` is a fault — the live glslang `TProgram` is the one member
the tables omit, and a decode that reconstructed one would be carrying the compiler front end
across the boundary that exists to keep it on the client side.
The verdict is `MGP_TRIP_WIRE_REPORT` with `MGP_TRIP_WIRE_TAG("PipeVerifyDiffer")`, so a verify
or poison build writes `Fatal{PipeVerifyDiffer} program-archive create_shader_state {slot=…,
gen=…}: …` and aborts — the marker G4 greps the retrace logs for. **Zero cost in push and
pull**: the include, the function and the call site are all inside the verify guard.
Mutation **M41** (making the decode fail) is what proves the pin is live code rather than a
comment.
---
## 4. Deviations, each with its reason
**W1 — `MGPipeApplyResourceSubData` gained a trailing defaulted parameter,
`const MGPSubRegion* regions = nullptr`.** The contract's signature has no tail parameter, and
D-D5 is unimplementable without one: `ResourceSubData` has carried `kVarTail` since P2, the
applier's pending-upload set is `(UnionBox, RegionCount, Regions[])`, and the verify lane's
retain mode compares all three. The parameter is **trailing and defaulted**, so P3a's one call
site (`MG_Impl/Pipe/PipeFill.cpp:705`), every existing case and every other package compile
unchanged. **Package B must pass the tail** when it emits a texture upload; a record that
declares `RegionCount != 0` and passes no tail is refused. This is the only signature change in
the package.
**W2 — four new bounds constants in `PipeApply.h`.** `kMGPipeMaxTextureLevels = 32`,
`kMGPipeMaxPendingUploads = 256`, `kMGPipeMaxPendingUploadRegions = 256`,
`kMGPipeMaxGlobalConstantsBytes = 16 MiB`. Every one of them is a number that arrives inside a
payload and decides how much the applier allocates or how far it indexes; the slot bounds' own
argument ("never allocated by being named; a slot at or above the bound is
`Fatal{ProtocolCorruption}` and never a resize") applies to each unchanged. They are additive
and inside A's own file.
**W3 — `resource_destroy` dispatches to the backend only for a buffer**, and the same is true
of `resource_create` and `resource_respecify`. D-B1 says every non-buffer target "stores and
returns"; the destroy's guard was missing in the first draft of `w1` and
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` found it. The fix is
folded into `86835b50` where it belongs (the branch was rewritten before anything was pushed,
so the four-commit shape and the four exact messages are intact).
**W4 — `set_framebuffer_state` counts no refusal.** The contract's header text lists
"framebuffer" among the families `RefusedObjectCalls` covers. It cannot: D-I2 gives the
framebuffer a handle and no wire lifetime, so this call resolves no record and there is nothing
to refuse. Its only verdict is `Fatal{ProtocolCorruption}` on a malformed record. Recorded here
rather than by weakening D-I3 into a surface-handle refusal, which the brief forbids in as many
words.
**W5 — the P4a records' create/re-issue serial rule differs from
`create_vertex_elements`'s, deliberately.** P3a's vertex-elements record bumps
`ContentSerial` on *every* create including the first ("Serial 0 means never created"). The
three P4a record types follow the **contract header's** rule instead: a fresh or recycled
identity leaves `Serial` at 0 so a fresh backend twin agrees without either side publishing, and
only a re-issue on a live identity counts up. Both statements are in the tree; this package
implements the one written on the P4a records.
**W6 — a re-issued `create_shader_state` clears the default uniform block.** Not stated by the
brief either way. A relink replaces the block's layout, so an image sized to the old one is a
hazard for the consumer and the `~0u` sentinel is exactly the value that says "nothing has been
uploaded for this program". `++GlobalConstantsSerial` announces the clearing so a twin cannot
match what it uploaded before the relink.
**W7 — a respecify clears the record's `PendingUploads`.** Not stated by the brief. The pending
entries are boxes and rects in the coordinate system of a level the respecify has just
redefined; keeping one across a shrink would have Espryt upload past the end of the new store,
and nothing is lost because the frontend entry points that respecify a texture re-mark the
levels they define (`AllocateStorage` then `MarkStorageDirty`).
**W8 — `~/w7/p4a-trees2.log` never contained `REBUILT wire`, and is empty.** The rebuild
nevertheless happened and finished: `~/w7/p4a-wire-submodule.log` (11:24:24) and
`~/w7/p4a-wire-build-{linux,push,verify}-build.log` (11:24:48 / 11:25:12 / 11:25:34) each end on
the last link of a complete build (980, 991, 991 targets), no builder was still running, and a
no-op `cmake --build` over all three returned rc 0 before any edit was made. The package
proceeded on that evidence. **The summary line the orchestration script was to append is the
thing that is missing, not the work** — worth knowing before the next package waits on it.
Those four logs were deleted with the round's own (ID-5); the timestamps and byte counts above
are the record.
---
## 5. What B, C, D, E and F must know
**H1 — `MGPTextureParams::BuiltinSampler` may never be null, and bit 10 can be set while bit 11
is clear.** The contract makes a null built-in sampler `Fatal{ProtocolCorruption}` and this
package implements it. But D-K2's dependency table has **no** "bit 10 requires bit 11", and
says the mirror pair is fine — so a `MOBILEGL_PIPE_PUSH=0x5ff` lane (texture resources on,
samplers off) would emit `set_texture_params` while the sampler CSO family is switched off. If
B/C mint the built-in sampler's handle only from the sampler emitter, that lane aborts on the
first `glTexParameter`. **Either** the handle is minted whenever the texture family emits
(the allocator, not the CSO cache, is what mints it), **or** the integrator adds "bit 10
requires bit 11" to D-K2. This is the one cross-package hazard the package found and cannot fix
from inside `MG_Pipe`.
**Blob size rules, exactly.**
| record | rule |
|---|---|
| `MGPSubData` (buffer) | `Blob.Size` is 0, or exactly `MGPipeSubDataBufferSize(record)`. Anything else is Fatal. |
| `MGPSubData` (texture) | **inert.** No field describes the blob's byte length, so any value is accepted; the destination is bounded by the box and the regions. Leave it 0. |
| `MGPSamplerDesc::Parameters` | 0, or exactly `sizeof(SamplerParameters)` (100). Anything else is Fatal. The value itself travels through the companion pointer, which may never be null. |
| `MGPProgramDesc::Spirv[6]` + `Reflection` | **inert**, all seven. Nothing in the descriptor describes their lengths. Leave them 0 and pass the two artefact pointers; **both** non-null or the record is Fatal. |
| `MGPGlobalConstants::Blob` | 0, or exactly the program's `Desc.GlobalUboSize` as the create declared it. Anything else is Fatal. |
**Unit-set window semantics, exactly.** `Start + Count <= 192` or Fatal. Entries land at
`Start + i`; **entries outside the window are never cleared**, so an emitter that wants a unit
unbound must include it in the window carrying a null handle. `Count == 0` is legal and still
moves the serial. A null handle in any entry is legal. The entry's own `Unit` field is stored
verbatim and never compared against `Start + i` — if the emitter lets the two disagree, nothing
here will say so.
**Serial semantics for D and E.** All five P4a working serials (`FramebufferSerial`,
`SamplerViewsSerial`, `SamplerStatesSerial`, `ShaderImagesSerial`, `ProgramBindingSerial`) are
`MGGen`-class: they **only ever advance**, including across `MGPipeApplierReset` and
`MGPipeApplierReleaseObjectRecords`, so no value can ever recur and a twin may safely memoise
one. The per-record serials (`Serial`, `ParamsSerial`, `GlobalConstantsSerial`) restart with the
record, which is safe because the handle's `Gen` moves with it. **Every serial moves before
anything downstream is told.**
**What D reads, per kind.** `TextureResources[slot]` / `RenderbufferResources[slot]` for the
descriptor, the parameters (`Params` + `ParamsSerial`), the view handle (`ViewCso`) and the
pending uploads; `SamplerCsos[slot].Params`; `SamplerViewCsos[slot].View`;
`ShaderCsos[slot]` **or** `CompositeShaderCsos[slot − kMGPipeShaderCsoCompositeSlotBase]` — a
consumer that resolves a `ShaderCso` handle must use the same band split the applier does, and
`MGPipeIsCompositeShaderSlot` is the one predicate for it. **Espryt consumes and clears a
`PendingUploads` entry only where it actually uploads**; a bail must leave it intact, which is
the whole point of the set being server-side.
**For F.** The package adds **33** ctest names — `ResourceEmit.` +3, `FramebufferEmit.` +4,
`TextureEmit.` +6, `SamplerEmit.` +7, `ImageEmit.` +4, `ProgramEmit.` +6,
`CompositeResolver.` +3 — for 46 added against `~/w7/p4a-before-ctest-names.txt` in total (the
contract's 13 plus these 33). None is removed and every one of them is a visible SKIP in a pull
build, so `ctest -N` stays name-for-name identical between the pull and push trees.
The six suites' `main()` points `MOBILEGL_LOG_FILE_PATH` at a per-pid temp file, because the
refusal cases read the trip wire's line back out of it.
---
## 6. Verification transcript (on `3c07c8c3`, working tree clean)
```
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
--after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change \
--fail-on-added-bytes 0
### Removed (0) _none_ ### Added (0) _none_
### Resized (0) _none_ ### Renamed only (same size) (0) _none_ rc=0
$ python3 scripts/gen_pipe.py --check
gen_pipe: inventory 477 rows: ... 0 UNMAPPED
gen_pipe: generated files are up to date rc=0
$ python3 scripts/gen_pipe.py --self-test
gen_pipe: self-test: 7 negative-control trip(s), positive control OK rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --self-test
dirty-surface self-test: 27 negative controls, all tripped rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ \
--self-test --require-all
include-closure: self-test: 6 negative-control trip(s), parser checks OK
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
[p3a-untouched] the 11 ... functions are byte-identical rc=0
$ cmake --build build-linux -j 12 ok
$ cmake --build build-push -j 12 ok
$ cmake --build build-verify -j 12 ok
$ ctest --test-dir build-linux -L unit -j 12 100% 1668/1668, 0 failed
$ ctest --test-dir build-push -L unit -j 12 100% 1668/1668, 0 failed
$ ctest --test-dir build-verify -L unit -j 12 100% 1668/1668, 0 failed
$ diff <(build-linux names) <(build-push names) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 46 added
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing, unchanged
```
Two failures were found during the round and both were the gates doing their job:
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` (deviation W3, a real
defect in `w1`'s first draft) and one flake of `LogLevel.ProductionBuildKeepsErrorAndWarn` under
`-j 12` (green on re-run and on every subsequent full run; a pre-existing shared-temp-file race
in a suite this package does not touch).
---
## 7. Mutation evidence
**41 mutations, 41 red, measured.** Each was applied to `MobileGL/MG_Pipe/PipeApply.cpp` in
this worktree, the tree rebuilt, the family's suite run, and the file restored from the commit
(the working tree was verified clean before and after; no other worktree was created). The rule
the brief asks for — *for each entry point a case that fails if its body is deleted* — is
therefore measured rather than claimed.
| # | mutation | first case to go red |
|---|---|---|
| M1 | `set_framebuffer_state`: the draw store removed | `FramebufferEmit.ADrawRecordAndAReadRecordAreKeptApartAndBothWritesBoth` |
| M2 | `set_framebuffer_state`: the read store removed | the same |
| M3 | `set_framebuffer_state`: the serial bump removed | the same |
| M4 | `set_framebuffer_state`: the target gate removed | `FramebufferEmit.ATargetOutsideTheThreeBindingsIsRefusedNamingTheRecord` |
| M5 | `set_framebuffer_state`: the draw-buffer gate removed | `FramebufferEmit.ADrawBufferEntryOutsideTheRecordsOwnArrayIsRefusedRatherThanRead` |
| M6 | `resource_create`: every target routed to the buffer table | `ResourceEmit.TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther` |
| M7 | `resource_destroy`: every kind routed to the buffer table | the same |
| M8 | `resource_destroy`: the texture dispatch guard removed | `ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` |
| M9 | `set_texture_params`: the store removed | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
| M10 | `set_texture_params`: the serial bump removed | the same |
| M11 | `set_texture_params`: the null-sampler gate removed | `TextureEmit.ARecordWithNoBuiltinSamplerCsoIsRefusedNamingTheTexture` |
| M12 | `set_texture_params`: the resolver replaced by a silent find (the refusal stops being counted) | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
| M13 | sub-data: the region-containment gate removed | `TextureEmit.TheSubDataValidatorRefusesALevelABoxAndARegionTheRecordCannotDescribe` |
| M14 | sub-data: the level bound removed | the same |
| M15 | sub-data: the encodable-box gate removed | the same |
| M16 | sub-data: the missing-tail gate removed | the same (**SegFault**, §7.1) |
| M17 | pending uploads: the box union removed | `TextureEmit.AnAccumulatedUploadUnionsItsBoxesAndCollapsesToTheBoxWhenARectListCannotDescribeIt` |
| M18 | pending uploads: the box-only collapse removed | the same |
| M19 | pending uploads: the accumulation removed | the same |
| M20 | respecify: the pending-upload clear removed | `TextureEmit.ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces` |
| M21 | `create_sampler_state`: the parameter store removed | `SamplerEmit.ACreateStoresTheParametersByValueAndAReissueOnALiveIdentityCountsUp` |
| M22 | `create_sampler_state`: the re-issue serial bump removed | the same |
| M23 | `create_sampler_state`: the blob-length gate removed | `SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength` |
| M24 | `delete_sampler_state`: the record drop removed | `SamplerEmit.ADeleteDropsTheRecordAndAStaleNoticeIsCountedRatherThanSilentlyDropped` |
| M25 | `create_sampler_view`: the back-pointer write removed | `SamplerEmit.AViewIsReissuedOnTheSameHandleAndKeepsItsTexturesBackPointerInStep` |
| M26 | `delete_sampler_view`: the back-pointer clear removed | the same |
| M27 | the unit sets: the entry copy loop removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
| M28 | the unit sets: the window gate removed | `SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated` |
| M29 | `set_sampler_views`: the serial bump removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
| M30 | `set_shader_images`: the serial bump removed | `ImageEmit.TheImageSetLandsInItsWindowWithEveryFieldTheShaderWasBuiltAgainst` |
| M31 | `create_shader_state`: the descriptor store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
| M32 | `create_shader_state`: the relink block clear removed | the same |
| M33 | `create_shader_state`: the artefact gate removed | `ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram` |
| M34 | `bind_shader_state`: the store removed | `ProgramEmit.TheThreeBindingsFollowTheirOwnHandleAndADeadOneLeavesThePreviousBindingStanding` |
| M35 | `set_draw_program`: the store removed | the same |
| M36 | `set_dispatch_program`: the store removed | the same |
| M37 | `delete_shader_state`: the binding sweep removed | `ProgramEmit.ADeleteDropsTheRecordAndClearsEveryBindingThatNamedIt` |
| M38 | `set_global_constants`: the image store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
| M39 | `set_global_constants`: the sentinel gate removed | `ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused` |
| M40 | the composite band routed into the ordinary table | `CompositeResolver.ACompositeRecordLandsInTheBandsOwnTableAndNeverGrowsTheOrdinaryOne` |
| M41 | **verify build**: the archive decode made to fail | three `ProgramEmit.*` cases, `Subprocess aborted` |
M1-M40 ran in `build-push`; **M41 ran in `build-verify`**, and it is the one that proves the
codec round trip is live code with a gate rather than a comment: with the decode failing, every
`ProgramEmit` case that creates a shader state dies on `Fatal{PipeVerifyDiffer}`.
### 7.1 A note on reading a mutation harness
Two of the forty-one (M16 and M41) kill the test **process** rather than failing an assertion —
M16 dereferences the tail it no longer refuses, M41 aborts inside the verify trip wire — so
`ctest` reports `***Exception: SegFault` and `Subprocess aborted` instead of `(Failed)`. A
harness that greps for `(Failed)` reads both as SURVIVED. They were re-run with the exit code as
the verdict (`rc=8` in both cases) and are red. **Worth knowing for anyone repeating this:
grepping ctest output for `(Failed)` silently under-reports exactly the mutations that matter
most.**
---
## 8. Left undone, and who owns it
- **Every emitter body** and the four `kMGPipeWired*Subsystem` constants — B and C, in their own
headers. Nothing consumes a record until they land.
- **`CompositeResolver.h`** — still not created; wholly C's. This package's
`CompositeResolverTest` cases are the applier's half of the band and are disjoint from C's.
- **`Resolve<Family>SubsystemArm()`**, D-C3's `MaxColorAttachments > 8` refusal, and the D-K2
dependency refusals — backend-side, package D. **H1 above is an input to that work.**
- **The five `MGPipeUnmigratedEmulation` call sites** — D and E.
- **`p4a_untouched_regions.sh`**, `p4a_descriptor_negative_control.sh`, the itest phase-mask
moves and `MagmaPipeArms.h` — package F.
- **The retain-mode comparison of the emitted `(UnionBox, RegionCount, Regions[])`** against the
tracker's pre-clear set (part of G4): the applier's half exists — the pending set is
accumulated and never recomputed — and the tracker's half is the client packages'.