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

462 lines
37 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.
# P3a package B, rework round 2 — the client (`client-v2`)
Branch `p3a/client`, worktree `/home/swung/w7/p3a-client`, **rebased onto `refs/heads/feat/disaggregated`
(`12e6bfcf`, wire v2 + the dev merge)** and then four new commits on top. **Not pushed.**
| step | hash | message (single line, empty body, no attribution) |
|---|---|---|
| b1' | `a6851a26` | *(rebased, unchanged)* `[Feat] (Pipe, State): mint a {slot, gen} handle for every buffer object …` |
| b2' | `13e4b6f4` | *(rebased, unchanged)* `[Feat] (Pipe): push the bound VAO's format, its vertex buffers with an explicit baseInstance …` |
| b3' | `f656620d` | *(rebased, unchanged)* `[Feat] (Pipe): widen the dirty-surface scan to MG_State …` |
| b4' | `5df05545` | *(rebased, ONE conflict resolved by union — §1)* `[Test] (Pipe): pin the buffer and vertex-input emitters …` |
| **r1** | `2da442a7` | `[Fix] (Pipe): stop the tracker's context Reset eating the pending base instance the same call is about to read, and clear it on the validate point's no-context exit too` |
| **r2** | `b6706362` | `[Feat] (Pipe, GLImpl): set the pending base instance from the three glDraw*BaseInstance entry points, through a pull-safe macro beside MGP_FILL` |
| **r3** | `d1f684a7` | `[Fix] (Pipe, State): look the resource handle up on the content paths instead of minting it, publish the bind mask from the two draw-time emitters, pair the destroy with the create's own latch, and state the record-lifetime rule the applier now holds` |
| **r4** | `dfaa8729` | `[Test] (Pipe): pin the base instance across a make-current and both of the validate point's exits, the record surviving one, the draw-time bind mask, the create-destroy pairing latch, and the bind-mask table against literals` |
`git diff --shortstat 12e6bfcf..HEAD` → **15 files changed, 2843 insertions(+), 69 deletions(-)**. The only file
outside C.5's grant is `MG_Impl/GLImpl/Drawing/GL_Drawing.cpp`, **+3 lines, exactly the three ID-10 grants**
(`:662`, `:685`, `:715` — each immediately above the `MGP_FILL` the review named at `:662/:684/:713`).
`MG_Test/Pipe/TrackerTest.cpp` is C.5's "nobody" file, as at `client-v1` (B-DEV-5), and the review's own rework
item 1 names a case in it.
---
## 1. The rebase, and how the conflict was resolved
`git rebase refs/heads/feat/disaggregated` replayed b1-b3 cleanly. **b4 conflicted in
`MG_Test/Pipe/ResourceEmitTest.cpp`, not in `VertexInputEmitTest.cpp`** — the opposite of what the task
predicted, and worth recording:
* `VertexInputEmitTest.cpp` **auto-merged**. Wire's rewrite of the placeholder case (`:67-110`, the two serial
assertions now "moved forward" 43/44 and the two vacuous `…empty()` assertions gone) and B's seven appended
cases do not overlap textually. Nothing was chosen; both sides are present.
* `ResourceEmitTest.cpp` conflicted as one block-vs-block hunk (`<<<<<<<` at :118, `=======` at :1325,
`>>>>>>>` at :1613), because at `39722687` the file held exactly ONE case and both packages appended to that
same point. **Resolved by union, in that order: wire's whole block first, then B's whole block**, keeping
every `#if !MOBILEGL_PIPE_PUSH` / pull-skip arm from both sides (the two use different pull-skip idioms —
wire per-case, B a macro list — and they compose without collision).
**Every test name from both sides survives**, verified by enumerating the resolved file and by `ctest -N`:
```
wire's 17 ACreateMarksTheSlotLiveAndCarriesItsDescriptor, ARespecifyReplacesTheDescriptorAndOnlyAMutation
MovesTheSerial, ADestroyDropsTheRecordAndAStaleGenerationResolvesToNothing, NoResourcePathInThis
PhaseLeavesHostWritesLive, TheSubDataRangeEncodingRefusesExactlyAtItsTwoBounds, EveryResourceCall
DispatchesByHandleThroughTheInstalledTableOnly, MapPersistentCountsEveryAttemptWhetherItMintsOr
Declines, AWriteOutsideTheDeclaredStorageIsRefusedNamingTheResource, TheObjectRecordsSurviveAMake
CurrentAndOnlyTheWorkingStateIsReset, ACallOnARecordTheApplierDoesNotHaveIsCountedRatherThan
SilentlyDropped, AVertexElementsBlobRoundTripsAndAShrinkLeavesNothingOfTheOneBeforeIt, AVertex
ElementsRecordThatDoesNotDescribeItsOwnBlobIsRefusedNamingIt, TheVertexBufferWindowIsBoundedAndIts
EntriesLandWhereItSays, SetIndexBufferMovesOnlyItsOwnSerialAndTheBindingFollowsTheHandle, Every
ContentCallsOwnBoundsGateRefusesAndNamesTheResource, TheLiveHostWritesWireFiresOnTheCallA
PersistentMapProducerWouldSetItOn, ASlotOutsideTheRecordTablesBoundIsRefusedRatherThanAllocated
B's 4 EveryBufferTargetSetsItsBindMaskBit, ABindMaskBitIsStickyAcrossARespecifyThatDoesNotRebind,
ADestroyedBufferReleasesItsSlotAndAStaleHandleResolvesToNothing,
AWholeBufferSubDataBeyondTheRecordBoundIsSplitIntoContiguousRecords
c0's 1 TheResourceOpTableIsUnregisteredUntilABackendInstallsOne (common prefix, never in the conflict)
```
One mechanical consequence of the union was carried into b4' itself: `MGPipeBuildSubDataRecord` gained a
parameter in r3, so the splitter case's call at `ResourceEmitTest.cpp:1574` passes it (r3, not b4').
**`feat/disaggregated` moved again while this round ran**, to `b9eaa474` — two version bumps
(`42d43af2` the plugin version to 26.09, `b9eaa474` `CoreVersion` to 26.9). Neither touches a file this
package edits, so the second rebase is a fast-forward with no conflict; every reading below was taken against
`12e6bfcf`, which is the tree the task named and the tree `~/w7/p3a-before-libMobileGL.so` was captured at
(`5cb826b0`, its ancestor). A `CoreVersion` bump does move `.rodata`, so **G1 must be re-taken with a baseline
re-captured at `b9eaa474`** if the integrator lands those two underneath rather than on top.
**A second consequence of the rebase, taken in r4:** `MG_Test/Pipe/TrackerTest.cpp`'s
`ResetTheServerSideSingletons()` (`:250`) now also calls `MGPipeApplierReleaseObjectRecords()` and
`MGPipeVertexInputEmitterInstance().Reset()/ResetCounters()`. Wire's §6 item 2 requires the first
(`MGPipeApplierReset` no longer empties the applier); the second is B's own (the emitter's latches describe an
applier that is about to be emptied). Nothing in that fixture asserted `Resources.empty()`, so this is
robustness for a by-hand run rather than a repair.
---
## 2. Per-finding disposition
### 2.1 Critical
| finding | disposition | where |
|---|---|---|
| **B-C1** `Reset()` zeroes the pending base instance the same call is about to read | **FIXED, one line deleted** — `Tracker.h`'s `Reset()` (`:378-396`) no longer clears `m_pendingBaseInstance`, with the reason written above it (`:368-377`): everything else `Reset()` clears is a latch describing what the server was told; this one is **this call's argument**, written one statement before `MGP_FILL` and not yet read. Both verb-scoped clears are kept. | `Tracker.h:368-396` |
| **B-C2** no re-publication path for resource records after `MGPipeApplierReset()` | **RESOLVED PER ID-12, and the claim replaced by the rule** — no re-publication is added and none may be; `ResourceTracker.h:471-492` now states the actual rule in place of "absence as policy" (below). | `ResourceTracker.h:471-493` |
**B-C1's second half (the review's rework item 1, and B-M1's hole).** The review asked to *"move
`PipeFill.cpp:1446`'s clear above the `ctx == nullptr` return at `:1371`, or record why not"*. Moving it there
would clear the value **before** `EmitVertexBuffers` reads it, which is the bug in the other direction. What
landed instead is the same guarantee on that exit only: `PipeFill.cpp:1440-1449` clears the pending value on
the no-live-context early return, so the property *"consumed by exactly the verb whose entry point set it, and
0 at every other `Update`"* holds on **both** of `MGPipeValidateForVerb`'s exits. That is now the whole
production guarantee, and both the tracker's accessor comment (`Tracker.h:447-452`) and `MGPipeLeaveVerb`'s
(`PipeFill.cpp:849-860`) say so in those words: **no GL entry point calls `MGPipeLeaveVerb`** — `grep` finds
`MG_Test/ScopedPipeVerb.h` and `MG_Test/Pipe/TrackerTest.cpp` and nothing else — so `client-v1` §4 B-DEV-3's
*"neither of them relies on the other being called"* was wrong and is withdrawn. The clear this package relies
on is `PipeFill.cpp:1527`'s, at the end of step 3.
**B-C2, the rule as it now reads** (`ResourceTracker.h:471-492`, beside `ResetForTest`, replacing
*"Never called by the library: a context change does not invalidate a handle"*):
> A buffer handle and the applier record it names are **share-group object state**. A GL object lives in a
> share group, not in a context, so a make-current changes neither. `MGPipeApplierReset()` is a make-current
> and deliberately keeps its `Resources` / `VertexElementsCsos`; the **only** things that drop a record are the
> object's own death signal — `resource_destroy`, which `~BufferObject` raises through
> `MGPipeEmitResourceDestroyAndFree`, and `delete_vertex_elements` — and
> `MGPipeApplierReleaseObjectRecords()`, which is the served context's teardown and is deliberately wired to
> nothing in the monolith. So this tracker needs no re-publication path on a fresh context **and must not have
> one**: re-emitting `resource_create` for a record the applier still holds would move its `Serial` for
> nothing. What the client owes instead is the destroy, which `~BufferObject` already emits in the fixed
> emit-then-free order (D-L).
The one asymmetry the review pointed at is now explained rather than repeated: the vertex-input emitter's
`Reset()` **stays** in the `FreshlyPrimed` arm, and `PipeFill.cpp:1484-1492` no longer says it is there
"because the applier's records were dropped" (they are not). It is there because the emitter's *other* latch,
`m_boundHandle`, mirrors `MGPipeApplierState::BoundVertexElements`, which `MGPipeApplierReset` **does** clear —
without the reset the bind after a make-current would be suppressed as unchanged and the server would draw with
no vertex elements bound. Re-creating an unchanged configuration alongside it is a bounded over-fire; a dropped
bind is not.
Pinned by `ResourceEmit.ABufferCreatedBeforeAMakeCurrentStillLandsItsSubDataAfterOne`
(`ResourceEmitTest.cpp:1686`), which is the client-side half of wire's applier-side case: a **real
`BufferObject`** created and respecified under ctxA, then `MGPipeApplierReset()` + a fresh `GLContext`, then a
real `glBufferSubData` — asserting the record is still `Live`, that the serial moved, that
`RefusedResourceCalls == 0`, and that `CreateCount() == 1` (i.e. the client did **not** grow a re-publication
path).
### 2.2 Major
| finding | disposition | where |
|---|---|---|
| **B-M1** the three `MGPipeSetPendingBaseInstance` call sites | **LANDED (ID-10)**, plus the `MGPipeLeaveVerb` correction above | `GL_Drawing.cpp:662, :685, :715`; `PipeFill.h:114-124` |
| **B-M2** `Acquire` mutating the global slot allocator on the off-thread `SubData` path | **FIXED — the mint stays on the GL thread at creation only**; all five content emitters now look the handle up | `PipeFill.cpp:581-596, :649, :670, :691, :705, :727` |
| **B-M3** `hostBytes` base-vs-base+offset | **NOT B'S** — handed on verbatim, §5 | — |
| **B-M4** the sampled `BindMask`'s DSA hole, and the C.1 misquotation | **FIXED both halves**, by the primary mechanism the review named | `VertexInputEmit.h:219, :267`; `ResourceTracker.h:363-408, :516-522` |
| **B-M5** the absent `UnmapPersistent` producer | **RECORDED, with the reason, beside the `MapPersistent` emitter** | `PipeFill.cpp:718-726` |
**B-M2.** Which of the two options the review allowed: **"make the mint happen on the GL thread at creation
only."** It already did — `MGPipeMintResourceHandle` is called unconditionally from the `BufferObject`
constructor — so on every content path the handle exists and a lookup is not merely safe but strictly correct.
`MGPipeEmitResource{SubData,FlushRange,Readback}`, `MGPipeEmitBufferSubDataResident` and
`MGPipeEmitMapPersistent` now go through one helper, `ContentHandleFor` (`PipeFill.cpp:581-596`), which calls
`MGPipeResourceTracker::Find` (const; no free-list pop, no map insert, no `m_bySlot.resize`) and answers a null
handle with `MGLOG_E_ONCE` naming the call and the GL buffer, then returns — rather than handing
`kMGPipeNullHandle` to the applier, which would count as a refusal with no way back to the cause.
`MGPipeEmitMapPersistent` returns `nullptr` on that path, which every one of its three call sites already
treats as "the backend declined" (`BufferObject.cpp:600-606`, `:650-658`). `Acquire` now survives in exactly
two places, both GL-thread by construction: the constructor's mint, and create/respecify.
**B-M4(a), the record corrected.** `client-v1` §4 B-DEV-2 said the bind entry points are *"`GL_Buffer.cpp`'s,
which C.5 assigns to no package and **C.1 does not list for this one**"*. That last clause is **false**:
`BRIEF-P3A.md:1130` lists `MobileGL/MG_State/GLState/BufferState/BufferState.{h,cpp}` for this package with
the note *"the sticky `everBoundAs` mask's bump points at the buffer bind entry points (D-A3), all
`#if MOBILEGL_PIPE_PUSH`"*, and C.5 gives B `MG_State/GLState/BufferState/**`. What is true is that the brief
pointed at a file that turns out not to contain the entry points: `BufferState` only *vends*
`BindingSlot<BufferObject>&` / `BindingSlotRange1D&`, and the `.Bind()` calls are `GL_Buffer.cpp`'s
(`BindBuffer_State`, `BindBufferBase_State`, `BindBufferRange_State`), which C.5 assigns to nobody. The
substance of the deviation survives; the sentence did not, and the corrected version is now written at
`ResourceTracker.h:376-386`.
**B-M4(b), the hole closed at the place that matters.** The real widening is a **transient** bind, and the DSA
idiom makes it the common case. `MGPipeVertexInputEmitter::EmitVertexBuffers` and `EmitIndexBuffer` already
resolve, at every draw, exactly the attribute buffers and the element-slot buffer, so both now call
`MGPipeResourceTrackerInstance().NoteBoundAs(handle, BufferTarget::Vertex | ::Index)`
(`VertexInputEmit.h:219`, `:267`). `NoteBoundAs` (`ResourceTracker.h:363-374`) grows the table rather than
dropping the note, and is GL-thread by construction (the validate point). **Any buffer ever drawn from carries
its `ARRAY_BUFFER` / `ELEMENT_ARRAY` bit for the rest of its life**, whether or not it was bound at a storage
op. `ResourceEmit.ADrawTimeIndexBindingPublishesElementArrayEvenWhenTheRespecifyCannotSeeIt`
(`ResourceEmitTest.cpp:1729`) drives exactly the review's sequence, with a negative control first (a respecify
with nothing bound publishes an empty mask), and goes red with the two calls removed (§4 M2).
**B-M4(b), the half NOT taken, and why.** The review also asked for `RefreshBindMask` from the other four
resource emitters. It is **not** taken, and the reason is B-M2's: `RefreshBindMask` walks the whole context's
binding state and writes the tracker, and one of those emitters (`resource_subdata`) is on the path D-A2
preserves as reachable **off the render thread**. Extra sampling can only widen a sticky union, but not at the
price of a context-wide read from the wrong thread — fixing one thread-safety finding by creating a larger one
is not a trade this package will make. The reasoning is written at `ResourceTracker.h:400-408`. With
`NoteBoundAs` in place the residue is strictly smaller than what the review's version would have left: a buffer
that is bound, **never drawn from**, and never re-specified afterwards. That is the P8 `GL_Buffer.cpp` item,
unchanged, and it is now the only thing on the list.
**B-M4 secondary, `BindEpoch`.** The sentence the review asked for is at `ResourceTracker.h:516-522`: the epoch
does not see the 84×4 indexed binding points, and that is sound **only** because `BindBufferBase_State` /
`BindBufferRange_State` also bind the generic slot (`GL_Buffer.cpp:1531`); if that stops being true,
`CONSTANT` / `SHADER_BUFFER` / `ATOMIC` / `STREAM_OUTPUT` start being missed silently, and the repair is to
fold `GetTouchedBufferBindingPointCount` into the epoch.
**B-M5.** Recorded, with the reason, at `PipeFill.cpp:718-726`: `BufferBackendOps` has seven hooks and none is
an unmap; `PipeResource::ReleasePersistentMap()` tells the backend nothing today and it learns from the
`Respecify` that follows; emitting `unmap_persistent` would be **new behaviour**, which D-J forbids. So the
client emits none, deliberately, and the applier's `RefusedResourceCalls` stays at 0 for it. The producer lands
with the phase that gives the backend an unmap hook.
### 2.3 Minors
| # | disposition | where |
|---|---|---|
| m1 | **taken** — `MGPipePendingBaseInstance()` now has a caller: `TrackerShippedEmitter.ABaseInstancedDrawAfterAMakeCurrentPublishesItsOwnBaseInstance` asserts on it three times (the setter took, the value was consumed, the no-context exit cleared it). Its declaration comment names that case. | `PipeFill.h:72-74`; `TrackerTest.cpp:862` |
| m2 | **taken, both directions** — `MOBILEGL_ASSERT(bindingIndex < 256)` and `attrib.Size in [0,255]` before the two `Uint8` narrowings, and `MOBILEGL_ASSERT(attrib.Stride >= 0)` before the signed→unsigned one, each with the failure it prevents named (binding 256 wrapping to 0; a negative stride arriving as a ~4 GiB fetch distance) | `VertexInputEmit.h:83-90`, `:224-226` |
| m3 | **taken** — `SourceIsVerbatimLevelShadow` is a **parameter** of `MGPipeBuildSubDataRecord`, `true` on `resource_subdata` (the client's own shadow) and `false` on `buffer_subdata_resident` (the application's staging store, or `FillSubData`'s locally expanded pattern) | `ResourceTracker.h:212-233`; `PipeFill.cpp:656`, `:678` |
| m4 | **taken** — both walk lambdas now `if (!MGPipeBuildSubDataRecord(...)) return;` rather than discarding the `Bool`, with the comment saying the pre-pass makes it unreachable today | `PipeFill.cpp:654-658`, `:675-680` |
| m5 | **taken** — `MGPipeClientOnGpuWritten` asserts the announced shape (exactly one range, non-null) and returns on `rangeCount == 0` rather than marking a whole buffer written; the resolve-to-null arm is now as loud as its sibling | `ResourceTracker.h:594-615` |
| m6 | **taken** — a `LiteralBindMaskFor` oracle spelled as raw bit positions read off `MGPipeTypes.h`'s documented order (no `default:` arm, so a new `BufferTarget` is a build break in both places); the emitted mask is compared to the **literal**, the table is compared to the literal for the bindable targets, and a second loop compares the table to the literal for **all 15** enumerators | `ResourceEmitTest.cpp:1417-1462`, `:1484-1490`, `:1505-1512` |
| m7 | **NOT taken** — §6 | — |
| m8 | **taken** — the `.def` row now says the publisher is the backend's (`Managers.cpp`'s `OnFrontendStateObjectDestroyed` consumer, package espryt), and that until it lands the row states the design and not the tree | `DirtySurface.def:295-298` |
| m9 | **taken** — the bit-7/bit-8 coupling is stated where an operator reads the constant: bit 8 without bit 7 sends handles the server cannot resolve and every such call lands in `RefusedResourceCalls`; neither `0x1ff` nor `0x7f` is in that arm | `PipeFill.cpp:978-988` |
| m10 | **taken** — a store of ≥ 4 GiB is `MGLOG_E_ONCE` + `MOBILEGL_ASSERT` naming the buffer and the size, with the reason (a silent narrowing makes the applier's range gate report `Fatal{ProtocolCorruption}` for a corruption that is really a truncation here); the 32-bit `Width` is the contract's, so the value is still narrowed after the line | `ResourceTracker.h:174-190` |
| m11 | **settled, and it agrees with wire** — wire's ONE Blob rule (0 = not declared; non-zero must be exact) makes filling optional. B **fills it, exactly**: `Blob.Seg = kMGHostSpanSegNone`, `Blob.Size` = the piece's own byte length, which is precisely what `SubDataBoxFault`'s `!= 0 && != MGPipeSubDataBufferSize` gate checks. The rule and the choice are written at the builder. | `ResourceTracker.h:218-224` |
| m12 | **taken** — `MGPipeResourceTracker::Entry` gains `Published`, set at the create (`NotePublished`) and read at the destroy (`WasPublished`); `MGPipeEmitResourceDestroyAndFree` now **returns** whether the destroy went out and `~BufferObject` uses that answer instead of asking `MGPipeResourceSubsystemEnabled()` a second time. That closes both directions: a live applier record on a slot about to be re-handed-out, and a legacy backend object nobody releases. | `ResourceTracker.h:328-352`, `:505`; `PipeFill.cpp:623-626`, `:745-762`; `PipeMutation.h:116-125`; `BufferObject.cpp:55-60` |
---
## 3. What changed in the deviations `client-v1` declared
Only two of the nine move; the rest stand as the review accepted them.
* **B-DEV-2 (sampled `BindMask`)** — the C.1 citation is corrected (§2.2 B-M4(a)), the hole is re-described as
the *transient* bind rather than "a bind after the last resource emission", and the fix for the two bits
anything keys on is now **in this package** rather than handed on. What is handed on is smaller and stated:
the three `GL_Buffer.cpp` binders, for the seven bits nothing keys on yet.
* **B-DEV-3 (bit 9's shutter)** — the mechanism is unchanged and still correct; the claim that the two clears
are independent is **withdrawn** (§2.1). There is one production clear, on two exits.
* **B-DEV-1, -4, -5, -6, -7, -8, -9** — unchanged. B-DEV-7's coordination item (`kMGPipeResourceTargetBuffer
== 0`) is still open for one look from `espryt`; nothing in `wire-v2` contradicts it, and
`ResourceEmit.EveryBufferTargetSetsItsBindMaskBit` asserts `created.Target == 0` on every target.
Two **new** deviations this round:
**R1 — the three call sites go through a macro, `MGP_SET_BASE_INSTANCE`, not a bare call.** The review's line
was `MG_Pipe::MGPipeSetPendingBaseInstance(baseinstance);` and warned to *"check that when the lines land"*.
Checked: `PipeFill.h`'s whole declaration block is inside `#if MOBILEGL_PIPE_PUSH` (`:16-113`), so a bare call
does not merely fail to **link** in a pull build, it fails to **compile**. The macro
(`PipeFill.h:114-124`, `((void)0)` in the pull arm) is the shape `MGP_FILL` already has, one line per site,
carrying the **raw** `baseinstance`. G1 is 0/0/0/0, which is the proof the pull text did not move.
**R2 — `RefreshBindMask` is deliberately not called from the content emitters** (§2.2 B-M4(b)). This is the one
place this round declines a reviewer instruction, and the reason is another of the review's own findings.
---
## 4. Mutation evidence — 4 mutations, 4 reds, measured
Each applied to the rebased tree, `build-push` rebuilt, the suites run, the file restored with
`git checkout --` (the tree was verified clean after every one).
| # | mutation | verdict | case that went red |
|---|---|---|---|
| M1 | **B-C1 reverted**: `m_pendingBaseInstance = 0;` put back into `Tracker.h`'s `Reset()` | **RED**, 2/2 failed | `TrackerWalk.ABaseInstanceSurvivesTheFirstWalkOnAFreshContext` **and** `TrackerShippedEmitter.ABaseInstancedDrawAfterAMakeCurrentPublishesItsOwnBaseInstance` |
| M2 | **B-M4 reverted**: both `NoteBoundAs` calls commented out of `VertexInputEmit.h` | **RED**, 1/1 failed | `ResourceEmit.ADrawTimeIndexBindingPublishesElementArrayEvenWhenTheRespecifyCannotSeeIt` |
| M3 | **B-M1's hole reopened**: the clear removed from the validate point's no-live-context exit | **RED**, 1/1 failed | `TrackerShippedEmitter.ABaseInstancedDrawAfterAMakeCurrentPublishesItsOwnBaseInstance` |
| M4 | **m12 reverted**: the destroy gated on `MGPipeResourceSubsystemEnabled()` again instead of the create's latch | **RED**, 1/1 failed | `ResourceEmit.ADestroyFollowsTheCreateEvenIfTheOpTableWasUnregisteredMeanwhile` |
No mutation survived. The restored tree is `100% tests passed, 0 failed out of 70` on
`ctest -R 'ResourceEmit\.|VertexInputEmit\.|Tracker'`.
---
## 5. For the integrator and for package C (espryt)
1. **B-M3, unchanged and still live — `hostBytes` is `shadow + offset` on two of the three content calls.**
`espryt-v1.md` §1 e1 latches *"the client's shadow base"*; the client sends, per D-A2 and correctly:
* `MGPipeEmitResourceRespecify` → `buffer.MappedData()` — the **true base** (`PipeFill.cpp:640`);
* `MGPipeEmitResourceSubData` → `base + at` where `base = buffer.MappedData()` — **base + offset**
(`PipeFill.cpp:650`, `:659`);
* `MGPipeEmitResourceFlushRange` → `buffer.MappedData() + offset` — **base + offset**
(`PipeFill.cpp:701`);
* `MGPipeEmitBufferSubDataResident` → the application's staging store, which `espryt-v1.md` D10 already and
correctly refuses to latch.
So after any `glBufferSubData(b, 4096, …)` Espryt's `hostBytes` is `shadow + 4096`, and the next pool reseed
or full re-upload reads 4096 bytes past the store's end. **B is brief-conformant and does not change**;
espryt's latch is the side that moves — `hostBytes = bytes - MGPipeSubDataBufferOffset(record)` /
`bytes - record.Offset`, or drop the latch on the two ranged calls and keep it only on respecify.
`espryt-review-v1.md`'s C-2 is a **different** defect (a cached base dangling after adoption/resize) and its
fix does not touch this one. The shape that catches it is a `StreamedArenaScenario` recycle plus a
`CrossFrameBufferScenario` flush at a non-zero offset.
2. **`kMGPipeResourceTargetBuffer == 0`** (B-DEV-7) still wants one confirming look from espryt.
3. **`MGPVertexBuffer::BindingIndex` is the attribute index for every entry** (`VertexInputEmit.h:222`), which
is what `espryt-v1.md` §6 item 14 says `VertexBufferForBindingIndex`'s fast path assumes. Confirmed.
4. **`OnGpuWritten` is announced as one `kMGPipeWholeBuffer` range** — the client now asserts that shape rather
than ignoring it (m5). A backend that announces zero ranges gets nothing marked, deliberately.
5. **The resident dispatch gate** (wire §6 item 7) is already the member, not the subsystem:
`BufferObject::LandBytesIntoResidentStore` asks `MGPipeResourceOpsHaveSubDataResident()`
(`BufferObject.cpp:435`), which reads `ops->SubDataResident != nullptr`.
6. **`map-persistent-roundtrips` is still 0 on this tree** and becomes non-zero the moment espryt registers the
table (G10). `MOBILEGL_PIPE_PUSH=0x7f` vs `0x1ff` is still emission-only (G12) until then.
7. **The three `MGP_SET_BASE_INSTANCE` sites are now the gate ID-10 describes**: espryt's
`DrawParameters` / `VertexAttribBinding` base-instance scenarios must be red without them and green with
them, and the integrator checks both directions once on the finished tree. Package C may now delete
`g_pendingFetchBaseInstance` without losing the emulation's input.
---
## 6. Left undone, and what it costs
1. **m7 — `set_index_buffer` has no content suppressor.** Bit 10's shutter mixes `vaoIdentity`, which includes
`GetConfigVersion()`, so any VAO reconfiguration re-emits an identical `MGPIndexBuffer` and moves the
applier's `IndexBufferSerial` — the memo espryt's `m_syncedIndexSerial` early-out reads. **Correctness is
fine (over-fire only); the cost is a measurable per-draw one for a reconfiguring app.** Not taken because
latching `m_lastIndex` changes emission counts that `TrackerWalk.TheIndexBufferBit*` and espryt's memo cases
both observe, and ID-6 makes performance a recorded item rather than a gated one. The fix is a latch plus a
skip and belongs with the phase that measures it.
2. **The `GL_Buffer.cpp` bind hook** — three one-line `NoteBoundAs` calls in `BindBuffer_State`,
`BindBufferBase_State`, `BindBufferRange_State`, for the seven `BindMask` bits nothing keys on yet. Now the
*only* residue of B-DEV-2: a buffer bound, never drawn from, and never re-specified afterwards. Still
nobody's file; still invisible in monolith.
3. **`delete_vertex_elements` and the VAO CSO slot free** (B-DEV-8) — package C's, by the ownership split. On
this tree VAO CSO slots are never freed.
4. **`RefreshBindMask` from the content emitters** (R2) — declined with a reason, not forgotten.
5. **The `MOBILEGL_PIPE_POISON_OMIT` caselist sweep** — declared off the critical path; the `FillPoints.def`
comment still says the verdict lands with the G15 caselist run and every row stays.
6. **The review's §7 items that are the integrator's, not a package's**: the `Blob.Size` off-by-one negative
control on the merged tree (§7.3), and the `TheXIsActuallyArmedWhenTheEnvironmentPinsItOn` family's race on
shared log files under concurrent load (`MG_IntegrationTest/CMakeLists.txt:1040`). This round's lanes were
run **serially, with no competing load**, and were clean first time — see §7.
The review's §7.2 (mirror-image applier assertions on every case) is **partly** discharged: the new cases all
read `MGPipeApplier()` directly (`VertexFetchBaseInstance`, `VertexBufferCount`, `Resources[slot].Live/Serial/
Desc.Width`, `RefusedResourceCalls`), and wire's own nine cases do the same from the other side. Turning
`EveryAttributeFieldSurvivesTheWireConversion` into a full round trip through
`MGPipeVertexElementsRecord::Attributes[]` is **not** done: G7's negative control is defined over the
conversion, and adding a second oracle to the same case would make a scripted field-drop fail twice for one
reason. It is a second `EXPECT` beside an existing one whenever the integrator wants it.
---
## 7. Verification transcript
All in `/home/swung/w7/p3a-client` at `dfaa8729`, `CCACHE_BASEDIR=/home/swung/w7`, on the rebased tree.
**G1 — pull build symbol identity, against `~/w7/p3a-before-libMobileGL.so` (the `5cb826b0` baseline, ID-9)**
```
python3 scripts/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: before: /home/swung/w7/p3a-before-libMobileGL.so (19114360 bytes on disk)
symbol-report: after : build-linux/libMobileGL.so (19114360 bytes on disk)
symbol-report: .text 10806323 -> 10806323 (+0, +0.000%) .data +0 .bss +0 .rodata +0
symbol-report: Total 17226471 -> 17226471 (+0)
symbol-report: 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
symbol-report: 27072 -> 27072 normalised names, 27072 unchanged
```
**0 / 0 / 0 / 0, and the two libraries are byte-identical in size.** `~/w7/p3a-before-head.txt` reads
`5cb826b01e00dd28a6e62c1aab65e3edc50e5758`, which is this branch's base, so the baseline problem `client-v1`
and `wire-v2` both raised is closed by the rebase. P3a's admitted-resize set stays empty.
**Three builds** (`cmake --build <dir> -j 24`): `build-linux` rc **0**, `build-push` rc **0**,
`build-verify` rc **0**.
**Three unit runs** (`ctest --test-dir <dir> -L unit -j 12 --no-tests=error`):
```
build-linux rc=0 100% tests passed, 0 failed out of 1617
build-push rc=0 100% tests passed, 0 failed out of 1617
build-verify rc=0 100% tests passed, 0 failed out of 1617
```
(1599 at `12e6bfcf` + b4's 13 + this round's 5.)
**Names — G2's name half, and G14**
```
ctest -N: build-linux 2537, build-push 2537, build-verify 3369
diff <linux names> <push names> -> EMPTY (rc 0)
comm -23 <p3a-before-ctest-names.txt> <linux names> -> 0 removed
comm -13 ... -> 35 added
```
The baseline is `p3a-before-ctest-names.txt`, 2502 names taken at `5cb826b0` (which already carries the
contract's 5). The 35 added are therefore **wire's 17** (all `ResourceEmit.*`), **b4's 13**
(4 `ResourceEmit`, 7 `VertexInputEmit`, 2 `TrackerWalk`) and **this round's 5**
(`ResourceEmit.ABufferCreatedBeforeAMakeCurrentStillLandsItsSubDataAfterOne`,
`ResourceEmit.ADrawTimeIndexBindingPublishesElementArrayEvenWhenTheRespecifyCannotSeeIt`,
`ResourceEmit.ADestroyFollowsTheCreateEvenIfTheOpTableWasUnregisteredMeanwhile`,
`TrackerWalk.ABaseInstanceSurvivesTheFirstWalkOnAFreshContext`,
`TrackerShippedEmitter.ABaseInstancedDrawAfterAMakeCurrentPublishesItsOwnBaseInstance`).
**Nothing removed, in any of the three builds.**
**Generators and closure**
```
python3 scripts/gen_pipe.py --check rc 0 "generated files are up to date"
71 calls, 71 verify payloads,
63 PipeInputs fields (7 sticky, 34 emitted)
inventory 477 rows, 0 UNMAPPED
git diff --exit-code -- MobileGL/MG_Pipe/generated rc 0
python3 scripts/gen_pipe_dirty_surface.py --check rc 0 "75 mutators, all mapped, no stale rows;
45 render-state answers derived and matching;
10 other answers derived; 0 COARSE; 0 UNDECIDED"
python3 scripts/gen_pipe_dirty_surface.py --self-test rc 0 "21 negative controls, all tripped;
positive controls OK"
python3 scripts/check_include_closure.py rc 0 "4 probes, 0 skipped, 0 problem(s)"
mutation-header OK 84 headers, 0 forbidden
python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all rc 0
"6 negative-control trip(s), parser checks OK"
```
(`--compiler clang++-20` does not exist on this host; `clang++` is the substitution the contract and client
packages both recorded.)
**G13 / layering**: `grep -c 'MG_State' MG_Pipe/PipeApply.h` → **0**; `grep -rc 'pGLContext' MG_Backend | grep
-v ':0$'` → empty.
**The four lanes** — run **serially, with no competing load**, which is the protocol `client-v1` established
after chasing the `TheXIsActuallyArmedWhenTheEnvironmentPinsItOn` race. All four green first time, no re-runs:
```
ctest --test-dir build-push -L integration-gpu -j 8 rc 0 100% passed, 0 failed of 920
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8 rc 0 100% passed, 0 failed of 920
MOBILEGL_PIPE_PUSH=0x7f ctest --test-dir build-push -L integration-gpu -j 8 rc 0 100% passed, 0 failed of 920
ctest --test-dir build-verify -L integration-verify -j 4 rc 0 100% passed, 0 failed of 832
```
With the applier bodies real and **no backend registered**, every emission still falls through: nothing
registers `MGPipeResourceOps` anywhere in the tree outside `MG_Test/Pipe/ResourceEmitTest.cpp`, so
`MGPipeResourceSubsystemEnabled()` is false in all three arms and the observable is unchanged. That is what
makes the `0` and `0x7f` arms identical to the default one on this tree, and what makes G12 still an
emission-only A/B until espryt lands.
**The retrace gate, verify-armed** — `MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree
~/w7/p3a-client --lib ~/w7/p3a-client/build-verify/libMobileGL.so --out ~/w7/retrace-out/p3a-client -j 4`:
```
retrace rc=0
PASS MobileGLTraceReplay.minecraft-1.21.4-main-menu.DirectVulkan rc=0 3s ssim=0.997009
PASS MobileGLTraceReplay.minecraft-1.21.4-rd12-odinlite-in-world.DirectGLES rc=0 63s ssim=1.0
PASS MobileGLTraceReplay.minecraft-1.21.4-rd12-odinlite-in-world.DirectVulkan rc=0 79s ssim=0.999991
PASS MobileGLTraceReplay.minecraft-1.21.4-startup.DirectGLES rc=0 1s ssim=1.0
PASS MobileGLTraceReplay.minecraft-1.21.4-startup.DirectVulkan rc=0 1s ssim=1.0
passed 79 / 79; failed: []
grep -l 'Fatal{' ~/w7/retrace-out/p3a-client/*.log -> empty
grep -L 'MGPipe verify:' ~/w7/retrace-out/p3a-client/*.log -> empty (all 79 armed)
ls ~/w7/retrace-out/p3a-client/*.log | wc -l -> 79
```
This is again the strongest single result in the document, and this time it is on a tree where the applier's
bodies are **real**: with the emission live in a verify build, whose compare-at-read re-reads every field from
the live context at every backend read, the whole corpus replays with zero divergence and zero unmigrated
reads on both backends. `~/w7/retrace-out/p3a-client` was deleted afterwards. No
`Fatal{UnmigratedPipeInput,"F@V"}` appeared, so no `FillPoints.def` row was owed and none was added.
**Ownership**: `git diff --stat 12e6bfcf..HEAD` names `MG_Impl/Pipe/{PipeFill.h,PipeFill.cpp,Tracker.h,
ResourceTracker.h,VertexInputEmit.h,SetHashSuppressor.h}`, `MG_Pipe/{PipeMutation.h,DirtySurface.def,
FillPoints.def}`, `MG_State/GLState/BufferState/BufferObject.cpp`, `scripts/gen_pipe_dirty_surface.py`, the
three `MG_Test/Pipe/*.cpp`, and `MG_Impl/GLImpl/Drawing/GL_Drawing.cpp` (**+3 lines, the ID-10 grant**). No
`MG_Backend`. `git status` clean.
---
## 8. Intermediate logs and working state
Deleted at the end of the round: `~/w7/p3a-client2-lanes.log`, `~/w7/p3a-client2-lane-*.log`,
`~/w7/p3a-client2-retrace.log`, `~/w7/client2-lanes-inner.sh`, and `~/w7/retrace-out/p3a-client/`. No mutation
harness worktree was created — every mutation was applied in place and reverted with `git checkout --`.
`git status` in `/home/swung/w7/p3a-client` is clean at `dfaa8729`. The trace fixtures are materialised (real
archives, not LFS pointers) and hidden with `git update-index --assume-unchanged`, which is the state the next
run of the retrace gate needs.