MobileGL/docs/archive/notes/p5b/PACKAGE-PREAMBLE.md

P5b 包通用前言 — 每个包开工前必读

P5b = verb migration under inproc, Minecraft-first（ID-66/ID-68）。目标一句话：让真实负载 （首先是每一条 Minecraft trace）在 MOBILEGL_TRANSPORT=inproc 下由 apply 线程渲染， 越快越好。四个包并行迁移 25 个实测 class-C slot，门只有一个：inproc lane 的 abort 数与 trace 的 first-blocker 表。

你在哪、读什么

• 集成树 ~/w7/pipe，分支 feat/disaggregated。不要直接在里面干活。 你的工作树：cd ~/w7/pipe && git worktree add ~/w7/p5b-<你的 slug> -b p5b/<你的 slug> refs/heads/feat/disaggregated
• 契约优先于 brief，按这个顺序读：
  1. MobileGL/MG_Remote/CONTRACT-P5.md（P5 的四张表与 R-1…R-17，仍然全部有效）。
  2. MobileGL/MG_Remote/CONTRACT-P5B.md（P5b 的增补：25 个 slot 每一行的 wire record、 sink 签名、拒绝形状、stamp；§6 是 c0b 的裁定与推翻条件；§8 是文件所有权）。
  3. ~/w7/notes/p5b/BRIEF-P5B.md（四个包各自的 slot、文件、门、以及之后的循环）。
  4. 普查：~/w7/notes/p6/census-classC.md（你的 slot 的命中数、"下一个 blocker"的估计）。
  5. c0b 的报告：~/w7/notes/p5b/p5b-results/c0b-v1.md（落了什么、每条裁定、数字、债）。
  6. P5 的材料按需：~/w7/notes/p5/PACKAGE-PREAMBLE.md、INTEGRATOR-DECISIONS.md （ID-57 的"按名拒绝"形状、ID-66 的流程规则、ID-68 的普查裁定）、 p5-results/c1-v3.md（五个 class-B emitter 是怎么写的）、v1-v3.md（ServerVerbSink）。

流程规则（用户，2026-09-16，ID-66）

• 快，不做过度验证。 不做轮次之间的对抗审查；整个 P5b 收尾时由 Codex 做一次。
• 一个包在自己的门 + 集成者的快门上落地：unit 四车道、integration-split（inproc）、 push monolith 逐名一致（G2/G14）、G1。没有 verifier 包。
• 你的门（BRIEF §3）：lane 里你的 slot 的 abort 数 → 0，受影响的每个场景到达它的下一个 first blocker，按名报告；d1 另加：每一条 Minecraft trace 在 inproc 下到达下一个 first blocker，按名报告。
• 设备 A/B 在后台记录，永不阻塞。

第一天必踩的两个坑（P5 原样继承）

1. worktree 的 submodule 是符号链接。抄 ~/w7/p5b-c0b-setup.sh 与 ~/w7/p5b-c0b-submodlinks.sh（把 p5b-c0b 换成你的 slug）。 跑任何 git 命令之前 submodlinks.sh off，跑构建之前 on。
2. 任何报构建结果的脚本，先确认 CTestTestfile.cmake 存在再相信它。
3. （新）后台任务要 setsid nohup … < /dev/null &：从 Windows 侧的 wsl.exe 起的 shell 退出时会带走普通的 nohup … &。

构建配方（不变）

export CCACHE_BASEDIR=/home/swung/w7
COMMON="-G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
 -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
 -DCMAKE_BUILD_TYPE=Release -DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO \
 -DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_INTEGRATION_TEST=ON -DMOBILEGL_BUILD_BENCHMARK=OFF \
 -DMOBILEGL_ITEST_EGL_VENDOR=/usr/share/glvnd/egl_vendor.d/50_mesa.json \
 -DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json \
 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_POLICY_VERSION_MINIMUM=3.5"
export GLIBC_TUNABLES=glibc.malloc.tcache_count=0

