Files
MobileGL/docs/Disaggregated/notes/p5b/p5b-results/r1-codex-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

77 lines
7.2 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.
# P5b r1 — server ownership, readback byte order, retirement back-pressure
Completed 2026-09-16. Branch `p5b/r1-codex`, isolated tree
`/home/swung/w7/p5b-r1-codex`, commit
`db8b3479520862cd47c546e96506b7332158abcf`.
Base is r2 `d50183cb`, so merge r2 first or merge this branch including its ancestry.
This implements ID-73 findings 1–4; it is not another adversarial review or a phase gate.
The inherited Windows tree `/mnt/c/Users/geekerwan/p5b-r1` was at `37fc4fdb`
with three uncommitted files: `PersistentMapTracker.cpp`, `.h`, and `BufferObject.cpp`.
Their complete file contents were copied into `/home/swung/w7/p5b-r1-codex-backup/`
before continuing in this new tree. The old tree and any old Claude process were left alone.
## Changes and evidence
| Finding | Implementation | Focused evidence |
|---|---|---|
| 1: coherent map bypass | Under split, retained backend `SyncPersistentMappedRange` calls return on the apply thread. `PushAllMembers`, `PushBlocksFor`, and the final `PushMappedSpanBlock` producer refuse server-role entry with `Fatal{RoleViolation,...}`, before reading map bytes or modifying frontend content serials. Server map-state teardown keeps membership valid but does not emit client live-write state. | Real GPU store readback test now holds a coherently mapped frontend object with bytes A and a server shadow with bytes B; Ensure uploads B. A live client session also asserts the producer's named apply-thread refusal. Separately, removing only client pre-verb push calls makes both coherent-pointer pixel cases fail while backend sync sites remain intact; restoring the calls makes both pass. |
| 2: framebuffer death on client | GLES' shared frontend-death callback forwards synchronously through the existing apply-thread control mailbox before any twin destruction or binding-cache changes. This covers every kind in that callback; framebuffer still has no invented wire opcode. | Native `glDeleteFramebuffers` interception observes one deletion on the apply thread and verifies that the native draw binding becomes zero. The previously failing `DirectGLES.P4aFinalFixScenario.ARenderbufferAndItsFramebufferDeletedAfterAClearLeaveTheNextDrawIntact` now passes. |
| 3: PACK_SWAP_BYTES | After validating the tight reply, swap each requested component/packed word on the client. Apply to both direct and bounce paths, before scatter; byte types remain unchanged. `FLOAT_32_UNSIGNED_INT_24_8_REV` swaps two separate 32-bit words. | Live emit-table peer covers ushort, float, packed uint, mixed depth/stencil, and byte data with swap off/on and tight/scattered layouts; sentinel gaps are preserved. Actual GL test reads a non-symmetric ushort from RGBA16F with tight and skipped/strided pack destinations: both monolith and inproc pass. RGBA8 was deliberately avoided because expanded ushort components repeat the same byte and cannot expose a missing swap. |
| 4: applied before retired | Preserve r2's staging allocator wait and truthful wait counter unchanged. `ClientSession::EmitAndWait` now treats command-ring capacity exhaustion as back-pressure after the encoder's individual-record size check. It waits for enough retired bytes including the wrap pad, then retries the same record without changing its sequence. Shutdown/timeout gets a named `RetirementWaitFailed` instead of a silent drop or indefinite wait. | Two live-session cases hold the server between applied publication and retirement using r2's scheduling-only hook. The staging case fills 3/4 of 1 MiB twice and observes one wait. The command case positions a legal 393 KiB draw record so its successor needs a wrap pad, observes the producer parked, releases retirement, and verifies the next ordinal is exactly prior+1. |
The death callback uses the existing inproc control mailbox, not a new wire lifetime record.
P6's separate address space still needs the already-planned lifetime/control transport work.
Staging's r2 five-second shutdown-aware bound and once-per-blocked-allocation counter are intact.
The command wait uses the session's existing `kBarrierTimeoutMs` (30 seconds); individually
oversized records still fail at `PipeWireEncoder::EncodeRecord`.
## Executed acceptance
All paths below are under `/home/swung/w7/`.
- Split build completed, `CTestTestfile.cmake` verified by the build driver. Logs:
`p5b-r1-codex-config-split.log`, `p5b-r1-codex-build-split.log`,
`p5b-r1-codex-build-fixes.log`. Build concurrency was at most 8.
- Final targeted run: **10/10 passed, zero skips**, `MOBILEGL_TRANSPORT=inproc`,
`MOBILEGL_ITEST_REQUIRE_GPU=1`, `p5b-r1-codex-final-targeted.log`.
Six unit entries plus four integration entries: the six ownership/wait/swap controls,
actual ushort swap pixels, FBO/RBO deletion pixels, and two coherent-pointer draw cases.
- Actual GL ushort swap: **1/1 monolith and 1/1 inproc**, zero skips,
`p5b-r1-codex-swap-{monolith,inproc}.log`.
- Client-only push suppression: **two own pixel failures** (CTest exit 8), plus the existing
map-arm metadata case's one intentional skip. The skip is not counted as a red.
`p5b-r1-codex-coherent-red.log`; driver `p5b-r1-codex-coherent-control.sh`.
It restores the source through an EXIT trap and rebuilds the restored integration binary.
The restored two pixel cases are included in the final 10/10 run.
- `git diff --check` passed. Final worktree clean, submodule links off. Commit is a single
line without trailers, author/committer `Swung0x48 <swung0x48@outlook.com>`.
The primary negative control removes **only** `PushPersistentMapsBeforeVerb()` from the
client pre-verb hooks. It does not set the block-size-zero knob, alter the backend's retained
sync sites, or remove the new server-role guard. It therefore proves client omission is no
longer repaired by server producer re-entry.
No new all-lane census, four-flavor unit run, G1 binary comparison, full integration lane,
device operation, push, or phase review was run here: the integrator explicitly owns the
combined quick gate. All production changes outside MG_Remote are inside
`#if MOBILEGL_BUILD_DISAGGREGATED`, so pull code is structurally unaffected; this is not
reported as a new measured G1 result. No `.def`, generated catalogue, contract, or opcode changed.
## Integration notes
1. Keep r2's StageAllocate implementation, its session doorbell hookup, telemetry semantics,
and before-retire hook. This commit changes command wait policy in ClientSession only;
it does not replace r2's codec implementation.
2. Five new unit entries; the existing staged-shadow unit is strengthened to use a persistent
coherent mapping. One new ordinary integration scenario, registered for both backends;
`integration-split` remains the same 22 selected entries. The new scenario is
`PixelStoreSweepScenario.ReadPixelsSwapsUnsignedShortComponentsAndPreservesPackGaps`.
3. The known 27 inproc ordinary failures should no longer be relabeled wholesale as unchanged:
the GLES FBO/RBO deletion case is now green on this isolated tree. The merged census must
determine the new aggregate; no count was extrapolated from this single case.
Tools retained: `p5b-r1-codex-submodlinks.sh`, `p5b-r1-codex-build.sh`,
`p5b-r1-codex-coherent-control.sh`; external backup directory above. No integration worktree,
other package source/build directory, adb device, or remote ref was modified.