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

435 lines
30 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 C — `clientsp`. Result, v1
Branch `refs/heads/p4a/clientsp`, four commits on top of `p4a/contract` = `08192d72`. **Not pushed.**
`git diff --stat 08192d72..HEAD`: **11 files, +2426 / −52.** Working tree clean.
| # | hash | message (exact, single line, no attribution) |
|---|---|---|
| c1 | `2700a058` | `[Feat] (Pipe): content-address sampler states, mint one sampler view per texture and push the three unit sets behind their own content hashes` |
| c2 | `384bff48` | `[Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive as a shader CSO and its default uniform block as global constants` |
| c3 | `7894f9bf` | `[Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved composite band and release it exactly once` |
| c4 | `ecd5b2e7` | `[Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof CSO identity, the program-resolved unit sets, the linked-snapshot stage mask and the composite band's single release` |
C.2's steps map one for one; c4's message is C's own (the brief prescribes none for step 4).
---
## 1. Verdict on the hard rules
| 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` | **0 added / 0 removed / 0 renamed / 0 resized.** File bytes and `.text` byte-identical (19114360 / 10806323), 27811 → 27811 defined symbols. rc 0. |
| `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 controls, all tripped); the two UNDECIDED rows are the contract's D6 and are unchanged |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 skipped, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds (pull / push / verify) | all three, rc 0 |
| `ctest -L unit` in all three | **rc 0 in each**, no failures |
| ctest names pull == push | `diff` empty |
| no baseline name removed | `comm -23 ~/w7/p4a-before-ctest-names.txt <names>` empty; **38 added** (13 the contract's, 25 C's) |
| `ctest -L integration-gpu -j 8` on `build-push`, default arm | **966/966**, rc 0 |
| same, `MOBILEGL_PIPE_PUSH=0` | **966/966**, rc 0 |
| same, `MOBILEGL_PIPE_PUSH=0x1ff` (P4a's subsystems off) | **966/966**, rc 0 |
| `ctest -L integration-verify -j 4` on `build-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` | **844/844**, rc 0, `grep -c 'Fatal{'` = **0** |
| `MOBILEGL_PIPE_VERIFY=1 retrace_gate.py … -j 4` | §5 |
| only C's files (+ granted) | yes — §4 |
| no push, no other worktree, no attribution lines | yes |
---
## 2. Per-file summary
### `MG_Impl/Pipe/SamplerEmit.h` (+714, the stub replaced)
Four things, in this order.
- **`MGPipeCanonicaliseSamplerParameters(src, out)`** — `memset` to zero, then sixteen field
assignments in `MGP_FIELDS_SamplerParameters`' order, `borderColorForm` included.
**It takes an OUT-PARAMETER and does not return a value** (§4 deviation D1).
`MGPipeHashSamplerParameters(canon)` is XXH64 over those 100 bytes;
`MGPipeHashOfSamplerParameters(src)` is the two in one step.
- **`MGPipeSamplerCsoCache`**, capacity 256: hash, probe, **memcmp-confirm**, LRU `Evict` that
emits `delete_sampler_state` and frees the slot, counters
`{Mints, Acquisitions, Hits, Collisions, Evictions}`, `RecordIsPublished(handle)` and a
test-only `ResetForTest()`. `MGPipeSamplerCsoCacheInstance()` is never destroyed and is
**package B's seam** for `MGPTextureParams::BuiltinSampler`.
- **`MGPipeSamplerUniformTextureTarget(GLenum)`** — DirectGLES' `SamplerUniformTextureTarget`
moved to the side of the boundary that now owns the question, and
**`MGPipeProgramOpaqueUnits`**, one inversion of the program's opaque-uniform table
(`unit → sampled target`, plus the highest image unit), memoised on
`(lifetimeId, linkVersion, backendStateVersion)`. `MGPipeProgramOpaqueUnitsShared()` is one
instance for the whole family, shared with `ImageEmit.h`.
- **`MGPipeSamplerEmitter`** — `EmitSamplerViews`, `EmitSamplerStates`, `AcquireSamplerView`,
`RecordIsPublished` / `NoteRecordDestroyed`, `Reset`, `ResetCounters`, and the
no-copy accessors a unit case reads. `kMGPipeWiredSamplerSubsystem` = `kMGPipeSubsystemSamplers`.
### `MG_Impl/Pipe/ImageEmit.h` (+120, the stub replaced)
`MGPipeShaderImageSetContentHash` and `MGPipeImageEmitter::EmitShaderImages`: the window, the
zero early-out taken **before** any hash, the per-unit `MGPImageView` build carrying the
application's format and access unrecast, `MGPipeEncodeImageAccess` (the three GL names folded
into one byte, with an assert on a fourth), the suppressor slot, `Reset` (the window is
per-context), and the accessors. It rides `kMGPipeWiredSamplerSubsystem`.
### `MG_Impl/Pipe/ProgramEmit.h` (+339, the stub replaced)
`kMGPipeGlobalConstantsNeverUploaded` + `MGPipeGlobalConstantsVersionIsEmittable`,
`MGPipeStageMaskOf` (off `GetLinkedShaderStages()`), and `MGPipeProgramEmitter`:
`EmitShaderState` (both joins, the composite observation, `bind_shader_state`,
`set_draw_program`, `set_dispatch_program`), `EmitGlobalConstants`, `AcquireShaderCso` (the
re-issue on the same handle), `AcquireShaderCsoHandle` (the one place the composite band can be
entered), the **two** latch tables (ordinary and band, never one wide one),
`RecordIsPublished` / `NoteRecordDestroyed`, `Reset`, `ResetCounters`, accessors.
`kMGPipeWiredProgramSubsystem` = `kMGPipeSubsystemPrograms`.
### `MG_Impl/Pipe/CompositeResolver.h` (+194, new)
`MGPipeProgramIsPipelineComposite(program)` (external index 0, Core.cpp:661's own invariant) and
`MGPipeCompositeResolver`: the signature-keyed memo, `Observe`, `Forget`, `Reset`, counters
`{Mints, Reuses, Releases}`. Entries hold a GL name, a signature of plain integers, a handle and
a lifetime id — **no frontend `SharedPtr`**, which is the exit-order rule.
`MGPipeCompositeResolverInstance()` is never destroyed.
**It is included BY `ProgramEmit.h`, not the other way round**, so the resolver is live in the
build that matters rather than only in a test.
### `MG_State/GLState/SamplerState/SamplerObject.cpp` (+17/−4)
The `#if MOBILEGL_PIPE_PUSH` destructor body's bare `NotifyStateObjectDestroyed(SamplerCso, …)`
becomes `MG_Pipe::MGPipeEmitSamplerCsoDestroyAndFree(m_lifetimeId)` — edited, never added
(G1). For a content-addressed CSO the helper correctly frees nothing (§3).
### `MG_State/GLState/ProgramState/ProgramObject.cpp` (+17/−4)
The same edit, `MGPipeEmitShaderCsoDestroyAndFree(m_lifetimeId)`, and it is the one line an
ordinary program and a pipeline composite share. `#include <MG_Pipe/PipeMutation.h>` added.
### `MG_State/GLState/ProgramState/ProgramObject.h` (+17)
One new accessor, **inside `#if MOBILEGL_PIPE_PUSH`**: `const SpirvArtifacts& GetSpirvReflection() const`
— the phase-B twin of `GetLinkReflection()`. `MGPipeApplyCreateShaderState` takes both whole
structs and the class had no public whole-struct SPIR-V accessor (§4 deviation D6).
### Tests
`MG_Test/Pipe/SamplerEmitTest.cpp` (+372, 10 cases), `ImageEmitTest.cpp` (+214, 5),
`ProgramEmitTest.cpp` (+259, 7), `CompositeResolverTest.cpp` (+215, 6). Each keeps the contract
commit's shape-pinning case verbatim, carries the pull-build SKIP list so `ctest -N` stays
name-for-name identical, and uses an RAII scope rather than a `TEST_F` (a fixture would file
every case under the fixture's name and out of the gates' `ctest -R` reach).
---
## 3. The identity rules, as implemented
### Sampler CSO — CONTENT-addressed, capacity 256
Key = XXH64 over a **zero-initialised canonical copy** built field by field, confirmed with a
`memcmp` over the same canonical bytes before any handle is reused. Slots come from
`MGPipeSlots().Allocate(SamplerCso)` **without a lifetime id**, deliberately: the CSO belongs to
a VALUE, not to a frontend object, so `~SamplerObject` must not free it — another live
`SamplerObject` may hold the same value. Its **only** death path is the cache's LRU eviction,
which is client-side and therefore backend-neutral from the first commit.
`static_assert(kMGPipeSamplerCsoCacheCapacity > kMGPipeMaxTextureUnits)` makes "a handle named
in the tail of the record being built now can never be the LRU victim" a build-time property:
one pass acquires at most 192 and touches every one of them.
### Sampler view — IDENTITY-addressed, one per `ITextureObject`
`MGPipeSlots().Acquire(SamplerViewCso, texture.GetLifetimeId())`, `create_sampler_view` re-issued
on the **same handle** whenever the restrictions move (`Gen` moves only on slot reuse).
The version-first skip latches `(GetShapeVersion(), GetTextureParamsVersion(), Gen, textureHandle)`
per slot. The shape version is the load-bearing half — it is what `BumpShapeVersion` moves, i.e.
exactly the inputs `MGPSamplerView` carries; the params version rides beside it belt-and-braces
(no field of the record depends on it, so a wrap of that `Uint16` can only cost a skipped
re-issue of an identical record). The four view restrictions are emitted from
`GetViewMinLevel/NumLevels/MinLayer/NumLayers`, which are `0` for an ordinary texture and written
by `glTextureView` for a view — so **zero unambiguously means "unrestricted"** and there is no
second spelling of that case to disagree with the first.
### Shader CSO — IDENTITY-addressed, one per `ProgramObject`
`Acquire(ShaderCso, program.GetLifetimeId())` for an ordinary program;
`AllocateComposite(lifetimeId)` for a composite. `create_shader_state` re-issued on the same
handle whenever `GetLinkVersion()` moves; the latch is `(RecordLive, RecordGen, LinkVersion)`.
All seven `MGPBlobRef`s declare `Seg = kMGHostSpanSegNone, Size = 0` (the one Blob rule) and the
artefacts ride beside the record through the entry point's companion pointers — **the codec is
never called on the monolith path**. `Offset` carries the staging address, diagnostics only.
### Composite — the band, and exactly one free
Minted off the composite `ProgramObject`'s **own** lifetime id out of
`[kMGPipeShaderCsoCompositeSlotBase, kMGPipeShaderCsoSlotLimit)` through the allocator's one
door. Two release paths, both through `MGPipeEmitShaderCsoDestroyAndFree`: the resolver's
signature-move release, and the composite's own `~ProgramObject`. Whichever runs second is a
proven no-op (`Free` refuses a slot that is not live at that generation and bumps no generation
of its own). Both orders are pinned.
**Two pipelines with the same signature do NOT share one handle** — see §4 deviation D4.
### The two unit sets and the image set
`set_sampler_views` is the **program-resolved** set (`Start = 0`,
`Count = GetMaxTouchedTextureUnit() + 1` clamped to 192); a unit the program does not sample, a
unit with nothing bound, an undefined default texture and a texture that
`SamplesAsIncompleteTexture` all carry the null view — which is the resolution DirectGLES
performs by leaving the native target unbound. `bind_sampler_states` is deliberately **not**
program-resolved (a sampler object is bound to a UNIT and applies to whatever it holds), which
is `BindCurrentUnitSamplers`' shape. All three hash field-wise over zero-initialised staging
arrays with `Start` and `Count` mixed in, and all three go through their `SetHashSuppressor` slot.
---
## 4. `EmittedCallSuppliesTheWholeField` — the decisions, and why none of them moved
All six P4a rows were placed in the **false** arm by the contract commit. C's implementation
confirms every one of them for its own families, so `PipeFill.cpp` (A's for the phase) needed no
edit and no field stopped being pulled:
| field | verdict | reason as implemented |
|---|---|---|
| `GetProgramForDraw` | **false** | pointer-valued. The emitted call carries a `{slot, gen}` HANDLE, not the `SharedPtr<ProgramObject>` the field returns — exactly `GetBoundVertexArray`'s reason. |
| `GetProgramForDispatch` | **false** | the same, and it is a second, independent slot. |
| `GetTextureUnitObject` | **false** | the field hands back a live `TextureUnit&` with one binding slot per target; `set_sampler_views` carries the RESOLVED single view per unit, which is strictly less. |
| `GetMaxTouchedTextureUnit` | **false** | the applier's `Count` can lag the frontend's mark by exactly the case the suppressor exists to swallow: a redundant re-bind moves `GetTextureBindGeneration()` and the mark, and the resolved set's hash does not move, so nothing is sent. |
| `GetImageTextureBinding` | **false** | the field is a live `ImageTextureBinding&` including its `SharedPtr`; the record carries a handle plus an access byte. And C's window is program-derived (§4 D7), so a unit outside it is not described at all. |
| `GetFramebufferBindingSlot` | **false** | package B's, untouched here. |
---
## 5. Verification transcript
```
$ git log --oneline -5
ecd5b2e7 [Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof …
7894f9bf [Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved …
384bff48 [Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive …
2700a058 [Feat] (Pipe): content-address sampler states, mint one sampler view per texture …
08192d72 [Feat] (Pipe): land the P4a contract - …
$ for d in build-linux build-push build-verify; do cmake --build $d -j 12; done all rc=0
$ 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
| before | ~/w7/p4a-before-libMobileGL.so | 19114360 | 10806323 |
| after | build-linux/libMobileGL.so | 19114360 | 10806323 |
.text 10806323 -> 10806323 (+0, +0.000%). 27811 -> 27811 defined symbols:
0 added, 0 removed, 0 resized, 0 renamed, 27072 unchanged. rc=0
$ python3 scripts/gen_pipe.py --check rc=0
gen_pipe: 71 calls (11 screen, 60 context), 72 verify payloads, 63 PipeInputs fields, 69 verbs
gen_pipe: inventory 477 rows: ... 0 UNMAPPED; generated files are up to date
$ python3 scripts/gen_pipe.py --self-test 7 negative-control trip(s), positive OK rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
dirty-surface: 79 mutators, all mapped, no stale rows; 45 render-state answers derived
... 0 COARSE; 2 UNDECIDED (the contract's D6, unchanged); 26 prose answers
$ python3 scripts/gen_pipe_dirty_surface.py --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: 4 probes, 0 skipped, 0 problem(s); self-test 6 negative-control trip(s) rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
[p3a-untouched] the 11 pool / deferred-release / ring / flush-drain functions are
[p3a-untouched] byte-identical between 37da3c3a and HEAD rc=0
$ for d in build-linux build-push build-verify; do ctest --test-dir $d -L unit --no-tests=error -j 12; done
all rc=0, 0 failed
$ diff <(names build-linux) <(names build-push) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(names build-linux) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(names build-linux) 38 added
$ ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.' \
--no-tests=error --output-on-failure 100% passed, 29/29 rc=0
$ ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ GLIBC_TUNABLES=glibc.malloc.tcache_count=0 \
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4
100% tests passed, 0 tests failed out of 844 ; grep -c 'Fatal{' = 0 rc=0
```
```
$ MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/p4a-clientsp \
--lib ~/w7/p4a-clientsp/build-verify/libMobileGL.so --out ~/w7/retrace-out/p4a-clientsp -j 4
79 tests selected of 79
...
passed 79 / 79; failed: []
retrace_gate rc=0
$ grep -l 'Fatal{' ~/w7/retrace-out/p4a-clientsp/*.log (empty)
$ grep -L 'MGPipe verify:' ~/w7/retrace-out/p4a-clientsp/*.log (empty - all 79 armed)
$ rm -rf ~/w7/retrace-out/p4a-clientsp
```
**The first attempt of this run reported `passed 2 / 79` with `ssim=None` on every Minecraft
case.** That is the LFS-pointer false red, not a regression — see deviation D11.
---
## 6. Granted sites
**None used.** C.7 grants C `MG_Impl/GLImpl/Program/GL_Program.cpp` ("nothing today —
`create_shader_state` is emitted from the validate point"); that stayed true and the file is
untouched. `MG_State/GLState/Core.{h,cpp}`, which C.7 gives to C after the tag, is **also
untouched** (deviation D5).
Every file C edited is one C.7 names as C's: `MG_Impl/Pipe/{SamplerEmit,ImageEmit,ProgramEmit,
CompositeResolver}.h`, `MG_State/GLState/{SamplerState,ProgramState}/**`, and
`MG_Test/Pipe/{SamplerEmit,ImageEmit,ProgramEmit,CompositeResolver}Test.cpp`.
Nothing under `MG_Backend/`, `MG_IntegrationTest/`, `.github/`, `scripts/`, `MG_Pipe/`,
`MG_Impl/Pipe/{PipeFill,Tracker,SetHashSuppressor,SlotAllocator,CsoCache,ResourceTracker,
VertexInputEmit}`, or any of B's `MG_State` directories.
---
## 7. Deviations, each with its reason
**D1 — the canonicaliser takes an out-parameter, and the cache stores its bytes with `memcpy`.**
D-F1 says "hashed with XXH64 over the copy". A copy is not enough: a copy of a trivially
copyable type leaves the padding **unspecified**, so a canonicaliser that returned by value
would hand its caller three bytes of whatever the copy left there, and `Entry::Params = canon`
would leave the cache's own stored bytes with different padding from the probe's.
**This is not theoretical — it was the bug.** With member-wise assignment the first probe's
`memcmp` rejected the cache's own entry, counted a collision that never happened, evicted and
minted a fresh CSO: a 256-entry cache with a hit rate of zero, whose failure depends on heap
contents, so `TwoIdenticalSamplersShareOneCso` **passed run alone and failed run in a suite**.
Both are now `memset`/`memcpy` and `PaddingCannotChangeTheHash` covers the hash and the confirm.
**D2 — [FINDING] `kMGPipeWired*Subsystem` is NOT the emission gate, so c1–c3 are not inert.**
The validate point's `wants()` (`PipeFill.cpp`) asks `MGPipeSubsystemForDirty(bit)` and the
runtime `MOBILEGL_PIPE_PUSH` mask **and nothing else**; only the texture drain additionally
tests `kMGPipeWiredSubsystems`. So the moment an emitter has a body it runs at the phase default
mask `0x1fff`, whatever its family constant says. The tree is still behaviourally unchanged —
every applier entry point is a stub on this branch — but C.1's b1 wording ("the emission is
proven semantically free before anything is switched over") does not hold for the framebuffer,
sampler, image or program families as `PipeFill.cpp` is written, and **package B inherits the
same fact**. It surfaced as a real test symptom: a `glBindImageTexture` reaches the validate
point and emits the set, so a direct `EmitShaderImages` afterwards is correctly suppressed
(deviation D14). Recorded rather than fixed, because `PipeFill.cpp` is A's for the phase.
**D3 — [FINDING] the six death helpers hardcode `published = false`, so no wire delete can go
out from a frontend destructor.** `PipeFill.cpp:899-980` reads
`const Bool published = false; // the … emitter publishes nothing yet` for all six kinds, and
that file is A's for the entire phase (ID-9 D1: "never touch `PipeFill.cpp`"). C therefore
cannot make `delete_sampler_view` or `delete_shader_state` go out at object death.
**Impact is bounded and no slot leaks**: `NotifyAndFree` still frees the slot, so `HighWater`
and the leak cases are unaffected; what stays behind after `wire` lands is a `Live` applier
record on a freed slot, which no live handle can reach and which a create on the recycled slot
starts over. **The fix is one line per helper and C has already provided the other half**: both
emitters expose `RecordIsPublished(handle)` and `NoteRecordDestroyed(handle)` with P3a's exact
signature, so each body becomes
`const Bool published = emitter.RecordIsPublished(handle); if (published) { …ApplyDelete…; emitter.NoteRecordDestroyed(handle); }`.
`SamplerCso` needs no fix at all: it is content-addressed, has no per-object slot, and its
delete rides the cache's own LRU eviction.
**D4 — `TwoPipelinesWithTheSameSignatureShareOneComposite` is implemented and named
`TwoPipelinesWithTheSameSignatureKeepTheirOwnComposite`.** Sharing one handle between two
composites is not safely implementable and the property that is true is the opposite one. A
composite is an ordinary `ProgramObject` with its own lifetime id, and the death helper resolves
the handle **from** that id; two composites sharing one handle would put only one id in the
allocator's map, so the first `~ProgramObject` would free a slot the second still names — a
premature free that reappears later as slot theft, which is the class the reserved band exists
to prevent. The frontend does not share either: each `ProgramPipelineObject` carries its own
one-slot draw-program cache. The case asserts both handles are distinct, both are in the band
and both stay live; the reason is written into the case.
**D5 — no `Core.{h,cpp}` hook; the composite is identified by `GetExternalIndex() == 0`.**
C.2 grants `Core.{h,cpp}` for "the hook the composite resolver observes". None is needed:
`Core.cpp:661` constructs the composite as `MakeShared<ProgramObject>(0u)` **deliberately**, so
that it is not a named program, does not answer `glIsProgram` and consumes no name — and
`glCreateProgram` never returns 0. A `Bool` member on `ProgramObject` would resize the pull
build's object and break G1 outright. `CompositeResolverTest.ACompositeIsMintedFromTheReservedBand`
pins the discriminator against a really flattened pipeline.
**D6 — `ProgramObject.h` gains one push-guarded accessor.** `MGPipeApplyCreateShaderState` takes
`const SpirvArtifacts*`, and the class exposes only granular SPIR-V getters — no public
whole-struct accessor, and `reservedNumSamplesOffset` has no getter at all.
`GetSpirvReflection()` is the phase-B twin of the existing `GetLinkReflection()`, inside
`#if MOBILEGL_PIPE_PUSH` so a pull build's symbol set and this class's layout are untouched
(G1 confirms: 0 resized).
**D7 — the image-unit window is derived from the program, because the frontend has no
image-unit high-water mark.** D-G2 says `Count` is "the image-unit high-water mark + 1", and
D-G4 property 1 is the zero early-out. `g_imageUnitHighWaterMark` is **DirectGLES'**, written
from inside its own per-unit sync; `TextureState::NoteUnitTouched` is the TEXTURE-unit path and
`glBindImageTexture` does not reach it. Adding a counter to `TextureState` would edit package
B's file **and** resize the pull build's object. So the window is
`max(highest image unit the current program names + 1, the emitter's own sticky window)`, taken
from the shared opaque-unit inversion. A program with no image uniform gives 0 and the set is
not emitted at all — which is property 1's intent exactly ("one integer test for a feature it
does not use"), and it costs no 192-entry walk to reach. The window is sticky so a program that
stops naming a unit does not silently stop describing it.
`ImageEmit.AZeroHighWaterMarkEmitsNothingWithoutHashing` pins it **with an image really bound**.
**D8 — the unit→target resolution is INVERTED once per program, not searched per unit.**
DirectGLES asks it the other way round (`sampledTargetForUnit` walks every uniform location for
one unit) and gets away with it because it only asks on an aliasing conflict. Per unit per verb
that would be O(units × locations), which is the per-draw cost the phase's budget forbids.
`MGPipeProgramOpaqueUnits` walks the locations once and memoises on
`(lifetimeId, linkVersion, backendStateVersion)` — the third being the counter
`SetUniformSamplerOrImageUnitIndex` bumps, i.e. the one thing that moves a uniform's unit
without a relink. First writer wins on a shared unit, which is DirectGLES' arbitration read
forwards. **One instance shared by the sampler and image emitters**, so the two halves cannot
be resolved against two different readings of one program.
**D9 — the sampler CSO cache's capacity is a `static_assert`ed safety bound, not only a size.**
`static_assert(kMGPipeSamplerCsoCacheCapacity > kMGPipeMaxTextureUnits)`.
**D10 — nothing in C's `Reset()` paths touches an object record.** D-J4 is obeyed literally:
`MGPipeSamplerEmitter::Reset()` invalidates only the per-context opaque-unit memo,
`MGPipeImageEmitter::Reset()` only the window, `MGPipeProgramEmitter::Reset()` only the three
bound-handle mirrors and the global-constants key, and the CSO cache and the two record halves
(`RecordIsPublished`) are **not** reset — re-publishing a record the applier still holds would
move its `Serial` for nothing. The cache's `ResetForTest()` is named for what it is.
**D11 — the trace fixtures in this worktree were LFS pointers.** The integrator's 12:24 reset
to the tag pulled `tools/trace_replay/fixtures` back to 131/133-byte pointers, and the first
retrace run reported `passed 2 / 79` with `ssim=None` — the exact false red `MEASUREMENTS.md:413`
names. Restored from `~/w7/pipe/tools/trace_replay/fixtures` (7.7 MB → 803 MB) and re-hidden with
`git ls-files … | xargs git update-index --assume-unchanged`; `git status` clean, 0 files under
1 KB remain. **Every other P4a worktree that was reset at 12:24 is in the same state and must be
checked before its retrace verdict is believed.**
**D12 — `~/w7/p4a-trees2.log` never received `REBUILT clientsp`.** The file was created empty at
12:25 and no build, cmake or `wsl_tree.sh` process was ever running. Before the first build C
confirmed no build process was active in the shared trees and built `build-{linux,push,verify}`
itself; `build-linux` needed 2 targets, so the 11:32 build was already valid.
**D13 — six test names beyond C.2's list, additions only** (G14 is about removals):
`SamplerEmit.AHashCollisionDoesNotAliasTwoSamplerStates`,
`ImageEmit.TheApplicationsFormatAndAccessTravelUnrecast`,
`ProgramEmit.{TheDrawAndDispatchProgramsAreTwoIndependentSlots, AnUnchangedProgramEmitsNothingAtAll}`,
`CompositeResolver.{ASignatureThatHasNotMovedReusesOneComposite, DestructionThenEvictionFreesTheSlotExactlyOnce}`.
**D14 — cases assert on the emitter's counters, not on a direct call's return value**, wherever
a GL entry point in the fixture already reached the validate point and emitted (D2).
`SamplerEmitTest` also shares ONE process-wide `MobileGL::Initialize()` context rather than
`VertexInputEmitTest`'s per-case fresh `GLContext`, because half its cases need a really linked
program and glslang lives behind that call; each case uses GL names of its own.
**D15 — `ProgramEmit.TheNeverUploadedSentinelIsNeverEmitted` pins the PREDICATE.** Driving
`GetUBOContentVersion()` to `~0u` takes four billion `MarkUBOContentDirty` calls, which is not a
test. `MGPipeGlobalConstantsVersionIsEmittable` is what `EmitGlobalConstants` consults, so
pinning it pins the behaviour and deleting the guard is a compile error in the case; the case
additionally asserts that the live path's last record carries an emittable version.
---
## 8. What must be re-run after the rebase onto `wire` + `clientfb`
Ordered by risk, highest first.
1. **`MGPTextureParams::BuiltinSampler` must be non-null on every `set_texture_params`** — the
applier makes a null there `Fatal{ProtocolCorruption}`. Package B's `TextureEmit.h` gets that
handle from **C's seam**, `MGPipeSamplerCsoCacheInstance().Acquire(texture.GetSamplerObject()->GetAllSamplerParameters(), bytes)`
in `MG_Impl/Pipe/SamplerEmit.h`. If B minted it any other way, or not at all, every texture
will trip that Fatal the moment `wire` lands. **Check this before anything else.**
2. **Deviation D3's one-line fill-in** in each of the six `PipeFill.cpp` death helpers, then
re-run `ctest -R 'HandleRecycle'` and G8b's leak cases: `delete_sampler_view` and
`delete_shader_state` only start going out once `published` is asked rather than assumed.
3. `ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.'`
— on this branch every applier entry point is a stub, so **no case has yet exercised a real
applier**: the `Start + Count` bounds gate, the record lifecycle, the refusal counters and the
verify build's program-archive round trip in `MGPipeApplyCreateShaderState` all come alive
with `wire`.
4. The full transcript of §5, in order — three builds, G1, the three generators, the closure
probe, `p3a_untouched_regions.sh`, unit ×3, the name parity pair, the three integration-gpu
arms, integration-verify under `GLIBC_TUNABLES`, and the retrace gate.
5. `MOBILEGL_PIPE_PUSH=0x9ff` (samplers set, texture resources clear) once package D's
`ResolveSamplerSubsystemArm` exists — C emits `MGPBoundView::Texture` and `MGPImageView::Res`
as `Texture` handles unconditionally, which is precisely the arm D-K2 says must be refused
and logged rather than half-run.
6. The retrace corpus, **after checking the fixtures are not LFS pointers** (D11).