Files
MobileGL/docs/Disaggregated/notes/p2/p2-results/espryt-review-v5.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

233 lines
17 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.
# Adversarial review — package `p2/espryt` (brief C.2, D13/D14/D18), result file `espryt-v5.md`, round 5
Reviewer: adversarial pass, round 5. Tree `~/w7/p2-espryt`, branch `p2/espryt`, HEAD **`0f29fa58`**,
base tag `p2/contract` (`9c6a8a25`). Read first: `~/w7/notes/p2/INTEGRATOR-DECISIONS.md` — ID-1 waives
the C.5 ownership of the six destructor sites (round-4's only major), ID-2 re-orders integration,
ID-3 fixes the G1 admitted set, ID-4 corrects the section-A commands. None of those is re-raised.
Everything below was re-run by me. The tree was left exactly as found (`git status --porcelain` →
`?? build-nolegacy/` only; `git diff --summary refs/tags/p2/contract..HEAD` → the two
`create mode 100644` lines, **no mode change**). The three source-patching negative controls were
reproduced in a **source copy** (`~/w7/rev5-nc`, deleted afterwards), never in the tree.
**Verdict: APPROVED — 0 majors, 10 minors.**
The six round-4 minors the rework named are closed for the reasons stated, the closure is
reproducible with my own scenario and my own negative controls, and no gate this tree can reach
regressed.
---
## 0. The six round-4 items, re-run
### (a) two-holder hazard — CLOSED, verified with my own scenario
`~/w7/rev5-espryt/twoholder.cpp` (kept, with its output in `twoholder-run.txt`): a standalone
program compiled with `SanityTest.cpp`'s own compile line and linked against `build-push`'s
`libMobileGL_s.a`. It uses the **real** `TextureImpl::g_backendTextureObjects`, real
`TextureObject2D`s, real `BackendTextureObject` twins over a fake GLES table that counts
`glDeleteTextures`, and the **real** `~TextureObjectBase` notice, with a counting wrapper around the
installed `StateObjectDeathOps` so the number of notices is observed, not inferred. Three holders of
kind Texture — the registry global, a by-value copy of it (`previousRegistry`'s shape), and an
independent `BackendSlotTable<ITextureObject, BackendTextureObject, Texture>` — all twin the same
object; `tex.reset()` then:
```
notice #1 kind=2 lifetimeId=1
[ok] reg.FindByHandle(h) == nullptr
[ok] copy.FindByHandle(h) == nullptr
[ok] other.FindByHandle(h) == nullptr
[ok] twinGlobal.expired()
[ok] twinOther.expired()
[ok] g_deletes == 2 # both twins ran glDeleteTextures once
[ok] slots.LiveCount(kKind) == live0 # the slot went back exactly once
[ok] MG_Pipe::MGPipeHandleIsNull(slots.FindByLifetimeId(kKind, id))
[ok] Registry::DestroyByLifetimeId(id) == false
```
Also observed: the fixture window (`saved = reg; reg = {}; …; reg = saved`) — a death inside the
window reaches the saved copy; a twin the restore drops without a `Free` still returns its slot on
the object's death (`slots.LiveCount == live0` afterwards); a transient table unlinks itself
(`HolderCount` back by one). The one `[FAIL]` lines in that output are my own wrong expectation
(`g_notices == 1`): every `TextureObject2D` death raises **two** real notices, `kind=2` (Texture)
and `kind=8` (SamplerCso, the texture's embedded `SamplerObject`, `TextureObject.h:206`) — see minor 3.
gdb on the shipped case (`break MGPipeSlotAllocator::Free`, `…::FindByLifetimeId`, `ignore`,
`info breakpoints`): `OneDeathNoticeDropsTheTwinInEveryHolderOfTheKind` → `Free` hit **2** (one per
successful notice: `object`, then the `uninvolved` cleanup), `ASavedCopyOfARealRegistry…` → `Free`
hit **1**. One `Free` per notice, never one per holder.
**NC8 (my reproduction, source copy)** — `SlotTables.h:311` `holder = next;` → `holder = nullptr;`:
exactly `OneDeathNoticeDropsTheTwinInEveryHolderOfTheKind` ("holder a kept the twin", "holder b
kept the twin"), `AWholeTableSavesResetsAndRestores`, `ASavedCopyOfARealRegistryDropsTheTwinOnTheSameNotice`
("the registry global kept the twin") fail; 15 pass. (`~/w7/rev5-espryt/nc-summary.txt`.)
The result file's correction about Magma is right: `grep -rn 'MGPipeSlots' ~/w7/p2-magma/MobileGL/MG_Backend/DirectVulkan/`
hits only the comment at `MagmaPipeArms.h:170`; there is no cross-backend holder. And each of the six
kinds has exactly one `TwinRegistry<…>` type (`Managers.h:954,1275,1366,1884,1984,2011`), so the
per-type holder list is per-kind in this backend.
### (b) caller-less "backstop" — CLOSED
`grep -rn 'ReclaimDeadSlots\|CollectGarbageNow\|CollectGarbageIfNeeded' MobileGL/ --include=*.h --include=*.cpp | grep -v DirectGLES.cpp`
→ `Managers.h:352` (comment), `:473`, `:492` (the registry's own, both `return` on the handle arm
with nothing to forward to), `SanityTest.cpp:3589` (comment). `SlotTables.h` has no
`ReclaimDeadSlots`, no `CollectGarbage*`, no `m_isCollecting`; the header now says the
teardown-dropped twin is a deliberate leak (`:64-68`).
### (c) call-site pin — CLOSED, and it catches exactly what the lane hides
**NC10 (my reproduction, source copy)** — `DirectGLES.cpp:10238` `DiagnoseEsprytSlotArm();` →
`(void)ResolveEsprytSlotTablesArm();`, rebuilt `SanityTest` **and** `MobileGLIntegrationTest`:
```
[ FAILED ] DirectGLESSlotTable.EglBringUpUnderTheArmlessKnobPairReturnsInsteadOfStopping (11 ms)
Result: died but not with expected exit code: Terminated by signal 6
EGL bring-up under MOBILEGL_PIPE_PUSH with kMGPipeSubsystemEsprytSlots clear and MOBILEGL_PIPE_LEGACY_MEMOS=0 did not RETURN: …
bring-up wrote a Fatal{} … [Linux SanityTest/FATAL]: MGPipe: Fatal{PipeLegacyMemosDisabled, …
-- same NC10 build, integration lane under the pair:
100% tests passed, 0 tests failed out of 13 skipped=13 aborted=0
```
i.e. with the round-3 regression re-applied, the ctest lane is green-by-skipping and the new
unit case is the only thing that goes red. The case runs in `build-push`, `build-verify` and
`build-nolegacy` (verdict `Handles` there, still must return: passed in isolation) and skips only
in `build-linux` (G2 parity).
### (d) fixed log path / leaked env and config — CLOSED
`ls /tmp | grep -c mobilegl-espryt` after the whole binary → `0`, in every arm run below.
`TheArmlessCasesLeaveTheLogPathAndTheConfigAsTheyFoundThem` passes with and without a pre-set
`MOBILEGL_LOG_FILE_PATH`, in isolation and shuffled. Note for the record: running the full binary
with `MOBILEGL_LOG_FILE_PATH=<file>` set never creates `<file>` — no SanityTest case other than the
armless ones writes a log line (`Log.cpp:63-75` opens the file lazily on the first write) — so the
restore is only observable through the pinning case, which is what it is there for.
### (e) sentinel arming site — MOVED as D13 says
`SlotTables.h:235` arms on the non-null `GetOrCreate` path before `Acquire`; `Managers.h:323-336`
dispatches to the table before the registry's own arming call. Pull-build codegen unchanged (G1
below: contract→HEAD `0 resized`, `.text +0`).
### (f) `HandleOf` negative memo — REMOVED
`SlotTables.h:283`: `if (!MG_Pipe::MGPipeHandleIsNull(handle)) RememberHandle(lifetimeId, handle);`.
My scenario B (real type, two holders): `other.HandleOf(tex2)` misses, `reg.GetOrCreate(tex2)`,
`other.HandleOf(tex2) == h2` → ok. **NC9 (my reproduction)** — memoise unconditionally → exactly
`ANegativeLookupIsNotCachedAcrossAnotherHoldersAcquire` fails ("the first holder kept answering the
null handle it cached before the second holder acquired"); 17 pass.
---
## 1. Section-A gates, re-run at `0f29fa58` (`CCACHE_BASEDIR=/home/swung/w7`)
All four build dirs were `ninja: no work to do` at HEAD before anything ran.
| gate | command | observed |
|---|---|---|
| **G1** | `symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | `27799 -> 27799 defined symbols: 0 added, 0 removed, 4 resized, 0 renamed`, `.text +160`; resized = `RenderState::RenderState()` +148, `SetCapability` +77, `IsCapabilityEnabled` +29, `_GLOBAL__sub_I_DirectGLES.cpp` −9 — exactly ID-3's set |
| **G1 attribution** | same, `--before ~/w7/p2-contract/build-linux/libMobileGL.so` | `0 added, 0 removed, 0 resized, 0 renamed`, `.text 10792739 -> 10792739 (+0)` |
| **G5** | `git show {48268068, refs/tags/p2/contract, HEAD}:…/DirectGLES.cpp \| awk '/namespace RenderStateImpl {/,/} \/\/ namespace RenderStateImpl/' \| sha256sum` | all `d8fd1c48…220efe27` = `~/w7/p2-before-syncrenderstate.sha` |
| **G13** | `grep -rc 'pGLContext' MobileGL/MG_Backend \| grep -v ':0$'` | empty, rc=1 |
| **G13** | `python3 scripts/check_include_closure.py` | `4 probes, 0 skipped, 0 problem(s)`, rc=0 |
| **G13** | `gen_pipe.py --check` / `--self-test` / `symbol_report.py --self-test` | rc=0 / `7 negative-control trip(s), positive control OK` / `OK (2 canned transcripts, 5 buckets, 3 gates)` |
| **G13 stdio** | `test.yml:1515-1522` alternation over `MG_Backend` + `MG_State` | 0 hits |
| C.2 grep | `OwnerEquals\|TwinLookupMemo\|g_fbSlotCache\|CollectGarbageIfNeeded` in `DirectGLES.cpp` | 37 (unchanged from v4; file untouched this round) |
| **G2** | ID-4 extraction ×4, `LC_ALL=C sort`, `diff` | `build-linux` 2385 = `build-push` 2385 = `build-nolegacy` 2385 (both diffs empty); `build-verify` 3203 |
| **G14** | `comm -23 <baseline> <pull names>` | 0 removed; 22 added = 4 contract placeholders + 18 `DirectGLESSlotTable.*` |
| unit ×4 | `ctest -L unit --no-tests=error -j 6` | `100% tests passed, 0 failed out of 1507` in **all four** |
| integration, push handle | `ctest --test-dir build-push -L integration-gpu -j 4 -R DirectGLES` | **446/446**, 50 skipped |
| integration, push legacy | same with `MOBILEGL_PIPE_PUSH=0` | **446/446**, 50 skipped |
| integration, nolegacy | | **446/446** |
| integration, pull | `build-linux` | **446/446** on the first run (v5 §5.1's two flakes did not reproduce, at load ≈45) |
| integration, verify | `build-verify -L integration-gpu -R DirectGLES` | **855/855** |
| **G4 (a)** | `build-verify -L integration-verify -j 4` | **818/818**; `Fatal{` = 0 in all ten lane logs |
| **armless red proof** | `MOBILEGL_PIPE_PUSH=0 MOBILEGL_PIPE_LEGACY_MEMOS=0 ctest --test-dir build-push -L integration-gpu -R '^DirectGLES\.CrossFrameBufferScenario'` | **`0% tests passed, 13 tests failed out of 13`**, rc=8, 13 × `Subprocess aborted`, **0 skipped** |
| armless, whole lane | same, `-R DirectGLES -j 4` | `17% tests passed, 369 tests failed out of 446`, 44 skipped (identical to v4) |
| armless, single binary | `MobileGLIntegrationTest --gtest_filter=CrossFrameBufferScenario.VertexBufferSubData` | harness comes up (`renderer: Espryt … llvmpipe`), `[ RUN ]`, exit **134** |
| **G3** | `retrace_gate.py --tree ~/w7/p2-espryt --lib build-push/libMobileGL.so -j 4 --only 'DirectGLES$'` | rc=0, **`passed 39 / 39; failed: []`** |
| **G4 (b)** | `MOBILEGL_PIPE_VERIFY=1 retrace_gate.py … --lib build-verify/libMobileGL.so …` | rc=0, **39/39**; 39 `*/*/output/mobilegl.log`: `Fatal{` 0, divergence 0, unarmed 0 |
| SanityTest | `build-push` / `MOBILEGL_PIPE_PUSH=0` / `build-nolegacy` / `build-verify` / `build-linux` | 100 / 96 + 4 skipped (the four handle-arm cases) / 99 + 1 skipped (`AnArmlessKnob…`) / 100 / 82 |
| SanityTest order | `--gtest_shuffle --gtest_random_seed={7,19,4242}` | 100/100 ×3; each of the eight new/changed slot cases also passes in isolation on push, and the relevant ones on nolegacy / legacy env |
| commits | `git log p2/contract..HEAD --format=%B \| grep -ci 'co-authored\|claude'` | 0; both new subjects `[Type] (Scope): …` + blank + `- ` bullets |
| CR/LF | `grep -c $'\r'` over all 17 touched files | 0 each |
Gates this tree cannot reach (unchanged from v4 and correctly declared in `espryt-v5.md` §3.4):
G6/G7, G8, G9 (`gen_pipe_dirty_surface.py` here accepts only `--summary`), G10, G11, G12, G14's CI
half. So `1507×4 + 446×4 + 855 + 818 + 39 + 39` is not a P2 acceptance pass; it is C's part of it.
On the "tracker gate" items in the round-5 reviewer instruction (synthetic dictionaries for six
negative controls, ten `RenderState` setters against the field-level match rule): those are package
B's deliverables (`gen_pipe_dirty_surface.py --check/--self-test`, G7), live in `~/w7/p2-tracker`
(read-only to this reviewer) and are not claimed by `espryt-v5.md`. Confirmed absent from this tree
(`--self-test` → `unrecognized arguments`); not reviewed here.
---
## 2. Minors (none blocks)
1. **`SanityTest` cannot be put on the armless pair from the environment.** `EsprytSlotArmEnvironment`
(`SanityTest.cpp:81-97`) reads `MOBILEGL_PIPE_PUSH` only; `MOBILEGL_PIPE_LEGACY_MEMOS=0` is ignored
because the binary never runs `MG_ConfigLoader`. Observed: `MOBILEGL_PIPE_PUSH=0
MOBILEGL_PIPE_LEGACY_MEMOS=0 ./build-push/…/SanityTest` → `[ PASSED ] 96` on the legacy arm,
silently. The armless cases set the knob in-process so they are unaffected; the comment's "the A/B
is one env var" is true for the bit only.
2. **`GetOrCreate`'s Gen-mismatch branch keeps the discipline `ReleaseTwinAt` was written for out.**
`SlotTables.h:230-235` holds `Entry& entry` into `m_slots` across `entry.backend.reset()` — a twin
destructor, i.e. a driver call — then writes `entry.Gen` / `entry.Live` / `entry.stateRef`;
`ReleaseTwinAt` (`:368-381`) moves the twin out first for exactly that reason. With every holder
notified the branch is unreachable in practice (my scenario C: no acquisition can land on a reset
window's slot while the object lives), so this is a consistency defect, not a live one.
3. **A texture death is two notices, not one.** Every `TextureObject2D` destruction raised
`kind=2` then `kind=8` (the embedded `SamplerObject`, `TextureObject.h:206`, `SamplerObject.cpp:29-39`)
— two `FindByLifetimeId` probes per texture death, one of which never finds a twin unless the
sampler registry twins embedded samplers. Correct, but undocumented per-death cost; belongs next
to the "no draw-path tick" sentence in `SlotTables.h:43-47`.
4. **`HandleOf`'s miss path is now an allocator hash probe every call** (`:281-283`) for an object
that is bound but never synced; round 4 cached that. Right trade for two holders, unpriced (G11,
`D.4.2/D.4.3` still owed, as v5 §6.6 says).
5. **`espryt-v5.md` §3.2 says the push handle lane had "100 (Skipped)"**; it has 50 (same as the
legacy arm, `build-nolegacy`, `build-linux`, and v4's count). Reporting slip only.
6. **G4 (a)'s lane logs: 8 of the 10 `build-verify/MobileGL/MG_IntegrationTest/*.log` carry no
`MGPipe: verify armed` line** (only `pipe-verify-arming-*.log` do). Each lane has one fixed
`MOBILEGL_LOG_FILE_PATH` opened with `"w"` per case, so the file is the last case's log — the same
shape v5 §5.1 reports to E. Package E's lane, not C's code; the brief's arming check is defined
over the retrace logs, where it is 0 unarmed.
7. **Round-4 minors left open on purpose remain open**: 3 (`build-nolegacy` still instantiates the
legacy `CollectGarbage()`: `nm -C … | grep -c` → 6), 6, 7, 10, 11, 13, 14. All declared in v5 §6.9.
8. **`SlotTables.h`'s "single-threaded" holder-list claim (`:403-404`) is an assumption, not a gate.**
It follows `BufferBackendOps::OnDestroy`'s shape (`BufferObject.cpp:38-42`) and I found no
worker thread that can hold the last `SharedPtr` of a re-keyed object; a debug-only thread-id
assert in `OnFrontendObjectDestroyed` would make the claim checkable.
9. **v5 §6.2 overstates what is left of debt #2.** With the holder list, a slot minted for a live
object cannot be re-handed during a reset window (nothing frees it while the object lives), so the
"semantic hazard" is moot in both forms, not one. Documentation only.
10. **v5 §5.1's two pull-lane flakes did not reproduce** here (446/446 at load ≈45 with another
package's lane running concurrently). Consistent with E's fixed-path collision reading, but the
integrator should not treat it as confirmed until E reproduces it.
---
## 3. Claims in `espryt-v5.md` checked and found accurate
§1's two commits, file list (all inside C.2 + ID-1), no mode change, no attribution lines; §2(a)'s
Magma correction; §2(b)'s deletions; §2(c)'s pin mechanism and NC10's lane-skip contrast (reproduced
above); §2(d)'s hygiene; §2(e)'s pull-codegen-unchanged; §2(f)'s NC9; §3.1's G1/G5/G13/G2/G14
numbers; §3.2's 1507×4, 446×4, 855, 818, 39+39, 100/96/99; §3.3's NC8–NC10 (all three reproduced
by me in a copy, with the same failing-case sets); §3.4's unreachable list.
## 4. Logs kept under `~/w7` for this review
`~/w7/rev5-espryt/{lanes-summary.txt, nc-summary.txt, twoholder.cpp, twoholder-run.txt}`. The
source copy `~/w7/rev5-nc`, both retrace output trees and every other intermediate log of this
review were deleted.
## Bottom line
The round-4 hazards are closed by construction (one notice, every holder, one free, last) and the
closure is observable from outside the package's own tests: a reviewer-written three-holder scenario
over the real Texture registry and the real destructor drops both twins and returns the slot once,
and each of the three new gates goes red for its own reason when its guard is removed — including
the call-site pin, which fails on exactly the edit that turns the integration lane green-by-skipping.
Every reachable gate holds on four build configurations with the tree left as found. Approved.