# 40-01 Android 正式粒子 State Seed 修复 Codex 完成报告 v1

## 1. 结论

已修复正式粒子的 State 初始化契约。40-01 保持 `WAITING_MANUAL_VALIDATION`；未运行 Android Gradle、ADB 或实体机。

## 2. 根因

`RenderTarget::render()` 按 MapLibre 既有 contract 将每个 offscreen pass clear 为 `(0,0,0,1)`。State shader 原本把 `previous.a < 0.5` 当作“尚未 seed”，但新的 State A/B target 因此是 opaque black，条件恒为 false。所有 16×16 State texel 都从 `(0,0)` 开始；uniform-east 仅移动 x，四个 deterministic marker 聚在 canonical world 顶缘，当前视口通常不可见。

没有修改 `src/mbgl/renderer/render_target.cpp`。

## 3. Seed contract

- `ParticleGpuResources::stateSeeded` 是唯一生命周期权威。
- State pass 使用已有 UBO 的 `u_mask.w`：`1.0 = SEED_STATE`，`0.0 = CONTINUE_STATE`。
- shader 在 `SEED_STATE` 时让每个 texel 从自身 `v_uv` 初始化，再采样 field；在 `CONTINUE_STATE` 时从 State read texture 的 `previous.rg` 继续。`field.a` 仍仅表示 Field/NoData validity。
- Composite commit 后既有 `commit()` 将 `stateSeeded=true`。新 resource、context recreation 和 fixture/field reset 令其恢复 false；普通 ACTIVE、Camera、STATIC 与 transient `markLayerRenderable(false)` 不会重 seed。
- STATIC zero-step bootstrap 使用相同 seed flag，但 `simulationStep=0`，因此建立分散的 deterministic state 而不推进 simulation。

Trail/Composite 的 State write → Trail write wiring、slot swap、hazard=SAFE、formal display、legacy validation display、fixture、mask、world wrap、antimeridian、rotation resource lifecycle 均未改变。

## 4. 诊断与静态验证

- 新增低频 `ParticleRender: stateSeed=INITIALIZE|CONTINUE`，含 generation、State A/B 和 fixture。
- shader source：`shaders/particle_gpu_validation.fragment.glsl`；由 `node shaders/generate_shader_code.mjs` 生成 OpenGL header，未手改 generated header。
- generator 二次运行幂等：PASS；GLSL source 与 generated fragment parity：PASS。
- Linux OpenGL `render_particle_validation_layer.cpp.o`、相关 `test/style/source.test.cpp.o` 精确编译：PASS。
- `clang-format --dry-run --Werror` 与 `git diff --check`：PASS。

## 5. 下一步

用户下一次只验收 GLOBAL + ACTIVE + `uniform-east`：四个 deterministic marker/trail 应分散在 world 内，且连续向 east 移动。通过前不声明 40-01 PASS。

## 6. Git 收尾

最终代码修复 commit：`087d80d0527c33743a6c59a5c7cce5eeb836dfb5`（`fix: seed particle state explicitly`）。push 成功后 remote branch 与 `origin/particle/main` HEAD 在交付结果中记录。