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

226 lines
17 KiB
Markdown

# contract v6 — c0f: the four P4a families require a registered consumer (ID-39)
**Commit `29d51ab9`** on `p4a/c0f`, worktree `~/w7/p4a-c0f`, branched from
`refs/heads/feat/disaggregated` = `17396216` (contract c0..c0e + wire + clientsp v3 + clientfb v2 +
esprytobj v2). One commit, seven files, +570/-11. Not pushed.
```
[Fix] (MG_Pipe, MG_Impl): gate the four P4a families on a backend having registered
MGPipeResourceOps - Magma emitted, the applier accepted, and the acceptance-cleared dirty flags
left its legacy path nothing to upload
```
---
## 1. The defect, restated from the code
P3a's buffers have always had **two** conjuncts in their client gate — `PipeFill.cpp:612`
`MGPipeResourceSubsystemEnabled()` is `bit 7 AND MGPipeGetResourceOps() != nullptr` — and the
comment at `PipeFill.cpp:656` (now ~:700) spells out why the second one is load-bearing.
P4a's four families had only **one and a half**: `FamilyIsLive(subsystem, wired)` was the
operator's `MOBILEGL_PIPE_PUSH` bit AND the family's `kMGPipeWired*Subsystem` constant, with no
per-backend half at all. DirectVulkan (Magma) registers no `MGPipeResourceOps`
(`Managers.cpp:2556` is DirectGLES-only) and has none of P4a's twins, so with
`kMGPipeWiredTextureSubsystem = 1`:
1. the client emitted `resource_create` / `resource_respecify` / `resource_subdata` /
`set_texture_params` for every texture;
2. the applier **accepted** every one of them (a non-buffer resource row is stored and returned —
`MGPipeApplyResourceCreate`'s own comment says so);
3. the emitter cleared the level's per-level dirty flags on that acceptance (D-D5 as amended by
ID-18 M3);
4. Magma's legacy pull path then read `IsStorageDirty` and found nothing to upload.
66 texture-upload-shaped DirectVulkan integration-gpu cases red on the push build at the default
mask, pull build 966/966 green. This is B's own finding (1) from ID-35, applied to Magma.
---
## 2. (a) The client gate — `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}`
| file:line | what |
|---|---|
| `PipeFill.cpp:882` | `kMGPipeP4aFamilySubsystems` = `Framebuffer | TextureResources | Samplers | Programs` (bits 9/10/11/12). Deliberately **not** `kMGPipeSubsystemsMigratedAtP4a` (0x1fff, every bit through P4a) — the rule belongs to the four families this phase adds and to no earlier one. |
| `PipeFill.cpp:920` | `Bool P4aFamilyHasItsConsumer(Uint64 subsystem)` → `(subsystem & kMGPipeP4aFamilySubsystems) == 0 \|\| MGPipeGetResourceOps() != nullptr`. A P2/P3a bit answers `true` unconditionally, so nothing that emits today changes. |
| `PipeFill.cpp:933-935` | `FamilyIsLive` gains the conjunct. This is the predicate **every** P4a birth hook resolves through (`MGPipeEmitTextureResourceCreate/Respecify`, `MGPipeEmitTextureParams`, `MGPipeNoteTextureLevelDirty`, `MGPipeEmitRenderbufferResourceCreate/Respecify`, `MGPipeEmitSamplerCsoCreate`, `MGPipeEmitSamplerViewCreate`, `MGPipeEmitShaderCsoCreate` — nine hooks, ~:1105-1170). |
| `PipeFill.cpp:2257` | `wants()` gains it as a fifth condition, so the seven walk-side emissions (`EmitFramebufferState`, `EmitShaderState`, `EmitSamplerViews`, `EmitSamplerStates`, `EmitShaderImages`, `EmitGlobalConstants`) are inert too. |
| `PipeFill.cpp:2329` | the `DrainTextureSubData` gate — the one with no dirty bit over it — gains it. This is the path whose acceptance clears the level flags. |
| `PipeFill.cpp:2408` | the residual fill's `supplied` conjunction gains it: "supplied" means *a call went out carrying this field*, and with no consumer none did, so withholding the pull would leave the field unfilled at the verb that reads it. (Inert today — `EmittedCallSuppliesTheWholeField` answers `false` for every P4a field; it is forward protection for the first one admitted.) |
| `PipeFill.cpp:1097` / `PipeFill.h:63` | `Bool MGPipeP4aFamilyEmits(Uint64 subsystem, Uint64 wired)` — the gate exported as an observable, returning `FamilyIsLive(...)` itself rather than a second copy. `wired` is a parameter because the constant lives in the family's emit header, which `PipeFill.h` may not include. Unit gate only. |
**The emit headers were not touched.** `MGPipeTextureRecordsReachTheApplier()` and its siblings are
compile-time (`constexpr`) restatements of the wired constant, and
`MGPipeTextureSubsystemEnabled()` / `MGPipeFramebufferSubsystemEnabled()` are B/C's runtime
copies; every path they guard runs *behind* `FamilyIsLive`, or (`RepublishMask`) behind
`MGPipeHandleIsPublished`, which no longer answers true. The single exception is documented in
(b).
**Bits 7 and 8 are untouched.** `MGPipeResourceSubsystemEnabled` and the vertex-input rows read
exactly what they read before.
**The register/unregister window** is the same one P3a lives with (`UnregisterBufferBackendOps`
nulls the table at context teardown, the re-register happens at the next MakeCurrent) and is
closed the same way: an object born in the window latches `Published = false`, and the family's own
self-healing create on the next respecify (`TextureEmit.h:576` / `:709`) publishes it. Written into
the comment at `PipeFill.cpp:914`.
**Make-current does not flap the gate.** `MGPipeApplierReset` explicitly does *not* clear
`g_resourceOps` (`PipeApply.cpp:1121`, and `ResourceEmit.TheResourceOpTableIsUnregisteredUntilA
BackendInstallsOne` pins it); `MGPipeApplierReleaseObjectRecords` does not touch it either and has
no non-test caller in the monolith. So the client's gate and the applier's belt read the same
signal and cannot disagree across a frame.
---
## 3. (b) The applier belt — `MobileGL/MG_Pipe/PipeApply.{h,cpp}`
`PipeApply.cpp:1116` `Bool NoP4aConsumer()` — `g_resourceOps == nullptr` → `++RefusedNoConsumer`,
return true. **Silent by design**: `RefusedResourceCalls` / `RefusedVertexInputCalls` /
`RefusedObjectCalls` each mean "a record named something this applier should have had" and a
non-zero value there is a seam defect; a non-zero value *here* is the designed steady state of a
backend with no P4a twins, so an `MGLOG_E_ONCE` would put an ERROR line in every ordinary Magma
run. The counter is the observable.
**Counter**: `MGPipeApplierState::RefusedNoConsumer` at `PipeApply.h:553`, beside the other three,
zeroed by `MGPipeApplierReset` (`PipeApply.cpp:1152`) like them.
**Fifteen entry points**, each returning `accepted = false` / declining:
| line | entry point | note |
|---|---|---|
| 1590 | `MGPipeApplyResourceCreate` | non-buffer target only — the buffer row is P3a's and its consumer question was already answered by the frontend |
| 1626 | `MGPipeApplyResourceRespecify` | non-buffer target only |
| 1759 | `MGPipeApplyResourceSubData` | the texture half; **the call whose acceptance clears the level flags** |
| 2255 | `MGPipeApplySetFramebufferState` | in front of `RecordAt` — see below |
| 2369 | `MGPipeApplyCreateSamplerState` | |
| 2428 | `MGPipeApplyCreateSamplerView` | |
| 2477 | `MGPipeApplySetTextureParams` | first in the body (it resolves before it validates) |
| 2535 | `MGPipeApplySetSamplerViews` | in front of `ApplyUnitWindow` |
| 2545 | `MGPipeApplyBindSamplerStates` | in front of `ApplyUnitWindow` |
| 2560 | `MGPipeApplySetShaderImages` | in front of `ApplyUnitWindow` |
| 2633 | `MGPipeApplyCreateShaderState` | after the blob rule, the slot bound and the verify round trip |
| 2670 | `MGPipeApplyBindShaderState` | first — the null-handle unbind is behind it too |
| 2727 | `MGPipeApplySetDrawProgram` | first |
| 2742 | `MGPipeApplySetDispatchProgram` | first |
| 2763 | `MGPipeApplySetGlobalConstants` | first (its bounds come out of the resolved program) |
Placement rule, written at `PipeApply.cpp:1108`: **after the record's own shape checks and before
anything moves**, so a malformed record stays `Fatal{ProtocolCorruption}` on every backend — a
trip wire that fires only on some backends is a trip wire nobody can trust. Two documented
exceptions: the three unit-set calls (`ApplyUnitWindow` validates and writes in one step, so the
question has to be asked in front of it), and the five entry points whose first act is a
resolution (asking after would report the designed state as `RefusedObjectCalls`).
**The death paths are deliberately not belted** — `resource_destroy`, `delete_sampler_state`,
`delete_sampler_view`, `delete_shader_state` are idempotent cleanup that must keep working
whatever the registration did, and with no consumer they find no record anyway. Asserted, so a
later commit that adds them has to change that line.
**One known, bounded residue**: for the four create-shaped calls the bound check *is* `RecordAt`,
which grows the table to the slot on its way to answering, so a refused create can leave a zeroed
non-live row behind. It costs nothing where it matters: on a backend with no consumer the client's
gate emits none of these, and the one record that reaches this applier *without* passing that gate
— `set_framebuffer_state`, published by name from `GL_Framebuffer.cpp:650`'s
`PipePublishFramebufferByName`, which calls the framebuffer emitter directly at the fifteen DSA
sites — is declined in front of its `RecordAt`. That direct call is also the reason the belt is not
redundant with the gate.
---
## 4. (c) Tests
| test | file | what it pins |
|---|---|---|
| `TextureEmit.WithNoBackendConsumerTheFamilyGateIsFalseAndNothingReachesTheApplier` | `MG_Test/Pipe/TextureEmitTest.cpp` | the **client** half. All four `MGPipeP4aFamilyEmits` rows false, `kMGPipeSubsystemVertexInput` still true; the handle is still minted but `MGPipeHandleIsPublished` is false, `CreateCount`/`RespecifyCount`/`SubDataCount` 0, `DrainListSize` 0, `TextureResources` empty, **`texture->IsStorageDirty(...)` still true**, and `RefusedNoConsumer == 0` (the *gate*, not the belt, is what stopped it). Second half: with the consumer back, create published, drain list 1, `SubDataCount` 1, `RefusedSubDataCount` 0, flag cleared. |
| `ResourceEmit.EveryP4aFamilyEntryPointDeclinesWhenNoBackendRegisteredTheConsumer` | `MG_Test/Pipe/ResourceEmitTest.cpp` | the **applier** half. All fifteen entry points driven with no table: `RefusedNoConsumer == 15` (the number is the assertion — an entry point added later that forgets the belt fails this line), the other three refusal counters and `StaleFramebufferRecordLookups` all 0, nothing live in any of the five object tables, `FramebufferRecords` empty, the three unit windows 0, the three program bindings null. Then with a table: every one lands, the counter does not move, and the two death paths run uncounted. |
**Fixture change, and why.** The five P4a emit suites and `ResourceEmitTest`'s texture/renderbuffer
case drive the emitter/applier pair as they behave under a backend that *consumes* the records —
the shipped DirectGLES configuration — so they now install the same signal that backend installs:
an empty `static const MGPipeResourceOps` registered in `main()` of `TextureEmitTest.cpp` and
`FramebufferEmitTest.cpp`, and a scoped `ScopedResourceOps` in `ResourceEmitTest.cpp`'s
`TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther`. The table is empty because none
of its hooks is on a non-buffer path (every non-buffer row is stored and returned, never
dispatched), so what the registration changes is the consumer question and nothing else; neither
file constructs a `BufferObject`. The two cases above take it away again
(`ScopedNoResourceOps` / the un-scoped arm). `SamplerEmitTest`, `ProgramEmitTest`, `ImageEmitTest`
and `CompositeResolverTest` needed nothing. `ResourceEmit.TheResourceOpTableIsUnregisteredUntilA
BackendInstallsOne` is unchanged and still asserts `nullptr` at entry.
### Mutations (run, not committed)
| # | mutation | result |
|---|---|---|
| M1 | `FamilyIsLive` drops `&& P4aFamilyHasItsConsumer(subsystem)` | `TextureEmit.WithNoBackendConsumer...` **RED** (1/1 failed). The 54-case DirectVulkan texture subset stayed **green** — because the belt then caught every record, which is exactly the belt's job. |
| M2 | `NoP4aConsumer()` never fires | `ResourceEmit.EveryP4aFamilyEntryPointDeclines...` **RED** (1/1 failed). |
| M3 | the walk-side conjuncts removed (`wants()` + the drain gate), `FamilyIsLive` kept | DirectVulkan **475/475 green** — reported honestly: with the birth hooks gated, the drain list is empty and the walk-side rows clear no client flag, so those two conjuncts are defence in depth (and the `supplied` one is forward protection), not independently lane-proved. Both are kept because ID-39 names them and because a family that later emits from the walk without a birth hook would otherwise be ungated. |
---
## 5. Gate numbers (all on `~/w7/p4a-c0f` @ `29d51ab9`)
| gate | result |
|---|---|
| builds | `build-linux` rc 0, `build-push` rc 0 |
| **G1 `symbol_report --threshold 0`** vs `~/w7/p4a-before-libMobileGL.so` | **0 added / 0 removed / 0 resized / 0 renamed**; `.text 10806323 -> 10806323 (+0, +0.000%)`; 27811 -> 27811 defined symbols |
| **G5 `scripts/p3a_untouched_regions.sh 37da3c3a HEAD`** | **rc 0** — "byte-identical between 37da3c3a and HEAD" |
| `gen_pipe.py --check` | rc 0 — "generated files are up to date" |
| `gen_pipe_dirty_surface.py --check` | rc 0 |
| `gen_pipe_dirty_surface.py --self-test` | rc 0 — 27 negative controls, all tripped |
| `check_include_closure.py --compiler clang++` | rc 0 — 4 probes, 0 skipped, 0 problems |
| `ctest -L unit` build-linux | **100%, 0 failed of 1762** (was 1761; +1, the ResourceEmit case is a visible SKIP in the pull build) |
| `ctest -L unit` build-push | **100%, 0 failed of 1763** (was 1761; +2) |
| **`ctest --test-dir build-push -L integration-gpu -R DirectVulkan -j 8`** | **100% tests passed, 0 failed out of 475** — was 409/475 (66 failed) on the same tree before the fix, measured here as the baseline |
| `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8` | 98%, **8 failed of 491 — the gate's exact eight, unchanged** |
### The DirectGLES eight, unchanged and unchased
Identical set and identical count to `~/w7/p4ag-igpu-push.log` (which reported 74 = 66 DirectVulkan
+ 8 DirectGLES out of 966):
- six `DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.*` (Subprocess aborted) — the 0x1ff
itest pins, package F's;
- `DirectGLES.SampledSetStalenessScenario.AQueuedClearIsMaterialisedWhenASamplerObjectCompletesTheTexture`;
- `DirectGLES.IntegerBorderColorScenario.SamplerParameterIivBorderColourSurvivesToAnIntegerSampler`.
**No DirectGLES case was fixed or broken by c0f**, which is what the design predicts: DirectGLES
registers the table unconditionally at `RegisterBufferBackendOps`, so every predicate answers
exactly what it answered before.
---
## 6. What packages B / C / D / E must know
- **Nothing changes on Espryt.** DirectGLES registers `MGPipeResourceOps` at bring-up,
unconditionally, so `FamilyIsLive`, `wants()`, the drain gate and all fifteen applier entry
points behave exactly as they did at `17396216`. Every existing assumption, counter and lane
number holds.
- **On Magma the client now emits nothing for bits 9/10/11/12.** The legacy pull path runs
untouched, exactly as on a pull build. Do not write a scenario that expects a P4a record to
exist on DirectVulkan.
- **B**: `TextureEmit.h`/`FramebufferEmit.h` are unchanged. Your emitters are simply not called on
a backend without the table; `MGPipeHandleIsPublished` stays false there, so the death helpers
emit nothing and your self-healing creates (`:576` / `:709`) are what recover if a table appears
later. `RepublishMask`'s own `MGPipeTextureSubsystemEnabled()` is now a second, weaker gate — it
is harmless because the `MGPipeHandleIsPublished` test beside it already answers false.
- **B, and this one matters**: `GL_Framebuffer.cpp:650`'s `PipePublishFramebufferByName` is the
**only** P4a emission in the tree that does not pass through `PipeFill`. On a backend with no
consumer those Named records reach the applier and are declined by the belt (counted in
`RefusedNoConsumer`, silent). If you want them gated at the client instead, the gate to add is
`MGPipeGetResourceOps() != nullptr` in `MGPipeFramebufferSubsystemEnabled()` — your file, your
call; the belt makes it optional rather than required.
- **C**: `SamplerEmit.h` / `ImageEmit.h` / `ProgramEmit.h` unchanged; the CSO cache is never
reached on a backend with no consumer because the hooks that call it are gated upstream.
- **D / E**: the applier gains one member, `MGPipeApplierState::RefusedNoConsumer`
(`PipeApply.h:553`). It is **not** a seam-defect counter — do not fold it into the eight-family
"zero refusals" census on the integrated tree, which is about `RefusedResourceCalls`,
`RefusedVertexInputCalls`, `RefusedObjectCalls` and `StaleFramebufferRecordLookups`. On Espryt
it must read **0**; on Magma a non-zero value is the designed state (framebuffer Named records
only, per the point above).
- **F**: the P4a A/B arms are unaffected — the conjunct is per-backend, not per-mask, and every
subsystem-control and dependency-refusal scenario runs on DirectGLES.
- **New test-suite convention**: `TextureEmitTest` and `FramebufferEmitTest` register an empty
`MGPipeResourceOps` for the whole binary; a case added to either that wants the no-consumer arm
must scope it off (`ScopedNoResourceOps` exists in `TextureEmitTest.cpp`).