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

410 lines
29 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 A — `wire`, round v3. Result
The round ID-21 launched: rebase onto c0c, retire v2's local packed-target decode, **ID-19(b)** (the per-object
framebuffer table), **ID-18 M3** (acceptance returns on create and respecify) and **ID-18 M4** (the metadata
respecify). Worktree `/home/swung/w7/p4a-wire`, branch `refs/heads/p4a/wire`, **not pushed**.
**HEAD = `70e742a3`**, three new commits on top of the nine rebased ones. Only
`MobileGL/MG_Pipe/PipeApply.{h,cpp}` and two `MG_Test/Pipe/*EmitTest.cpp` are touched; nothing outside package
A's own C.7 set was opened.
---
## 0. Rebase onto `refs/heads/feat/disaggregated` = `17db7598` (c0 + c0b + **c0c**)
Clean, nine commits, **no conflicts** (c0c touches `MGPipeTypes.h`, `PipeFields.def` and
`PipeCatalogueTest.cpp`; wire owns `PipeApply.{h,cpp}` and three of the emit test files). The mapping:
| v2 | after rebase | |
|---|---|---|
| `86835b50`/`686ad38c` | `395cb841` | w1: the framebuffer + resource records |
| `bc9abfbd`/`e5038c3d` | `ed635ea5` | w2: samplers, views, unit sets |
| `0f990633`/`59bceb4c` | `0ce08d03` | w3: shader CSOs, the default uniform block |
| `3c07c8c3`/`529cb262` | `b2a53c90` | v1's test commit |
| `3c5b2d01` | `7b5b3957` | C1 + m4 + m3 |
| `026d2c48` | `fb709418` | m1 |
| `9f75fbbb` | `52a16a1e` | m5 |
| `aaad9691` | `be0e032a` | m2 + n1 + n3 |
| `6f263284` | `22a3e265` | v2's test commit |
**LFS note (ID-13).** The 92 `tools/trace_replay/fixtures/*` blobs were 132-byte POINTERS in this tree *before*
this round (mtime 12:24, the WSL restart), and `git lfs checkout` fails here — `/usr/bin/git-lfs` exists but the
repo has no `filter.lfs.smudge` configured. They are `assume-unchanged` (`git ls-files -v` → `h`), so I restored
all 92 by copying from `~/w7/base` and the working tree stayed clean (`git status --porcelain` empty,
0 pointers left). No retrace ran this round and none was needed — see §6.
## 1. The three new commits
| # | hash | items | message |
|---|---|---|---|
| 1 | `aff381c7` | **ID-19(b)** | `[Feat] (Pipe): key the framebuffer record by the framebuffer handle and resolve the two bindings through it, so a framebuffer that is named but bound to neither can still be described` |
| 2 | `282325d5` | **c0c retirement**, **ID-18 M3**, **ID-18 M4** | `[Fix] (Pipe): read a sub-data record's target halves through the contract's own accessors, answer the emitter whether a create or a respecify was accepted, and apply a respecify that restates the stored storage as a metadata update rather than a redefinition` |
| 3 | `70e742a3` | the five new cases | `[Test] (Pipe): pin what a Named framebuffer record does and does not move, the stale-generation refusal on the per-object table, the two handles it will not store, and that a respecify which redefines no storage carries the mask without eating the texels` |
`aff381c7` was verified independently (build rc 0, the seven emit suites 69/69) before `282325d5` was applied, so
the history bisects. The three items in commit 2 are one commit because they share hunks: the decode retirement
and the metadata predicate are adjacent blocks in the same anonymous namespace, and the acceptance return and the
metadata arm are the same two function bodies.
---
## 2. Item by item
### (1) c0c's accessors — v2's local decode is gone
- **`PipeApply.cpp:515-524`** — v2's `SubDataResourceTargetOf` (the local `& 0x00FF`) is **deleted**. The comment
that replaces it says the encoding is the contract's, names the three helpers, and states that nothing in this
file open-codes a half any more.
- **`PipeApply.cpp:1698`** — the m3 gate now reads `MGPipeSubDataResourceTargetOf(record.Target)` and compares
`Uint8` against `Uint8`.
- **`PipeApply.cpp:1701-1710`** — the refusal line gained the **upload half**, through
`MGPipeSubDataUploadTargetOf`: *"the record's resource target names no texture to upload into (target=%u,
resource target=%u, upload target=%u)"*. A reader no longer has to do the arithmetic the encoding exists to
stop anyone doing by hand, and the second half is what says whether an emitter packed the pair the wrong way
round. The existing case's needle stops before the parenthesis and is unaffected.
- **`TextureEmitTest.cpp:490`** — the case's hand-packed `(1u << 8) | kTex2D` is now
`MGPipePackSubDataTarget(kTex2D, 1u)`.
**Unchanged, deliberately:** `SubDataNamesABuffer` still matches the **whole field** against
`kMGPipeResourceTargetBuffer` (ID-12, and c0c's own `static_assert` is what keeps that exact), and
`MGPipeResourceRecord::PendingUpload::UploadTarget` still stores `MGPSubData::Target` **verbatim**. ID-12 gives
the high-byte decode to package D at its two match sites, and `MGPRespecifiedLevel::UploadTarget` is documented
to B as "the same packed value that level's sub-data emission uses" — changing the stored key here would silently
break that pairing. contract-v3 §4 leaves the choice to D; wire stays as ID-12 wrote it.
### (2) ID-19(b) — the framebuffer record is per object
**New in `PipeApply.h`:**
| where | what |
|---|---|
| `:156` | `kMGPipeMaxFramebufferSlots = 1u << 16` — the bounds gate the five object tables already carry |
| `:173` | `kMGPipeFramebufferTargetNamed = 3`, the **declared local** ID-21 asked for, with… |
| `:177-179` | …a `static_assert(static_cast<Uint8>(MGPipeFramebufferTarget::Count) == kMGPipeFramebufferTargetNamed)`. The day c0e lands, `Count` becomes 4 and **this fires**: the retirement cannot be forgotten |
| `:182-186` | `kMGPipeFramebufferBindingCount = 2` + a `static_assert` that `Draw == 0 && Read == 1` |
| `:397-401` | `struct MGPipeFramebufferRecord { Uint32 Gen; Bool Live; MGPFramebufferState State; }` |
| `:504` | `Vector<MGPipeFramebufferRecord> FramebufferRecords` — **beside the five object tables**, not in the working-state block |
| `:597` | `Array<MGPipeHandle, kMGPipeFramebufferBindingCount> BoundFramebuffer{}` (replaces the two `MGPFramebufferState` members) |
| `:614` | `mutable Uint64 StaleFramebufferRecordLookups = 0` |
| `:663-665` | `FramebufferRecordFor(MGPipeHandle) const`, `DrawFramebuffer() const`, `ReadFramebuffer() const`, all returning `const MGPFramebufferState*` |
**Bodies in `PipeApply.cpp`:**
- **`:2144` `MGPipeApplySetFramebufferState`.** The target gate is now `state.Target > kMGPipeFramebufferTargetNamed`
(so **3 is admitted**). Two new refusals, both `Fatal{ProtocolCorruption}` and neither counted: the **null
handle** (`{0,0}` is what "nothing is bound" reads as, so a record installed there would be answered to every
caller asking about an empty binding) and a **slot at or above the bound**. Then: the record is written at
`FramebufferRecords[state.Fbo.Slot]` **whatever the target is**; Draw/Both sets `BoundFramebuffer[Draw]`,
Read/Both sets `BoundFramebuffer[Read]`, **Named sets neither**; `++FramebufferSerial` on every applied record,
Named included.
- **`:2235` `MGPipeApplierState::FramebufferRecordFor`.** Null for a null handle (silent — that is an unbound
binding, not an error), null for a slot with no record (silent — that is every framebuffer before its first
emission), and for a **stale generation**: `++StaleFramebufferRecordLookups` and one `MGLOG_E_ONCE` naming both
generations, then null. Loud, because the only way to reach it is an emitter defect and the consequence on the
handle arm is a blit or clear into another framebuffer's attachments. Defined in the `.cpp`, not inline in the
header, so the header's include closure does not grow a logger.
- **`:2266`/`:2270` `DrawFramebuffer()` / `ReadFramebuffer()`** = `FramebufferRecordFor(BoundFramebuffer[t])`.
- **`:1176` `MGPipeApplierReset`** clears **`BoundFramebuffer` only** and keeps the table. A make-current is a
binding change; the record is an object record. Dropping the table there would lose the record of every
framebuffer that is addressed only BY NAME, because the client's re-emission on a fresh context is driven by
`MGPipeSetHashSuppressor::InvalidateAll`, which re-sends the two BOUND records and nothing else.
- **`:1222`/`:1236` `MGPipeApplierReleaseObjectRecords`** clears the table **and** the bound handles (m1
extended). Here there is nothing to outlive: the context is going away, its framebuffers are container objects
that go with it, and a table left standing would answer a lookup from the next context on a re-minted slot.
I checked c0e's in-flight `MGPipeTypes.h` in `~/w7/p4a-c0e` (uncommitted, branch still at `17db7598`) and wrote
to match it: `Named = 3`, "describes the framebuffer object it names and changes NO binding", per-object table
keyed by the handle's slot with the generation checked on lookup, a successor's record overwriting the slot.
**Nothing was cherry-picked.**
### (3) ID-18 M3 — acceptance returns on create and respecify
`Bool MGPipeApplyResourceCreate` (`PipeApply.h:800`, `.cpp:1524`) and `Bool MGPipeApplyResourceRespecify`
(`:848` / `:1576`). Contract at `PipeApply.h:786-799`, written once for all three calls: the emitter cannot see
either refusal from its call site, because a dead or stale handle is a counted no-op and a corrupt record is a
`Fatal` that deliberately moves no counter.
- **create** returns false for the reserved slot 0, a target that names no resource kind, and a slot past
`kMGPipeMaxResourceSlots`; true otherwise, dispatch or no dispatch.
- **respecify** returns false for a target that names no resource kind and for a handle with no live record at
that generation; true otherwise, **metadata updates included** — the record did move.
- Source-compatible: `PipeFill.cpp`'s P3a call sites discard the value, nothing is `[[nodiscard]]`, and
`gen_pipe.py` never parses this header (wire review W1) — `git diff -- MobileGL/MG_Pipe/generated` is rc 0 and
`gen_pipe.py --check` is rc 0.
### (4) ID-18 M4 — the metadata respecify
`RespecifyRedefinesNoStorage(stored, next)` (`PipeApply.cpp:558`), asked **before** the descriptor is replaced
(`:1595`), and its three consequences:
- `record->Desc = desc` — BindMask and ImageBindableHint take their new values (that is the whole call);
- `++record->Serial` — the entire publication; the twin re-derives its storage flags from the new mask at its
next sync and decides for itself whether the backend needs a recreate;
- `:1640` — the **third arm of the pending-upload clear**: a metadata update drops **nothing**, whatever `level`
says. This refines C1 rather than contradicting it: C1's rule drops the uploads against the storage a call
REPLACES, and a call that replaces no storage replaces no level's coordinate system.
- `MGPipeResourceRespecifyNeedsAck` is false for every such record **by construction** (`:1660-1670`), not by a
second suppression rule — see the deviation below.
**The comparison is field by field, not a memcmp** (`MGPResourceDesc` carries `Pad0`/`Pad1` and neither side is
guaranteed to have written them — the padding coin flip clientsp's sampler cache already paid for once).
### (5) The tests
Five new cases; three existing ones extended to the new shape. Every case is a visible SKIP in a pull build, so
`ctest -N` stays name-for-name identical between the pull and the push trees.
| suite | case | pins |
|---|---|---|
| `FramebufferEmit` | `ANamedRecordDescribesTheFramebufferItNamesWithoutMovingEitherBinding` (`:431`) | the Named record is found **by handle** with its attachments; **neither** binding moved (two *different* framebuffers are bound first, so it is an assertion about values and not about null); the serial moved anyway; the same object can then be bound |
| `FramebufferEmit` | `AFramebufferHandleWhoseGenerationHasMovedOnIsRefusedRatherThanAnswered` (`:488`) | stale gen → null **and** `StaleFramebufferRecordLookups + 1`, in both directions across a recycle; the null handle and an undescribed slot are **not** counted; `RefusedObjectCalls` stays 0 |
| `FramebufferEmit` | `AFramebufferRecordThatNamesNoUsableHandleIsRefusedRatherThanStored` (`:528`) | the default framebuffer `{0,1}` is the positive control; the null handle and a slot at the bound are refused by name; nothing stored, no serial, no resize |
| `TextureEmit` | `ARespecifyThatRedefinesNoStorageCarriesTheStickyMaskAndKeepsThePendingUploads` (`:687`) | the immutable `glTexStorage2D` → `glTexSubImage2D` → `glBindImageTexture` order; mask and hint land, the pending upload survives, the serial moves, `NeedsAck` is false; **with a level pointer too**; and the negative control — move one storage field and the same call drops the level |
| `TextureEmit` | `TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` (`:757`) | true on both, false on the reserved slot and on a stale generation (with `RefusedResourceCalls + 1`), and the buffer half on the same terms with no backend table registered |
Extended: `ADrawRecordAndAReadRecordAreKeptApartAndBothWritesBoth` (`:216` — Draw moves Draw only, Both moves
both, **and the two earlier framebuffers keep their own records**); `AMakeCurrentClearsBothRecordsAnd…` (`:334` —
both accessors null, both handles null, **the record survives**); `AReleaseOfTheObjectRecordsAlsoClears…`
(`:371` — `FramebufferRecords` is **empty** afterwards). `ATargetOutsideTheThreeBindings…` (`:270`) now drives
`kMGPipeFramebufferTargetNamed + 1`, because 3 is legal.
`ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` (C1's case, `:473`) was **rewritten to stay a gate**: it
now gives each respecify the descriptor the call it models would carry (`Levels` 1 → 2 as a mip build adds
level 1 — package B's `desc.Levels = mipmap->GetMipmapLevelCount()`, which is also why B's own memcmp dedupe
emits that respecify at all; and a new `InternalFormat` for the redefinition of level 1). Fed the *same*
descriptor three times, as v2 wrote it, it would have been exercising the metadata arm instead of the per-level
one. MU8 below proves C1's gate survived the restructure.
---
## 3. Deviations
**W10 — a BUFFER respecify is never classified as metadata-only, and the comparison is wider than the brief's
list.** ID-21 names the storage-defining set as InternalFormat / Width / Height / Depth / ArrayLayers / Levels /
Samples / FixedSampleLocations / StorageKind / Target / the buffer-texture fields. The implementation compares
**everything except** `BindMask`, `ImageBindableHint`, `GlNameForDiag` and the two padding words — so also
`Immutable`, `HasDefinedContent`, `Usage`, `StorageFlags` and `ViewOf` — and refuses the buffer target outright.
Two reasons, both written at `PipeApply.cpp:526-557`:
1. **Direction of the asymmetry.** Comparing too much can only mis-classify a metadata update as a redefinition,
whose cost is one level's pending upload dropped by a call B does not emit. Comparing too little
mis-classifies a REDEFINITION as metadata and keeps boxes in a coordinate system that no longer exists —
an upload past the end of the new level. None of the extra fields moves on a mask republish (B re-publishes
the same descriptor with a new mask), so the wider set costs M4 nothing.
2. **`glBufferData` at an unchanged size is the canonical ORPHANING idiom** — a real reallocation whose whole
point is that the old store is gone — and `glBufferStorage` is the one entry point allowed a synchronous ack.
Excluding the buffer target is what makes ID-18 M4's *"no reallocation ack
(`MGPipeResourceRespecifyNeedsAck` false)"* true **by construction** rather than by a second suppression rule
the transport would later have to learn: the predicate is already false for every non-buffer target. ID-18 M4
is a statement about a texture's (and a renderbuffer's) sticky mask, and a buffer has no pending upload for
the arm to protect.
**W11 — "identical storage fields clear nothing, whatever the level pointer says" is implemented literally, and
here is its one sharp edge.** A per-level respecify whose descriptor happens not to move would now keep the very
level it redefines. On the tree as built that is unreachable: B publishes `desc.Levels` from
`MipmapStorage::GetMipmapLevelCount()`, so the glTexImage\*D that defines a new level moves the descriptor, and
B's 88-byte memcmp dedupe means a respecify whose descriptor did **not** move is never emitted at all. The case
at `TextureEmitTest.cpp:687` pins the ruling as written (a metadata update with a non-null level drops nothing)
and the case at `:473` pins the other arm on the descriptors a real mip build produces. **If B's rework ever
emits a per-level respecify with a byte-identical descriptor, that level's pending upload survives the
redefinition** — worth ten lines of a reviewer's attention on B's `AllocateStorage` path, and invisible to every
gate P4a has.
W1–W6, W8 and W9 stand as v1/v2 recorded them and as the reviews accepted them. **W7′ is superseded by W11's
third arm** (the scope argument is unchanged; the metadata arm now precedes it).
---
## 4. Mutation evidence — nine mutations, nine red, each killing exactly one case
Measured in `build-push` at HEAD; each applied to `MobileGL/MG_Pipe/PipeApply.cpp`, the tree rebuilt, the seven
emit suites run (74 tests), the file restored from the commit. **The verdict is `ctest`'s exit code**, not a grep.
| # | mutation | verdict |
|---|---|---|
| MU1 | the Named arm also moves the draw binding (`Target == Draw \|\| Both` → `Target != Read`) | rc 8, 1/74 — `FramebufferEmit.ANamedRecordDescribesTheFramebufferItNamesWithoutMovingEitherBinding` |
| MU2 | the stale-generation test disarmed | rc 8, 1/74 — `FramebufferEmit.AFramebufferHandleWhoseGenerationHasMovedOnIsRefusedRatherThanAnswered` |
| MU3 | the null-framebuffer-handle refusal disarmed | rc 8, 1/74 — `FramebufferEmit.AFramebufferRecordThatNamesNoUsableHandleIsRefusedRatherThanStored` |
| MU4 | the metadata-respecify arm disarmed | rc 8, 1/74 — `TextureEmit.ARespecifyThatRedefinesNoStorageCarriesTheStickyMaskAndKeepsThePendingUploads` |
| MU5 | a refused respecify answers accepted | rc 8, 1/74 — `TextureEmit.TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` |
| MU6 | the teardown no longer drops the framebuffer records | rc 8, 1/74 — `FramebufferEmit.AReleaseOfTheObjectRecordsAlsoClearsTheWorkingHandlesThatCouldNameThem` |
| MU7 | a make-current drops the framebuffer records | rc 8, 1/74 — `FramebufferEmit.AMakeCurrentClearsBothRecordsAndAdvancesTheSerialRatherThanZeroingIt` |
| MU8 | **C1's** per-level scoping disarmed (the whole-resource clear again) | rc 8, 1/74 — `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` |
| MU9 | `resource_create` always answers accepted (the reserved-slot arm) | rc 8, 1/74 — `TextureEmit.TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` |
After each sweep the tree was restored, rebuilt and re-run: `git status --porcelain` empty, 74/74.
---
## 5. The exact applier API the other packages must call
### Package B — clientfb
1. **Emit a `Named` record at every DSA entry point that hands a framebuffer to Espryt by name** (ID-19(c)):
`BlitNamedFramebuffer`, the four `ClearNamedFramebuffer*`, and the DSA attachment / draw-buffer / read-buffer
setters at their validate point. `state.Target = static_cast<Uint8>(MGPipeFramebufferTarget::Named)` once c0e
lands; **until then `MG_Pipe::kMGPipeFramebufferTargetNamed`** (`PipeApply.h:173`, which B already includes).
The record's every other field describes the framebuffer named by `Fbo` exactly as a bound record does,
`ReadSurface` included. The rule is *"any framebuffer Espryt is about to receive by name has a record"*.
2. **The suppressor must be keyed by the framebuffer the record names, not by one global slot.** Two different
objects' Named records in a row must both go out, and a Named record must never be suppressed against the
same object's bound record or the reverse. (c0e's comment says this too; the applier cannot see the
difference, so it is B's to hold up.)
3. **`state.Fbo` may never be the null handle** — it is now `Fatal{ProtocolCorruption}`. `kMGPipeDefaultFramebuffer`
`{0,1}` for the default framebuffer, a minted `{slot, gen}` otherwise, which is what `HandleFor` already does.
4. **`MGPipeApplyResourceCreate` and `MGPipeApplyResourceRespecify` now return `Bool`.** Together with
`MGPipeApplyResourceSubData` (v2), that is D-D5 step 1's complete signal: **clear a level's
`m_isDirty`/`m_dirtyRects`/`m_dirtyRegions`, and advance the per-entry descriptor dedupe, only on true.**
Discarding compiles.
5. **`MGPipeApplyResourceRespecify`'s third parameter is still `const MGPRespecifiedLevel* level = nullptr`**
and B must pass it at every per-level respecify, with `UploadTarget` set to **the same packed
`MGPSubData::Target` value that level's sub-data emission uses** (build it with c0c's
`MGPipePackSubDataTarget`) and `Level` to the level index. `glTexStorage*`, `glBufferData`,
`glBufferStorage` and texture views pass `nullptr`.
6. **The mask republish (M4) passes `nullptr` for the level and changes only `BindMask` /
`ImageBindableHint`.** If any other descriptor field moves in the same emission the applier reads it as a
redefinition and drops that level's pending upload — see W11.
7. The refusal line for a mis-packed sub-data target now names **both halves**, so a wrong-way-round packing is
readable straight out of the log.
### Package D — esprytobj
`FramebufferImpl::PushedFramebufferRecord` (`Managers.cpp:8216-8226`) is now one call:
```cpp
const MG_Pipe::MGPFramebufferState* PushedFramebufferRecord(MG_Pipe::MGPipeHandle fbo) {
return MG_Pipe::MGPipeApplier().FramebufferRecordFor(fbo); // null = no record / stale gen
}
```
The `asTarget` parameter and the `record.Fbo == fbo` test **go**: the table is keyed by the handle, so a record
that comes back is that framebuffer's by construction, and it comes back whether the object is bound to Draw, to
Read, to both or to neither. That is C-1's fix: `SyncToBackend(fbo, Draw)` for a DSA-named framebuffer now finds
its attachments instead of declining and clearing into an unattached driver FBO.
Where D genuinely needs the **binding** question (rather than the description), it is one array compare:
`MG_Pipe::MGPipeApplier().BoundFramebuffer[static_cast<SizeT>(asTarget == FramebufferTarget::Read
? MG_Pipe::MGPipeFramebufferTarget::Read : MG_Pipe::MGPipeFramebufferTarget::Draw)] == fbo` (ID-19(d)).
Also for D: `MGPipeApplier().StaleFramebufferRecordLookups` is the counter to assert 0 in a scenario;
`MGPipeApplierReleaseObjectRecords` now empties `FramebufferRecords` as well as the bindings.
### Package E — esprytdraw
E's v2 already routed all six reads through one function, and that function is the only thing that changes.
`DirectGLES.cpp:284-287`:
```cpp
static const MG_Pipe::MGPFramebufferState* BoundFramebufferRecord(FramebufferTarget target) {
const auto& st = MG_Pipe::MGPipeApplier();
return target == FramebufferTarget::Draw ? st.DrawFramebuffer() : st.ReadFramebuffer();
}
```
— a reference becomes a **pointer**, and `const auto& st` stays const (both accessors are `const`; the stale
counter is `mutable` precisely so E keeps its shape). The seven call sites (`:2127`, `:2273`, `:2863`, `:2864`,
`:2905`, `:4009`, `:4179`) take `const auto*` and null-check. In `SyncCurrentFBOByRecord` (`:2765`) the
half-described test
```cpp
if (MGPipeHandleIsNull(st.DrawFramebuffer.Fbo) || MGPipeHandleIsNull(st.ReadFramebuffer.Fbo)) return false;
```
becomes `if (st.DrawFramebuffer() == nullptr || st.ReadFramebuffer() == nullptr) return false;` — the same
question, and it now also covers "the bound handle's record has a stale generation", which used to be
unrepresentable. `st.FramebufferSerial` is unchanged and still advances on every applied record.
### Package F — gates
`RefusedObjectCalls` must still be **0 across every framebuffer call in every build**; the framebuffer family's
own refusal counter is the separate `StaleFramebufferRecordLookups`, and **0 is the expected value there too** on
an integrated tree — a non-zero one is a seam defect, not traffic.
---
## 6. Gate transcript (HEAD `70e742a3`, working tree clean)
Run in `/home/swung/w7/p4a-wire` with `CCACHE_BASEDIR=/home/swung/w7`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, `-j 8` / `--parallel 8`.
```
build-linux / build-push / build-verify rc=0 / rc=0 / rc=0
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 rc=0
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
27072 -> 27072 normalised names, 27072 unchanged
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0)
ctest --test-dir build-linux -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-push -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-verify -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-push -R 'ResourceEmit\.|FramebufferEmit\.|TextureEmit\.|
SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.|HandleRecycle'
100% passed, 0 failed out of 130 rc=0
bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc=0
the 11 pool / deferred-release / ring / flush-drain functions are
byte-identical between 37da3c3a and HEAD
python3 scripts/check_include_closure.py --mode both --compiler clang++
--self-test --require-all rc=0
4 probes, 0 skipped, 0 problem(s); self-test 6 negative-control trips
python3 scripts/gen_pipe.py --check rc=0
477 inventory rows, 0 UNMAPPED; generated files are up to date
python3 scripts/gen_pipe.py --self-test 7 negative-control trips rc=0
python3 scripts/gen_pipe_dirty_surface.py --check rc=0
0 COARSE, 2 UNDECIDED (c0's BindVertexArray / UseProgram rows, unchanged)
python3 scripts/gen_pipe_dirty_surface.py --self-test 27 negative controls rc=0
git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
```
**ctest name sets** (`LC_ALL=C`, `ctest -N`):
```
build-linux vs build-push 2646 == 2646, 0 differing lines (G2)
vs ~/w7/p4a-before-ctest-names.txt 0 removed, 58 added, 2588 -> 2646
```
58 = c0's 13 + c0b's 1 + **c0c's 2** + wire v1's 33 + v2's 4 + **v3's 5**. Unit count 1673 (v2, on c0+c0b) →
**1680** = c0c's 2 + this round's 5.
**Not run this round, and why**: the integration / verify-scenario / retrace / APK lanes and the device arms.
This package is still behaviour-neutral — all four `kMGPipeWired*Subsystem` are 0 on this tree, nothing consumes
a P4a record, `PipeApply.{h,cpp}` are push-only translation units and G1 is 0/0/0/0. No retrace ran, so the LFS
restore in §0 was hygiene for the next round rather than a prerequisite for this one.
---
## 7. What the integrator must re-run
1. **The full five-part gate of D.3** on the merged head — nothing here substitutes for it — plus
`symbol_report --threshold 0` (P4a's admitted set is EMPTY) and `p3a_untouched_regions.sh 37da3c3a HEAD`.
2. **When c0e lands**: the `static_assert` at `PipeApply.h:177` **fires** (its `Count` becomes 4). That is the
trip wire, not a regression. Retiring it is wire's verification round: delete
`kMGPipeFramebufferTargetNamed` and its assert (`PipeApply.h:173-176`) and spell
`static_cast<Uint8>(MGPipeFramebufferTarget::Named)` at its six readers — `PipeApply.cpp:2153` (the target
gate), `FramebufferEmitTest.cpp:276`, `:443`, `:454`, and the two prose mentions at `PipeApply.h:595`/`:965`.
One constant, six sites, no behaviour change.
3. **After B lands**, three reads worth ten minutes each: (a) does B emit a Named record at **all five** DSA
entry points plus the DSA setters, and is its suppressor keyed per framebuffer (§5 B.1/B.2)? (b) does B gate
its dirty-flag clear on the three acceptance returns? (c) does the mask republish move **only** BindMask /
ImageBindableHint (W11)? None of the three is visible to any gate P4a has.
4. **After D lands**: `PushedFramebufferRecord` must lose its `asTarget` parameter and its `record.Fbo == fbo`
test, or C-1 is only half fixed — a Named record would still be refused for not being the bound one. And D's
teardown path must not read a binding after `MGPipeApplierReleaseObjectRecords`.
5. **After E's verification round**: `StaleFramebufferRecordLookups` should be **0** on the integrated tree's
scenarios. A non-zero value is the seam defect ID-19 was written to make visible, not traffic.
6. **D-K2's fourth row** (ID-15's H1) is still owed by D and F; the applier's `Fatal` on a null `BuiltinSampler`
is unchanged and correct, and the `0x5ff` lane still aborts until that row exists.
7. **The brief's D-C2** still describes the record as per bound target and **D-J4** still lists the framebuffer
records as working state; both are amended by ID-19(b) and by this round. D.5 should carry the correction
alongside c0e's.
8. **LFS**: this tree's fixtures were restored by copy from `~/w7/base` because `git lfs checkout` reports
*"Git LFS is not installed"* here — `/usr/bin/git-lfs` exists but the repo has no `filter.lfs.smudge`. A
`git lfs install --local` in each worktree would stop ID-13's trap recurring after every WSL restart.