• pull = 无额外 flag；push = -DMOBILEGL_PIPE_PUSH=ON； verify = -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON； split = -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON。
• -j 24。~/w7/p5b-c0b-gate.sh 是可抄的骨架（四目录 + 生成器 + 纯度 + G1 + 四条 unit 车道）， ~/w7/p5b-c0b-census.sh <tree> <outdir> 是把 P6 普查跑在任意树上的版本 （results.json 里每条 entry 的 status 与第一行 Fatal{…}）。

每个包都要自测的五件事

1. G1：python3 scripts/symbol_report.py --before ~/w7/p5-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 必须 0 增 / 0 删 / 0 resize / 0 重命名、.text +0（基线 .READY = 4595163c）。 P5b 最容易破的门：你加的一切都必须 push/split-only。后端里的任何新函数、新字符串、 新成员都要在 #if MOBILEGL_BUILD_DISAGGREGATED（或至少 MOBILEGL_PIPE_PUSH）之内。
2. ctest -L unit 四目录（c0b 头上的基线见 c0b-v1.md §2）。
3. integration-split 在 build-split、MOBILEGL_TRANSPORT=inproc 下 22/22； push integration-gpu 1128/1128 且与 ~/w7/p5-before-ctest-names.txt 逐名相同（G2/G14）。
4. 你的普查：~/w7/p5b-c0b-census.sh ~/w7/p5b-<slug> ~/w7/p5b-<slug>-census-logs， 然后按 slot 数 Fatal{UnmigratedVerb, "…"}；c0b 头（f5676103，含 v1 round 3）上的基线是 432 passed / 185 skipped / 505 aborted / 27 failed，505 个 abort 全部是 UnmigratedVerb， 逐 slot 表与 census-classC.md 相同（P6 的 426/185/511/27 里那 6 个 StageSnapshotTooNarrow 已被 v1 r3 修掉，见 c0b-v1.md §2.5）。基线的 results.json 在 ~/w7/p5b-c0b-census-logs/。你的 slot 的计数必须归零，多出来的 first blocker 必须按名列出。 d1 另跑 ~/w7/notes/tools/p6_census_traces.sh 的同等物（trace 的 first-blocker 表）。 c0b 头上的其余基线：unit 1817 × 3、split 2084；integration-split inproc 22/22（2 skipped）； push integration-gpu 1128/1128；G1 .text 10806611 +0、27814 符号 0/0/0/0。
5. python3 scripts/gen_pipe.py --check / gen_pipe_field_ownership.py --check （若你碰了任何 .def — 除 CONTRACT-P5B.md §8 明确授权的两处外你不该碰）。

铁律

• 提交信息 [Type] (Scope): description，单行，绝不加 Co-Authored-By 或任何署名行。
• 只改你拥有的文件（CONTRACT-P5B.md §8）。需要改别人的，向集成者提。
• 目录行的 opcode 永不移动；新调用追加，退役的调用保留槽位。
• 不要拉 GitHub LFS。fixture 从 ~/w7/pipe/tools/trace_replay/fixtures 拷（全部已 hydrate）。
• 不要碰任何 adb 设备。
• 临时文件 ~/w7/p5b-<slug>-*，收工时只留报告引用的那几个。 别在别的任务正在写日志时用通配 rm。
• 绝不把源文件通过"引号 heredoc 套引号 heredoc"写出去。
• 性能只记录不设门；inproc 是 lockstep，慢是预期（R-1 的栅栏税）。

收工

1. 在你的分支上提交（多个单行提交没问题）。
2. 写 ~/w7/notes/p5b/p5b-results/<slug>-v1.md：落了什么、每一条契约没做的裁定 （带证据 + 推翻它需要什么）、五件自测的数字、你的 slot 归零后的下一个 first blocker 表 （按场景、按 trace，逐名）、以及留给后续轮次的账。
3. 返回 ≤200 词：提交区间、验收数字、其他包最需要知道的三件事。