[Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository

Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
This commit is contained in:
2026-09-18 23:31:39 -04:00
parent edd0fef5cd
commit aba329cc53
420 changed files with 131235 additions and 6 deletions
@@ -0,0 +1,101 @@
# 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 词:提交区间、验收数字、其他包最需要知道的三件事。