[Docs] (.claude/skills, .github/workflows, CMakeLists.txt, docs/archive, docs/Disaggregated, docs/MobileVA, docs/Performance, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/Record, MG_Gbm, MG_Impl, MG_Impl/EGLImpl, MG_Impl/GLImpl, MG_Impl/GLXImpl, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Pipe/generated, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test/Pipe, MG_Test/Util, MG_Test/Wire, MobileGL, scripts, scripts/data, tools/device_bench, userguide): archive the planning notes and agent contracts under docs/archive

- DEBTS.md and OPEN-QUESTIONS.md stay maintained, now in docs/Disaggregated.
This commit is contained in:
2026-10-15 20:01:45 -04:00
parent 0e3e2b7761
commit aabca3c171
1035 changed files with 410 additions and 398 deletions
+434
View File
@@ -0,0 +1,434 @@
# P0.5 implementation brief — value header + artifacts header + include-closure gate
Tree: `feat/disaggregated @ 6672778b` (worktree `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`; WSL `~/w7/pipe` and the three package worktrees `~/w7/p05-value-types` / `~/w7/p05-program-artifacts` / `~/w7/p05-include-gate`, branches `p05/<slug>`, all at `6672778b`, all with a configured `build-linux/` — Release, `/usr/sbin/clang++` (clang 22; there is no `clang++-20` in WSL), ccache, `MOBILEGL_BUILD_TEST=ON`, `MOBILEGL_BUILD_INTEGRATION_TEST=ON`, `MOBILEGL_BUILD_DISAGGREGATED=OFF`, log level INFO).
Every `file:line` below was re-opened at `6672778b`; the scouts were written at `6e0e3df3` and all their line numbers still hold. Corrections to the scouts are marked **[correction]**.
---
## A. Goal and acceptance gate (verbatim)
`docs/Disaggregated/ROADMAP.md:16`:
> **P0.5** 值头与制品头抽取 | 6–9 | `MG_Pipe/MGPipeValueTypes.h`(`RenderStateParameters`、`SamplerParameters`、`PixelStoreParameters`、`VertexAttribute`… 不 include `MG_State/GLState`);`MG_State/GLState/ProgramState/ProgramArtifacts.h`(五个反射类型,不 include `ShaderObject.h`/`SpvcSession.h`,更新 7 个 includer);`Visit()` 归档 + `sizeof` 绊线;CI `-H` include 闭包断言 | **全套测试逐名不变(纯搬移);两条闭包断言绿且人为加回一个 `MG_State` include 能变红;`nm`/`.text` 变化可逐符号归因** | P0;**P1 与 P7 的硬前置**
`docs/Disaggregated/ARCHITECTURE.md:260` is the manifest: value header = `MAX_DRAW_BUFFERS`, `PerBufferBlendState`, `StencilFaceState`, `PixelStoreParameters`, `RenderStateParameters`, `SamplerParameters`, `BorderColorForm`, `VertexAttribute`, `VertexBufferBindingPoint`, "它不 include `MG_State/GLState` 任何东西"; artifacts header = `TypeFacts`, `ResourceReflection`, `XfbVarying`, `LinkArtifacts`, `SpirvArtifacts`, "只 include `<Includes.h>` 与容器". `ARCHITECTURE.md:259`: archive = `Visit()` + `static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`, one field table for both directions. `ROADMAP.md:7`: **每个门必须能因它存在的理由变红**; Windows 机器不是正确性门. `ROADMAP.md:34`: P0.5 is one of the five boundaries that owes a full `gl44to46` caselist run (CI/device, off the critical path).
Decoded: (1) no behaviour change, every existing test name still present and green (adding tests is fine); (2) two closure probes green + a negative control that goes red; (3) every `nm --defined-only -S` delta on `libMobileGL.so` explainable per symbol.
---
## B. Package split
### B.0 Decisions shared by all three packages (fixed here; do not re-decide inside a package)
| # | decision | why |
|---|---|---|
| D1 | **`DynamicBackendParameters` does NOT move.** `MGPipeTypes.h:32` keeps `#include <MG_Backend/BackendObject.h>`; the compositional assertion `MGPipeTypes.h:144-145` stays. | Not in the manifest; it has `SizeT` fields (`BackendObject.h:317,322,545`) and two member functions taking `TextureTarget` (`:487-497`) that force `TextureEnum.h`; "fixed-width members" is a type change, not a move. Escalate to the plan owner as a P1/P7 item. Consequence: probe A asserts `MGPipeValueTypes.h`, not `MGPipeTypes.h`. |
| D2 | **All eleven enums `RenderState.h:15-189` move**, including `StencilFace`, `PixelStoreParam`, `CapabilityInput`. | A split (some enums here, some there) is the maintenance trap; namespace `MobileGL` is unchanged so no spelling changes anywhere. |
| D3 | **`VertexAttribute`, `VertexBufferBindingPoint`, `VertexAttributeVersion` keep namespace `MobileGL::MG_State::GLState`** (the value header reopens it and forward-declares `class BufferObject`). **[correction** to scout-value-types §7.2, which recommended re-homing them in `MobileGL` + a `using`]. | Zero mangled-name churn for the value-types package, so the symbol report attributes 100 % of P0.5 churn to the artifacts de-nesting. Gate A is a path check; namespaces are irrelevant to it. Re-homing is a P13 cosmetic. |
| D4 | `MAX_DRAW_BUFFERS` becomes `inline constexpr Uint kMGMaxDrawBuffers = 8;` in `namespace MobileGL` (value header); `FramebufferObject::MAX_DRAW_BUFFERS` is **defined from it** (`= MobileGL::kMGMaxDrawBuffers`), so the 80 existing spellings keep working and cannot drift. `RenderStateParameters::MAX_VIEWPORTS` moves with its struct unchanged. No other new constants (**[correction]**: scout-value-types §6 `kMGMaxViewports`/`kMGMaxVertexAttribs*` are dropped). | Single definition; no `static_assert`-in-a-.cpp indirection. |
| D5 | **`LinkArtifacts::program` (`SharedPtr<glslang::TProgram>`) and `uniformInitialValues` (`Vector<glslang::TIntermediate::TUniformInitializer>`) move VERBATIM.** No `UniformInitializer` replacement in P0.5 (**[correction]** to scout-program-artifacts §6.2 item 5; recorded as the P7 follow-up). | Pure move. Both are symbol-free: `shared_ptr`'s deleter is type-erased at construction (only `ProgramLinkTask.cpp` constructs one) and `TUniformInitializer` (`include/glslang/MachineIndependent/localintermediate.h:627-636`) is an aggregate of `std::string`/`std::vector`/an unscoped enum with implicit inline special members. `<Includes.h>:80-84` makes both types complete on every side anyway. The gate pins the count of `glslang::` tokens in the header at exactly 2 so nothing new sneaks in. |
| D6 | `ProgramArtifacts.h` includes exactly `<Includes.h>` and `<set>` (`std::set<String>` at `ProgramObject.h:1331,1336`; `<set>` is in no header on the path today). | `ARCHITECTURE.md:260`. |
| D7 | `sizeof` tripwires: exact literal for POD types on every ABI (`TypeFacts` 44, `PixelStoreParameters` 28, `PerBufferBlendState` 28, `StencilFaceState` 28, `RenderStateParameters` 1168 — `MEASUREMENTS.md:86`, `ARCHITECTURE.md:188`, consistent with `MGL_RESIDUAL_BLOCK_SIZE 1248` at `MGPipeTypes.h:535`); **per-STL** numbers for container-bearing structs, asserted only under `__GLIBCXX__ && !_GLIBCXX_DEBUG` (the CI toolchain) with a `_LIBCPP_VERSION` (NDK) branch pinned by the integrator; MSVC unasserted. | `sizeof(std::string/std::set)` differs between libstdc++ and libc++ (`ARCHITECTURE.md:259` assumes one number; it cannot be one number). |
| D8 | **No `PipeFields.def` field lists for the value types in P0.5** (they need `std::array<struct>` support in `gen_pipe.py`'s comparator; `std::array::operator==` is unconstrained, so the `requires (x == y)` branch in `PipeVerify.inc:230` would hard-error); only the two comments that promise them "in P0.5" (`scripts/gen_pipe.py:163-165`, generated into `generated/PipeVerify.inc:232-238`) are re-worded to say P1. | Pure move; `MOBILEGL_PIPE_VERIFY` is not live until P1. |
| D9 | Gate skip semantics: a probe whose header does not exist prints `SKIP` and is counted; `--require-all` turns a SKIP into a failure. The negative control does not depend on either new header. CI and the ctest run **without** `--require-all` until the integrator flips it after all three packages land. | The task's "tolerate a not-yet-existing header" requirement, reconciled with `ROADMAP.md:7` (an all-skip run must not be a pass once the headers exist). |
| D10 | `.github/workflows/test.yml:3-8` triggers are NOT changed (`feat/disaggregated` is not a push trigger). The integrator runs `gh workflow run test.yml --ref feat/disaggregated` and records the run URL. | Adding the branch to the trigger list also fires the retrace jobs on every push; that is the plan owner's call, not this phase's. |
**Header paths and probe TUs (fixed contract; the gate package codes against these before the other two land):**
| probe | header (repo-relative) | probe TU text (exact) | forbidden path prefixes (repo-relative, after `normpath`) |
|---|---|---|---|
| `value-header` | `MobileGL/MG_Pipe/MGPipeValueTypes.h` | `#include <MG_Pipe/MGPipeValueTypes.h>\n` | `MobileGL/MG_State/`, `MobileGL/MG_Impl/`, `MobileGL/MG_Backend/`, `MobileGL/MG_Remote/` |
| `artifacts-header` | `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` | `#include <MG_State/GLState/ProgramState/ProgramArtifacts.h>\n` | `MobileGL/MG_State/GLState/ProgramState/ShaderObject.h`, `MobileGL/MG_Util/ShaderTranspiler/`, `MobileGL/Config.h`, `MobileGL/MG_Backend/`, `MobileGL/MG_State/GLState/BufferState/`, `MobileGL/MG_State/GLState/ProgramState/Shader` (prefix; catches `ShaderStage.h`, `ShaderCompileTask.h`, `ShaderCompileAdoptionMap.h`, `ShaderPreprocessCache.h`, `ShaderSourceKey.h`); text limit: `glslang::` ≤ 2 occurrences |
| `wire-header` (bonus, green today) | `MobileGL/MG_Remote/Transport/ITransport.h` | `#include <MG_Remote/Transport/ITransport.h>\n` | `MobileGL/Includes.h` (`WireLog.h:9-24` states the rule; `ITransport.h:33,35` include only `../Protocol/mg_protocol_base.h` and `<cstdint>`) |
The forbidden sets deliberately exclude glslang / spirv-cross / vulkan: `MobileGL/Includes.h:53,56,59,80-84,130` pulls `ska`, `xxhash`, `spirv_cross_c.h`, five glslang headers and `vulkan.h` unconditionally, and both new headers are allowed `<Includes.h>`. A "no glslang in the closure" assertion is unsatisfiable by construction; P7's criterion is `nm -D | grep glslang` on the server binary, a symbol gate.
---
### B.1 Package `p05-value-types` (tree `~/w7/p05-value-types`, branch `p05/value-types`)
**Files**
| action | file | what |
|---|---|---|
| CREATE | `MobileGL/MG_Pipe/MGPipeValueTypes.h` | the value header (layout below) |
| MODIFY | `MobileGL/MG_State/GLState/RenderState/RenderState.h` | replace `:11-12` with `#include <MG_Pipe/MGPipeValueTypes.h>`; delete `:15-370` (keep `:14 namespace MobileGL {`); `namespace MG_State { namespace GLState { class RenderState … } }` (`:372-538`) untouched |
| MODIFY | `MobileGL/MG_State/GLState/RenderState/RenderState.cpp` | add `#include <MG_State/GLState/FramebufferState/FramebufferObject.h>` after `:9` — **[correction]**: no scout saw that `RenderState.cpp:460,488,524,542,572,586` spell `MG_State::GLState::FramebufferObject::MAX_DRAW_BUFFERS` while the .cpp includes only `RenderState.h`, `Log.h`, `Types.h` (`:9-11`) |
| MODIFY | `MobileGL/MG_State/GLState/SamplerState/SamplerObject.h` | replace `:11` (`VectorTypes.h`) with `#include <MG_Pipe/MGPipeValueTypes.h>`; delete `:14-97` (keep `:13 namespace MobileGL {`; `class SamplerObject` from `:99` unchanged — it uses `SamplerParameters`, `FloatVec4/IntVec4/UintVec4`, `BorderColorForm`, all now supplied by the value header) |
| MODIFY | `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` | add `#include <MG_Pipe/MGPipeValueTypes.h>` after `:12`; delete `:17-70` (`VertexAttribute`, `VertexBufferBindingPoint`, `VertexAttributeVersion`); keep `:11 "../BufferState/BufferObject.h"` (the class at `:72+` uses `BufferObject` 6 times) |
| MODIFY | `MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h` | add `#include <MG_Pipe/MGPipeValueTypes.h>` after `:13`; `:106` → `static constexpr Uint MAX_DRAW_BUFFERS = MobileGL::kMGMaxDrawBuffers;` |
| MODIFY | `MobileGL/MG_Pipe/MGPipeTypes.h` | `:33` → `#include "MGPipeValueTypes.h"`; keep `:32` (D1); rewrite the debt comment `:24-31`: the `MG_State` half is repaid, `MGPCaps`/`DynamicBackendParameters` remains (D1) and is what still keeps gate A off `MGPipeTypes.h`; `:36-40` `using` lines unchanged except the comment `:37-38` ("now live in MGPipeValueTypes.h") |
| MODIFY | `scripts/gen_pipe.py:163-165` + regenerate `MobileGL/MG_Pipe/generated/PipeVerify.inc` | comment only: "field lists of their own in P1 (P0.5 moved the types)"; run `python3 scripts/gen_pipe.py` and commit the regenerated `.inc` (CI `pipe-gates` diffs it, `test.yml:819-827`) |
| MODIFY | `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | add the tests in "Tests" below; **must not gain any include** (`:17-18` are `"Includes.h"` + `<MG_Pipe/MGPipe.h>`; adding `RenderState.h` there would defeat the gate) |
| MODIFY (only if the build demands) | any `.cpp` that relied on `RenderState.h` transitively supplying `FramebufferObject.h`/`TextureObject.h`/`RenderbufferObject.h`/`SamplerObject.h` | add the direct include **to that .cpp**, immediately after its existing `MG_State/GLState/...` include; never re-add anything to `RenderState.h`. Candidates: the TUs including the four `MG_Util/Converters/*/RenderStateEnumConverter.h` or `MG_Util/Texture/PixelStoreProcessor.h` (`DirectGLES.cpp`, `VulkanRenderer.cpp`, `GL_Buffer.cpp`, `GL_Getter.cpp`, `GL_RenderState.cpp`, `GL_Texture.cpp`, `TextureTest.cpp`) — all also include `Core.h`, whose `:20 FramebufferState.h:12` keeps `FramebufferObject.h`, so most likely none. List every such file in the commit message. |
**`MGPipeValueTypes.h` layout** (one `namespace MobileGL` block, dependency order; every moved region is a verbatim cut, comments included):
```
// banner: copy MGPipeTypes.h:1-7, path = MobileGL/MG_Pipe/MGPipeValueTypes.h
#pragma once
#ifndef MOBILEGL_MG_PIPE_VALUE_TYPES_H // belt and braces: this file is reachable both as
#define MOBILEGL_MG_PIPE_VALUE_TYPES_H // <MG_Pipe/…> and <…> (CMakeLists.txt:531,535)
#include <Includes.h>
#include <MG_Util/Math/VectorTypes.h> // includes only <Includes.h> + <cstring> (VectorTypes.h:11,13)
#include <cstddef> // offsetof
#include <type_traits>
// PURITY: nothing from MG_State/, MG_Impl/, MG_Backend/, MG_Remote/ — scripts/check_include_closure.py
// probe "value-header" (ROADMAP P0.5; ARCHITECTURE.md:260, :501 gate A). Adding one turns CI red.
namespace MobileGL {
// GL_MAX_DRAW_BUFFERS as MobileGL advertises it. FramebufferObject::MAX_DRAW_BUFFERS is defined
// from this constant, so the two cannot drift.
inline constexpr Uint kMGMaxDrawBuffers = 8;
// RenderState.h:15-189 verbatim (11 enums, D2)
// RenderState.h:191-370 verbatim, with :263 and :273 respelled
// Array<PerBufferBlendState, kMGMaxDrawBuffers> BlendStates;
// Array<BoolVec4, kMGMaxDrawBuffers> ColorMasks;
// MEMBER ORDER UNCHANGED (DirectGLES.cpp:2070-2081 offsetof spans; PipeSpanTable.inc:34-59 names 24 members)
// SamplerObject.h:14-97 verbatim (6 enums incl. BorderColorForm : Uint8, SamplerParameters)
namespace MG_State::GLState {
class BufferObject; // BufferObject.h:61 forward-declares it the same way
// VertexArrayObject.h:17-70 verbatim: VertexAttribute, VertexBufferBindingPoint, VertexAttributeVersion
// (SharedPtr<BufferObject> members: NOT trivially copyable by design; MGPipeTypes.h:247-253 carries them as a blob)
}
// ---- trip wires (new; none existed for these before) ----
static_assert(std::is_trivially_copyable_v<PixelStoreParameters> && sizeof(PixelStoreParameters) == 28);
static_assert(std::is_trivially_copyable_v<PerBufferBlendState> && sizeof(PerBufferBlendState) == 28);
static_assert(std::is_trivially_copyable_v<StencilFaceState> && sizeof(StencilFaceState) == 28);
static_assert(std::is_trivially_copyable_v<RenderStateParameters>);
static_assert(std::is_standard_layout_v<RenderStateParameters>); // offsetof legality
static_assert(sizeof(RenderStateParameters) == 1168, "RenderStateParameters changed size; MGL_RESIDUAL_BLOCK_SIZE and the Espryt spans depend on it");
static_assert(offsetof(RenderStateParameters, BlendStates) < offsetof(RenderStateParameters, LogicOp));
static_assert(std::tuple_size_v<decltype(RenderStateParameters::BlendStates)> == kMGMaxDrawBuffers);
static_assert(std::is_trivially_copyable_v<SamplerParameters> && sizeof(SamplerParameters) == /*measure: expected 100*/);
static_assert(std::is_trivially_copyable_v<MG_State::GLState::VertexAttributeVersion> && sizeof(MG_State::GLState::VertexAttributeVersion) == 6);
} // namespace MobileGL
#endif
```
Measure a number before pinning it: compile once with `== 1`; clang/gcc print `note: expression evaluates to 'N == 1'`. If `is_standard_layout_v<RenderStateParameters>` fails (it should not: all members public, `Vec4` adds no data to `VecBase`, `VectorTypes.h:17,161`), drop that one assertion and say so in the commit — do not touch the vector types.
**Ordered steps**
1. Create the header by cutting the regions above (cut, never copy; the ODR grep in step 6 proves it).
2. Apply the five `MG_State` header edits and the `RenderState.cpp` include.
3. Apply the `MGPipeTypes.h` edit; `gen_pipe.py` comment + regenerate.
4. Build: `cmake --build ~/w7/p05-value-types/build-linux --parallel $(nproc)`. Resolve any lost-transitive-include failure by adding the direct include at the consumer (table above).
5. Add the tests; rebuild; run.
6. Verification commands (below) all green; commit as ONE commit: `[Refactor] (Pipe, State): extract MGPipeValueTypes.h - move the render-state, sampler and vertex value types and their enums out of MG_State/GLState so MG_Pipe no longer reaches RenderState.h; pure move, member order and namespaces unchanged`.
**Constraints**
- Byte-for-byte identical behaviour: no member reorder (Espryt spans `DirectGLES.cpp:2070-2081, 2660-2683`; `PipeSpanTable.inc:34-59` names 24 members by string for P2's `offsetof` table), no enum underlying-type change (`BorderColorForm : Uint8` is load-bearing for `SamplerParameters` tail padding), no `SizeT`→fixed-width widening, no renames, no namespace changes (D3), no reformatting beyond the re-indentation the cut itself needs (do not run `scripts/format_code.sh` over the touched files unless it is a no-op on the untouched ones).
- `MobileGL/MG_Backend/**` is not touched: all 51 `RenderStateParameters` uses in `DirectGLES.cpp`, the 17 in `VulkanRenderer.cpp`, the `Managers.h:1087,1825` `SamplerParameters` shadows, `Managers.h:744,788` `VertexAttribute`/`VertexAttributeVersion` compile unchanged (P1's `sed` counts at `ARCHITECTURE.md:344` depend on this — verify `grep -rc "pGLContext" MobileGL/MG_Backend | sort` is identical before/after).
- No `#include <MG_State/…>` or `<MG_Backend/…>` in the new header, ever; MG_Pipe never includes MG_State back.
- Existing test names unchanged; only additions.
**Tests to add** (`MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp`, `TEST(PipeCatalogue, …)`, no new includes):
- `ValueTypeLayoutsArePinned`: runtime `EXPECT_EQ` twins of the `sizeof`/`offsetof` static assertions above (so the numbers show up in `ctest` output on every platform, including ones where a static assertion is skipped).
- `ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail`: `offsetof(ResidualValueBlock, Pack) == sizeof(RenderStateParameters)` and `offsetof(ResidualValueBlock, CapabilityBits) == 1200` — pins that the move did not alter the carrier.
**Verification (WSL, in `~/w7/p05-value-types`)**
```
cmake --build build-linux --parallel $(nproc)
ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
ctest --test-dir build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > /tmp/vt-after.txt
ctest --test-dir ~/w7/pipe/build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > /tmp/vt-before.txt
comm -23 /tmp/vt-before.txt /tmp/vt-after.txt # must print nothing (no test name lost)
# ODR: exactly one definition each, all in the new header
grep -rn "^\s*struct \(RenderStateParameters\|PixelStoreParameters\|PerBufferBlendState\|StencilFaceState\|SamplerParameters\|VertexAttribute\|VertexBufferBindingPoint\|VertexAttributeVersion\)\b\|^\s*enum class \(BlendFactor\|BorderColorForm\|CapabilityInput\)\b" MobileGL
# purity (text)
grep -n "MG_State/\|MG_Backend/\|MG_Impl/\|MG_Remote/" MobileGL/MG_Pipe/MGPipeValueTypes.h # empty
grep -n "#include" MobileGL/MG_State/GLState/RenderState/RenderState.h # Includes.h + MGPipeValueTypes.h only
# closure (compiler; header must be self-contained)
printf '#include <MG_Pipe/MGPipeValueTypes.h>\n' > /tmp/probe_vt.cpp
clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -H -E -o /dev/null /tmp/probe_vt.cpp 2>&1 | grep -E '^\.+ ' | grep -c 'MobileGL/MG_State/\|MobileGL/MG_Backend/' # 0
clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -fsyntax-only /tmp/probe_vt.cpp
# once p05/include-gate exists (rebase onto it, or copy the script in): python3 scripts/check_include_closure.py --mode both --probe value-header
# backend read sites untouched
git diff --stat 6672778b -- MobileGL/MG_Backend # empty
# symbol report expectation for this package alone: 0 added / 0 removed / 0 resized / 0 renamed (see B.3 symbol_report.py)
python3 scripts/symbol_report.py --before ~/w7/pipe/build-linux/libMobileGL.so --after build-linux/libMobileGL.so
python3 scripts/gen_pipe.py --check
```
---
### B.2 Package `p05-program-artifacts` (tree `~/w7/p05-program-artifacts`, branch `p05/program-artifacts`)
**Files**
| action | file | what |
|---|---|---|
| CREATE | `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` | the five types + `kInvalidUniformOffset` + `VisitFields` tables + tripwires (layout below) |
| MODIFY | `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h` | commit 1: add `#include "ProgramArtifacts.h"` after `:11`; delete `:41-104` and insert the alias block; `:545-547` → `static constexpr Uint kInvalidUniformOffset = MobileGL::MG_State::GLState::kInvalidUniformOffset;` (keep the comment); delete `:1144-1171` (XfbVarying + its 2-line comment) and `:1173-1449` (the LinkArtifacts comment block, `LinkArtifacts`, the SpirvArtifacts comment block, `SpirvArtifacts`). Commit 2: delete `:14 #include <MG_Util/ShaderTranspiler/SpvcSession.h>` (the header names no `spvc_*`/`SpvReflect*`/`SpvcMetadata` symbol — verified by grep, the include line is the only match) |
| CREATE | `MobileGL/MG_Test/Program/ProgramArtifactsTest.cpp` | tests below |
| MODIFY | `MobileGL/MG_Test/Program/CMakeLists.txt` | append a `ProgramArtifactsTest` stanza copied from the complete `AsyncCompileTest` stanza (`add_executable`, `target_include_directories` with `${MGL_ROOT}/include ${MGL_ROOT}/MobileGL`, `target_link_libraries(... GTest::gtest_main ${LINK_LIBRARIES})`, its `gtest_discover_tests(... DISCOVERY_TIMEOUT 30 PROPERTIES LABELS unit)`) |
| MODIFY (commit 2, only if the build demands) | any `.cpp` that got `<spirv_reflect.h>`/`SpvcSession.h` transitively via `ProgramObject.h` | add `#include <MG_Util/ShaderTranspiler/SpvcSession.h>` **immediately after that TU's `ProgramObject.h` include line**. Candidates: `UniformManager.cpp`, `VulkanRenderer.cpp`, `ProgramInterface.cpp`, `ProgramFactory.h`, `ProgramTranslationCache.h/.cpp`, `ProgramLinkTask.h/.cpp`, `ProgramObject.cpp` (the other 17 `SpvcSession.h` includers already include it themselves) |
Includers of `ProgramObject.h` **[correction]**: 8 non-self files, in two spellings — `MG_Backend/DirectVulkan/Renderer/ProgramFactory.h:13`, `UniformManager.cpp:13`, `VulkanRenderer.cpp:17`, `MG_Impl/GLImpl/Program/ProgramInterface.cpp:11`, `ProgramLinkTask.h:11`, `ProgramTranslationCache.h:11` (as `<MG_State/GLState/ProgramState/ProgramObject.h>`), `ProgramPipelineObject.h:11`, `ProgramState.h:12` (as `"ProgramObject.h"`), plus `ProgramObject.cpp:9`. The roadmap's "7" is `ShaderObject.h`'s count. **None of the 8 needs an edit**: the in-class aliases keep every spelling (`ProgramObject::LinkArtifacts`, `ProgramObject::TypeFacts`, `ProgramObject::kInvalidUniformOffset` at `VulkanRenderer.cpp:4659,8553`, `GL_Program.cpp:1249,1304,1522`, `Core.cpp:513-514`, `ProgramSpirvTask.cpp:353,357,454`, the tests) compiling unchanged. Narrowing `ProgramTranslationCache.h`/`ProgramInterface.cpp` to the new header is a P7 follow-up, not P0.5.
**`ProgramArtifacts.h` layout**
```
// banner (copy from ProgramObject.h:1-7, path adjusted)
#pragma once
#include <Includes.h> // String/Vector/Array/UnorderedMap/SharedPtr + GL enums. DEBT NOTE (MGPipeTypes.h:24-31 style):
// Includes.h:80-84 still pulls glslang and :59 spirv_cross_c.h; this header is glslang-free BY SYMBOL
// (what P7's `nm -D | grep glslang` measures), not by preprocessed text. A textually glslang-free
// closure needs MG_Util/Types.h split off Includes.h (Types.h:11 includes it back) - out of scope.
#include <set> // std::set<String> (LinkArtifacts); NOT provided by Includes.h
// PURITY: no ShaderObject.h, no SpvcSession.h, nothing under MG_Util/ShaderTranspiler/, no Config.h, no MG_Backend/.
// scripts/check_include_closure.py probe "artifacts-header". `glslang::` appears exactly twice below (D5) and the gate pins that.
namespace MobileGL::MG_State::GLState {
// ProgramObject.h:545-547 -> namespace scope (SpirvArtifacts::reservedNumSamplesOffset defaults to it)
inline constexpr Uint kInvalidUniformOffset = ~0u;
// ProgramObject.h:41-72 verbatim struct TypeFacts
// ProgramObject.h:74-99 verbatim struct ResourceReflection
// ProgramObject.h:101-104 verbatim using UniformReflection/BlockReflection/PipeInputReflection/PipeOutputReflection
// ProgramObject.h:1144-1171 verbatim struct XfbVarying
// ProgramObject.h:1173-1393 verbatim (comment block + struct LinkArtifacts; the I5 paragraph :1184-1188 gets one added
// sentence: "m_artifacts lives in ProgramObject and is private there; the type being
// namespace-scope changes nothing about that gate")
// ProgramObject.h:1395-1449 verbatim (comment block + struct SpirvArtifacts)
// ---- the archive field tables (ARCHITECTURE.md:259): ONE table per type, serving both directions ----
// Visitor contract: v(const char* name, Field&). A visitor recurses into TypeFacts/XfbVarying/ResourceReflection
// by calling VisitFields on the element itself; the tables never recurse.
template <class Self, class V> requires std::same_as<std::remove_const_t<Self>, TypeFacts>
void VisitFields(Self& a, V&& v) { v("isArray", a.isArray); … v("basicType", a.basicType); } // 20
…ResourceReflection (14, `type` visited as a value)… XfbVarying (11)…
…LinkArtifacts: every member EXCEPT `program` (52 of 53) - `program` is null for every archived instance by
construction (ProgramTranslationCache.h:42-50) and must never be serialized…
…SpirvArtifacts (8)…
// ---- trip wires ----
static_assert(std::is_trivially_copyable_v<TypeFacts> && sizeof(TypeFacts) == 44); // 13 Bool + 3 pad + 7 x 4
#if defined(__GLIBCXX__) && !defined(_GLIBCXX_DEBUG) && (SIZE_MAX == UINT64_MAX)
#define MGL_RESOURCEREFLECTION_SIZE <measure>
#define MGL_XFBVARYING_SIZE <measure>
#define MGL_LINKARTIFACTS_SIZE <measure>
#define MGL_SPIRVARTIFACTS_SIZE <measure>
#elif defined(_LIBCPP_VERSION) && (SIZE_MAX == UINT64_MAX) && defined(MGL_ARTIFACT_SIZES_LIBCXX_PINNED)
// integrator pins these from the NDK build (see C.4); until then this branch is inert
#endif
#ifdef MGL_LINKARTIFACTS_SIZE
static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE,
"LinkArtifacts changed size: add the field to VisitFields(LinkArtifacts) (and its serializer when one exists), then update this number");
… same for the other three …
#endif
}
```
`VisitFields` is a free constrained template rather than a member so the moved struct bodies stay verbatim, and a single table serves `const` and non-`const` (`Self` deduces either).
**`ProgramObject.h` alias block** (replaces `:41-104`, stays in the public section; a fully qualified RHS is mandatory — an unqualified `TypeFacts` would self-reference):
```
using TypeFacts = MobileGL::MG_State::GLState::TypeFacts;
using ResourceReflection = MobileGL::MG_State::GLState::ResourceReflection;
using UniformReflection = ResourceReflection;
using BlockReflection = ResourceReflection;
using PipeInputReflection = ResourceReflection;
using PipeOutputReflection = ResourceReflection;
using XfbVarying = MobileGL::MG_State::GLState::XfbVarying;
using LinkArtifacts = MobileGL::MG_State::GLState::LinkArtifacts;
using SpirvArtifacts = MobileGL::MG_State::GLState::SpirvArtifacts;
```
`MAX_UNIFORM_LOCATIONS` (`:39`, glslang-bound) and the inline accessors that spell `glslang::ElmRowMajor` (`:489,:502`) / `glslang::TQualifier::layoutLocationEnd` (`:1476`) stay in `ProgramObject.h`.
**Ordered steps**
1. Commit 1 (pure move): create the header (types + `kInvalidUniformOffset` only), apply the `ProgramObject.h` cuts + aliases + re-export; build; add the test file + CMake stanza (alias/POD tests only); run. Message: `[Refactor] (Program): extract ProgramArtifacts.h - move TypeFacts, ResourceReflection, XfbVarying, LinkArtifacts and SpirvArtifacts to namespace scope with in-class aliases so every existing spelling compiles unchanged; pure move`.
2. Commit 2: drop `ProgramObject.h:14`; build; fix consumers per the table; message `[Refactor] (Program): stop ProgramObject.h including SpvcSession.h - it names no spirv-cross or SPIRV-Reflect symbol`.
3. Commit 3: the `VisitFields` tables + tripwires + the field-count tests. Message `[Feat] (Program): add the reflection-archive field tables and sizeof trip wires to ProgramArtifacts.h`.
(Three commits so the symbol report attributes churn to commit 1 only, and any `SpvcSession.h` fallout is bisectable.)
**Constraints**
- Struct bodies verbatim (D5): both glslang-typed members stay; no field added/removed/reordered/re-typed; comments move with their structs.
- Do not leave a second definition behind (the classic failure: `GLState::TypeFacts` and `GLState::ProgramObject::TypeFacts` would both compile and silently split the type). The ODR grep below must show exactly one `struct` per name.
- I5 (`ProgramObject.h:1622-1631`): `m_artifacts`/`m_spirv` stay private; `Artifacts()`/`Spirv()` remain the only readers. Nothing in this package touches `ProgramObject.cpp`, `ProgramLinkTask.*`, `ProgramSpirvTask.*`, `MG_Backend/**` (except commit 2's include lines).
- Existing test names unchanged; `MG_Test/Program/*` test binaries untouched except the new one.
**Tests** (`ProgramArtifactsTest.cpp`; first include is `<MG_State/GLState/ProgramState/ProgramArtifacts.h>`, then `<gtest/gtest.h>`, then — for the alias checks only — `<MG_State/GLState/ProgramState/ProgramObject.h>`):
- `AliasesAreTheSameTypes`: `static_assert(std::is_same_v<ProgramObject::LinkArtifacts, LinkArtifacts>)` ×5, and `ProgramObject::kInvalidUniformOffset == kInvalidUniformOffset`.
- `TypeFactsIsPodOf44Bytes`.
- `VisitFieldsCoversEveryMember` (commit 3): counting visitor → `TypeFacts` 20, `ResourceReflection` 14, `XfbVarying` 11, `LinkArtifacts` 52, `SpirvArtifacts` 8; `const` and non-`const` instances count the same.
- `SizesArePinnedOnThisToolchain`: `EXPECT_EQ(sizeof(LinkArtifacts), MGL_LINKARTIFACTS_SIZE)` under the same `#if`, plus an unconditional `RecordProperty("sizeof_LinkArtifacts", …)` (and the other three) so the number is visible in every `ctest -V` log on every platform (this is how the integrator obtains the libc++ numbers).
**Verification (WSL, in `~/w7/p05-program-artifacts`)**
```
cmake --build build-linux --parallel $(nproc)
ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
# test-name diff vs ~/w7/pipe exactly as in B.1 (comm -23 must be empty)
grep -rn "^\s*struct \(TypeFacts\|ResourceReflection\|XfbVarying\|LinkArtifacts\|SpirvArtifacts\)\b" MobileGL # 5 hits, all in ProgramArtifacts.h
grep -n "#include" MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h # <Includes.h> and <set> only
grep -c "glslang::" MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h # 2 (D5)
printf '#include <MG_State/GLState/ProgramState/ProgramArtifacts.h>\n' > /tmp/probe_pa.cpp
clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -H -E -o /dev/null /tmp/probe_pa.cpp 2>&1 | grep -E '^\.+ ' | grep -E 'ShaderObject.h|SpvcSession.h|MG_Util/ShaderTranspiler/|MobileGL/Config.h|MobileGL/MG_Backend/|BufferState/' # empty
clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -fsyntax-only /tmp/probe_pa.cpp
git diff --stat 6672778b -- MobileGL/MG_Backend MobileGL/MG_Impl # empty after commit 1 (commit 2 may add include lines)
# symbol report expectation: 0 added / 0 removed / 0 resized after --strip-scope; all churn is ProgramObject::X -> X renames
python3 scripts/symbol_report.py --before ~/w7/pipe/build-linux/libMobileGL.so --after build-linux/libMobileGL.so \
--strip-scope 'MobileGL::MG_State::GLState::ProgramObject::' --only-names 'TypeFacts,ResourceReflection,XfbVarying,LinkArtifacts,SpirvArtifacts'
```
---
### B.3 Package `p05-include-gate` (tree `~/w7/p05-include-gate`, branch `p05/include-gate`)
Compiles and passes against the base tree (probes A/B `SKIP`, C `OK`, self-test `OK`) and needs nothing from the other two packages.
**Files**
| action | file | what |
|---|---|---|
| CREATE | `scripts/check_include_closure.py` | the closure gate (spec below) |
| CREATE | `scripts/symbol_report.py` | the nm/`.text` attribution (spec below) |
| CREATE | `MobileGL/MG_Test/Purity/CMakeLists.txt` | ctest wiring (below) |
| MODIFY | `MobileGL/MG_Test/CMakeLists.txt` | after `:90 add_subdirectory(Pipe)`: a 2-line comment in the `:88-89` voice + `add_subdirectory(Purity)` |
| MODIFY | `.github/workflows/test.yml` | new job `include-graph-check` inserted after `flatc-check` (after `:323`, before `:325 benchmark`); name reserved by `ARCHITECTURE.md:568` |
**`scripts/check_include_closure.py` — specification**
- `REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))` (`gen_pipe.py:37` idiom); `argparse` with `description=__doc__`; every stdout line prefixed `include-closure: `; failures end with a GitHub `::error::` line and `sys.exit(1)` (`test.yml:829-846` house style).
- `PROBES` module-level table exactly as in B.0 (Name, Header, Tu, Forbidden, Allow=[] — policy: an allow entry needs a `Reason` string printed in the summary and a PR justification, `test.yml:831-835` — TextLimits, Why).
- Flags: `--mode {text,clang,both}` (default `text`), `--compiler PATH` (default order: `$CXX`, `clang++-20`, `clang++`, `c++`, `g++`; print which one was used), `--compile-commands PATH` (optional: take any entry whose `file` is under `MobileGL/`, keep `-D/-I/-isystem/-std`, drop `-o/-c/-MD/-MF/-MT` and the input), `--probe NAME` (repeatable), `--self-test`, `--require-all`, `--json PATH`.
- Default clang flags when no compile-commands (measured to reproduce the full-flag closure exactly, 666 lines): `-std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -H -E -o /dev/null`, cwd = `REPO_ROOT`. Before running clang mode, check `include/ska/flat_hash_map.hpp`, `3rdparty/xxHash/xxhash.h`, `3rdparty/Vulkan-Headers/include/vulkan/vulkan.h` exist; if not, fail with `run from a full checkout: git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers` (never silently downgrade).
- `-H` parsing: stderr only; accept only lines matching `^(\.+) (.*)$` (g++ appends a "Multiple include guards may be useful for:" trailer that must be discarded); depth = dot count, so the chain to a violation is reconstructed by walking back to depth−1; `path = os.path.normpath(os.path.join(cwd, path))` before prefix matching (today's output contains `TextureState/../SamplerState/SamplerObject.h`); paths outside the repo are ignored.
- Text mode: transitive walk of literal `#include` lines (there are no macro-driven includes under `MobileGL/`: 3377 includes, all literal). Resolution: `"…"` → including file's directory first; then `include/`, `MobileGL/`, `MobileGL/MG_Pipe/`, `3rdparty/xxHash/`, `3rdparty/Vulkan-Headers/include/`; unresolved = leaf. Blind to `#if`; the compiler mode is the arbiter. In `--mode both` a disagreement between the modes' violation sets is itself a failure that prints both sets.
- Second assertion per probe in clang mode: `-fsyntax-only` on the probe TU (self-contained header), reported on its own line.
- Missing header (D9): `include-closure: <probe> SKIP header not present yet: <path>`; counted in the summary; with `--require-all` a SKIP is a failure.
- Summary lines (always): `include-closure: <probe> OK|SKIP|FORBIDDEN <n> headers in closure, <m> forbidden (mode=…, cxx=…)`, then `include-closure: <k> probes, <s> skipped, <p> problem(s)`. On a violation print the chain, one hop per line, indented.
- Assert that the manifest contains both `value-header` and `artifacts-header` — deleting a probe is red.
- `--self-test` (always run by the ctest and the CI job; must not touch any tracked file — synthesize TUs in `tempfile.mkdtemp()`):
1. Negative control independent of P0.5: TU `#include <MG_Pipe/MGPipeHandles.h>\n#include <MG_State/GLState/RenderState/RenderState.h>\n` checked with the `value-header` forbidden list → must report ≥1 violation with `RenderState.h` at depth 1.
2. When `MGPipeValueTypes.h` exists: TU `#include <MG_Pipe/MGPipeValueTypes.h>\n#include <MG_State/GLState/RenderState/RenderState.h>\n` → must trip (the roadmap's literal "人为加回一个 MG_State include 能变红").
3. When `ProgramArtifacts.h` exists: TU with `#include <MG_State/GLState/ProgramState/ShaderObject.h>` added → must trip on the `artifacts-header` list; and a canned copy of the header with a third `glslang::` token must trip the text limit.
4. Parser unit checks: a canned g++ `-H` transcript with trailer lines parses to the dot lines only; a `../`-spelled path normalises and matches.
5. Each of 1-3 runs in every enabled mode. Zero violations anywhere → `::error:: negative control did not trip: the closure gate is not checking anything`, exit 1.
**`MobileGL/MG_Test/Purity/CMakeLists.txt`**
```
cmake_minimum_required(VERSION 3.14)
# The P0.5 include-closure assertions (ROADMAP P0.5; ARCHITECTURE.md:501 gate A): no MobileGL
# compilation, no GL context. Text mode only here, because this CTestTestfile also runs on the
# `test` job's runner (test.yml:149-203), which has no submodules; the compiler-backed run is the
# include-graph-check job and the developer's local `--mode both`.
find_package(Python3 COMPONENTS Interpreter)
if (Python3_Interpreter_FOUND)
add_test(NAME MobileGLPurity.IncludeClosure
COMMAND ${Python3_EXECUTABLE} ${MGL_ROOT}/scripts/check_include_closure.py --mode text --self-test)
# ctest -L unit (test.yml:198-203). NO ENVIRONMENT property: it replaces the job env (ARCHITECTURE.md:567).
set_tests_properties(MobileGLPurity.IncludeClosure PROPERTIES LABELS unit)
else()
message(STATUS "MobileGLPurity.IncludeClosure not registered: no python3 interpreter (Windows is not a correctness gate)")
endif()
```
The integrator later appends `--require-all` (C.3). The `test` job's path rewrite (`test.yml:185-196`) only touches the cmake binary path; the script's absolute path is the same on both runners.
**CI job** (insert after `test.yml:323`):
```
# P0.5 interface-purity gate A (ARCHITECTURE.md:501): the two extracted headers' include closure,
# asserted on `-H` output because `nm --undefined-only` is blind to "included but not called".
# Needs a preprocessor and three header submodules, no CMake configure, no glslang sources -
# independent of build-linux for the same reason pipe-gates is.
include-graph-check:
name: Include-closure purity gate
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v6
- name: Check out the three header submodules the closure needs
# ska/flat_hash_map.hpp, xxhash.h and vulkan/vulkan.h are the only submodule headers
# Includes.h reaches; glslang and spirv_cross are vendored under include/.
run: git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers
- name: Install clang
run: sudo apt-get update && sudo apt-get install -y clang-20
- name: Include-closure assertions and negative control
run: python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test
```
(`--require-all` appended by the integrator, C.3.)
**`scripts/symbol_report.py` — specification** (informational; `ARCHITECTURE.md:507`; name `monolith-symbol-report` from `:568`; no nm/size tooling exists in the tree today)
- `--before <.so>` `--after <.so>` `[--nm nm] [--size size] [--cxxfilt c++filt] [--markdown out.md] [--json out.json] [--strip-scope PREFIX]* [--rename-map OLD=NEW]* [--only-names A,B,…] [--threshold 0] [--self-test]`.
- Per side: `nm --defined-only -S <so>` → `{mangled: (type, size)}`; demangle via `c++filt` for the normalised key; apply `--strip-scope`/`--rename-map` textual substitutions to the demangled name (this folds `ProgramObject::LinkArtifacts` → `LinkArtifacts` everywhere, including template arguments such as `std::vector<ProgramObject::ResourceReflection>`); `size --format=sysv <so>` for `.text`/`.data`/`.bss`/Total.
- Buckets sorted by |Δ|: removed, added, resized, renamed-only (same normalised name, byte-identical size — the pure-move signature), unchanged (count). `--only-names` restricts the listing to symbols whose demangled text contains one of the names.
- Prints `symbol-report: .text B -> A (+d, +p%)` and `symbol-report: N -> M defined symbols: a added, r removed, s resized, n renamed`, then a Markdown table; always exit 0; `--fail-on-added-bytes N` reserved for a future hard gate.
- Docstring guard rails: same `CMAKE_BUILD_TYPE` on both sides (visibility presets differ, `CMakeLists.txt:578-598`), `MOBILEGL_ENABLE_LTO` OFF on both (`:108,137-146`), same compiler; print both `.so` paths and sizes in the header.
- `--self-test`: two tiny canned `nm -S` transcripts → expected buckets.
**Verification (WSL, in `~/w7/p05-include-gate`, base tree — no new headers yet)**
```
python3 scripts/check_include_closure.py --mode both --self-test # value-header SKIP, artifacts-header SKIP, wire-header OK, self-test OK, exit 0
python3 scripts/check_include_closure.py --mode both --self-test --require-all; echo exit=$? # exit 1, message names the two missing headers
python3 scripts/check_include_closure.py --mode text --self-test # exit 0 (this is what the ctest runs)
python3 scripts/check_include_closure.py --mode both --compiler g++ --self-test # trailer-line handling, exit 0
# red-for-its-reason, by hand: temporarily add `#include <MG_State/GLState/RenderState/RenderState.h>` to
# MobileGL/MG_Remote/Transport/ITransport.h -> probe wire-header FORBIDDEN with the printed chain; revert.
cmake -S . -B build-linux && ctest --test-dir build-linux -R MobileGLPurity --output-on-failure
ctest --test-dir build-linux -L unit -N | grep -c MobileGLPurity # 1 (the label reaches ctest -L unit)
python3 scripts/symbol_report.py --self-test
python3 scripts/symbol_report.py --before ~/w7/pipe/build-linux/libMobileGL.so --after build-linux/libMobileGL.so # 0/0/0/0 on an unchanged tree
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/test.yml'))" # syntax only
```
Commits: `[CI] (Purity): add scripts/check_include_closure.py - the -H include-closure gate for the P0.5 headers with an always-on negative control, wired as a unit ctest and the include-graph-check job` and `[Tooling] (Purity): add scripts/symbol_report.py - per-symbol nm/.text attribution between two libMobileGL.so builds`.
---
### B.4 File-ownership table (the guarantee that the three trees never touch the same file)
| file / glob | value-types | program-artifacts | include-gate | integrator |
|---|---|---|---|---|
| `MobileGL/MG_Pipe/MGPipeValueTypes.h` (new) | owner | – | – | – |
| `MobileGL/MG_Pipe/MGPipeTypes.h`, `scripts/gen_pipe.py`, `MobileGL/MG_Pipe/generated/*.inc` | owner | – | – | – |
| `MobileGL/MG_State/GLState/{RenderState/RenderState.h, RenderState/RenderState.cpp, SamplerState/SamplerObject.h, VertexArrayState/VertexArrayObject.h, FramebufferState/FramebufferObject.h}` | owner | – | – | – |
| `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | owner | – | – | – |
| `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` (new), `ProgramObject.h` | – | owner | – | – |
| `MobileGL/MG_Test/Program/ProgramArtifactsTest.cpp` (new), `MobileGL/MG_Test/Program/CMakeLists.txt` | – | owner | – | – |
| `scripts/check_include_closure.py`, `scripts/symbol_report.py` (new), `MobileGL/MG_Test/Purity/**` (new) | – | – | owner | – |
| `MobileGL/MG_Test/CMakeLists.txt`, `.github/workflows/test.yml` | – | – | owner | flips `--require-all` after all land |
| `MobileGL/MG_Backend/**`, `MobileGL/MG_Impl/**`, `MobileGL/MG_Util/**`, other `MG_State/**` | include-line additions only, only if the build demands, placed after the TU's existing `MG_State/GLState/...` include | include-line additions only (commit 2), placed after the TU's `ProgramObject.h` include line | – | – |
| `docs/Disaggregated/*.md` | – | – | – | owner |
| `tools/**`, `android-plugin/**`, root `CMakeLists.txt` | nobody | nobody | nobody | nobody |
The one shared-file possibility is the "include-line additions" row: the two packages add at different anchors of a TU, so the hunks do not overlap; the integrator resolves an adjacent-hunk conflict by keeping both lines.
---
## C. Integration order and what the integrator runs
C.0 Preconditions: all three branches green on their own verification lists; `~/w7/pipe` clean at `6672778b` (fixture binaries hidden as in `wsl_integrate.sh`); capture the base library: `cp ~/w7/pipe/build-linux/libMobileGL.so ~/w7/p05-before-libMobileGL.so` (Release, `/usr/sbin/clang++`, built at `6672778b` — verify with `git -C ~/w7/pipe log -1` and `grep CMAKE_BUILD_TYPE ~/w7/pipe/build-linux/CMakeCache.txt`); capture `ctest -N` names and `grep -rc "pGLContext" MobileGL/MG_Backend | sort > ~/w7/p05-before-pglcontext.txt`.
C.1 Order: **include-gate → value-types → program-artifacts.** The gate first, so probes A and B flip from SKIP to OK as each header lands and the integrator runs the real gate on each merge. The p05 trees are worktrees of `~/w7/pipe` (`git worktree list` shows them; branches are local), so the P0 helper's fetch step is unnecessary; per slug:
```
cd ~/w7/pipe && git checkout -q feat/disaggregated
git checkout -q p05/<slug> && git rebase feat/disaggregated # conflict => abort, report, stop
git checkout -q feat/disaggregated && git merge --ff-only p05/<slug>
cmake --build build-linux --parallel $(nproc) && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
python3 scripts/check_include_closure.py --mode both --self-test # after value-types: A OK; after artifacts: A+B OK
```
(`scratchpad/wf2/wsl_integrate.sh` is the P0 shape of this loop; it hard-codes `p0/` and `~/w7/p0-<slug>` and fetches — copy it to `wsl_integrate_p05.sh` with the prefix changed and the fetch removed rather than editing it.)
C.2 After all three: `python3 scripts/check_include_closure.py --mode both --self-test --require-all` (exit 0); `ctest -N` name diff against the C.0 capture (`comm -23` empty; additions listed in the merge message); `git diff --stat 6672778b -- MobileGL/MG_Backend` shows include-line additions only (or nothing); `grep -rc "pGLContext" MobileGL/MG_Backend | sort | diff - ~/w7/p05-before-pglcontext.txt` empty; `python3 scripts/gen_pipe.py --check`.
C.3 Flip the ratchet (one commit, integrator-owned): append `--require-all` to the ctest COMMAND in `MobileGL/MG_Test/Purity/CMakeLists.txt` and to the CI step in `test.yml`; message `[CI] (Purity): require both P0.5 closure probes now that the headers exist`.
C.4 Symbol report: `python3 scripts/symbol_report.py --before ~/w7/p05-before-libMobileGL.so --after build-linux/libMobileGL.so --strip-scope 'MobileGL::MG_State::GLState::ProgramObject::' --markdown ~/w7/p05-symbol-report.md`. Expected: `.text` unchanged (the library gains no code: the `VisitFields` templates are uninstantiated outside the test binary, all moved types are declarations); 0 added / 0 removed / 0 resized after normalisation; N renamed. Anything else is attributed line by line in the report before the `dev` merge. Paste the two summary lines into the merge commit. Android/libc++ sizes: build the plugin APK once (`gradle -p android-plugin :app:assemblePluginRelease`, see `apk.yml:78`) with a temporary `static_assert(sizeof(LinkArtifacts) == 1)` (and the other three) to read the values from the NDK clang notes, then pin the `_LIBCPP_VERSION` branch of `ProgramArtifacts.h` and define `MGL_ARTIFACT_SIZES_LIBCXX_PINNED` there; message `[Test] (Program): pin the libc++ artifact sizes`.
C.5 CI and docs: `gh workflow run test.yml --ref feat/disaggregated` (and `apk.yml` if dispatchable) — record run URLs; `include-graph-check`, `pipe-gates`, `test` green. Then docs (integrator-owned): `docs/Disaggregated/README.md:3` status → P0.5 landed with the commit hash; `ROADMAP.md:16` ✅ with the "7 includers" wording corrected to "8 includers, none edited (in-class aliases)"; `ARCHITECTURE.md:260` note that `DynamicBackendParameters` stayed (D1) and its `:563` stale citation `MG_Test/CMakeLists.txt:93-95` → `:100-103`. Then `[Merge]` to `dev` per the milestone flow, and schedule the full `gl44to46` caselist (`ROADMAP.md:34`) on the two devices per the Wave-7 protocol — device time, not on the integration critical path.
---
## D. Risks and mitigations
| risk | mitigation |
|---|---|
| **ODR — a struct copied, not moved.** Two same-named definitions in `namespace MobileGL` (value types) compile per-TU and silently break Espryt's `offsetof` shadow if they drift; for the artifacts, `GLState::TypeFacts` vs `GLState::ProgramObject::TypeFacts` compile as two different types. | The per-package ODR greps (exactly one `struct X` per name) are mandatory verification, and the alias `static_assert(is_same_v<…>)` in `ProgramArtifactsTest.cpp` catches the artifacts case at compile time. |
| **Include cycles.** MG_State now includes MG_Pipe (`RenderState.h`, `SamplerObject.h`, `VertexArrayObject.h`, `FramebufferObject.h` → `MGPipeValueTypes.h`). | `MGPipeValueTypes.h` includes only `<Includes.h>`/`VectorTypes.h` and forward-declares `BufferObject`; the gate makes any MG_State include in it red; MG_Pipe is "永远进构建" and below MG_State (`ARCHITECTURE.md:550-561`), so the direction is the intended one. `ProgramArtifacts.h` includes nothing from `ProgramState/`, so `ProgramObject.h → ProgramArtifacts.h` cannot cycle. |
| **Lost transitive includes.** `RenderState.h` stops dragging `FramebufferObject.h → TextureObject.h → RenderbufferObject.h → SamplerObject.h …` (8 headers) into the 73 `Core.h` consumers and its 5 direct includers; `ProgramObject.h` (commit 2) stops dragging `SpvcSession.h`/`<spirv_reflect.h>`. | Only the compiler enumerates the fallout; the rule is "add the direct include at the consumer, never at the forwarding header", one anchor per package (B.4), listed in the commit message. `RenderState.cpp` is the one known case (fixed in the package). |
| **MSVC / Android not built locally.** `test.yml` builds Linux only (clang-20, `build-linux`); `apk.yml` builds the NDK APK; neither runs on `feat/disaggregated` pushes; the Windows box is not a correctness gate. | Nothing in P0.5 is platform-specific: no `SizeT` widening (D1/D5), no language feature beyond C++20 constraints (`requires std::same_as`; fine on MSVC 19.3x and NDK r27 clang), `offsetof` on `RenderStateParameters` is already compiled on all three toolchains by `DirectGLES.cpp`. Container-bearing `sizeof` assertions are libstdc++-only until the integrator pins libc++ (C.4); MSVC is unasserted. The integrator's `workflow_dispatch` of `apk.yml` is the Android build gate; a `cmake --build` in the Windows worktree before the `dev` merge is cheap and recommended, not required. |
| **glslang types leaking by value in the archive.** `LinkArtifacts::program` and `uniformInitialValues` keep glslang types (D5). | Symbol-free by construction (type-erased deleter; aggregate with inline implicit members); the gate pins `glslang::` at exactly 2 occurrences in `ProgramArtifacts.h`, so a third leak is red; `VisitFields(LinkArtifacts)` excludes `program` and the future deserializer must assert it null (`ProgramTranslationCache.h:42-50` already asserts that at insert). The `UniformInitializer` re-typing is the recorded P7 follow-up, together with narrowing `ProgramTranslationCache.h`/`ProgramInterface.cpp` to the new header and moving `MAX_UNIFORM_LOCATIONS`' glslang RHS behind a client-side assert. |
| **`PipeInputs` (P1) needs.** `ARCHITECTURE.md:328`: accessors return "exactly the types the backend reads today"; `:344`: 293 `pGLContext->` sites + 58 non-arrow lines are `sed`'d mechanically; `ResidualValueBlock` needs `offsetof` computability; `MOBILEGL_PIPE_VERIFY` keeps its `MG_State` includes (`:369`). | D3 keeps every type's qualified name; the value header keeps standard layout and asserts it; `MG_Backend/**` is diff-empty apart from possible include lines; the `pGLContext` count is captured before/after (C.0/C.2); the value header coexists with `MG_State` includes (no mutual exclusion). `PipeFields.def` field lists for the value types are P1 work (D8), and `MEMCMP_FALLBACK_TYPES` in `gen_pipe.py:166-171` stays as is until then. |
| **`RenderStateParameters` is about to change in P2** (`FramebufferSrgb`/`DepthClamp` storage, `ROADMAP.md:18,78`), moving `sizeof` off 1168. | After P0.5 every 1168-dependent number lives in exactly two places: the value header's assertions and `MGL_RESIDUAL_BLOCK_SIZE` (`MGPipeTypes.h:535`); the test twins name both. P2 updates both in one commit. |
| **A gate that is green because it never ran.** `feat/disaggregated` is not a trigger branch (`test.yml:3-8`); a mislabelled ctest never runs under `ctest -L unit`. | `LABELS unit` verified by `ctest -L unit -N`; the ctest runs in every local build; the integrator dispatches the workflow and records the URL (D10); `--self-test` is always on, so a broken parser cannot pass silently; `--require-all` after integration makes SKIP red. |
| **`#pragma once` with two include spellings** (`<MG_Pipe/X.h>` and `<X.h>`, `CMakeLists.txt:531,535`) on case-insensitive/symlinked Windows worktrees. | The macro guard in `MGPipeValueTypes.h`. |
| **`nm` attribution looks catastrophic** because de-nesting renames every mangled name mentioning the five artifact types (including every `std::vector<…>` instantiation). | `symbol_report.py --strip-scope` folds them into the renamed-only bucket with byte-identical sizes; the value-types package contributes zero churn by D3, so the two packages are separable in the report by construction. |
+24
View File
@@ -0,0 +1,24 @@
# P0.5 — 值头与制品头抽取(`5d99ee43`)
> 本页是该阶段的**阶段汇总**:阶段表行、实测与落地形状的完整文本(2026-09-24 从上层索引移入,原文照录)都在这里;上层只留摘要——[`ROADMAP.md`](../../../Disaggregated/ROADMAP.md)、[`MEASUREMENTS.md`](../../../Disaggregated/MEASUREMENTS.md)、[`ARCHITECTURE.md`](../../../Disaggregated/ARCHITECTURE.md)。文中 `file:line` 与"今天""当前"按各段写成时的头理解;文中的 `MEASUREMENTS.md §N` / `ARCHITECTURE.md §17.x` 编号保留,对照表见 [`../README.md`](../README.md)。
## 摘要
- 落地:`MG_Pipe/MGPipeValueTypes.h`(不 include `MG_State/GLState`)、`ProgramArtifacts.h`、`Visit()` 归档 + `sizeof` 绊线、CI `-H` include 闭包断言(`scripts/check_include_closure.py`)与 `scripts/symbol_report.py`。
- 门:测试名零删除、`.text` 不变、符号 0 增 / 0 删 / 42 重命名。没有这一步,server 不链 glslang 的判据不可达。
## 阶段表行(原 `ROADMAP.md`)
- **阶段**:**P0.5** 值头与制品头抽取
- **状态**:✅ `5d99ee43`
- **落地什么 / 范围**:`MG_Pipe/MGPipeValueTypes.h`;`ProgramArtifacts.h`;`Visit()` 归档 + `sizeof` 绊线;CI `-H` include 闭包断言(`scripts/check_include_closure.py`)+ `scripts/symbol_report.py`
- **验收门 / 证据**:测试名零删除、`.text` 不变、符号 0 增 / 0 删 / 42 重命名
## 本目录
| 文件 | 内容 |
|---|---|
| [`BRIEF-P05.md`](BRIEF-P05.md) | P0.5 implementation brief — value header + artifacts header + include-closure gate |
| [`p05-results/`](p05-results/) | 6 个文件:三个包(value-types / program-artifacts / include-gate)的实现与评审稿 |
捞回的独有材料:[`../recovered/wf3/`](../recovered/wf3/)(四份 scout)。
@@ -0,0 +1,95 @@
# Adversarial review — package `p05-include-gate` (v1)
Tree `~/w7/p05-include-gate`, branch `p05/include-gate` = `fe3dc1dd` + `2318f6ae` on `6672778b`.
Reviewer stance: refute "correct, complete, pure, meets the brief (A, B.0, B.3, C, D)".
Verdict: **approved — 0 majors, 9 minors.** Tree left exactly as found (`git status --porcelain --untracked-files=all | grep -v build-linux/` empty before and after every experiment).
All scripts used are under `scratchpad/wf3/p05-include-gate-review/s01..s07.sh`; long outputs under `~/w7/review-p05g/`.
## 1. Scope and purity of the diff
`git diff --stat 6672778b..HEAD` = exactly the five B.4-assigned files, 1089 insertions, 0 deletions:
`.github/workflows/test.yml` (+26), `MobileGL/MG_Test/CMakeLists.txt` (+3), `MobileGL/MG_Test/Purity/CMakeLists.txt` (+15), `scripts/check_include_closure.py` (+659), `scripts/symbol_report.py` (+386).
`git diff --stat 6672778b -- MobileGL/MG_Backend MobileGL/MG_State MobileGL/MG_Pipe` empty. No fixture binaries. No CRLF (`xargs grep -lU $'\r'` empty). No attribution trailers in either commit message (`git log --format=%B | grep -i "co-authored\|signed-off"` empty); subjects are `[Type] (Scope): …` with `- ` bullets.
No C++ was added, so "copied vs moved", member order, alignment, constexpr-ness and static_assert coverage are not applicable to this package; the symbol report on the rebuilt library is 0/0/0/0 (section 3).
## 2. Spec conformance (B.3) — line-by-line against `scripts/check_include_closure.py`
| B.3 item | where | verdict |
|---|---|---|
| `REPO_ROOT` idiom, `description=__doc__`, `include-closure: ` prefix, `::error::` + exit 1 | `:62,:64,:161-166,:544,:651-653` | as specified |
| `PROBES` table with Name/Header/Tu/Forbidden/Allow/TextLimits/Why, values identical to B.0 | `:72-118` | byte-compared against the B.0 table: identical (six forbidden prefixes for artifacts incl. the `ProgramState/Shader` prefix, `glslang::` ≤ 2) |
| flags `--mode/--compiler/--compile-commands/--probe/--self-test/--require-all/--json` | `:546-558` | all present; default mode `text` |
| compiler order `$CXX, clang++-20, clang++, c++, g++`, printed | `:141,:286-303,:591` | as specified |
| default flags = the measured 6, cwd = REPO_ROOT | `:125-132,:576` | identical to the brief's line |
| prereq check that refuses rather than downgrades | `:135-139,:340-345` | verified: without the submodules, `--mode clang` exits 1 with the exact `git submodule update --init …` message (s06) |
| `-H` parse: stderr only, `^(\.+) (.*)$`, normpath, outside-repo ignored | `:156,:169-194,:348-352` | as specified; g++ trailer verified live and by canned transcript |
| text mode: literal walk, `"…"` includer-dir first then the 5 search dirs, unresolved = leaf | `:145-151,:197-241` | as specified |
| `--mode both` disagreement is a failure printing both sets | `:624-631` | verified (experiment B3) |
| `-fsyntax-only` second assertion, own line | `:410-424,:632-634` | verified |
| SKIP semantics + `--require-all` | `:603-615` | verified (section 4) |
| manifest assertion for both required probes | `:121,:561-566` | present |
| self-test 1–5, tempdir only, never touches a tracked file | `:431-540,:572` | verified incl. controls 2/3 and the third-`glslang::` control, which only arm when the headers exist (experiments B1, C1) |
| CMake stanza | `MG_Test/Purity/CMakeLists.txt` | verbatim to the brief; inserted after `add_subdirectory(Pipe)` at `MG_Test/CMakeLists.txt:91-93` |
| CI job after `flatc-check`, before `benchmark`, steps verbatim | `test.yml:325-349` | YAML parses (Windows PyYAML): 13 jobs, neighbours `['flatc-check','include-graph-check','benchmark']`, no `needs`, triggers untouched (D10) |
`scripts/symbol_report.py`: every flag in the spec list exists (`:269-289`); `nm --defined-only -S` / `c++filt` / `size --format=sysv` (`:131-138`); buckets sorted by |Δ| (`:189-191`); the two summary lines + Markdown (`:324-363`); always exit 0 (`:382`); guard rails in the docstring (`:24-31`); `--self-test` with two canned transcripts (`:209-263`).
Declared deviations (result file §3, items 1–6) were each checked and are accepted: `--strip-scope` de-nesting is the only semantics that produces the fold the brief asks for (a literal prefix delete would put the two spellings in removed/added); one SKIP line per probe; disagreement check on probes only; the extra normalised-names line; local clang 22/g++ 16 vs CI clang-20; cosmetic YAML spacing.
## 3. Independent re-run of the verification list (all in `~/w7/p05-include-gate`, s04)
```
cmake --build build-linux -j 16 -> [47/47] … (incremental, clean)
ctest --test-dir build-linux -L unit --no-tests=error -j 8
-> 1459 tests, 0 failed (2 skipped LogLevel.* as on base)
ctest -N name diff vs ~/w7/pipe/build-linux -> lost: (none); added: MobileGLPurity.IncludeClosure ; 1327 -> 1328
ctest --test-dir build-linux -L unit -N | grep -c MobileGLPurity -> 1
python3 scripts/gen_pipe.py --check -> generated files are up to date, exit 0
python3 scripts/check_include_closure.py --mode both --self-test -> exit 0, "3 probes, 2 skipped, 0 problem(s)", 2 trips
python3 scripts/check_include_closure.py --mode text --self-test -> exit 0, 1 trip
python3 scripts/check_include_closure.py --mode both --self-test --require-all -> exit 1, two "SKIP is a failure under --require-all" lines
python3 scripts/check_include_closure.py --mode both --compiler g++ --self-test -> exit 0, 2 trips
python3 scripts/symbol_report.py --self-test -> OK (2 canned transcripts, 5 buckets)
python3 scripts/symbol_report.py --before ~/w7/pipe/build-linux/libMobileGL.so --after build-linux/libMobileGL.so
-> .text 10792579 -> 10792579 (+0); 27799 -> 27799 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed; 27060 unchanged
ODR grep (8 value-type structs) -> 8 hits, all still in MG_State (nothing moved by this package, as expected)
git status -> clean
```
Generated CTestTestfile (`build-linux/MobileGL/MG_Test/Purity/CTestTestfile.cmake`): `add_test(MobileGLPurity.IncludeClosure "<python3>" ".../MobileGL/MG_Test/../../scripts/check_include_closure.py" "--mode" "text" "--self-test")`, `LABELS "unit"`, no ENVIRONMENT. `build-linux/MobileGL/MG_Test/CTestTestfile.cmake:20 subdirs("Purity")`, and the runtime tarball packs `${BUILD_DIR}/MobileGL/MG_Test` whole (`test.yml:126`), so the `test` job's `ctest -L unit` reaches it the same way it reaches `Pipe`.
## 4. Gate semantics and red-for-its-reason (s05, every edit restored by an EXIT trap)
**A. Manual negative control on the live probe.** `sed` inserted `#include <MG_State/GLState/RenderState/RenderState.h>` after `ITransport.h:35`; `--mode both --probe wire-header` → exit 1, both modes `wire-header FORBIDDEN … 1 forbidden` with the identical 3-hop chain `ITransport.h → RenderState.h → Includes.h` (76 / 672 headers in closure vs 2 / 42 clean). `git checkout --` restored; 0 dirty lines.
**B. Probe A exercised with a scratch `MobileGL/MG_Pipe/MGPipeValueTypes.h`** (never run before; deleted afterwards):
- pure (`<Includes.h>`, `<MG_Util/Math/VectorTypes.h>`, `<cstddef>`, `<type_traits>`): `value-header OK 66 / 654 headers, 0 forbidden`, SELF-CONTAINED OK, **control-2 arms and trips in both modes** (9 violations, RenderState.h at depth 1), `3 probes, 1 skipped, 0 problem(s)`, exit 0. So the B.0 forbidden set is satisfiable with `Includes.h` in the closure, and the brief's layout will go green.
- `RenderState.h` added back: both modes `FORBIDDEN … 9 forbidden`, chain printed, exit 1 — the roadmap's literal red.
- `<MG_Backend/BackendObject.h>` (the D1 route): `FORBIDDEN … 2 forbidden` both modes — the gate would catch `DynamicBackendParameters` being moved after all.
**C. Probe B exercised with a scratch `ProgramArtifacts.h`** (`<Includes.h>`, `<set>`, exactly two `glslang::`): `artifacts-header OK 65 / 653, 0 forbidden`, SELF-CONTAINED OK, control-3 trips in both modes (16 violations, ShaderObject.h at depth 1), text-limit control trips (`glslang:: occurs 3 times, budget is 2`), exit 0. Then `#include "ShaderObject.h"` (quoted spelling) → `FORBIDDEN … 16 forbidden` with chain; a third `glslang::` in a comment → `FORBIDDEN`, `text limit: glslang:: occurs 3 times`. `MobileGL/Config.h` is not reached via `Includes.h` (0 forbidden), so the Config.h rule is satisfiable too.
**D. CI file-set simulation** (s06): tracked files of `MobileGL include scripts` only + the three submodules linked in (exactly what `include-graph-check` sees) → `--mode both --self-test` exit 0 with the same 42-header wire closure and 2 trips. Every header the closure reaches outside the submodules (`include/EGL/egl.h`, `include/GL/*`, `include/GLES3/gl32.h`, `include/glslang/*`, `include/spirv_cross/spirv_cross_c.h`) is `git ls-files`-tracked, so the job does not depend on `update_glslang_sources.py` or system GL headers. Same set without the submodules (the `test` job's checkout) → `--mode text --self-test` exit 0, and `--mode clang` refuses with the submodule message. `apt-get install -y clang-20` is the same mechanism `build-linux` already uses (`test.yml:61`), so the install step is no less reliable than the existing lane.
## 5. Majors
None.
## 6. Minors (none blocks; ordered by usefulness to the integrator)
1. **`flags_from_compile_commands` corrupts a two-token `-isystem DIR`** (`check_include_closure.py:327-330`): the path token is dropped and the bare `-isystem` then swallows the next flag. Repro: canned entry `-DFOO=1 -isystem /opt/sys/include -I…/MobileGL -std=gnu++23` → `['-DFOO=1', '-isystem', '-I/…/MobileGL', '-std=gnu++23']`. Latent here: this tree's `compile_commands.json` uses no `-isystem` (Init.cpp entry checked), and neither CI nor the ctest passes `--compile-commands`. Fix: treat `-isystem` like `-o` (keep both tokens).
2. **`--require-all` only inspects selected probes**: `--mode text --probe wire-header --require-all --self-test` → exit 0 (`1 probes, 0 skipped, 0 problem(s)`) with both P0.5 headers absent (`main:593-615`). Not reachable from the CI/ctest command lines, which never pass `--probe`, but the ratchet has a hole for a hand-run. `--probe value-header --require-all` correctly exits 1.
3. **Text-only ctest lane has no arbiter for `#if`-guarded includes**: an `#if 0`-guarded `RenderState.h` include in the value header gives `FORBIDDEN 9 forbidden` in text mode and `OK` in clang; `--mode both` reports MODE DISAGREEMENT (2 problems). This is the brief's design, but it means the unit ctest can go red for something the compiler never includes. Rule for the two header authors: no conditionally compiled includes of forbidden paths, ever.
4. **`count_text_limits` counts comments** (`:272-283`): the brief's own suggested comment line for `ProgramArtifacts.h` ("`glslang::` appears exactly twice below (D5)") is itself a third token and turns probe B red (experiment C2). The program-artifacts author must spell it without the `::`, or the integrator sees a spurious FORBIDDEN on the first real run.
5. **`tempfile.mkdtemp` is never removed** (`:572`); two `/tmp/mgl-include-closure-*` directories were left behind by the review runs. Harmless on CI runners; a `shutil.rmtree` in a `finally` would do.
6. **ERROR + disagreement interplay**: when clang-mode preprocessing fails for a probe, `run_probe` returns `set()` (`:387`) and the disagreement check (`:624-631`) can print a spurious MODE DISAGREEMENT on top of the ERROR. Cosmetic; the run is red either way.
7. **`symbol_report.py` folding hides a count change**: with `--strip-scope`, the copied-not-moved case (both `ProgramObject::LinkArtifacts::Reset()` and `LinkArtifacts::Reset()` present after) surfaces as `resized +16`, not `added`, and the per-name `count` (1→2) is not in any table (`:150-157,:161-192`). Visible, but mislabelled; the ODR grep stays the primary defence, as D says.
8. **`flags_from_compile_commands` takes the first entry whose absolute path contains `MobileGL/`** (`:311-313`): on the Windows main worktree (`…/FoldCraftLauncher/MobileGL/`) every entry matches, including 3rdparty TUs. WSL trees are unaffected; only matters for a developer using the flag on Windows.
9. **Manifest assertion is two literals in one file** (`:121` vs `:72-118`): it guards against accidental deletion of a probe, not against a deliberate edit that removes both. Acceptable for its stated purpose ("deleting a probe is red").
## 7. Notes for the integrator (not findings)
- Probes A and B have now been exercised end-to-end with scratch headers built from the brief's own include lists (section 4 B/C); both go OK, their controls arm, and each forbidden rule was tripped at least once. Expect `1 skipped` after value-types lands and `0 skipped` after program-artifacts.
- The `--require-all` flip (C.3) is one appended token in each of `MG_Test/Purity/CMakeLists.txt:10` and `test.yml:349`.
- `clang++-20` is absent in WSL; local runs use clang 22 / g++ 16 and produce the same 42-header wire closure as the brief's measured defaults.
@@ -0,0 +1,280 @@
# P0.5 package `p05-include-gate` — result (v1)
Tree `~/w7/p05-include-gate`, branch `p05/include-gate`, based on `feat/disaggregated @ 6672778b`.
Nothing pushed. Neither P0.5 header exists in this tree, so probes A and B are SKIP by design (D9).
## 1. Commits
| sha | subject |
|---|---|
| `fe3dc1dd` | `[CI] (Purity): add scripts/check_include_closure.py - the -H include-closure gate for the P0.5 headers with an always-on negative control, wired as a unit ctest and the include-graph-check job` |
| `2318f6ae` | `[Tooling] (Purity): add scripts/symbol_report.py - per-symbol nm/.text attribution between two libMobileGL.so builds` |
`git diff --stat 6672778b HEAD`:
```
.github/workflows/test.yml | 26 ++
MobileGL/MG_Test/CMakeLists.txt | 3 +
MobileGL/MG_Test/Purity/CMakeLists.txt | 15 +
scripts/check_include_closure.py | 659 +++++++++++++++++++++++++++++++++
scripts/symbol_report.py | 386 +++++++++++++++++++
5 files changed, 1089 insertions(+)
```
Exactly the five files the B.4 ownership table assigns to this package. Working tree clean apart
from the untracked `build-linux/`. All new/modified files are LF (`grep -lU $'\r'` empty).
Absolute paths:
- `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/scripts/check_include_closure.py`
- `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/scripts/symbol_report.py`
- `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/MobileGL/MG_Test/Purity/CMakeLists.txt`
- `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/MobileGL/MG_Test/CMakeLists.txt`
- `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/.github/workflows/test.yml`
## 2. Verification — every command and its actual output
Environment: WSL Arch, `python3` 3.14.4, `/usr/sbin/clang++` = clang 22.1.6, `/usr/sbin/g++` = GCC
16.1.1. `clang++-20` does not exist in WSL, so the local runs used clang 22 and g++ 16; the CI job
still pins `clang++-20` as the brief specifies.
### 2.1 `python3 scripts/check_include_closure.py --mode both --self-test` → exit 0
```
include-closure: compiler: /usr/sbin/clang++
include-closure: value-header SKIP header not present yet: MobileGL/MG_Pipe/MGPipeValueTypes.h
include-closure: artifacts-header SKIP header not present yet: MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h
include-closure: wire-header OK 2 headers in closure, 0 forbidden (mode=text, cxx=-)
include-closure: wire-header OK 42 headers in closure, 0 forbidden (mode=clang, cxx=/usr/sbin/clang++)
include-closure: wire-header SELF-CONTAINED OK (-fsyntax-only, cxx=/usr/sbin/clang++)
include-closure: self-test: negative controls (must trip) in mode(s) text, clang
include-closure: self-test parser: trailer discarded, `../` normalised and matched
include-closure: self-test control-1 (independent of P0.5) [text]: tripped, 9 violation(s), MobileGL/MG_State/GLState/RenderState/RenderState.h at depth 1
include-closure: self-test control-1 (independent of P0.5) [clang]: tripped, 9 violation(s), MobileGL/MG_State/GLState/RenderState/RenderState.h at depth 1
include-closure: self-test: 2 negative-control trip(s), parser checks OK
include-closure: 3 probes, 2 skipped, 0 problem(s)
```
This is the required shape: **A SKIP, B SKIP, C OK, self-test OK, exit 0**. The two modes agreed on
the wire-header violation set (empty), so the `--mode both` disagreement check stayed silent.
### 2.2 `--mode text --self-test` (what the ctest runs) → exit 0
Same three probe lines, `self-test: 1 negative-control trip(s), parser checks OK`,
`3 probes, 2 skipped, 0 problem(s)`. No compiler and no submodules touched.
### 2.3 `--mode both --self-test --require-all` → **exit 1**, names both missing headers
```
include-closure: value-header SKIP header not present yet: MobileGL/MG_Pipe/MGPipeValueTypes.h
include-closure: value-header SKIP is a failure under --require-all: MobileGL/MG_Pipe/MGPipeValueTypes.h does not exist
include-closure: artifacts-header SKIP header not present yet: MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h
include-closure: artifacts-header SKIP is a failure under --require-all: MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h does not exist
include-closure: wire-header OK 2 headers in closure, 0 forbidden (mode=text, cxx=-)
include-closure: wire-header OK 42 headers in closure, 0 forbidden (mode=clang, cxx=/usr/sbin/clang++)
include-closure: wire-header SELF-CONTAINED OK (-fsyntax-only, cxx=/usr/sbin/clang++)
...
include-closure: 3 probes, 2 skipped, 2 problem(s)
::error::include-closure gate failed: 2 problem(s); see the chains above
exit=1
```
### 2.4 `--mode both --compiler g++ --self-test` → exit 0 (trailer-line handling)
```
include-closure: compiler: /usr/sbin/g++
include-closure: wire-header OK 33 headers in closure, 0 forbidden (mode=clang, cxx=/usr/sbin/g++)
include-closure: wire-header SELF-CONTAINED OK (-fsyntax-only, cxx=/usr/sbin/g++)
include-closure: self-test: 2 negative-control trip(s), parser checks OK
include-closure: 3 probes, 2 skipped, 0 problem(s)
```
g++ appends a `Multiple include guards may be useful for:` paragraph of bare `/usr/include/...`
paths to its `-H` output (confirmed by hand: 702 stderr lines, of which the trailer is ~40). The
`^(\.+) (.*)$` filter discards it, and `--self-test`'s canned-transcript check pins that behaviour
independently of which compiler is installed.
### 2.5 Red-for-its-reason (the manual negative control on the one live probe)
Temporarily added `#include <MG_State/GLState/RenderState/RenderState.h>` to
`MobileGL/MG_Remote/Transport/ITransport.h`, then `python3 scripts/check_include_closure.py
--mode both --probe wire-header --self-test`:
```
include-closure: wire-header FORBIDDEN 76 headers in closure, 1 forbidden (mode=text, cxx=-)
include-closure: forbidden: MobileGL/Includes.h (rule MobileGL/Includes.h) reached by:
include-closure: MobileGL/MG_Remote/Transport/ITransport.h
include-closure: MobileGL/MG_State/GLState/RenderState/RenderState.h
include-closure: MobileGL/Includes.h
include-closure: wire-header FORBIDDEN 672 headers in closure, 1 forbidden (mode=clang, cxx=/usr/sbin/clang++)
include-closure: forbidden: MobileGL/Includes.h (rule MobileGL/Includes.h) reached by:
include-closure: MobileGL/MG_Remote/Transport/ITransport.h
include-closure: MobileGL/MG_State/GLState/RenderState/RenderState.h
include-closure: MobileGL/Includes.h
include-closure: 1 probes, 0 skipped, 1 problem(s)
::error::include-closure gate failed: 1 problem(s); see the chains above
exit=1
```
Both modes went red with an identical three-hop chain; the closure grew 2 → 76 (text) and 42 → 672
(clang). Reverted with `git checkout --`; `git status --porcelain` for that path is empty.
### 2.6 Other flag paths exercised
- `--probe wire-header --json /tmp/p05g.json`: exit 0, JSON carries `modes`, per-mode `results`
(`headers` 2 / 42, `forbidden` 0), `skipped`, `problems`, `self_test`, `require_all`.
- `--probe nope`: `::error::unknown probe(s): nope`, exit 1.
- `--compile-commands build-linux/compile_commands.json --mode clang --probe wire-header`:
`flags from build-linux/compile_commands.json (27 tokens), cwd=/home/swung/w7/p05-include-gate/build-linux`,
then `wire-header OK 42 headers in closure, 0 forbidden` — the same closure as the default flags,
which is the point of having measured the defaults.
- Manifest assertion: `REQUIRED_PROBE_NAMES = ("value-header", "artifacts-header")` is checked
before anything else runs, so deleting a probe is red.
### 2.7 ctest wiring
```
$ cmake -S . -B build-linux # exit 0
$ ctest --test-dir build-linux -R MobileGLPurity --output-on-failure
Start 1064: MobileGLPurity.IncludeClosure
1/1 Test #1064: MobileGLPurity.IncludeClosure .... Passed 0.08 sec
100% tests passed, 0 tests failed out of 1
Label Time Summary:
unit = 0.08 sec*proc (1 test)
$ ctest --test-dir build-linux -L unit -N | grep -c MobileGLPurity
1
```
Full unit suite (`ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure -j 8`):
```
100% tests passed, 0 tests failed out of 1459
Label Time Summary: unit = 106.08 sec*proc (1459 tests)
Total Test time (real) = 13.42 sec
```
Test-name diff against the read-only reference tree `~/w7/pipe`:
```
comm -23 before after -> (empty; no test name lost)
comm -13 before after -> MobileGLPurity.IncludeClosure
1327 before / 1328 after
```
### 2.8 `.github/workflows/test.yml`
`python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))"` was run with the **Windows**
interpreter against a copy of `//wsl.localhost/Arch/home/swung/w7/p05-include-gate/.github/workflows/test.yml`
(WSL's python has no `yaml`):
```
parsed OK; jobs: 13
order around flatc-check: ['integration', 'flatc-check', 'include-graph-check', 'benchmark']
include-graph-check present: True
name: Include-closure purity gate
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v6
- name: Check out the three header submodules the closure needs
run: git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers
- name: Install clang
run: sudo apt-get update && sudo apt-get install -y clang-20
- name: Include-closure assertions and negative control
run: python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test
```
Inserted immediately after `flatc-check` and before `benchmark`, as B.3 requires. Triggers
untouched (D10).
### 2.9 `scripts/symbol_report.py`
`python3 scripts/symbol_report.py --self-test` → `symbol-report: self-test: OK (2 canned
transcripts, 5 buckets)`, exit 0. The canned pair pins removed / added / resized / renamed-only /
unchanged, including that a de-nested member folds to *renamed*, not to added+removed.
Two real builds — `~/w7/pipe/build-linux/libMobileGL.so` (read-only reference) vs this tree's
`build-linux/libMobileGL.so`, both Release / `/usr/sbin/clang++` / LTO off:
```
symbol-report: before: /home/swung/w7/pipe/build-linux/libMobileGL.so (19101056 bytes on disk)
symbol-report: after : build-linux/libMobileGL.so (19101056 bytes on disk)
symbol-report: .text 10792579 -> 10792579 (+0, +0.000%)
symbol-report: .data 76824 -> 76824 (+0)
symbol-report: .bss 1296872 -> 1296872 (+0)
symbol-report: .rodata 1534938 -> 1534938 (+0)
symbol-report: Total 17209819 -> 17209819 (+0)
symbol-report: 27799 -> 27799 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
symbol-report: 27060 -> 27060 normalised names, 27060 unchanged (name, size and mangling all identical)
```
**0 added / 0 removed / 0 resized / 0 renamed** on an unchanged tree, as expected (this package
adds no C++). `--markdown` output was also written and checked.
Synthetic `--strip-scope` rename case (two purpose-built .so files, `N::Outer::Inner::f` de-nested
to `N::Inner::f`, plus an untouched `N::Stable`):
```
without --strip-scope : 17 -> 17 defined symbols: 1 added, 1 removed, 0 resized, 0 renamed
with --strip-scope 'N::Outer::' :
17 -> 17 defined symbols: 0 added, 0 removed, 0 resized, 1 renamed, 16 unchanged
### Renamed only (same size) (1)
| normalised symbol | before mangling | after mangling |
| N::Inner::f(int) | _ZN1N5Outer5Inner1fEi | _ZN1N5Inner1fEi |
```
That is exactly the shape the `p05-program-artifacts` package's report is supposed to have.
## 3. Deviations from the brief, with reasons
1. **`--strip-scope` semantics.** The brief describes it as a textual substitution that "folds
`ProgramObject::LinkArtifacts` → `LinkArtifacts`". A literal *delete the whole prefix* would
break the fold: the before side becomes `LinkArtifacts::Reset()` while the after side is
`MobileGL::MG_State::GLState::LinkArtifacts::Reset()`, so the two would land in the
removed/added buckets — the opposite of the intent. Implemented as a **de-nesting**:
`--strip-scope 'A::B::C::'` rewrites every `A::B::C::X` to `A::B::X` (it deletes only the final
class component), which produces the stated fold and works inside template arguments too. The
behaviour is documented in `--help` and pinned by `--self-test`; C.4's command line is unchanged.
2. **One SKIP line per probe, not one per mode.** The brief's summary-line template carries a
`mode=` field, but whether a header exists is mode-independent; printing it twice under
`--mode both` was noise and double-counted the skip. A SKIP is now emitted once, before either
mode runs, and counted once. `--require-all` adds its own explicit line naming the header.
3. **The mode-disagreement check is applied to probes only, not to the self-test controls.** For a
probe, a text/clang divergence is a real signal and fails the run (implemented, prints both
sets). For the negative controls, whose TUs deliberately drag in the whole `MG_State` tree, text
mode's blindness to `#if` can legitimately produce a different violation *set* from clang's; the
self-test therefore requires each control to trip **in every enabled mode** with the expected
depth-1 path, which is the property that matters, rather than comparing sets.
4. **Extra output line in `symbol_report.py`.** `27799 -> 27799 defined symbols` and
`27060 unchanged` are different denominators (several mangled symbols fold to one normalised
demangled name). Added an explicit `N -> M normalised names` line so the two numbers cannot be
misread as 739 lost symbols.
5. **Local compiler.** `clang++-20` does not exist in WSL, so the local `--mode both` runs used
clang 22 (default resolution order) and g++ 16 (explicit `--compiler g++`). The CI job pins
`clang++-20` exactly as the brief specifies; the default compiler search order in the script is
`$CXX, clang++-20, clang++, c++, g++` as written.
6. **Cosmetic YAML.** The CI job got a blank line between `runs-on:` and `steps:` and a longer
comment block than the brief's snippet, to match the voice and spacing of the neighbouring
`flatc-check` / `benchmark` jobs. Steps and commands are verbatim from the brief.
No other deviation. `--fail-on-added-bytes` is accepted and documented as reserved (spec says
"reserved for a future hard gate"), `Allow` entries require a printed `Reason`, and the
`--json` / `--markdown` / `--only-names` / `--threshold` / `--rename-map` flags are all implemented.
## 4. Unfinished / handed to the integrator
- **The `--require-all` ratchet (C.3) is deliberately not flipped.** Both call sites
(`MobileGL/MG_Test/Purity/CMakeLists.txt` `add_test` COMMAND and the `include-graph-check` step
in `test.yml`) are one appended flag away; verified today that the flag produces exit 1 with a
message naming both headers.
- **Probes A and B have never run against a real header** — they cannot, in this tree. Their
forbidden lists, the `glslang::` ≤ 2 text limit, self-test controls 2 and 3 and the
"third `glslang::` token" text-limit control are all coded and arm themselves automatically the
moment `MGPipeValueTypes.h` / `ProgramArtifacts.h` appear. The integrator should see A flip to OK
after merging `p05/value-types` and B after `p05/program-artifacts` (C.1), and should treat an
all-SKIP run at that point as a failure.
- **CI has not run** (D10): `feat/disaggregated` is not a push trigger, so the new job needs
`gh workflow run test.yml --ref feat/disaggregated` from the integrator, who records the URL.
- **The `gl44to46` caselist run** owed by `ROADMAP.md:34` is device time and out of this package.
- Nothing was pushed; both commits are local on `p05/include-gate`.
@@ -0,0 +1,114 @@
# p05-program-artifacts — adversarial review v1
Reviewed: tree `~/w7/p05-program-artifacts`, branch `p05/program-artifacts`, HEAD `77beb7d6` (3 commits on `6672778b`: `a180dc57`, `3ce1264c`, `77beb7d6`).
Against: `BRIEF-P05.md` (A, B.0, B.2, C, D) and `p05-results/program-artifacts-v1.md`.
Every command below was re-run by me in WSL Arch from the package tree (scripts `scratchpad/wf3/p05-review-pa/s1..s10.sh`, raw outputs under `~/w7/rv-pa/`). `~/w7/pipe` was used read-only (`ctest -N`, `nm`, one run of one existing integration binary). The tree was left exactly as found: `git status --short` (excluding `build-linux/`) empty before and after, HEAD unchanged, `~/w7/pipe` clean.
**Verdict: APPROVED — 0 majors, 6 minors.** The package is a pure move that meets the brief; every claim in the result file that matters reproduced, and every gate it adds goes red for its reason.
---
## 1. What I tried to refute, and what I found
### 1.1 "Pure move" — copied vs moved, verbatim bodies, semantics
| check | command | observed |
|---|---|---|
| Struct bodies verbatim | `git show 6672778b:ProgramObject.h` regions `:41-104`, `:1144-1171`, `:1173-1449` vs `git show a180dc57:ProgramArtifacts.h` `:28-400`, both with leading whitespace stripped and blank lines dropped, `diff` | 7 hunks, all declared: 5 comment lines `glslang::X` → `glslang X` (deviation 1 in the result file), the one added I5 sentence the brief itself prescribes (B.2 layout), and the closing `} // namespace` line. **No field added, removed, reordered, re-typed, no default changed.** |
| ODR: one definition per name | `grep -rn "^\s*struct \(TypeFacts\|ResourceReflection\|XfbVarying\|LinkArtifacts\|SpirvArtifacts\)\b" MobileGL` | exactly 5 hits, `ProgramArtifacts.h:31,63,95,160,359` |
| `kInvalidUniformOffset` one definition | `grep -rn "kInvalidUniformOffset\s*=" MobileGL` | `ProgramArtifacts.h:26` (`inline constexpr Uint = ~0u`) and `ProgramObject.h:496` defined *from* it; the old `= ~0u` in class is gone |
| Alias identity actually enforced | scratch farm `~/w7/rv-pa/neg4f`: replaced the `using TypeFacts = …` alias in a copy of `ProgramObject.h` with a second `struct TypeFacts {…}` body, compiled `ProgramArtifactsTest.cpp` by hand with the farm first on the include path | `ProgramArtifactsTest.cpp:29: error: static assertion failed … is_same_v<ProgramObject::TypeFacts, GLState::TypeFacts>` (plus `ProgramObject.h:464` no-viable-conversion). The copy-left-behind failure the brief's risk table names is caught at compile time. |
| Behaviour unchanged (strongest evidence) | own `symcmp.py` (`nm --defined-only -S` + `c++filt`, fold `GLState::ProgramObject::{5 names}` → `GLState::X`, multiset compare) on `~/w7/pipe/build-linux/libMobileGL.so` (built 22:06 at `6672778b`, commit time 22:13 — same tree state) vs `build-linux/libMobileGL.so` | `symbols 30511 -> 30511; 43 names folded on the before side, 0 on the after side; added 0 removed 0 resized 1`; `.text 10792579 -> 10792579`, `.rodata`, `.data`, `.bss`, `Total 17209819` all byte-identical. The 1 resized is `typeinfo name for std::_Sp_counted_ptr_inplace<…LinkArtifacts,…>` 122 → 107 bytes: the RTTI name *string* lost `13ProgramObject`. Fully attributed. Byte-identical `.text` also rules out any ADL/overload-resolution shift from de-nesting. |
| No mangled-name dependence anywhere | `grep -rn "typeid\|type_info\|__PRETTY_FUNCTION__\|__FUNCSIG__" MobileGL` (non-test) | empty |
| B.0 D5 (glslang members verbatim, count pinned) | `grep -o "glslang::" ProgramArtifacts.h \| wc -l` (occurrences, not lines) | `2` — `:165 SharedPtr<glslang::TProgram> program;`, `:232 Vector<glslang::TIntermediate::TUniformInitializer> uniformInitialValues;` |
| B.0 D6 (includes) | `grep -n "#include" ProgramArtifacts.h` | `:10 <Includes.h>`, `:15 <set>` — nothing else |
| B.0 D7 (sizes) | header `:179-203`; test prints `sizeof: TypeFacts=44 ResourceReflection=128 XfbVarying=128 LinkArtifacts=1056 SpirvArtifacts=88` | TypeFacts pinned unconditionally at 44 with `is_trivially_copyable_v`; the four container-bearing sizes under `__GLIBCXX__ && !_GLIBCXX_DEBUG && SIZE_MAX == UINT64_MAX`; libc++ `#elif` inert behind `MGL_ARTIFACT_SIZES_LIBCXX_PINNED`; MSVC unasserted. Exactly the brief's shape. |
| I5 untouched | `git diff --stat 6672778b..HEAD` | only 4 files: `ProgramArtifacts.h` (new), `ProgramObject.h`, `MG_Test/Program/CMakeLists.txt`, `ProgramArtifactsTest.cpp`. `MG_Backend/**`, `MG_Impl/**`, `ProgramObject.cpp`, `ProgramLinkTask.*`, `ProgramSpirvTask.*` untouched; `m_artifacts`/`m_spirv` and `Artifacts()`/`Spirv()` not in the diff. |
| Includers of `ProgramObject.h` | repo-wide grep (both spellings) | the 8 non-self includers the brief lists + `ProgramObject.cpp` + the new test; none edited; all compile through the in-class aliases. |
### 1.2 Tests exist, run under the right label, and can fail
| check | command | observed |
|---|---|---|
| Incremental build | `cmake --build build-linux -j 16` (`CCACHE_BASEDIR=/home/swung/w7`) | `ninja: no work to do.` |
| Unit suite | `ctest --test-dir build-linux -L unit --no-tests=error -j 12` | `100% tests passed, 0 tests failed out of 1463`; 3 `***Skipped` (`LogLevel.DebugBuildKeepsEverything`, `LogLevel.AssertIsLiveInDebugBuilds`, `XfbFrontendOrderInvarianceTest.DumpBSpirvForDisassembly`) — skip-by-design, same as base |
| No test name lost | `ctest -N` (pattern `'^\s+Test\s+#'` — the implementer is right that the brief's single-space pattern drops tests < #1000) on both trees, `comm -23 before after` | before 2326, after 2331, **lost: none**, added: exactly `ProgramArtifacts.{AliasesAreTheSameTypes,SizesArePinnedOnThisToolchain,TypeFactsIsPodOf44Bytes,VisitFieldsCoversEveryMember,VisitFieldsPassesConstnessThrough}` |
| Label reaches `ctest -L unit` | `ctest -L unit -N \| grep -c ProgramArtifacts` | `5` |
| CMake wiring executes | `MG_Test/CMakeLists.txt:85 add_subdirectory(Program)` unconditional; stanza `Program/CMakeLists.txt:280-297` = the `AsyncCompileTest` shape with `${LINK_LIBRARIES}`, `gtest_discover_tests(… DISCOVERY_TIMEOUT 30 PROPERTIES LABELS unit)`; CI `test` job configures `-DMOBILEGL_BUILD_TEST=ON` (`test.yml:86`) and runs `ctest -L unit` | wired, discovered, runs |
| **Red-for-its-reason C1** — member added without a table entry | scratch copy `~/w7/rv-pa/neg1/…/ProgramArtifacts.h` with `Int addedWithoutATableEntry = 0;` appended to `LinkArtifacts`; `clang++ -I~/w7/rv-pa/neg1 -std=gnu++23 -Iinclude -IMobileGL … -fsyntax-only probe_pa.cpp` | exit 1: `error: static assertion failed … 'sizeof(LinkArtifacts) == 1056': LinkArtifacts changed size: add the field to VisitFields(LinkArtifacts) …` / `note: expression evaluates to '1064 == 1056'` |
| **Red-for-its-reason C2** — table entry dropped | symlink farm `~/w7/rv-pa/neg2f` (`cp -rs MobileGL`, header replaced by a copy minus `v("linkStatus", a.linkStatus);`); compiled `ProgramArtifactsTest.cpp` with its exact `compile_commands.json` line + `-I<farm>` first, linked with the ninja link line, ran | `ProgramArtifactsTest.cpp:84: Failure … Which is: 56 / Which is: 57`, plus `:110` (`linkStatus` write-through) fails; exit 1. Same hand pipeline on the **unmodified** header (`~/w7/rv-pa/pos2f`): `[ PASSED ] 2 tests` — so the failure is the dropped entry, not the pipeline. |
| **Red-for-its-reason C3** — purity | farm `~/w7/rv-pa/fake2` with `#include "ShaderObject.h"` inserted at header `:15`; (a) manual `-H` probe with the brief's grep; (b) the real gate from `~/w7/p05-include-gate/scripts/check_include_closure.py` copied under the farm's `scripts/` | (a) hits: `MobileGL/Config.h`, `MG_Backend/BackendObject.h`, `MG_Backend/BackendObjects.h`, `…/BackendObject_DirectGLES.h`, `…/BackendObject_DirectVulkan.h`, `BufferState/BufferObject.h`; (b) `artifacts-header FORBIDDEN 89 headers in closure, 16 forbidden (mode=text)` / `FORBIDDEN 678 headers, 16 forbidden (mode=clang)`, chain printed one hop per line, `::error::…`, exit 1 |
| Table completeness vs struct bodies (independent of the counting test) | python cross-check: member names parsed from each struct body vs `v("name", a.name)` entries | TypeFacts 20/20, ResourceReflection 14/14, XfbVarying 11/11, LinkArtifacts members 58 / table 57 (**only `program` missing**), SpirvArtifacts 8/8; every `"name"` string equals its member, every table in declaration order |
### 1.3 The closure gate, on the real tree
The gate lives in `p05/include-gate`; I ran that script (copied, unmodified) against this tree through a symlinked root `~/w7/rv-pa/fake/{MobileGL,include,3rdparty → tree}` so the tree itself was not touched:
```
include-closure: value-header SKIP header not present yet: MobileGL/MG_Pipe/MGPipeValueTypes.h
include-closure: artifacts-header OK 65 headers in closure, 0 forbidden (mode=text, cxx=-)
include-closure: artifacts-header OK 653 headers in closure, 0 forbidden (mode=clang, cxx=/usr/sbin/clang++)
include-closure: artifacts-header SELF-CONTAINED OK (-fsyntax-only, cxx=/usr/sbin/clang++)
include-closure: wire-header OK …
include-closure: self-test control-3 (ShaderObject.h added back to the artifacts header's TU) [text]: tripped, 16 violation(s) … [clang]: tripped, 16 violation(s) …
include-closure: self-test text limit: tripped as expected (glslang:: occurs 3 times, budget is 2)
include-closure: 3 probes, 1 skipped, 0 problem(s) exit 0
--require-all: exit 1 (value-header absent — expected until p05/value-types lands)
--probe artifacts-header alone: OK/OK/SELF-CONTAINED OK, exit 0
```
Manual equivalent (brief B.2): `-H -E` probe → 653 closure lines, 0 matches for `ShaderObject.h|SpvcSession.h|MG_Util/ShaderTranspiler/|MobileGL/Config.h|MobileGL/MG_Backend/|BufferState/`; the only `MobileGL/` headers in the closure are `Defines.h`, `Includes.h`, `ProgramArtifacts.h`, `MG_Util/Debug/Log.h`, `MG_Util/GLExtensions.h`, `MG_Util/PlatformStubs.h`, `MG_Util/Types.h`. `-fsyntax-only` OK. `python3 scripts/gen_pipe.py --check` → `generated files are up to date`.
### 1.4 Lost transitive includes — TUs this configuration never compiled
`ProgramObject.h` sits behind `Core.h`, so commit 2 (dropping `SpvcSession.h`, which forwards `<spirv_reflect.h>` and `MG_Util/ShaderTranspiler/Types.h`) affects every `Core.h` consumer. The local build has `MOBILEGL_BUILD_BENCHMARK=OFF`; **CI's `test` job has it ON (`test.yml:87`)**, so the implementer's "no consumer needed an include" was proven only for the TUs in `compile_commands.json`. I enumerated every `.cpp` under `MobileGL/ tools/ android-plugin/` absent from `compile_commands.json` (48 files: benchmarks, MG_Remote transport, CGL/WGL/NSOpenGL, Wire tests, JNI, tools) and syntax-checked the ones that reach the program headers with the exact flag set of a compiled test TU plus `_deps/benchmark-src/include`:
```
OK MobileGL/MG_Benchmark/Buffer/BufferBench.cpp
OK MobileGL/MG_Benchmark/Container/UnorderedMapBench.cpp
OK MobileGL/MG_Benchmark/Program/ProgramBench.cpp
OK MobileGL/MG_Benchmark/SanityBench.cpp
OK MobileGL/MG_Benchmark/ShaderCache/TranslationCacheBench.cpp
OK MobileGL/MG_Benchmark/Transpile/TranspileProfile.cpp
OK MobileGL/MG_Util/Converters/SPIRVCrossToGL/SpvcTypeConverter.cpp (referenced by no CMakeLists; checked anyway)
```
Repo-wide, every TU that names `SpvReflect*`/`SpvcSession`/`SpvcMetadata` either includes `SpvcSession.h`/`spirv_reflect.h` itself or is in this build's compile set (and built). `MG_Test/Backend/DirectVulkan/SanityTest.cpp` fails only on `GLFW/glfw3.h` (not installed; unrelated). `DriverBenchJni.cpp` names none of those symbols. Conclusion: commit 2 is safe for the CI configuration as well; the binding check remains the integrator's `gh workflow run` (C.5).
### 1.5 The integration-gpu failure the result file reports
`DirectVulkan.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput`: one run each of the untouched base binary (`~/w7/pipe/build-linux/MobileGL/MG_IntegrationTest/MobileGLIntegrationTest`, DirectVulkan + lavapipe env as the ctest property injects) and the package's: **both `[ FAILED ]`**. Pre-existing on this machine, as the implementer's 3×3 A/B said; with byte-identical `.text` it cannot be this package.
---
## 2. Majors
None.
## 3. Minors (none blocks; listed for the integrator / a follow-up commit)
1. **File mode.** `MobileGL/MG_Test/Program/ProgramArtifactsTest.cpp` is committed as `100755`; its 15 siblings in that directory are `100644` (`git ls-files -s MobileGL/MG_Test/Program/`). Cosmetic; `git update-index --chmod=-x` in the integrator's merge or a follow-up.
2. **Test/header `#if` drift risk.** `ProgramArtifactsTest.cpp:297` re-spells the header's guard (`__GLIBCXX__ && !_GLIBCXX_DEBUG && SIZE_MAX == UINT64_MAX`) instead of `#ifdef MGL_LINKARTIFACTS_SIZE`. The brief literally asked for "under the same `#if`", so this is by the letter — but when C.4 pins the libc++ branch, the header will assert on Android while the runtime twin silently records `sizes_pinned: no` there. Recommend `#ifdef MGL_LINKARTIFACTS_SIZE` in the test (one-line change, integrator-owned since C.4 touches the header anyway).
3. **Macro leak.** `MGL_RESOURCEREFLECTION_SIZE`/`MGL_XFBVARYING_SIZE`/`MGL_LINKARTIFACTS_SIZE`/`MGL_SPIRVARTIFACTS_SIZE` (`ProgramArtifacts.h:187-190`) are `#define`d in a header reached by every `Core.h` consumer and never `#undef`'d. No collision today (`grep -rn MGL_.*_SIZE` shows only `MGL_RESIDUAL_BLOCK_SIZE`); the brief prescribed this shape. Note only.
4. **Transitive-include reliance inside the header.** `std::same_as` (`<concepts>`), `std::remove_const_t` (`<type_traits>`), `SIZE_MAX`/`UINT64_MAX` (`<cstdint>`) are not included by the header; D6 pins the include list, and the `-H` closure shows `concepts` and `cstdint` arrive via `<Includes.h>` on libstdc++ (`-dM -E` confirms `SIZE_MAX`, `UINT64_MAX` defined). Two things worth knowing: (a) if `SIZE_MAX`/`UINT64_MAX` were ever *not* defined at that point, the preprocessor evaluates `0 == 0` → true, i.e. the guard fails open rather than closed; `-Wundef` is not in the project flags. (b) libc++ and MSVC supply `std::same_as` through `<string>`/`<set>` in C++20 mode in practice. Not a defect under D6; a `<cstdint>`/`<concepts>` pair would cost nothing and is not forbidden by the gate — the plan owner's call.
5. **Result-file correction (deviation 6).** The implementer warns that the brief's C.4 recipe `--strip-scope 'MobileGL::MG_State::GLState::ProgramObject::'` would report "43 added / 43 removed". With the real `scripts/symbol_report.py` from `p05/include-gate` it does not: `--strip-scope 'MobileGL::MG_State::GLState::ProgramObject::'` → `27799 -> 27799 defined symbols: 0 added, 0 removed, 1 resized, 42 renamed`, identical to the `--rename-map` fold and to `--strip-scope 'ProgramObject::'`. The warning was true of the implementer's hand-rolled `symcmp.py`, not of the script the integrator will run. The C.4 recipe can be used as written; the expected line is `0 added, 0 removed, 1 resized, 42 renamed` with the one resized = the RTTI name string (`-15` bytes).
6. **Cosmetic.** `ProgramArtifacts.h:18` starts a sentence in lowercase ("…asserts that closure. the glslang scope token appears…").
## 4. Deviations declared by the implementer — verified
| # | claim | verdict |
|---|---|---|
| 1 | 5 comment respellings `glslang::X` → `glslang X` | exactly those 5 lines differ (§1.1 verbatim diff); no code token changed; needed because the gate counts occurrences in the whole file (the include-gate self-test confirms "budget is 2") |
| 2 | LinkArtifacts 57 of 58, not 52 of 53 | independent count 58 members (§1.2 cross-check); the brief's 53 was stale |
| 3 | `ctest -N` grep pattern | correct; used here |
| 4 | extra test `VisitFieldsPassesConstnessThrough` | additive; fails when the table is broken (§1.2 C2 also tripped it at `:110`) |
| 5 | CMake stanza appended at file end | content matches the `AsyncCompileTest` shape; wired (§1.2) |
| 6 | `symbol_report.py` `--strip-scope` warning | **incorrect for the real script** — see minor 5 |
## 5. Not verified here (by design)
- The libc++/NDK sizes (integrator C.4) and the MSVC build; nothing in the package is platform-specific beyond the per-STL `#if`.
- The full `integration-gpu` suite (only the reported failure was A/B'd, §1.5).
- CI dispatch of `test.yml` on `feat/disaggregated` (D10, integrator).
## 6. State of the trees after review
`~/w7/p05-program-artifacts`: HEAD `77beb7d6`, `git status --short` (minus `build-linux/`) empty, `build-linux/` rebuilt to no-op. `~/w7/pipe`: untouched, `6672778b`, clean. All scratch work under `~/w7/rv-pa/` (farms `fake`, `fake2`, `neg1`, `neg2f`, `pos2f`, `neg4f`, logs) and `scratchpad/wf3/p05-review-pa/`.
@@ -0,0 +1,66 @@
# p05-program-artifacts — results v1
Tree `~/w7/p05-program-artifacts`, branch `p05/program-artifacts`, base `feat/disaggregated @ 6672778b`.
Build: `build-linux/` Release, `/usr/sbin/clang++` (clang 22), ccache (`CCACHE_BASEDIR=/home/swung/w7`), libstdc++ (`__GLIBCXX__ 20260625`), `MOBILEGL_BUILD_TEST=ON`, `MOBILEGL_BUILD_INTEGRATION_TEST=ON`.
Not pushed. `~/w7/pipe` untouched (only read: `ctest -N`, `nm`, and a direct run of one existing test binary for the A/B below).
## Commits (oldest first)
| hash | subject |
|---|---|
| `a180dc57` | `[Refactor] (Program): extract ProgramArtifacts.h - move TypeFacts, ResourceReflection, XfbVarying, LinkArtifacts and SpirvArtifacts to namespace scope with in-class aliases so every existing spelling compiles unchanged; pure move` |
| `3ce1264c` | `[Refactor] (Program): stop ProgramObject.h including SpvcSession.h - it names no spirv-cross or SPIRV-Reflect symbol` |
| `77beb7d6` | `[Feat] (Program): add the reflection-archive field tables and sizeof trip wires to ProgramArtifacts.h` |
Files touched (vs `6672778b`): `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` (new, 576 lines), `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h` (-386/+15), `MobileGL/MG_Test/Program/ProgramArtifactsTest.cpp` (new), `MobileGL/MG_Test/Program/CMakeLists.txt` (+21). Nothing else — commit 2 needed no consumer include additions (all 8 includers + `ProgramObject.cpp` built without `SpvcSession.h` forwarded).
## What landed (B.2 checklist)
- `ProgramArtifacts.h`: banner copied from `ProgramObject.h`; includes exactly `<Includes.h>` and `<set>`; PURITY comment; `namespace MobileGL::MG_State::GLState { inline constexpr Uint kInvalidUniformOffset = ~0u; TypeFacts; ResourceReflection; the 4 `using` reflections; XfbVarying; LinkArtifacts (+ its comment block, with the one added I5 sentence); SpirvArtifacts (+ comment block); VisitFields x5; trip wires }`. Struct bodies moved verbatim (re-indented one level), no field added/removed/reordered/re-typed; `program` and `uniformInitialValues` keep their glslang types (D5).
- `ProgramObject.h`: `#include "ProgramArtifacts.h"` after `"ShaderObject.h"`; old `:41-104` replaced by the 9-line alias block (fully qualified RHS); `kInvalidUniformOffset` re-exported as `static constexpr Uint kInvalidUniformOffset = MobileGL::MG_State::GLState::kInvalidUniformOffset;` (comment kept); old `:1144-1171` and `:1173-1449` deleted; commit 2 drops `#include <MG_Util/ShaderTranspiler/SpvcSession.h>`. `MAX_UNIFORM_LOCATIONS` and the `glslang::` accessors stay. `m_artifacts`/`m_spirv` private, `Artifacts()`/`Spirv()` untouched (I5).
- `VisitFields`: free constrained templates (`requires std::same_as<std::remove_const_t<Self>, T>`), contract `v(const char*, Field&)`, tables never recurse; counts TypeFacts 20, ResourceReflection 14 (`type` as a value), XfbVarying 11, LinkArtifacts 57 (every member except `program`), SpirvArtifacts 8.
- Trip wires: `static_assert(is_trivially_copyable_v<TypeFacts> && sizeof(TypeFacts) == 44)`; under `#if defined(__GLIBCXX__) && !defined(_GLIBCXX_DEBUG) && (SIZE_MAX == UINT64_MAX)`: `MGL_RESOURCEREFLECTION_SIZE 128`, `MGL_XFBVARYING_SIZE 128`, `MGL_LINKARTIFACTS_SIZE 1056`, `MGL_SPIRVARTIFACTS_SIZE 88` (measured on this build via `== 1` notes); `#elif defined(_LIBCPP_VERSION) && (SIZE_MAX == UINT64_MAX) && defined(MGL_ARTIFACT_SIZES_LIBCXX_PINNED)` left inert for the integrator (C.4); the four `static_assert`s guarded by `#ifdef MGL_LINKARTIFACTS_SIZE` with the "add the field to VisitFields(...) then update this number" messages.
- Tests (`ProgramArtifacts.*`, label `unit`, first include is the artifacts header): `AliasesAreTheSameTypes` (9 `is_same_v` static_asserts + `kInvalidUniformOffset`), `TypeFactsIsPodOf44Bytes`, `VisitFieldsCoversEveryMember` (20/14/11/57/8, const == non-const, names distinct), `VisitFieldsPassesConstnessThrough` (extra: const walk yields const refs, mutable walk writes through), `SizesArePinnedOnThisToolchain` (`EXPECT_EQ` under the same `#if`, `RecordProperty("sizeof_*")` x5 always, plus a printf line `sizeof: TypeFacts=44 ResourceReflection=128 XfbVarying=128 LinkArtifacts=1056 SpirvArtifacts=88`).
## Verification — every command and its actual result
All run in WSL Arch, cwd `~/w7/p05-program-artifacts`, after commit 3 (`77beb7d6`) unless stated.
| # | command | result |
|---|---|---|
| 1 | `cmake --build build-linux -j 16` (after each commit) | commit 1: OK (186 steps, whole ProgramObject.h fan-out); commit 2: OK (183 steps, zero consumer edits needed); commit 3: OK; post-commit re-run: `ninja: no work to do.` Logs `~/w7/pa-build{1,2,3}.log` |
| 2 | `ctest --test-dir build-linux -L unit --no-tests=error -j 8` | `100% tests passed, 0 tests failed out of 1463` (3 `***Skipped`: `LogLevel.DebugBuildKeepsEverything`, `LogLevel.AssertIsLiveInDebugBuilds`, `XfbFrontendOrderInvarianceTest.DumpBSpirvForDisassembly` — skip by design). Log `~/w7/pa-unit3.log`. (After commit 1 alone: 1460/1460.) |
| 3 | `ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 8` | `99% tests passed, 5 tests failed out of 868`: the four `*IsActuallyArmedWhenTheEnvironmentPinsItOn*` (DirectGLES UnlocatedIoBlocks, DirectVulkan PrimGenReroute, DirectGLES + DirectVulkan PointSizeDemotion) — the known `-j` flake — and `DirectVulkan.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput`. Log `~/w7/pa-igpu3.log` |
| 4 | `ctest --test-dir build-linux -L integration-gpu --rerun-failed -j 1` | `80% tests passed, 1 tests failed out of 5`: the four flake lanes pass; `DirectVulkan.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput` still fails (`IterationRPProgram203Scenario.cpp:371,377`, golden half-float texel mismatch, `mismatchTexels` 1 vs 0). Log `~/w7/pa-igpu3-rerun.log` |
| 5 | A/B of #4's failure on the UNTOUCHED base binaries: `MOBILEGL_BACKEND_TYPE=DirectVulkan __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json ~/w7/pipe/build-linux/MobileGL/MG_IntegrationTest/MobileGLIntegrationTest --gtest_filter=IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput --gtest_also_run_disabled_tests` (cwd = that binary's `MG_IntegrationTest` dir; the env is what the ctest ENVIRONMENT property injects) x3, and the same for my binary x3 | base (built 22:06 at `6672778b`): FAILED 3/3; mine: FAILED 3/3. **Pre-existing on this WSL/lavapipe machine, independent of this package** (the package touches no code path — only type scope — and the library `.text` is byte-identical, see #13). Its DirectGLES twin is `***Skipped` on both. |
| 6 | `ctest -N` name diff: `ctest --test-dir build-linux -N \| grep -E '^\s+Test\s+#' \| sed 's/^ *Test *#[0-9]*: //' \| sort` vs the same on `~/w7/pipe/build-linux`; `comm -23 before after` | before 2326, after 2331; `comm -23` **empty**; `comm -13` = exactly the 5 new `ProgramArtifacts.*` names. NOTE: the brief's pattern `'^\s+Test #'` (single space) only matches test numbers >= 1000 (ctest right-aligns: `Test #984:` vs `Test #1234:`); with it the diff is garbage (two spurious `QueryTest.*` "additions", my tests invisible). Use `'^\s+Test\s+#'`. |
| 7 | `ctest --test-dir build-linux -L unit -N \| grep -c ProgramArtifacts` | `5` (the label reaches `ctest -L unit`) |
| 8 | ODR: `grep -rn "^\s*struct \(TypeFacts\|ResourceReflection\|XfbVarying\|LinkArtifacts\|SpirvArtifacts\)\b" MobileGL` | exactly 5 hits, all in `ProgramArtifacts.h` (lines 31, 63, 95, 160, 359) |
| 9 | `grep -n "#include" MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` | 2 lines: `<Includes.h>` (line 10), `<set>` (line 15) |
| 10 | `grep -c "glslang::" MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` | `2` (lines 165 `SharedPtr<glslang::TProgram> program;` and 232 `Vector<glslang::TIntermediate::TUniformInitializer> uniformInitialValues;`) |
| 11 | Closure probe: `printf '#include <MG_State/GLState/ProgramState/ProgramArtifacts.h>\n' > /tmp/probe_pa.cpp; clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -H -E -o /dev/null /tmp/probe_pa.cpp 2>&1 \| grep -E '^\.+ ' \| grep -E 'ShaderObject.h\|SpvcSession.h\|MG_Util/ShaderTranspiler/\|MobileGL/Config.h\|MobileGL/MG_Backend/\|BufferState/'` | **empty** (0 forbidden of 653 closure lines). The only `MobileGL/` headers in the closure: `Defines.h`, `Includes.h`, `ProgramArtifacts.h`, `MG_Util/Debug/Log.h`, `MG_Util/GLExtensions.h`, `MG_Util/PlatformStubs.h`, `MG_Util/Types.h`. |
| 12 | `clang++ ... -fsyntax-only /tmp/probe_pa.cpp` | OK (header self-contained; `ProgramArtifactsTest.cpp` includes it first as the in-tree proof) |
| 13 | `git diff --stat 6672778b -- MobileGL/MG_Backend MobileGL/MG_Impl` | **empty** (also after commit 2 — no include-line additions were needed) |
| 14 | Symbol attribution (no `scripts/symbol_report.py` in this tree — done by hand with `nm --defined-only -S` + `c++filt` + `size --format=sysv`, script `scratchpad/wf3/p05-program-artifacts/symcmp.py`; normalisation folds `GLState::ProgramObject::{TypeFacts,ResourceReflection,XfbVarying,LinkArtifacts,SpirvArtifacts}` -> `GLState::X` on both sides, multiset compare on (name, type, size)); before = `~/w7/pipe/build-linux/libMobileGL.so` (6672778b, 22:06), after = `build-linux/libMobileGL.so` | `symbol-report: .text 10792579 -> 10792579` (byte-identical); `30511 -> 30511 defined symbols: 0 added, 0 removed, 1 resized, 43 renamed`; identical after commit 1 alone (`~/w7/pa-sym1.txt`) and after commit 3 (`~/w7/pa-sym3.txt`). The 1 "resized" is `r [122] -> [107] typeinfo name for std::_Sp_counted_ptr_inplace<...LinkArtifacts, allocator<void>, _Lock_policy 2>` — the RTTI **name string** (rodata, not code), 15 bytes shorter because `13ProgramObject` left the mangled name. Fully attributed; commits 2 and 3 add no symbol (VisitFields is uninstantiated outside the test binary). |
| 15 | Red-for-its-reason (scratch copy of the header under `/tmp/pa-neg`, tree untouched): add `Int addedWithoutATableEntry = 0;` to `LinkArtifacts`, `clang++ -I/tmp/pa-neg ... -fsyntax-only /tmp/probe_pa.cpp` | exit 1: `error: static assertion failed ... 'sizeof(LinkArtifacts) == 1056': LinkArtifacts changed size: add the field to VisitFields(LinkArtifacts) ..., then update this number` / `note: expression evaluates to '1064 == 1056'` |
| 16 | `git status --short` (excluding `build-linux/`) after each commit | clean |
| 17 | Line endings: `grep -c $'\r'` on the two headers and the test | 0 / 0 / 0 |
## Deviations from the brief (with reasons)
1. **Comment respellings in the moved text (commit 1).** Five comment lines that moved verbatim spell `glslang::TType`, `glslang::TLayoutMatrix`, `glslang::TBasicType`, `glslang::TObjectReflection`, `glslang::TProgram`; with them the header had 8 `glslang::` lines, and the gate/D5 pins the count at exactly 2. Respelled comment-only as `glslang TType` etc. (no code token changed). The brief's "verbatim" and "exactly 2" cannot both hold literally; the gate wins (`ROADMAP.md:7`).
2. **`LinkArtifacts` field count is 57 of 58, not 52 of 53.** Counted mechanically from the moved source (`program` + 57 others; a lines-ending-in-`;` count under-reads because several members carry trailing comments). `VisitFieldsCoversEveryMember` expects 57. The brief's 53 is a stale scout number.
3. **`ctest -N` grep pattern** corrected to `'^\s+Test\s+#'` (see #6) — the brief's pattern silently drops tests numbered < 1000.
4. **One extra test** `VisitFieldsPassesConstnessThrough` (adds only; brief allows additions) — pins that the single table really serves both directions.
5. **`MobileGL/MG_Test/Program/CMakeLists.txt` stanza** appended at the end of the file (after the existing `gtest_discover_tests` block) rather than "copied next to" `AsyncCompileTest`; content is the `AsyncCompileTest` shape with `DISCOVERY_TIMEOUT 30 PROPERTIES LABELS unit` as specified.
6. **`scripts/symbol_report.py` absent** in this tree (owned by `p05-include-gate`); the by-hand equivalent above records the numbers. The brief's `--strip-scope 'MobileGL::MG_State::GLState::ProgramObject::'` as a plain textual strip is NOT the right normalisation (it leaves a bare `LinkArtifacts` on the before side versus `MobileGL::MG_State::GLState::LinkArtifacts` on the after side and reports 43 added / 43 removed); the integrator's run of the real script should fold `GLState::ProgramObject::X` -> `GLState::X` (or strip only `ProgramObject::`). Flagging so C.4 does not read a false 43/43.
## Notes for the integrator
- libc++ branch of the trip wires is inert until `MGL_ARTIFACT_SIZES_LIBCXX_PINNED` is defined with the NDK numbers (C.4); `ProgramArtifacts.SizesArePinnedOnThisToolchain` prints and `RecordProperty`s all five sizes on every platform for that purpose.
- The glibc++ guard is exactly the brief's (`__GLIBCXX__ && !_GLIBCXX_DEBUG && SIZE_MAX == UINT64_MAX`); it does not exclude `_GLIBCXX_USE_CXX11_ABI=0` (COW `std::string`, 8 bytes) — no MobileGL toolchain uses that, mentioned only for completeness.
- `DirectVulkan.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput` is red on this WSL machine at the base commit (#5) — expect it in the integrator's baseline too.
## Unfinished
Nothing in scope. Not done by design/ownership: libc++ size pin (integrator, C.4); `scripts/check_include_closure.py --probe artifacts-header` run (script lives in `p05/include-gate`; the manual `-H` probe #11 is its equivalent); narrowing `ProgramTranslationCache.h`/`ProgramInterface.cpp` to the new header and the `UniformInitializer` re-typing (P7 follow-ups per the brief).
@@ -0,0 +1,83 @@
# p05-value-types — adversarial review v1
Reviewed: `~/w7/p05-value-types`, branch `p05/value-types`, HEAD `92e925f9` (one commit on `6672778b`).
Reference: `~/w7/pipe` @ `6672778b` (read-only; untouched — `git status` clean apart from its build dirs).
Review scripts: `scratchpad/wf3/p05-review-vt/s1..s6.sh`; logs under `~/w7/logs/review-vt/`.
Tree state at exit: `git status --short` prints only `?? build-linux/` (identical to the implementer's state); the temporarily copied gate script was removed; the red-for-its-reason experiments were done on out-of-tree copies (`~/w7/logs/review-vt/red*/`), never in the tree.
**Verdict: APPROVED — 0 majors, 3 minors.** The claim "correct, complete, pure move meeting the brief" survived every attempt to refute it.
---
## 1. What I tried to refute, and what I observed
### 1.1 "Cut, not copy" — verbatim-move proof (s2)
Reconstructed the moved regions from the base commit and diffed them against the new header:
```
git show 6672778b:.../RenderState.h | sed -n '15,370p' -> old_rs.txt
git show 6672778b:.../SamplerObject.h | sed -n '14,97p' -> old_so.txt
git show 6672778b:.../VertexArrayObject.h | sed -n '17,70p' -> old_vao.txt
```
- Non-vertex part (`old_rs + old_so`, with the two `MG_State::GLState::FramebufferObject::MAX_DRAW_BUFFERS` → `kMGMaxDrawBuffers` respellings applied) vs `MGPipeValueTypes.h:32-471`: `diff -B` **exit 0** — byte-exact including indentation and comments.
- Vertex part (`old_vao` de-indented by 4) vs `MGPipeValueTypes.h:474-529`: `diff -B` **exit 0**.
- Whole region `diff -w -B`: the only extra lines are the three the brief prescribes (`namespace MG_State::GLState {`, `class BufferObject;`, closing brace).
- Banner `MGPipeValueTypes.h:1-7` == `MGPipeTypes.h:1-7` with the path substituted (`banner-ok`).
- Deleted "extra" lines (`RenderState.h:371`, `SamplerObject.h:97`, `VertexArrayObject.h:71`) are all blank (`cat -A` shows `$`), so deviation 1 of the result file is whitespace-only as declared.
Member order, defaults, enum underlying types (`BorderColorForm : Uint8` at `MGPipeValueTypes.h:441`), `constexpr`-ness (`MAX_VIEWPORTS` at `:244`), namespaces (`MG_State::GLState` reopened at `:473`, D3) — all unchanged by construction of the diff above.
### 1.2 ODR — no second definition anywhere
- Brief grep (8 structs + 3 enums) over `MobileGL/`: **11 hits, all in `MobileGL/MG_Pipe/MGPipeValueTypes.h`** (lines 32, 168, 208, 219, 229, 239, 441, 447, 476, 517, 525).
- Extended grep for **all 17 moved enums** over `MobileGL tools android-plugin` (`*.h *.hpp *.cpp *.inc`, build dirs excluded): 17 hits, all in the new header.
- `MAX_DRAW_BUFFERS\s*=`: exactly one, `FramebufferObject.h:107` `= MobileGL::kMGMaxDrawBuffers` (D4). `kMGMaxDrawBuffers` appears 8 times (header, tests, FramebufferObject.h); none in `MG_Backend`.
### 1.3 Purity / closure (s3, s4)
- Text: `grep -n "MG_State/\|MG_Backend/\|MG_Impl/\|MG_Remote/" MGPipeValueTypes.h` → **empty** (exit 1).
- Includes of the four forwarding headers: `RenderState.h:10-11` = `<Includes.h>` + `<MG_Pipe/MGPipeValueTypes.h>` only; `SamplerObject.h:10-11` same; `VertexArrayObject.h:10-13` keeps `BufferObject.h`/`Types.h` + value header; `FramebufferObject.h:14` adds the value header.
- Compiler closure, brief's exact flags, `-H -E` on `#include <MG_Pipe/MGPipeValueTypes.h>`: **654 lines, 0 under `MobileGL/MG_State/ | MG_Backend/ | MG_Impl/ | MG_Remote/`**. `MobileGL/` headers in the closure: `Defines.h, Includes.h, MG_Pipe/MGPipeValueTypes.h, MG_Util/{Debug/Log.h, GLExtensions.h, Math/VectorTypes.h, PlatformStubs.h, Types.h}`. `-fsyntax-only` exit 0 (self-contained).
- **Real gate run** (copied `~/w7/p05-include-gate/scripts/check_include_closure.py` into `scripts/` for the run, removed afterwards; `REPO_ROOT` is derived from the script location so it had to be in-tree):
- `--mode both --self-test`: `value-header OK 66 headers (text)`, `OK 654 headers (clang)`, `SELF-CONTAINED OK`; `artifacts-header SKIP` (expected, other package); `wire-header OK`; `self-test: 4 negative-control trip(s), parser checks OK`; `3 probes, 1 skipped, 0 problem(s)`, exit 0. The 4 trips = self-test steps 1 and 2 (step 2 is the roadmap's literal "add an `MG_State` include back and it goes red", which only runs once `MGPipeValueTypes.h` exists — it does now, and it trips) in both modes.
- `--require-all`: exit 1, names only the missing `ProgramArtifacts.h` (D9 semantics correct; the value header itself is not the reason).
- `--probe value-header`: `1 probes, 0 skipped, 0 problem(s)`.
- **Red-for-its-reason, by hand** (out-of-tree shadow copy at `~/w7/logs/review-vt/red/MG_Pipe/MGPipeValueTypes.h` with `#include <MG_State/GLState/RenderState/RenderState.h>` inserted after `:15`, put first on the `-I` path): the same `-H` probe reports **1 forbidden line**. Restored = nothing to restore; the tree was never edited.
- **Tripwire fires**: shadow copy with `sizeof(RenderStateParameters) == 1` → `error: static assertion failed ... note: expression evaluates to '1168 == 1'`.
### 1.4 Behaviour unchanged (s3)
- `cmake --build build-linux -j 16`: `ninja: no work to do` (the implementer's build is current).
- `ctest -L unit --no-tests=error -j 8`: **100% passed, 0 failed of 1460**, 11.0 s. The two new tests ran inside the `-L unit` selection (`#1053`, `#1054` Passed) — they are labelled, not orphaned.
- `ctest -N` names, `comm -23 before after`: **lost: none**; added exactly `PipeCatalogue.ValueTypeLayoutsArePinned`, `PipeCatalogue.ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail` (1327 → 1329).
- `python3 scripts/gen_pipe.py --check`: `generated files are up to date`, exit 0; tree still clean afterwards.
- `nm --defined-only -S` keyed on mangled name (type+size): **30511 → 30511, diff empty**; with addresses included: diff empty. `size --format=sysv`: `.text 10792579` and `Total 17209819` on both sides. `objcopy --only-section=.text` + `cmp`: **`.text` byte-identical**. The baseline `.so` carries a `GIT@a4baa9d` configure stamp (implementer already attributed it); since `.text` is byte-identical to a build known to be at `6672778b`+header-move, the baseline is a valid `6672778b` build.
- `grep -rc "pGLContext" MobileGL/MG_Backend | sort` identical to pipe; `git diff --stat 6672778b -- MG_Backend MG_Impl MG_Util` empty.
### 1.5 Lost transitive includes on platforms that were not built
- 27 files include the touched headers; every `.cpp` among them (8) is in `build-linux/compile_commands.json`.
- 31 `.cpp` under `MobileGL/` are not built on Linux (Android JNI, WGL/CGL/NSOpenGL, MG_Remote split-only, benchmarks, a dead `VkTextureSamplerManager.cpp` referenced by no CMake file). Inspected their includes: none includes `RenderState.h`/`SamplerObject.h`/`VertexArrayObject.h` directly; the JNI ones go through `MG_Impl/GLImpl/*` and `Includes.h` (same path the Linux build exercises). The 18 split-only TUs (`~/w7/pipe/build-linux-split`) are all `MG_Remote/Transport/*` and `MG_Test/Wire/*`, which by the wire-header rule do not include `Includes.h` at all. No plausible Android/Windows/split fallout found.
### 1.6 Wiring, formatting, docs
- No CI format gate exists (`grep clang-format .github/workflows/*.yml` empty); `clang-format --dry-run` on the new header nevertheless reports **0 warnings** (clang-format 22.1.6, repo `.clang-format`). No trailing whitespace in the diff (`grep -P '^\+.*[ \t]+$'` count 0); LF endings, newline at EOF, mode 100644.
- `scripts/check_doc_citations.py` (base tree, the `test.yml:853-861` lint, which is `|| true` anyway) on the three `docs/Disaggregated/*.md`: `19 citations ... 0 problem(s)`. `MGPipeTypes.h` line numbers are unchanged (the comment rewrite is line-for-line), so `ARCHITECTURE.md:359`'s `MGPipeTypes.h:535` still points at `MGL_RESIDUAL_BLOCK_SIZE`.
- Commit message: prescribed subject verbatim + `- ` bullets explaining why; no attribution lines; not pushed; no fixture binaries touched.
- Deviations 1-7 in the result file were each checked and are as declared (whitespace, comment wording, additional-only test expectations, tooling not present in this tree).
## 2. Majors
None.
## 3. Minors
1. **`MGPipeTypes.h:16-18` overstates the repaid debt.** The rewritten comment says "this header no longer reaches into MG_State". The `-H` closure of `#include <MG_Pipe/MGPipeTypes.h>` still contains `.. MobileGL/MG_Backend/BackendObject.h` → `... MobileGL/MG_State/GLState/TextureState/TextureEnum.h` (`BackendObject.h:11`), exactly the D1 reason the brief gives for not moving `DynamicBackendParameters`. The following sentence ("that one include is what still keeps purity gate A off this header") is correct, so nothing functional depends on it, but the first sentence should read "no longer includes MG_State directly; the remaining MG_State reach is `TextureEnum.h` via `BackendObject.h`". Comment-only; fix in the integrator's docs/comment pass or a follow-up, not a reason to hold the package.
2. **`PipeCatalogue.ValueTypeLayoutsArePinned` is tautological on the CI toolchain** (`PipeCatalogueTest.cpp:117-135`): every `EXPECT_*` compares the same compile-time constants the header's `static_assert`s already pin, so on Linux/libstdc++ it cannot fail without the build already failing. This is exactly what the brief asked for ("runtime twins ... so the numbers show up in ctest output on every platform"), and it does earn its keep on MSVC/NDK where a static assertion might be `#if`'d out later; recorded so nobody counts it as an independent gate.
3. **Result-file line range `SamplerObject.h:14-96` vs brief `14-97`**: line 97 at `6672778b` is blank, so the cut is the brief's cut; only the description differs. No action.
## 4. Notes for the integrator (not findings against this package)
- The package's `build-linux/CMakeCache.txt` has `MOBILEGL_ITEST_VK_ICD=` empty (implementer's Program203 diagnosis checks out against `MG_IntegrationTest/CMakeLists.txt:284-298`); reconfigure the three p05 build dirs with the lavapipe ICD before relying on a plain `ctest -L integration-gpu`.
- With this package merged after include-gate, `check_include_closure.py --mode both --self-test` already reports `value-header OK` in both modes plus the step-2 negative control tripping; only `artifacts-header` remains `SKIP` until program-artifacts lands.
@@ -0,0 +1,63 @@
# p05-value-types — result v1
Tree `~/w7/p05-value-types`, branch `p05/value-types`, base `feat/disaggregated @ 6672778b`.
Build dir `build-linux/` (Release, `/usr/sbin/clang++` clang 22, ccache, tests + integration tests ON).
Logs: `~/w7/logs/p05vt-*.log`, `~/w7/logs/nm-*.raw`, `~/w7/logs/probe_vt_H.txt`, `~/w7/logs/p203-*.log`.
## Commits (one, as the brief asks)
- `COMMIT_HASH` `[Refactor] (Pipe, State): extract MGPipeValueTypes.h - move the render-state, sampler and vertex value types and their enums out of MG_State/GLState so MG_Pipe no longer reaches RenderState.h; pure move, member order and namespaces unchanged`
Files: `MobileGL/MG_Pipe/MGPipeValueTypes.h` (new, 550 lines), `MobileGL/MG_Pipe/MGPipeTypes.h`, `MobileGL/MG_Pipe/generated/PipeVerify.inc`, `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}`, `MobileGL/MG_State/GLState/SamplerState/SamplerObject.h`, `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h`, `MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h`, `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp`, `scripts/gen_pipe.py`. Nothing under `MG_Backend/`, `MG_Impl/`, `MG_Util/` touched. Not pushed.
## What was done (B.1, in order)
1. `MGPipeValueTypes.h` created by a Python script (`scratchpad/wf3/p05-value-types/cut.py`) that slices the exact line ranges the brief names, with the anchor line of every range asserted before the cut: `RenderState.h:15-189` (11 enums, D2), `:191-370` (4 structs; `:263`/`:273` respelled to `kMGMaxDrawBuffers`), `SamplerObject.h:14-96` (6 enums + `SamplerParameters`), `VertexArrayObject.h:17-70` (3 vertex types, re-indented by one level because they now sit in `namespace MG_State::GLState` inside `namespace MobileGL` instead of three nested namespaces; namespace unchanged, D3; `class BufferObject;` forward-declared). `inline constexpr Uint kMGMaxDrawBuffers = 8;` (D4). Macro guard + `#pragma once`; includes exactly `<Includes.h>`, `<MG_Util/Math/VectorTypes.h>`, `<cstddef>`, `<type_traits>`. Trip wires as in the brief layout; the two "measure" numbers came out as `SamplerParameters` 100 and `VertexAttributeVersion` 6 (the build accepted them first time; `is_standard_layout_v<RenderStateParameters>` holds, so that assertion is kept).
2. Forwarding edits: `RenderState.h` now includes `<Includes.h>` + `<MG_Pipe/MGPipeValueTypes.h>` only; `RenderState.cpp` gained the direct `FramebufferObject.h` include (it spells `FramebufferObject::MAX_DRAW_BUFFERS` six times); `SamplerObject.h` and `VertexArrayObject.h` include the value header and keep only their classes; `FramebufferObject.h` includes the value header and defines `MAX_DRAW_BUFFERS = MobileGL::kMGMaxDrawBuffers`.
3. `MGPipeTypes.h:33` → `#include "MGPipeValueTypes.h"`, `:32` kept (D1), debt comment rewritten to say the MG_State half is repaid and `DynamicBackendParameters` is what still keeps gate A off `MGPipeTypes.h`; `using` comment updated. `gen_pipe.py:163-165` and the MEMCMP FALLBACK comment (`:410-414`, the source of `PipeVerify.inc:232-238`) reworded to P1; `python3 scripts/gen_pipe.py` run and the regenerated `.inc` committed (comment-only diff).
4. Full build: **zero lost-transitive-include failures** — no consumer `.cpp` needed a direct include (the candidates all reach `FramebufferObject.h` through `Core.h`, as the brief predicted).
5. Tests `PipeCatalogue.ValueTypeLayoutsArePinned` and `PipeCatalogue.ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail` added to `PipeCatalogueTest.cpp`; **no include added** (`offsetof` reaches it through `MGPipe.h → MGPipeTypes.h → MGPipeValueTypes.h → <cstddef>`).
## Verification (every command, actual result)
| # | command | result |
|---|---|---|
| 1 | `cmake --build build-linux -j 16` (three times: after the cut, after the tests, after a comment reword) | exit 0 each time; first build 237 steps, `libMobileGL.so` + all test binaries link |
| 2 | `ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure -j 8` | **100% tests passed, 0 failed out of 1460** (log `p05vt-unit.log`; rerun after the final rebuild: see `p05vt-unit2.log`, UNIT2_RESULT) |
| 3 | new tests present in the run | `#1053 PipeCatalogue.ValueTypeLayoutsArePinned Passed`, `#1054 PipeCatalogue.ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail Passed` |
| 4 | `ctest -N` name lists, `comm -23 before after` (`~/w7/pipe/build-linux` vs mine) | before 1327 / after 1329 names; **lost: none**; added: the two tests above |
| 5 | ODR grep (`^\s*struct (RenderStateParameters\|…)\b \| ^\s*enum class (BlendFactor\|BorderColorForm\|CapabilityInput)\b` over `MobileGL/`) | 11 hits, **all in `MobileGL/MG_Pipe/MGPipeValueTypes.h`** (lines 32, 168, 208, 219, 229, 239, 441, 447, 476, 517, 525); no second definition anywhere |
| 6 | `grep -n "MG_State/\|MG_Backend/\|MG_Impl/\|MG_Remote/" MGPipeValueTypes.h` | **empty** (after rewording my own PURITY comment, which had matched with a slash spelling) |
| 7 | `grep -n "#include" RenderState.h` | `10:#include <Includes.h>`, `11:#include <MG_Pipe/MGPipeValueTypes.h>` only |
| 8 | closure probe: `clang++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include -H -E` on `#include <MG_Pipe/MGPipeValueTypes.h>` | 654 closure lines, **0 under `MobileGL/MG_State/`, `MG_Backend/`, `MG_Impl/`, `MG_Remote/`** |
| 9 | same flags, `-fsyntax-only` on the probe TU | exit 0 (header is self-contained) |
| 10 | `git diff --stat 6672778b -- MobileGL/MG_Backend` | **empty** |
| 11 | `grep -rc "pGLContext" MobileGL/MG_Backend \| sort` before (pipe) vs after | **identical** |
| 12 | `python3 scripts/gen_pipe.py --check` | `generated files are up to date`, exit 0 |
| 13 | symbol report — `scripts/symbol_report.py` does not exist in this tree (it is the include-gate package's deliverable), so the equivalent was done by hand: `nm --defined-only -S` on `~/w7/pipe/build-linux/libMobileGL.so` vs `build-linux/libMobileGL.so`, keyed on mangled name, comparing type+size | 30511 → 30511 defined symbols; **0 added / 0 removed / 0 resized; 0 symbols changed address**; `size --format=sysv`: `.text` 10792579 B on both sides, Total 17209819 on both |
| 14 | attribution of every differing byte between the two `.so` files (`cmp -l`, mapped to sections) | 31 bytes total, length equal: 20 B in `.note.gnu.build-id`; 7 B in `.rodata` = the `GIT@a4baa9d` → `GIT@6672778` build stamp string (the reference build carries an older configure-time stamp); 4 B in `.rodata` = SPIRV-Tools' `Timestamp: 2026-09-05T22:05:41` → `22:36:04` string. `.text`, `.rodata` otherwise, `.data`, `.data.rel.ro`, `.eh_frame`, `.init_array`, `.dynsym`, `.dynstr`, `.gnu.hash` byte-identical (`objcopy --only-section` + `cmp`). Section table identical. **Zero code bytes differ.** |
| 15 | `ctest -L integration-gpu -j 8` (as configured) | 99%: 4 failed of 868 — three `*IsActuallyArmedWhenTheEnvironmentPinsItOn*` (the known `-j` flake) + `DirectVulkan.IterationRPProgram203Scenario.FixedCompleteInputProducesFixedCompleteGoldenOutput`; `--rerun-failed -j 1`: the three flakes pass, Program203 still fails (1 texel at (0,0), actual `(0x357a,0x4b65)` vs golden `(0x3a74,0x4821)`) — **diagnosed below as a configure difference of the build dir, not a regression** |
| 16 | `ctest -L integration-gpu -j 8` with `MOBILEGL_MAGMA_FIX_ITERATIONRP_SUBGROUP_SCRATCH=1 MOBILEGL_MAGMA_DERIVE_NUM_SUBGROUPS=1 MOBILEGL_MAGMA_ITERATIONRP_FIX_BARRIER=1` exported (what CI's integration-gpu job does, per `MG_IntegrationTest/CMakeLists.txt:286-291`), then `--rerun-failed -j 1` | ITEST2_RESULT |
### Program203 diagnosis (item 15)
- Passes 3/3 in `~/w7/pipe/build-linux`, fails 3/3 in mine, deterministically, same wrong bits every time.
- `.text` of `libMobileGL.so` **and** of `MobileGLIntegrationTest` are byte-identical between the two trees.
- `ctest -N -V` shows the reference registers the test with `ENVIRONMENT … VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.json; MOBILEGL_MAGMA_FIX_ITERATIONRP_SUBGROUP_SCRATCH=1; MOBILEGL_MAGMA_DERIVE_NUM_SUBGROUPS=1; MOBILEGL_MAGMA_ITERATIONRP_FIX_BARRIER=1`; mine registers only `MOBILEGL_BACKEND_TYPE=DirectVulkan`.
- Cause: `MG_IntegrationTest/CMakeLists.txt:284-298` attaches the three repairs only when `MOBILEGL_ITEST_VK_ICD MATCHES "lvp_icd|lavapipe"`. `~/w7/pipe/build-linux/CMakeCache.txt` has `MOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json`; **`~/w7/p05-value-types/build-linux/CMakeCache.txt` has `MOBILEGL_ITEST_VK_ICD=` (empty)** — the package worktree was configured without the ICD pin. The only ICD on the machine is lavapipe, so the test runs on lavapipe either way, just without the repairs forced on — exactly the "Program 203 misses its golden output" case the CMake comment describes.
- Proof: my binary run by hand with the three variables → `mismatches=0/262656`, PASSED; the reference binary run by hand without them → `mismatches=1/262656`, the identical wrong bits, FAILED.
- I did not reconfigure `build-linux/` (the brief handed it to me as-is); I ran the lane with the variables exported instead (item 16). **Integrator note:** the other two p05 worktrees were presumably configured the same way and will show the same single failure on this test under a plain `ctest -L integration-gpu`; `cmake -DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json build-linux` on each fixes the registration.
## Deviations from the brief
1. **Deleted the blank separator line after each cut region** (`RenderState.h:371`, `VertexArrayObject.h:71`) in addition to the ranges the brief names, so the forwarding headers do not keep a stray empty line right after the opening `namespace` brace. Whitespace only.
2. **The value header's leading comment is not the brief's two-line PURITY text verbatim**: I spelled the forbidden directories without a trailing slash (`MG_State, MG_Impl, MG_Backend or MG_Remote`) because the brief's own text-purity grep (`grep -n "MG_State/\|…"`) matched the brief's suggested wording; the grep is now empty as the brief requires. Added a short paragraph saying what the header is and why the MG_State headers forward to it.
3. **`MGPipeTypes.h` debt comment / `gen_pipe.py` comments are my wording**, following the brief's content instructions (MG_State half repaid; `DynamicBackendParameters` remains and keeps gate A off `MGPipeTypes.h`; field lists in P1). `gen_pipe.py:165` was wrapped onto two lines to stay under the file's line width.
4. **`ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail` pins two more offsets than the brief lists** (`RenderState` at 0, `PatchVertices` at 1208) and `ValueTypeLayoutsArePinned` also checks `ColorMasks`' extent and the trivially-copyable/standard-layout predicates at runtime. Additions only.
5. **No `scripts/symbol_report.py`** in this tree (B.3 deliverable, not yet landed): the nm comparison was done by hand as the task allows; every byte of difference is attributed (item 14).
6. **`ctest -L integration-gpu` was run twice**: once as configured (item 15, one non-regression failure explained above) and once with CI's three environment variables exported (item 16). No test file, CMake file or build configuration was changed to get there.
7. `scripts/check_include_closure.py --mode both --probe value-header` (the "once p05/include-gate exists" line) was not run: the script is not in this tree. The equivalent manual `-H` probe (items 8-9) is green.
## Unfinished
UNFINISHED_TEXT