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

460 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P4a package F — `gates`. Result, v1
Four commits on `refs/heads/p4a/gates`, branched from the tag `refs/tags/p4a/contract` = `08192d72`.
**Not pushed.** Working tree clean. 11 files, **+3831 / −57**.
| # | hash | message (exactly as C.5 gives it, single line, no attribution) |
|---|---|---|
| 1 | `0bc9aafa` | `[Test] (Pipe): reproduce the texture, framebuffer, renderbuffer, sampler, view and program handle ABA through public GL and prove the pre-rekey guards are what stops it` |
| 2 | `4f006f3c` | `[Test] (Espryt): assert a glTexParameter on a texture that only ever was an attachment, an image binding or a copy endpoint reaches the driver` |
| 3 | `70868f93` | `[Test] (Pipe): switch P4a's four object subsystems off against the shipping mask and record the texture upload shape the two counters make visible` |
| 4 | `303a9dc8` | `[CI] (Pipe): gate that the unpack ring, the attachment permutation, the depth-stencil sampling core and the format caveat did not move` |
**Commit 3's message is not in C.5** — C.5 names three. `ObjectSubsystemControlScenario` (G12) and
`TextureUploadShapeScenario` (D-D4) are in C.5's file table but belong to none of the three messages,
and putting them under either of the two `[Test]` messages would have made the message describe
something else. **Declared deviation F-1**, below. Every commit builds on its own: the CMake source
list and the lane registrations were staged so that no commit names a scenario file that does not
exist in it (verified by walking each commit's `CMakeLists.txt` against its own tree).
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 renamed / 0 resized**, rc 0. The pull `.so` is byte-for-byte the same size as `$BASE`'s: 19114360 file, 10806323 `.text`. None of this package's files reaches the library. |
| every ctest name at the tag still exists (**G14**) | `comm -23 ~/w7/p4a-before-ctest-names.txt <names at HEAD>` **empty**; **+119 added** |
| ctest names pull == push (**G2**) | `diff` empty, **2707** names in each |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, seventeen regions |
| `bash scripts/p4a_untouched_regions.sh --self-test` | **rc 0**, 3 positive + **4 negative** controls, each tripped and named |
| `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0** (and `--self-test` rc 0) |
| `bash scripts/p4a_descriptor_negative_control.sh build-push` | **rc 2**, naming both absent field copies — the contract tree's correct answer |
| `ctest --test-dir build-verify -R 'HandleRecycle\|Leak'` | **180/180 passed, 0 failed**; every non-assertion is a named SKIP |
| `ctest --test-dir build-push -R 'ObjectSubsystemControl\|TextureParamsWithoutASamplerView\|TextureUploadShape'` | **18/18 passed, 0 failed** (8 + 10 across two runs); named SKIPs only |
| `ctest -L unit`, three builds | **1635 / 1635 / 1635**, 0 failed |
| `ctest --test-dir build-push -L integration-gpu -j 6` | **1072/1072 passed, 0 failed** |
| only this package's files | yes — `MG_IntegrationTest/**`, `.github/workflows/test.yml`, `scripts/p4a_*.sh`, and F's one granted DirectVulkan file `Renderer/MagmaPipeArms.h` |
| no push, no other worktree, no attribution lines | yes |
**Not run here, and why:** the retrace sweeps, the verify retrace and the device work are D.3/D.4's
and need `~/w7/pipe`, which package agents never touch (ID-3). `build-bench` does not exist in this
worktree (`wsl_tree.sh` creates `build-linux`, `build-push`, `build-verify`), so C.5's
`cmake --build build-bench && ctest -L benchmark` line could not run; **nothing in this package
touches `MG_Benchmark/`**, so there is nothing for it to have broken — the integrator's own bench
tree covers it.
---
## 2. Per-file summary
| action | file | what |
|---|---|---|
| MODIFY | `MG_IntegrationTest/Harness/PipeSlotPeek.{h,cpp}` | `PipeSlotKind` gains `Texture, Renderbuffer, Framebuffer, SamplerCso, SamplerViewCso, ShaderCso`. `Translate` is now an exhaustive switch with **no `default:`** — a kind added without a decision is a `-Wswitch` warning rather than a row that silently counts `VertexElementsCso` and reports "did not leak" about a kind it never looked at. `ShaderCso` covers ordinary programs **and** band composites, because that is what the allocator has. |
| MODIFY | `MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` | +1057 lines. Four new ABA cases (renderbuffer, sampler object, sampler view, program); the two existing texture/framebuffer cases become real controls; seven `…ReturnTheir…Slots` leak cases; three new gates (`ThisBackendsObjectRekeyHasLanded`, `ObjectAbaControlIsWiredHere`, `SkipUnlessTheObjectHandlePathIsAssertableHere`) and one shared assertion block (`AssertChurnReturnsEverySlot`). |
| MODIFY | `MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h` | The **only** DirectVulkan file P4a touches. `MagmaPipeAbaControlDefeatsIdentity` keeps its body; beside it, `MagmaPipeAbaControlCoversKind(MGPipeKind)` states **per kind** what the knob defeats — true for `VertexElementsCso` and `Buffer` (the only two kinds `MagmaPipeIdentityTables` mints), false for P4a's six, with the one change that flips it written out. Inside the file's existing `#if MOBILEGL_PIPE_PUSH`, so the pull build is untouched (G1 0/0/0/0 confirms). |
| CREATE | `MG_IntegrationTest/Scenarios/TextureParamsWithoutASamplerViewScenario.cpp` | G9. D-E3's four cases, DirectGLES only, every setup step through the DSA entry points so no case ever binds its texture to a unit before the observation. |
| CREATE | `MG_IntegrationTest/Scenarios/TextureUploadShapeScenario.cpp` | D-D4, recorded not gated. |
| CREATE | `MG_IntegrationTest/Scenarios/ObjectSubsystemControlScenario.cpp` | G12. `0x1fff` vs `0x1ff`, plus the `0x9ff` dependency refusal. |
| MODIFY | `MG_IntegrationTest/CMakeLists.txt` | +280 lines: three sources, one new probe function, five new capability markers, every `0x1ff` phase pin raised, four new lanes. §4. |
| CREATE | `scripts/p4a_untouched_regions.sh` | G5, seventeen regions across three files. §5. |
| CREATE | `scripts/p4a_descriptor_negative_control.sh` | G7, two field drops. §6. |
| MODIFY | `.github/workflows/test.yml` | `BASELINE` → `37da3c3a`, two new `pipe-gates` rows, three new `-R` alternatives on the push-build control step. §7. |
---
## 3. What each scenario asserts, and how it skips on an unimplemented tree
Every arm that needs a subsystem this tree does not have **SKIPs with a named reason**. No
registration is withheld, no arm vanishes, and no arm asserts something that cannot exist yet
(ID-2). The decision is the BUILD's, through content probes with `CONFIGURE_DEPENDS`, never a
hand-maintained list.
### 3.1 `HandleRecycleScenario` — the six ABA cases (G8)
**On a complete tree** each case builds an ABA through public GL — an object is created, drawn with
for `kWarmupFrames`, unbound, deleted, and immediately replaced at the same GL name with a
byte-identical configuration and different contents — and asserts the pixels come from the
replacement. On the `AbaControl` arm, where the knob defeats the identity half of the memo key, the
**corruption is the assertion**.
| case | what a stale key would produce | observable |
|---|---|---|
| texture (existing, now a control) | the dead texture's texels | sampled colour |
| framebuffer (existing, now a control) | the clear lands in the DEAD framebuffer | **both** attachments read back: FRESH = (replacement green, dead red), STALE = dead turned green. P4a added the dead attachment's red warm-up clear so the corruption has a place to be visible, not just an absence |
| renderbuffer | the dead 4×4 storage under an 8×8 replacement | 8×8 readback all green, plus the framebuffer's completeness |
| sampler object | the dead sampler's border colour | `GL_CLAMP_TO_BORDER` sampled at a constant UV outside [0,1] — one colour for the whole viewport, and the border colour is the parameter with the fewest other paths to the driver |
| sampler view | the dead texture through a LIVE sampler object | a bound sampler object is what makes this a different question from the texture case: the view's key names the texture, and the sampler half deliberately does not move |
| program | the dead program's fragment output | the colour is baked into the source, not a uniform — a uniform would be re-set on the replacement and hide the inheritance |
**On this tree** the six SKIP on the `Handles` arm with *"subsystem not implemented on this tree: …
no source under `MobileGL/MG_Backend/<backend>` names any of
`kMGPipeSubsystem{Framebuffer, TextureResources, Samplers, Programs}`"* — and they PASS on the
`Legacy` arm (asserting today's address/`weak_ptr` guards, which is exactly what "the replacement has
to be at least as strong" means).
### 3.2 The `AbaControl` arm for the six kinds — a finding, not an omission
`armExpectsCorruption` is `ObjectAbaControlIsWiredHere()`, which is
`knob-consumer-for-this-backend AND object-re-key-for-this-backend`. **Both are false on every
backend today, and the reason is structural rather than temporal**:
* `MOBILEGL_PIPE_HANDLE_ABA_CONTROL` has exactly one consumer in the tree,
`MagmaPipeAbaControlDefeatsIdentity`, and its consumers are Magma's **vertex-input** keys;
* `MagmaPipeIdentityTables` mints `{slot, gen}` for **two** kinds, `VertexElementsCso` and `Buffer`.
A texture, a framebuffer, a sampler, a view and a program are still reached from their frontend
objects on that backend, and moving them onto handles is **P7's** (`ROADMAP.md:24`, D-Q);
* on DirectGLES the knob has no consumer at all, which is why the `AbaControl` lanes are
DirectVulkan-only in the first place.
So **D.2's expectation that the six kinds' `.AbaControl` arms PASS by asserting the corruption cannot
be met on this tree, and no package in P4a owns the file that would change that** (the Espryt knob
consumer would live in `MG_Backend/DirectGLES/SlotTables.h`/`Managers.cpp`, which C.7 gives to
package D; the Magma one is P7). Rather than a lane that asserts a corruption nothing can produce —
a hard red on an always-on `integration-gpu` lane, the exact failure this file's own header records
having had once — the arm **asserts the correct pixels and says, on stdout and in
`RecordProperty("aba_control_wired", 0)`, that it is not a control for that kind yet**. One `if` in
a backend's `GetOrCreate`/`FindByHandle`, the shape `MagmaPipeClaimSlotMemos` already has, flips all
six. **Declared deviation F-2.**
### 3.3 `HandleRecycleScenario` — the seven leak cases (G8b)
Shape: two warm-up rounds, then `kChurn = 48` create/draw/destroy rounds, asserting
`liveAfter == liveBefore`, `highWaterAfter == highWaterBefore` and
`peakLive − liveBefore <= maxInFlight`. `peakLive` is sampled **inside** the round through an
`observe()` callback the round must call while its object is still alive — sampled after the destroy
the third assertion would be vacuous, and it is the one that catches a death path that works but runs
at the wrong time.
Three ways a case declines to assert, all of them named:
1. not the `Handles` arm → the other lanes run `MOBILEGL_PIPE_PUSH=0`, where there is no allocator;
2. `PeekPipeSlot*` returns false → "could not look" is not "did not leak";
3. **nothing of that kind was ever minted** (`highWater == 0 && peakLive == 0 && liveAfter == 0`) →
*"the client minted no `<kind>` slot at all over 50 rounds"*. This third one is P4a's addition and
it is what stops six of the seven cases from being `0 == 0` greens before the emitters land.
**Measured on the contract tree, DirectGLES `Handles` lane** (the numbers are in
`p4a-handlerecycle-before-verbose.log`):
| case | reading | verdict |
|---|---|---|
| `DestroyedVertexArraysReturnTheirVertexElementsSlots` (P3a's) | live 1→1 (peak 1), hw 3→3 | pass |
| `DestroyedTexturesReturnTheirTextureSlots` | live 3→3 (peak 4), hw 5→5 | pass — **the client already mints and frees Texture slots at `c0`** |
| `DestroyedRenderbuffersReturnTheirRenderbufferSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedFramebuffersReturnTheirFramebufferSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedSamplersReturnTheirSamplerCsoSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedProgramsReturnTheirShaderCsoSlots` | live 1→1 (peak 1), hw 2→2 | pass |
| `EvictedPipelineCompositesReturnTheirShaderCsoSlots` | live 1→1 (peak 1), hw 2→2 | pass, **partially armed** — see below |
| `DestroyedTexturesReturnTheirSamplerViewSlots` | live 0→0 (peak 0), hw 0→0 | **SKIP**, "the client minted no SamplerViewCso slot at all" |
On the DirectVulkan `Handles` lane every one of the seven SKIPs on the same "nothing minted" rule,
which is the honest reading for a backend whose object kinds are P7's — and it is exactly where the
cases have to run once they arm, because P3a's C-1 was a **Magma** leak (ID-8).
**The composite case is only partially armed today.** `ShaderCso` is minted (so the "nothing minted"
skip does not fire and the case is not vacuous about the *kind*), but no slot comes out of the
composite band yet: `CompositeResolver` is package C's. The case therefore asserts today that
pipeline churn leaks no `ShaderCso`, and asserts the two-release-path property — LRU eviction **and**
the composite `ProgramObject`'s destructor, the pair D-H7 calls out — when C lands. It also depends
on contract review v1's **M5** (`HighWater(ShaderCso)` returning the band top makes the high-water
assertion vacuous); the fix is in flight on `c0b` and this case is one of its consumers.
### 3.4 `TextureParamsWithoutASamplerViewScenario` (G9) — **the mandatory red could not be produced, and the reason is a finding**
The four cases put a texture through exactly one reachability path, move a parameter while it is
reachable only that way (through `glCreateTextures` / `glTextureStorage2D` / `glTextureSubImage2D` /
`glTextureParameteri`, so no setup step ever binds it to a sampler unit), and sample it once at the
end.
**All four are GREEN on `08192d72`** — including
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver`, which D-E3 says must be RED.
`p4a-texparams-before.log` is the run. The mechanism, re-opened at the base ref:
* a texture parameter's only public-GL observable is a **sample** — nothing about an attachment, an
image binding or a copy endpoint reads a swizzle or an aspect mode;
* a sample puts the texture on `SyncNeccessaryTextures`' **unit** list, and that walk calls
`SyncTextureParamsToBackend` for every entry whose `IsDrawSyncClean` is false
(`DirectGLES.cpp:1896-1898`);
* `IsDrawSyncClean` is false **whenever the frontend parameter version has moved** since the last
sync (`Managers.h:1399-1416`: `m_syncedTextureParamsVersion != paramsVersion`).
So the D-E3 gap is real — between the parameter change and the next sampler binding the driver
really is not told — and it is closed by the only thing that can see it. **No public-GL integration
scenario on a monolith tree can produce ROADMAP.md:20's `落地前必须红` artefact for this case.**
Producing it needs an observation of the *driver's* texture object taken while the texture is still
read-attachment-only, i.e. a probe inside `MG_Backend/DirectGLES` — package D's files (C.7), not
this package's.
What the scenario is instead, stated in its own header so nobody reads a green as more than it is:
a **regression net around D10**. It goes red if any of the four reachability paths is ever made to
depend on the texture having a sampler **view** — which is the coupling P4a's resource-addressed
`set_texture_params` removes and a later phase could reintroduce. **The integrator's ruling is
needed** (§9). **Declared deviation F-3.**
### 3.5 `ObjectSubsystemControlScenario` (G12)
Workload: a user framebuffer with a texture attachment (bit 9), a texture with parameters and a
sub-region upload per iteration (bit 10), an explicit sampler object on the unit (bit 11), a program
with a default-uniform write (bit 12) — all four families, four times, in one counted window.
* **On (`0x1fff`)**: `fbe + sve + sse + sie + ctu > 0`, and `fbe > 0` on its own so a large upload
count cannot hide a framebuffer family that never emitted.
* **Off (`0x1ff`)**: every one of those five is **zero** — the dead-switch reading.
* **Both**: the pixels do not move.
* **Refused (`0x9ff`)**: the library's own log must **name both bits** (the constant's name or its
hex mask, so the assertion does not pin the wording), and the run must still draw what every other
lane draws — a refusal runs the LEGACY arm, so the pixels are the one thing it may not change.
**On this tree** the on/off case SKIPs on `MGITEST_PIPE_OBJECT_EMITTER_PRESENT` (no `MG_Impl/Pipe`
source emits `FramebufferEmissions`, so the counters are structurally zero in *both* arms and their
difference is not observable). The refusal case SKIPs on `MGITEST_HANDLE_REKEY_OBJECTS_DirectGLES`:
D-K2's refusal lives in `ResolveSamplersSubsystemArm()`, package D's file, and a backend that does
not honour P4a's mask cannot refuse a dependency inside it. **That skip was added after measurement**
— the first cut of the case FAILED on the contract tree, which is precisely the "fail on an
unimplemented subsystem" ID-2 forbids.
### 3.6 `TextureUploadShapeScenario` (D-D4, recorded)
Asserts only what is assertable before the shape policy is finished: the numbers could be read at
all, the server bracket's own arithmetic (`box + rect == emit`, `jobs >= emit`), and that the two
sides agree **when both are non-zero**. Everything else is `RecordProperty` + stdout.
**Recorded on the contract tree**, 3 frames × (40 scattered 2×2 rects + one 64×8 contiguous band):
```
[ TextureUploadShape ] backend=DirectGLES frames=3 scattered_rects_per_frame=40
server[emit=6 box=6 rect=0 jobs=6] client[ctu=0]
```
Six emissions (3 frames × 2 textures), **all six took the union-box shape**, 6 driver jobs — i.e.
Espryt collapsed 40 scattered rects into one box on every frame, on llvmpipe. The client side reads
zero and the case says so rather than reporting a divergence against an emitter that does not exist.
This is the P3b/P4b gate's baseline.
---
## 4. `MG_IntegrationTest/CMakeLists.txt`
**Every phase pin was re-read, not pattern-replaced.** Raised to the P4a constant:
`MGL_ITEST_HANDLES_ARM_KNOBS` (`0x1ff`→`0x1fff`), the two CSO **On** lanes, the CSO **Off** lanes'
`0x80000000000001ff`→`0x8000000000001fff` (the mask moves with the phase, the control is bit 63),
`ResourceSubsystemControl`'s On lane, both `MapPersistentRoundtrips` lanes and
`LargeArenaAdoption`'s On lane. **Left alone**: the two `0x7f` pins
(`ResourceSubsystemControl`'s Off lane and `LargeArenaAdoption`'s Off lane) — `0x7f` is P2's constant
and those lanes' named A/B control. The three comment blocks that explained the old masks were
rewritten to explain the new ones; a stale comment beside a moved pin is how the next phase gets it
wrong. **Measured: those lanes are green at the raised mask** — `CsoContentAddressing |
ResourceSubsystem | MapPersistentRoundtrip` is 28/28 on `build-push` and 36/36 on `build-verify`.
**New probes** (all inside the existing `if (MOBILEGL_PIPE_PUSH)`, all content probes over a
directory rather than filename globs, all `CONFIGURE_DEPENDS`):
| marker | probe | gates |
|---|---|---|
| `MGITEST_HANDLE_REKEY_OBJECTS_<backend>` | `kMGPipeSubsystem(Framebuffer\|TextureResources\|Samplers\|Programs)` under that backend | the six ABA cases' `Handles` arm; the refusal case |
| `MGITEST_HANDLE_ABA_OBJECTS_<backend>` | **conjunction**: `PipeHandleAbaControl` **and** a P4a subsystem constant, in ONE source | whether the six expect the corruption |
| `MGITEST_PIPE_OBJECT_EMITTER_PRESENT` | `FramebufferEmissions` under `MG_Impl/Pipe` | `ObjectSubsystemControl`'s emission case |
The conjunction needed a new helper, `mgl_itest_probe_for_two_symbols`. A single-regex probe for
`PipeHandleAbaControl` would hit `MagmaPipeArms.h` **today** and arm six controls on a backend where
the knob cannot reach any of their kinds; a single-regex probe for the subsystem constants will be
true for any backend that honours the mask, long before anyone wires the knob. What the arm needs is
one source that does both.
**New lanes** (all `DirectGLES`, all registered in every build so G2's name-for-name comparison
holds, each with a private `MOBILEGL_LOG_FILE_PATH` and a `TEST_FILTER` naming ONE case because the
library opens its log `fopen(path, "w")` and two readers in a lane race under `-j`):
`ObjectSubsystemControl.{On,Off,Refused}.` and `TextureUploadShape.`. Every environment goes through
`mgl_itest_join_environment(... ${MGL_ITEST_COMMON_ENV})`, so the `;` separators are escaped and the
EGL vendor / ICD pinning is not lost to the property that replaces the job environment.
**No `RESOURCE_LOCK` was needed**: it exists for lanes where a whole scenario shares one log and one
case reads it; each of the four new lanes selects a single case, which is the stronger form of the
same guarantee. `TextureParamsWithoutASamplerViewScenario` gets **no lane at all** — it reads no log
and no counter, and its claim is about the shipping configuration, so the ambient registrations are
exactly its arms.
---
## 5. `scripts/p4a_untouched_regions.sh` — exit contract and self-test
```
p4a_untouched_regions.sh <ref-a> <ref-b> compare the seventeen at two git refs
p4a_untouched_regions.sh <ref> print the seventeen shas at one ref
p4a_untouched_regions.sh --self-test prove the comparison can go red
```
stdout is always the `<sha256> <region>` list in the fixed order (a baseline capture is a plain
redirect); everything else is stderr. **0** identical / **1** at least one moved, first one named /
**2** could not run (bad ref, missing file, a name not defined exactly once, a self-test control that
did not trip). Both arguments are git refs, so an uncommitted edit is invisible by design.
The seventeen: P3a's eleven in `Managers.cpp` (which P4a must not touch either) plus P4a's six —
`StageBlocksIntoUnpackRing`, `UnpackRingAvailable`, `UnpackRingAllocate`,
`RecomputeBackendColorSlots` (`Managers.cpp`), `DepthStencilSamplingReadImpl` (`DirectGLES.cpp`) and
`ShouldUseCaveatTextureFormat` (`Utils.cpp`). Both preprocessor arms of the duplicated flush ladder
are hashed, exactly as in the parent (`FlushPendingRangesNow` in the `#else`,
`FlushPendingRangesFrom` in the `#if MOBILEGL_PIPE_PUSH`), so a push arm that re-spells the ladder is
a finding rather than an invisible drift.
**Self-test evidence, verbatim:**
```
[p4a-untouched] positive control: 17 regions extracted from the working tree
[p4a-untouched] positive control: an untouched copy compares equal
[p4a-untouched] positive control: an edit outside the seventeen regions is invisible, in all three files
[p4a-untouched] negative control 1: a perturbed ClearBufferPool body is reported, and named
[p4a-untouched] negative control 2: a perturbed FlushPendingRangesNow body is reported, and named
[p4a-untouched] negative control 3: a perturbed RecomputeBackendColorSlots body is reported, and named
[p4a-untouched] negative control 4: a perturbed StageBlocksIntoUnpackRing body is reported, and named
[p4a-untouched] self-test passed: 4 negative controls, all tripped and all named
```
The four are D-N's four, and they are four different shapes on purpose: the small no-overload body,
one of a PAIR of identically shaped ladders in two preprocessor arms, a `Class::method(` with a
multi-line signature and a call site of its own, and a `static` in an anonymous namespace between two
other protected bodies. The count is asserted (`!= 4` is exit 2), so a control cannot be dropped
silently.
**The seventeen shas at `37da3c3a` == at `HEAD`** (rc 0). For the record:
```
ba79b92d… IsPoolable 6563286e… EnrollIntoPool dc9d3066… AcquireFromPool
12656cfd… TrimBufferPool c44a1274… ClearBufferPool 15259e54… ProcessDeferredBufferReleases
2daaa525… CreateRingStorage 6221df2e… RingAvailable 709b6f41… RingAllocate
c6557002… FlushPendingRangesNow 37fc94ff… FlushPendingRangesFrom (the PINNED sha, unchanged)
791b54a3… StageBlocksIntoUnpackRing 1d6f15c9… UnpackRingAvailable 19e614af… UnpackRingAllocate
3ae7e347… RecomputeBackendColorSlots 822ca3b0… DepthStencilSamplingReadImpl
266710e0… ShouldUseCaveatTextureFormat
```
**Two declared deviations from D-N, both written into the script's header:**
* **D-N/1 — a region KIND.** `DepthStencilSamplingReadImpl` is a **namespace**
(`DirectGLES.cpp:8117-8578`), not a function. D-N's table names it as though it were one, and the
parent's extractor — which finds the one `<name> (` whose closing paren is followed by `{` — finds
**zero** definitions of it and would exit 2 forever. Rows now carry `function` or `namespace`;
hashing the whole namespace block is also the stronger reading of "the D24S8 sampling-emulation
CORE".
* **D-N/2 — the pin is consulted unconditionally.** The parent falls back to
`PINNED_SHA_FlushPendingRangesFrom` only when `<ref-a>` does not define the function; at P4a's base
ref it **does**, so the fallback would never fire and the pin D-N names would stop being the
baseline. This script always compares against the pin and says so on stderr if `<ref-a>` defines it
differently. **Measured: they agree** (`37fc94ff…` at `37da3c3a` is the sha pinned at `3e298c9a`),
so the two readings are the same answer on this tree.
---
## 6. `scripts/p4a_descriptor_negative_control.sh` — exit contract
```
p4a_descriptor_negative_control.sh <build-dir>
```
**0** both controls tripped **and named their field**; **1** a control did not answer (a suite stayed
green with its field dropped, or went red without ever naming it — both are findings about the TEST,
and both leave the tree restored, rebuilt and re-run); **2** a control could not run. **Exit 2
outranks exit 1**: "could not run" is never reported as "did not answer".
The two breaks: `MGPSurface::Layered` stops being copied in `FramebufferEmit.h`, and
`SamplerParameters::borderColorForm` in `SamplerEmit.h`. Each is patched by **regex over any
`.<field> = <expr>[;,]`**, because both headers belong to other packages (C.7: B and C) and their
spelling is theirs; the right-hand side is *replaced*, not deleted, so the record still has the
field, still asserts its size, and the break stays one the compiler cannot see.
**Restore is not enough; the rebuild is part of the contract.** Every exit after a patch goes through
`repair()` — restore from a byte-for-byte copy taken before the patch (never from git, so a dirty
tree gets its own state back), rebuild, re-run the suite — and `repair()` also runs from the `EXIT`,
`INT` and `TERM` traps, so a Ctrl-C during a rebuild cannot leave a hard-wired field in the tree. A
failed repair downgrades the verdict to 2. Both controls always run even when the first could not,
because "one emitter has landed and the other has not" is a different tree from "neither has". Logs
and backups live in `<build-dir>/p4a-g7-logs/`, never in the repository.
**On this tree it exits 2 and says why**, which is the required answer:
```
[p4a-g7] MobileGL/MG_Impl/Pipe/FramebufferEmit.h exists but assigns no .Layered.
[p4a-g7] On the P4a CONTRACT tree that is the expected answer: the contract commit creates all five
[p4a-g7] emit headers with STUB emitters (contract-v1 D1) that return 0 payload bytes and copy
[p4a-g7] nothing, and package B (clientfb) fills the body in. …
[p4a-g7] ---- G7 (P4a descriptor emission) ----
Layered (MobileGL/MG_Impl/Pipe/FramebufferEmit.h): could-not-run
borderColorForm (MobileGL/MG_Impl/Pipe/SamplerEmit.h): could-not-run
```
No patch was applied and no rebuild was needed, so nothing was left behind — verified by
`git status` after the run.
---
## 7. `.github/workflows/test.yml`
* `BASELINE: "44c2b5cf"` → **`"37da3c3a"`**, with the comment rewritten to say why the narrowing is
safe: P3a's eleven were byte-identical against `44c2b5cf` at P3a's exit, so `37da3c3a` carries the
same bodies (verified here: `p3a_untouched_regions.sh 37da3c3a HEAD` rc 0, and
`FlushPendingRangesFrom` still hashes to its `3e298c9a` pin). Both gates now answer "did anything
on the list move during **P4a**".
* **Two new `pipe-gates` rows**, `p4a_untouched_regions.sh "${BASELINE}" HEAD` and its
`--self-test`, under the **same** `feat/disaggregated`-or-`workflow_dispatch` guard the P3a rows
carry. The P3a rows stay and keep running: neither gate can be silenced by editing the other's
list.
* The push-build control step gains three `-R` alternatives — `ObjectSubsystem`,
`TextureParamsWithoutASamplerView`, `TextureUploadShape` — each the shortest string that selects
only what it means to. **`ResourceSubsystem` does not match `ObjectSubsystemControl`**: the two
families are named apart on purpose, and a filter that merged them would hide one behind the other.
That step (in `integration-verify`) is the **only** CI job that unpacks a push build, which is why
the new entries have to be there and not in the pull `integration` job.
* **The TEMPORARY trigger lines at the top of the file are untouched.**
---
## 8. Deviations, declared
| # | deviation | why |
|---|---|---|
| **F-1** | **four commits, not three.** C.5 gives three messages; `ObjectSubsystemControlScenario` and `TextureUploadShapeScenario` are in C.5's file table but under none of them | putting them under one of the two `[Test]` messages would have made the message describe something it does not. The three exact messages are present, in C.5's order, with the fourth between the second and the last |
| **F-2** | **the six ABA cases' `AbaControl` arm asserts the CORRECT pixels and says it is not a control yet**, instead of asserting the corruption | no backend keys P4a's six kinds on `{slot, gen}` *and* reads `Features.PipeHandleAbaControl`; Magma's object paths are P7 and the Espryt knob consumer is package D's file. A lane asserting a corruption nothing can produce is a permanent red on an always-on `integration-gpu` lane. §3.2 |
| **F-3** | **G9's mandatory red-before was not produced**; all four cases are green on `08192d72` | mechanically impossible through public GL on a monolith tree: the only observable of a texture parameter is a sample, and the sample repairs the state it was meant to catch. §3.4 |
| **D-N/1** | the byte-identity script gains a region **kind**; `DepthStencilSamplingReadImpl` is a namespace | D-N names it as a function; the parent's extractor finds zero definitions and exits 2 forever. §5 |
| **D-N/2** | the pinned baseline is consulted **unconditionally** | D-N says that row is compared against the `3e298c9a` pin, and the parent's fallback would never fire at P4a's base ref. Both readings agree here. §5 |
| **F-4** | `MagmaPipeArms.h` gains `MagmaPipeAbaControlCoversKind` rather than changing `MagmaPipeAbaControlDefeatsIdentity`'s behaviour | C.5 asks for the knob to defeat "P4a's memo keys on the Magma side too"; there are none to defeat. The per-kind function states that as code rather than as a comment, and is where the answer changes when a consumer appears |
| **F-5** | `build-bench` does not exist in this worktree, so C.5's benchmark verification line did not run | `wsl_tree.sh` creates three build dirs; nothing in this package touches `MG_Benchmark/` |
| **F-6** | `~/w7/p4a-trees2.log` never contained `REBUILT gates` | the file was 0 bytes with no build process running when work started, and the tree's own build dirs and per-tree logs were complete. Building proceeded from there; all three builds reconfigured and relinked cleanly, and the pull `.so` is byte-identical to `$BASE`'s, which is the check that would have caught a stale tree |
---
## 9. What the integrator must decide, and re-run on the finished tree
**Two rulings are needed before the phase verdict:**
1. **G9's missing red-before artefact (F-3).** ROADMAP.md:20 requires it by hand. The options, in the
order I would rank them: (a) accept the scenario as a regression net and record in
`MEASUREMENTS.md` that the artefact is unobtainable through public GL, with §3.4's mechanism as
the reason — this is the honest reading and it costs nothing that is real; (b) ask **package D**
(which owns `Managers.cpp`/`DirectGLES.cpp`) for an Espryt-internal probe or a one-off
instrumented run taken *before* its own change, which would produce a genuine red-before but
inside a file this package may not touch; (c) drop the requirement, recorded.
2. **The six ABA controls' arm (F-2).** Either accept that they arm when a backend wires the knob
over its P4a object slot tables — the probe is already in place and the change is one `if` — or
grant package D (or E) that one `if` explicitly, in which case the six flip to expecting the
corruption with no change to this package.
**Re-runs the integrator owes on the integrated tree** (this package integrates LAST, so all of them
run against the finished code):
| what | why it must be re-run here |
|---|---|
| `ctest --test-dir build-verify -R 'HandleRecycle'` | the six ABA cases' `Handles` arm and the seven leak cases **arm themselves** when D and E land. The leak cases are the phase's only defence against P3a's C-1 shape, on both backends |
| `ctest --test-dir build-push -R 'ObjectSubsystemControl'` and `MOBILEGL_PIPE_PUSH=0x9ff ctest -R 'ObjectSubsystemControl'` | both cases SKIP today; the On/Off A/B arms when B and C land, the refusal when D lands. The refusal lane already pins `0x9ff` itself, so D.3's separate `0x9ff` invocation is a second reading of the same thing rather than the only one |
| `ctest --test-dir build-push -R 'TextureUploadShape'` | the client half (`ctu=`) is zero today; once B lands, the `ctu == emit` assertion is live and is the client/server shape comparison D-L exists for. **Record the new numbers** — the P4a baseline is `emit=6 box=6 rect=0 jobs=6` |
| `bash scripts/p4a_descriptor_negative_control.sh build-push` | exits 2 today because both emit headers are the contract's stubs. It becomes a real G7 control the moment B and C fill them in, and it is **not** a CI lane (it rebuilds the library up to four times) |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` | this is the gate D and E can break. It is rc 0 here because nothing on the list has been touched yet |
| `ctest --test-dir build-push -R 'TextureParamsWithoutASamplerView'` | green here; after `esprytobj` it is the regression net that says the parameter sync did not move onto the sampler view |
| the full `-L integration-gpu` on the **pull** build | run here on the push build only (1072/1072). G2 wants both, and the pull build's ambient entries include the three new scenarios' skips |
**Artefacts kept** in `~/w7/notes/p4a/p4a-results/`: `p4a-handlerecycle-before.log` (180/180, the six
kinds' arms per lane), `p4a-handlerecycle-before-verbose.log` (the leak cases' live/high-water
numbers and every skip reason in full), `p4a-texparams-before.log` (G9's four cases, all green — the
D.2 evidence, such as it is), `p4a-object-subsystem-before.log` (G12 and the upload shape).
Everything else this package wrote under `~/w7` has been deleted.