docs(step097): close A2 Android Core validation

docs/报告/STEP-097_A2_阶段验证记录_v3.md

@@ -0,0 +1,96 @@
+# STEP-097 A2 阶段验证记录 v3
+
+## 1. 结论
+
+**A2 Android/Core 验证完成；STEP-097 整体仍 PARTIAL。** A2 的 04–07 在 Core、OpenGL/Metal host 回归和 FZG1-2 设备闭环达到本阶段检查点。没有开始 B/C，没有执行 Jest、STEP-098 或 `.13` 发布。iOS runtime 依用户决定豁免，记为 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`，不是 iOS PASS。
+
+Codex 会话配置：**GPT-6 Luna High**，用户可见会话。RDC 独立执行了 CMake/GTest、shader generator、标准 Android APK 构建、FZG1-2 安装和设备场景。Codex 本轮未执行这些命令。
+
+## 2. Git 与版本基线
+
+- 仓库：Mac `Mac-mini-tei.lan`，`/Users/tei/dev/MapLibreParticleLab`；分支 `particle/main`。
+- 验证源码基线 HEAD：`5bb1a0e6353c5dfe8db8a61bbeba9cef447280ef`；A2 源码工作树 dirty，尚未提交。结束 HEAD 未变化。
+- 本次记录前的 A2 source diff SHA-256：`18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2`；与 `artifacts/maplibre-particle/step097-a2-final-validation/mix-reuse-build-source.diff` SHA-256 完全一致。标准 APK 的 build-info 也记录相同 commit/branch 和 `git_dirty=true`，证明设备验证所用 source snapshot 与本轮代码一致。
+- Integration `main`：`318f8ccf911ac3136c3086a1d14e61f83e2d4bce`；C-001 未修改。
+- 冻结的 `.13` 发布坐标、tag、manifest 与产物未修改；本轮不发布。
+- 用户 untracked `docs/40_任务/STEP-098_QBIN_V4单帧首显与八帧滚动缓存_Codex任务_v1.md` 保持原样、未 stage。
+
+## 3. A2 实施内容
+
+| 项 | 实施与不变量 |
+| --- | --- |
+| 04 N04/B06 Forecast PLAY | Map Continuous update 驱动 Source-owned monotonic forecast clock；Android/iOS timer 只负责唤醒。同步 SourceObserver reentry 由 `forecastTickInProgress` 防止重复推进。显式 setTime、PLAY/PAUSE、rate、clear 保持 Core clock 所有权。 |
+| 05 B13 GPU endpoint / mix-only reuse | `sameFieldGpuContent()` 继续只表示 version-agnostic decoded payload 等价；新的 `sameFieldGpuEndpoint()` 严格比较 revision/time、U/V、validity、grid、encoding 等 renderer endpoint 身份。Source 对相同 content identity、binding、immutable decoded frame 与 plane/validity storage pointer 复用已有 materialized T0/T1，只更新 `sampleState`。frame/revision 或任一输入 storage 改变则重新物化；invalid/clear fail-closed。移除每 tick 深比较完整 snapshot vectors。 |
+| 06 B07 RGBA8 signed zero | 增加内部 `particle_gpu_math.hpp` signed RGBA8 编码，byte 128 明确表示 0；shader 以 high precision 还原 byte。未改公开 QBIN/FieldProfile encoding。数学测试覆盖正负取消、零、NaN/invalid 与量化下限。 |
+| 07 B08 Mercator U/V | helper 与 GL/Metal shader 的东向 U、北向 V 都使用相同纬度度量，极区分母夹紧；保持 canonical m/s 和现有视觉时间倍率。测试覆盖 0°/45°/60° 四方向及极区有限值。 |
+
+三项 A2 Source 测试还覆盖 50 次 mix-only clock tick 不重物化、真实 endpoint 和相同 valid-time revision 替换触发重物化、clear 后 projection 清空，以及 source notification 嵌套 tick 不双推进。Host-facing 新 API、C-001、QBIN 格式未改变。
+
+## 4. 修改文件
+
+### 源码、shader 与 A2 测试
+
+- `include/mbgl/particle/field/field_data_adapter.hpp`
+- `include/mbgl/particle/field/particle_gpu_math.hpp`（新增）
+- `include/mbgl/shaders/gl/particle_gpu_validation.hpp`
+- `include/mbgl/shaders/mtl/particle_gpu_validation.hpp`
+- `include/mbgl/style/sources/raster_array_source.hpp`
+- `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java`
+- `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt`
+- `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/Step097V4GoldenFixture.kt`（新增）
+- `platform/android/MapLibreAndroidTestApp/src/main/assets/integration/step097-v4/wind/T0.qbin`、`T1.qbin`、`contract.json`（新增 test-only fixture）
+- `platform/ios/src/MLNParticleFieldRuntime.mm`
+- `shaders/particle_gpu_validation.fragment.glsl`、`shaders/particle_gpu_validation.vertex.glsl`
+- `src/mbgl/map/map_impl.cpp`
+- `src/mbgl/particle/field/field_data_adapter.cpp`
+- `src/mbgl/particle/field/field_projection_materialization.cpp`
+- `src/mbgl/particle/field/field_runtime.cpp`
+- `src/mbgl/renderer/layers/render_particle_validation_layer.cpp`
+- `src/mbgl/style/sources/raster_array_source.cpp`、`src/mbgl/style/sources/raster_array_source_impl.hpp`
+- `test/CMakeLists.txt`
+- `test/particle/field_runtime.test.cpp`
+- `test/particle/particle_gpu_math.test.cpp`（新增）
+- `test/source/raster_array_v4_host_api.test.cpp`
+- `test/style/source.test.cpp`（仅修正旧断言对 `sameFieldGpuContent()` 的预期；严格 endpoint identity 由新断言覆盖）
+
+本报告之后的文档变更为 `docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md`、本报告、`docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v2.md`、`docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md`、`docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md` 及根目录 `粒子开发记录.md`。无其他步骤范围代码。
+
+## 5. RDC 构建与测试
+
+| 验证 | RDC 结果 |
+| --- | --- |
+| 原有完整 58 项回归（修正旧断言后） | OpenGL **58/58 PASS**。先前 57/58 的失败根因是旧断言把 `sameFieldGpuContent()` 当成 revision-sensitive；函数原有契约明确忽略 generation/dataVersion。测试现在分别验证 payload 等价与 strict endpoint identity，没有放宽 endpoint 比较。 |
+| 当前 broad Core filter `Particle*.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*` | OpenGL **121/121 PASS**；Metal host **121/121 PASS**。 |
+| A2 定向 Source 三项 | OpenGL **3/3 PASS**；Metal host **3/3 PASS**，包括 mix-only 50 ticks、endpoint/revision invalidation 与同步通知重入。 |
+| shader generator | `node shaders/generate_shader_code.mjs` 连续两次成功，输出幂等。 |
+
+构建/测试日志：`artifacts/maplibre-particle/step097-a2-final-validation/mix-reuse-broad-opengl.log`、`mix-reuse-broad-metal-host.log`、`mix-reuse-focused-opengl.log`、`mix-reuse-focused-metal-host.log`、`build-mix-reuse-opengl.log`、`build-mix-reuse-metal-host.log`。Metal host 测试是 Mac Core runner，不是 iOS runtime 或设备 Metal 验证。
+
+## 6. Android APK 与 FZG1-2
+
+- 标准命令由 RDC 执行：`./tools/particle_android_validation/build_validation_apk.sh`。
+- 产物：`artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`；OpenGL Debug、x86_64、61,753,803 bytes；SHA-256 `27bf4a6cc191bd86c4d1c10398478d81c2999edd61fe7242e40e5188516b0ca5`。步骤归档副本：`artifacts/maplibre-particle/step097-a2-final-validation/MapLibreAndroidTestApp-A2-mix-reuse-x86_64.apk`。
+- RDC 安装至 Panasonic FZG1-2（ADB `192.168.200.139:5555`）成功；设备内 APK SHA-256 与构建产物相同。
+- Test-App-only Golden Wind T0/T1 场景脚本 exit 0，17 PNG、24 steps、ANR=0：load、seek 25/75、speed 2x/1x、PLAY 30 秒与 PLAY 时 UI/TIME 响应、PAUSE/stable pause、replay、CLEAR、reload、再次 PLAY/PAUSE。截图 `after-v4-mix-reuse/05_play_15s.png` 可见粒子。
+- 上传/reset 计数按资源 epoch 记录：clear/reload 前 mix-only playback 稳定于 `fieldUploadCount=6/resetCount=2`；CLEAR/reload 后计数合法增加到 `fieldUploadCount=10/resetCount=4`，reload 后 playback 稳定。没有宣称跨 CLEAR/reload 零上传/零 reset。
+- APK 输入源码 diff 与保存快照 `mix-reuse-build-source.diff` 的 SHA-256 都为 `18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2`。
+
+## 7. 历史失败、性能与平台边界
+
+- 2026-09-26 12:43 首次 FZG1 ANR 的 main stack 是 Forecast clock tick 的同步 SourceObserver reentry；`forecastTickInProgress` guard 与回归测试针对该缺陷。后续有一轮没有 ANR 但 UI/TIME 仍不可用、主线程高负载；debuggerd 定位到每 tick 对大 QBIN projection 重复物化 validity/vector 并深比较 snapshot。mix-only immutable snapshot reuse 后，最终 FZG1 闭环通过。
+- 历史 debuggerd、首次 ANR、第二次无响应试跑及最终验证证据均保存在 `artifacts/maplibre-particle/step097-a2-final-validation/`；报告保留失败经过，不把中间失败覆盖成 PASS。
+- PLAY 30 秒只是交互闭环，不是 long-run 稳定性、FPS、frame time、内存或 GPU 性能基准；本轮没有这类数字。
+- 用户豁免 iOS runtime：`USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`。Android 与 Metal host Core 结果不能替代 iOS device PASS。
+- Integration C-001 未改，Host 公开 API/QBIN schema 未改；没有进入 B/C、没有运行 STEP-098/Jest、没有更改 `.13` 发布物。
+
+## 8. 阶段与 Git 收尾
+
+- A2 状态：Android/Core 代码、原生回归和 FZG1 验证完成。
+- STEP-097 整体：**PARTIAL**；B/C 未开始。其余 24 项逐项状态见更新后的去重矩阵。
+- 本报告无 commit/push。RDC 后续做独立 QA 与 scoped Git 操作；用户未跟踪 STEP-098 不得纳入。
+
+## 9. RDC Git 源码提交核验（报告编写后更新）
+
+- A2 源码、标准 TestApp 内部 fixture 与定向测试已以 **`f49ffa68a17e0a505199bdbeccf07f8543f3a05f`** 独立 scoped commit 提交并推送 `origin/particle/main`；26 个代码/fixture/test 路径，未包含任何文档、STEP-098、Integration、NavSea 或发布资产。远端 HEAD 回读相同。
+- 该提交只是把已经通过 RDC 验证的源码固定进 Git；构建时仍如实为 `5bb1a0e` + dirty source diff。源码部分保存快照的 SHA-256 对应提交内容，不把后续文档更新误算进构建输入。
+- 文档与 Step/矩阵/测试清单将作为独立 scoped commit 收尾。

docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v2.md

@@ -0,0 +1,96 @@
+# STEP-097 V13 三轮审查问题合并修复 — Codex 完成报告 v2
+
+## 1. 执行结论
+
+**PARTIAL：A1 与 A2 的 Android/Core 检查完成；B/C 未开始。** A2 04–07 已由 Codex GPT-6 Luna High 在用户可见会话实现，由 RDC 独立构建、测试和执行 FZG1-2 运行闭环。iOS runtime 依据用户决定豁免，状态为 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`，不是 iOS PASS。没有运行 Jest、STEP-098 或发布 `.13`。
+
+## 2. Git、环境与发布基线
+
+- 机器：`Mac-mini-tei.lan`；仓库：`/Users/tei/dev/MapLibreParticleLab`；branch：`particle/main`。
+- 源码验证基线 HEAD：`5bb1a0e6353c5dfe8db8a61bbeba9cef447280ef`；验证时 worktree dirty，未提交。报告编写只增加/更新本报告所列 A2 文档。
+- A2 source diff SHA-256 `18927a5f30a88f5c1c3a00e0017473dc33b04151c227e4baf52250dc4ad2e6a2`，与 APK build source snapshot 完全相同。
+- Integration `main`=`318f8ccf911ac3136c3086a1d14e61f83e2d4bce`；C-001 未修改。
+- 冻结 `.13` 坐标/tag/manifest/发布产物未改。没有提交或 push。
+- 用户 untracked STEP-098 任务文件保持未跟踪、未修改、未 stage。
+
+## 3. 修改文件
+
+源码、shader、测试及 Test-App-only V4 Golden fixture 的完整路径列于 [A2 阶段验证记录 v3](STEP-097_A2_阶段验证记录_v3.md) 第 4 节。核心范围包括 `RasterArraySource` 与 `Map::Impl` Forecast clock、严格 GPU endpoint identity 和 mix-only snapshot reuse、signed RGBA8 helper、GL/Metal shader 与 Mercator 数学、Android/iOS timer wake bridge、A2 Core 回归和 test-only Wind T0/T1 fixture。
+
+本轮交付文档：
+
+- `docs/报告/STEP-097_A2_阶段验证记录_v3.md`
+- 本文件 `docs/报告/STEP-097_V13三轮审查问题合并修复_Codex完成报告_v2.md`
+- 更新 `docs/30_设计/STEP-097_V13三轮问题去重与修复矩阵_v1.md`、`docs/50_Step记录/STEP-097_V13三轮审查问题合并修复_v1.md`、`docs/60_测试/STEP-097_V13修复后集中验证清单_v1.md`
+- 仅追加根目录 `粒子开发记录.md`
+
+未修改 Integration、NavSea、项目总则、C-001、QBIN schema、`.13` 发布物、用户 STEP-098 或 Host public API。
+
+## 4. 24 项状态
+
+| # | 状态与实际结论 |
+| --- | --- |
+| 01 N01/B01 | A1 Android/Core 检查完成；同源 stencil fixture FZG1 检查已在 A1 报告记录。A1 iOS runtime 按用户决定豁免。 |
+| 02 N02/B02 | A1 Android/Core 阶段收口；Metal host 不是设备验证。无 iOS runtime，按用户豁免记录。 |
+| 03 N03/B12 | A1 Android/Core 阶段收口；异常恢复 GTest 已在 A1 报告记录。 |
+| 04 N04/B06 | A2 完成；唯一 Source forecast clock、wake-only timer 与同步回调重入保护；OpenGL/Metal host 定向测试和 FZG1 PLAY/PAUSE 实测通过。 |
+| 05 B13 | A2 完成；`sameFieldGpuContent` 仍为 payload 等价，strict endpoint identity 独立比较；mix-only snapshot reuse 与 revision invalidation 通过 Core/设备验证。 |
+| 06 B07 | A2 完成；内部 signed zero encoding/shader 路径和数学边界测试通过 OpenGL 与 Metal host broad 回归。 |
+| 07 B08 | A2 完成；U/V 纬度 metric 和极区夹紧，数学回归与 Android 场景通过；不等于 iOS runtime。 |
+| 08 N05 | `WAITING_RDC_BUILD_AND_RUNTIME`；B 未开始。 |
+| 09 N06 | `WAITING_RDC_BUILD_AND_RUNTIME`；B 未开始。 |
+| 10 N07 | `WAITING_RDC_BUILD_AND_RUNTIME`；B 未开始。 |
+| 11 F01/C01 | `WAITING_RDC_BUILD_AND_RUNTIME`；C 未开始。 |
+| 12 F02/C02/B03 | `DEFERRED_DESIGN`；同步等待依赖未在本阶段处理。 |
+| 13 F03/C03/B04 | `WAITING_RDC_BUILD_AND_RUNTIME`；C 未开始。 |
+| 14 F04/C04 | `DEFERRED_DESIGN`；无资源预算改动。 |
+| 15 C04/B11 | `DEFERRED_DESIGN`；无 store 总容量语义改动。 |
+| 16 F07/C05 | `WAITING_RDC_BUILD_AND_RUNTIME`；C 未开始。 |
+| 17 C06/B05/B10 | mix-only immutable materialization 子项随 A2 完成；其他 diagnostics、ordinal、UI owner 工作仍待后续，整体不得解读为 C 完成。 |
+| 18 C07 | `DEFERRED_DESIGN`；drawable/tweaker 生命周期未改。 |
+| 19 F09/O01 | A1 已有 GTest 与 FZG1 证据保留；不把资源诊断夸大为 GPU 无泄漏证明。 |
+| 20 F05/E01 | `WAITING_RDC_BUILD_AND_RUNTIME`；B/Test Host package lock 未改、未验证。 |
+| 21 F06 | `DEFERRED_DESIGN`；保留 multi-C 安全 fallback。 |
+| 22 F08 | `DEFERRED_DESIGN`；保留保守失效策略。 |
+| 23 F10/E02 | `DEFERRED_DESIGN`；需要跨项目协调，Integration status 未改。 |
+| 24 STEP-095 §7/B09 | `DEFERRED_DESIGN`；共享地理 Ocean Mask 需要后续跨项目契约。 |
+
+矩阵保留全部 24 项、旧编号及平台边界。
+
+## 5. 实现摘要与偏差
+
+1. Forecast clock 每次由 Map Continuous update 调用一次；同步 SourceObserver 重入不再触发第二次 tick。Android/iOS timers 负责 triggerRepaint 唤醒，不独立推进时间。
+2. Strict endpoint identity 涵盖 frame/revision、grid、U/V、validity 与 encoding。mix-only 时复用当前 immutable materialized snapshots；新 frame/revision 或 storage identity 改变时重新 materialize；clear/invalid 仍 fail-closed。没有使用 generation/dataVersion 偷换 `sameFieldGpuContent()` 的已有语义。
+3. RGBA8 byte 128 表示 signed zero，GL/Metal shader 使用高精度 byte reconstruction。东/北向 Mercator 位移应用一致纬度 metric。
+4. 新增 A2 定向 source 测试、GPU math 测试及 test-only Golden Wind 两帧 fixture；没有新建 Host API、QBIN 格式或 C-001 语义。
+5. 首次 FZG1 ANR 是同步 clock notification 重入；guard 修复后仍有一轮因每 tick 重物化大场、深比较而 UI 不响应。最终 mix reuse 版本完成设备闭环。原始失败日志与 debuggerd 均保留。
+
+## 6. RDC 构建、测试、设备及产物
+
+- 原 58 项回归：旧断言修复后 **58/58 PASS**。失败断言与旧函数定义不符，修复测试语义；没有放宽新 strict endpoint 条件。
+- OpenGL broad Core filter：**121/121 PASS**。
+- Metal host 相同 broad Core filter：**121/121 PASS**。
+- 三项 A2 Source 定向测试：OpenGL 和 Metal host 各 **3/3 PASS**。
+- Shader generator 连续两次成功、输出幂等。
+- 标准 APK `./tools/particle_android_validation/build_validation_apk.sh`：OpenGL Debug、x86_64、61,753,803 bytes；SHA-256 `27bf4a6cc191bd86c4d1c10398478d81c2999edd61fe7242e40e5188516b0ca5`。FZG1-2 安装成功、设备 hash 相同。
+- Golden 闭环：17 PNG、24 steps、exit 0、ANR=0；PLAY 30 秒并确认 TIME/UI 操作响应，随后 PAUSE/stable pause/replay/CLEAR/reload/replay/PAUSE。15 秒截图有可见粒子。
+- 日志资源 epoch：首次 stable mix-only `upload=6/reset=2` 保持不变；CLEAR/reload 后合法到 `upload=10/reset=4`，随后 playback 稳定。没有宣称跨 CLEAR/reload 零上传或 reset。
+- Android 产物、测试日志、设备日志、截图、步骤清单、debuggerd 与历史失败证据在 `artifacts/maplibre-particle/step097-a2-final-validation/`。
+- 本轮无 FPS、p50/p95/p99、frame time、内存或 long-run 性能结论。iOS runtime 未运行，用户豁免。
+
+## 7. 未完成与限制
+
+- STEP-097 总体仍 `PARTIAL`：B/C 未进入。04–07 完成不代表 08–24 全完成；第 17 项只有 mix-only 子项完成。
+- iOS runtime：`USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`。Metal host GTest 只证明共享 Core host 路径，不能替代 iOS Metal device PASS。
+- FZG1 Golden 是 Test-App-only fixture，不是 NavSea、正式产品数据链或全量天气验收。
+- 30 秒 PLAY 交互不构成长时稳定性或正式 GPU 性能验收。
+- 无提交/推送；用户 STEP-098 未触碰；`.13` 未发布。
+
+## 8. 后续交接
+
+RDC 对当前 dirty A2 代码与本报告做独立 QA，按用户后续授权执行 scoped Git 操作。若后续继续 STEP-097，只能由用户明确允许进入下一个阶段后启动 B；本报告不自动开启 B/C。
+
+## 9. RDC 源码 Git 后续事实（本报告编写后）
+
+- 源码 scoped commit **`f49ffa68a17e0a505199bdbeccf07f8543f3a05f`** 已推送 `origin/particle/main`，远端核对一致。此事实覆盖前文“未提交/未推送”的报告编写时状态，保留原始验证 HEAD 以便追溯 dirty APK 的实际构建来源。
+- 文档另行提交；不将源代码 Git commit 当作额外编译/设备测试。用户 STEP-098 仍不提交，B/C 不启动。