docs: close STEP-099 render source diagnostics

2026-10-06 15:33:12 +09:00
parent 8a5214d92d
commit c4b481fd2c
3 changed files with 721 additions and 0 deletions
--- a/docs/报告/STEP-099_RenderSource就绪与RenderSegment失效诊断_Codex完成报告_v1.md
+++ b/docs/报告/STEP-099_RenderSource就绪与RenderSegment失效诊断_Codex完成报告_v1.md
@@ -0,0 +1,536 @@
+# STEP-099 RenderSource 就绪与 RenderSegment 失效诊断 — Codex 完成报告 v1
+
+## 1. 执行结论
+
+**CLOSED / PASS（诊断阶段完成）**。
+
+STEP-099 按任务书保持“纯诊断、fail-closed、不优化正式语义”的范围完成。Renderer/Source/RenderSegment diagnostics、Android Test App T1～T4 场景、定向 native 测试和 Android 实机运行证据均已取得，Q1～Q7 可以据实回答。
+
+本 Step **没有**修改 retained cache 算法、fast path gate、`singleContinuousSegment`、multi-continuous 行为、segment-local invalidation、RenderSegment 执行语义、NavSea、Source `isLoaded()` 定义或 RN 业务 API 语义。
+
+## 2. 基线与 Git
+
+- 仓库：`/Users/tei/dev/MapLibreParticleLab-step099`
+- branch：`step099-render-source-diagnostics`
+- frozen release tag：`maplibre-particle/rn/13.4.1-particle.17`
+- frozen release commit / start base：`e8b451fe70054107773e82484c80e90df3889147`
+- implementation commit：`8a5214d92dd2f8899db76d2194da42999fa0c87d`
+- implementation message：`diagnostics: add STEP-099 render source readiness audit`
+- Integration/NavSea：未修改。
+- 文档 closeout commit、push result、`origin/particle/main` Final HEAD：Git 提交无法在自身内容中自指其最终 SHA，按项目既有规则由最终交付回读记录。
+
+## 3. 实际修改范围
+
+生产源码 / diagnostics：
+
+- `include/mbgl/renderer/render_segment.hpp`
+- `src/mbgl/renderer/render_orchestrator.cpp`
+- `src/mbgl/renderer/render_orchestrator.hpp`
+- `src/mbgl/renderer/render_segment_json.hpp`
+- `src/mbgl/renderer/render_source.hpp`
+- `src/mbgl/renderer/retained_underlay_runtime_state.hpp`
+- `src/mbgl/renderer/sources/render_tile_source.cpp`
+- `src/mbgl/renderer/sources/render_tile_source.hpp`
+- `packages/maplibre-particle-rn/src/index.ts`
+- `packages/maplibre-particle-rn/src/types.ts`
+
+测试 / Test App：
+
+- `test/renderer/retained_underlay_cache.test.cpp`
+- `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/Step099ReadinessFixture.kt`
+
+项目记录：
+
+- `docs/50_Step记录/STEP-099_RenderSource就绪与RenderSegment失效诊断_v1.md`
+- `docs/报告/STEP-099_RenderSource就绪与RenderSegment失效诊断_Codex完成报告_v1.md`
+- `粒子开发记录.md`
+
+## 4. 诊断能力
+
+### 4.1 全局 readiness
+
+新增只读 snapshot：
+
+- `styleLoaded`
+- `imageManagerLoaded`
+- `renderOrchestratorLoaded`
+- `spriteLoaded`
+- `hasFadingTiles`
+- global retained `contentRevision`
+- RenderSegment plan/config/topology 信息
+- 最近 mutation sequence / reason / source / affected segment diagnostics
+
+正式 loaded 路径保持原式：
+
+```cpp
+renderTreeParameters->loaded = updateParameters->styleLoaded && isLoaded();
+```
+
+diagnostics snapshot 在旁路采样，失败被 best-effort 隔离，不决定正式 loaded。
+
+### 4.2 per-source readiness
+
+每个 RenderSource additive 暴露：
+
+- sourceId / sourceType
+- enabled / isLoaded
+- tileBacked
+- tileCount / incompleteTileCount / loadedTileCount
+- hasFadingTiles
+- last source/tile mutation sequence
+- last tile action / reason
+
+默认非 tile source 返回完整显式初始化的空统计，Android NDK `-Werror` 下已验证通过；未改变任何 Source `isLoaded()` 实现。
+
+### 4.3 RenderSegment 只读依赖
+
+每个 segment additive 暴露：
+
+- segmentIndex / strategy / beginIndex / endExclusive
+- `dependentSourceIds`
+- `unknownDependencies`
+
+规则：
+
+- 从实际 ordered layers 的 sourceId 推导；
+- shared source 可出现在多个 segment；
+- source-less background 不制造假依赖；
+- symbol/custom 等无法仅靠 sourceId 完整表达的依赖标记为 unknown/global；
+- 依赖图只用于诊断，不参与 cache/loaded/fast path/execution。
+
+### 4.4 mutation 定位
+
+Source/tile mutation 复用已有回调记录 sequence/source/reason/action。原 `retainedUnderlayContentRevision` 的增长次数与正式调用路径不变；diagnostics 不增加额外 revision。
+
+query 路径不清理或修改 event history，重复 snapshot/JSON 查询保持无副作用。
+
+## 5. Native 定向测试
+
+### 5.1 Metal host 定向 GTest
+
+实际执行：
+
+```bash
+cmake --preset macos-metal
+cmake --build build-macos-metal --target mbgl-test-runner --parallel 3
+build-macos-metal/mbgl-test-runner --gtest_filter='RenderSegmentDiagnostics.*'
+```
+
+结果：
+
+- `RenderSegmentDiagnostics.*`：**6/6 PASS**
+- 新增 `ReadinessSnapshotMapsSourcesToSegmentsWithoutSideEffects`：PASS
+- 覆盖 source loaded/unloaded、tile stats、source→segment、shared source、source-less、重复 query、topology/cache/content revision 无副作用。
+
+证据：
+`artifacts/maplibre-particle/android-validation/step099-metal-gtest.log`
+
+SHA-256：
+`f0618750ead03eae1b251126dd49488a9269a120373a66e3453fa9aaa1dc0f10`
+
+说明：该 6/6 发生在 Android NDK 首轮暴露“默认 readiness struct designated initializer 未显式列完 optional 字段”之前；随后仅补全默认空字段初始化。最终源码由 Android 全量 native build 成功覆盖。为了在最终源码上重跑 Metal，重新 configure 时当前 Mac 缺 `libuv` pkg-config，configure fail；没有安装系统依赖来制造 PASS。
+
+### 5.2 Vulkan
+
+`macos-vulkan` configure：**BLOCKED / NOT RUN TESTS**。
+
+原因：
+
+```text
+The following required packages were not found:
+ - libuv
+```
+
+这是当前 Mac host 环境依赖，不是 STEP-099 源码编译错误。
+
+### 5.3 Jest
+
+**NOT RUN**。用户未要求 Jest，任务未加入 Jest。
+
+## 6. Android 构建与设备
+
+### 6.1 首轮 Android 编译问题
+
+首轮 x86_64 OpenGL build 在 Android NDK `-Werror` 下发现：
+
+```text
+render_source.hpp:84:51:
+error: missing field 'tileCount' initializer
+[-Werror,-Wmissing-designated-field-initializers]
+```
+
+修复仅补全 `RenderSourceReadinessStats` 默认空字段初始化，不改变运行语义。
+
+随后 native C++ 已越过原失败点并完整编译。
+
+### 6.2 磁盘阻塞与恢复
+
+第一次完整 native build 后，在：
+
+`MapLibreAndroidTestApp:stripOpenglDebugDebugSymbols`
+
+因 Mac 仅剩约 2 GiB 出现：
+
+```text
+No space left on device
+```
+
+RDC 只清理可再生 Gradle 9.5.1 cache / 本轮失败中间产物，保留 Android native object；可用空间恢复到约 12 GiB 后增量重跑。
+
+### 6.3 最终 APK
+
+命令：
+
+```bash
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+最终结果：
+
+- Gradle：**BUILD SUCCESSFUL in 4m 54s**
+- actionable tasks：86（7 executed / 79 up-to-date）
+- variant：OpenGL Debug
+- ABI：x86_64
+- APK：61,923,024 bytes
+- `libmaplibre.so`：39,602,856 bytes
+- APK SHA-256：
+  `5de73f0358b835a78d3ae7e2ac22f4efdb2a66775b8c63654a8bb7313957d90a`
+
+构建时 metadata：
+
+- base commit：`e8b451fe70054107773e82484c80e90df3889147`
+- `git_dirty=true`
+- 构建内容与随后形成的 implementation commit `8a5214d92` 源码一致；当前 source tree 对 implementation commit clean，剩余仅 docs closeout。
+
+### 6.4 Android 设备
+
+Mac ADB 直接连接：
+
+- serial：`192.168.200.139:5555`
+- model：`FZG1-2`
+- Android：13
+- API：33
+- ABI：x86_64
+
+APK 覆盖安装成功，`ParticleCoreLayerValidationActivity` 冷启动成功。
+
+运行 log：
+`artifacts/maplibre-particle/android-validation/step099-logcat.txt`
+
+log SHA-256：
+`0f15d75dde77e7dd2f4d98c46a4c1501a628205e8aae62130b0cb96db6b8482f`
+
+## 7. T1～T4 实测
+
+### T1 STATIC
+
+场景：
+
+- R0：静态 GeoJSON retained
+- C：本地静态 RasterArray field 驱动 WeatherColor + Particle
+- R1：静态 retained
+- camera fixed
+
+结果：
+
+- 启动阶段 1 个 false window：204 ms；
+- 随后 `renderOrchestratorLoaded=true` 稳定；
+- `particle-fixture` 与 `step099-static` 均 loaded；
+- retained cache 建立后持续 reuse；
+- fast path 进入 `active=true / eligible=true / reason=none`；
+- 没有持续 style-not-loaded。
+
+aggregate：
+
+```text
+falseWindowCount=1
+falseWindowAvgMs=204
+falseWindowMaxMs=204
+openFalseWindowMs=0
+```
+
+结论：静态基线可稳定进入 loaded/cache reuse/fast path。
+
+### T2 GEOJSON_1HZ
+
+两个 GeoJSON source 每 500 ms 交错更新，因此每个约 1 Hz。
+
+实际：
+
+- 总 source update：122 次，约 61 次/源；
+- 60 秒量级观察中，出现 10 个 loaded=false window；
+- 平均 203 ms；
+- 最大 205 ms；
+- 最终 open window = 0；
+- 总 false 时间约 2.03 s，约占 60 s 的 3.4%，不是“几乎始终 false”。
+
+aggregate：
+
+```text
+falseWindowCount=10
+falseWindowAvgMs=203
+falseWindowMaxMs=205
+openFalseWindowMs=0
+```
+
+同时 final sample：
+
+- global contentRevision 已到 1679；
+- R0 仅依赖 `step099-static`，但 cache build=241、invalidation=362；
+- R1 依赖动态 GeoJSON，也同样 build=241；
+- mutation diagnostics 能正确指出动态 source 只 `affected=[2]`，但正式 cache invalidation 仍非局部。
+
+### T3 PERMANENT_UNREADY
+
+额外加入：
+
+`step099-unready-raster-array`
+
+它：
+
+- 没有 layer；
+- 因此 `enabled=false`；
+- host-submission 无 field；
+- `isLoaded=false`。
+
+其他主要 source 均 loaded。
+
+实测：
+
+- `renderOrchestratorLoaded=false` 持续；
+- retained segment cache 持续 fallback；
+- `lastInvalidationReason=style-not-loaded`；
+- 观察结束仍没有恢复。
+
+aggregate：
+
+```text
+falseWindowCount=0
+openFalseWindowMs=21459
+```
+
+结论：即使 source 与当前 layer/segment 无关且 disabled，只要仍在 `renderSources` 且 `isLoaded=false`，V17 全局 `RenderOrchestrator::isLoaded()` 就保持 false。
+
+### T4 R-C-R
+
+结构：
+
+- R0：`deps=[step099-static]`
+- C：`deps=[particle-fixture]`，WeatherColor + Particle
+- R1：`deps=[org.maplibre.annotations, step099-dynamic, step099-static]`
+- `step099-dynamic` 约 1 Hz 更新
+
+实际：
+
+- dynamic update：61 次；
+- loaded false window：4；
+- 平均 203 ms；
+- 最大 207 ms；
+- global contentRevision：1760 → 2540；
+- mutation diagnostics：`step099-dynamic` 对应 `affected=[2]`；
+- R0 并不依赖 `step099-dynamic`，但：
+  - build：1 → 121
+  - invalidation：20 → 200
+- R1 同步得到相同级别 build/invalidation 增长；
+- fast path 在稳定窗口可恢复 active，但 global revision / transient readiness 会反复制造 full CPU work。
+
+aggregate：
+
+```text
+falseWindowCount=4
+falseWindowAvgMs=203
+falseWindowMaxMs=207
+openFalseWindowMs=0
+```
+
+结论：依赖诊断已经能准确表达“R1 source-local”，但 V17 正式 content revision/cache invalidation 仍是 global。
+
+## 8. Q1～Q7
+
+### Q1：单个 permanently unloaded source 会造成 V17 style-not-loaded 吗？
+
+**YES / CONFIRMED。**
+
+T3 中 `step099-unready-raster-array` 无 layer、`enabled=false`、`isLoaded=false`；其他主要 source loaded，但整体 `renderOrchestratorLoaded=false` 持续 21.459 s 未恢复，retained cache 持续 `style-not-loaded` fallback。
+
+源码事实与运行事实一致：`RenderOrchestrator::isLoaded()` 遍历全部 `renderSources`，不按 enabled/segment dependency 排除 source。
+
+### Q2：1 Hz GeoJSON 会周期性让 isLoaded=false 吗？平均/最大窗口？
+
+**YES / CONFIRMED。**
+
+T2 双 source 交错各约 1 Hz：
+
+- 10 次 false window；
+- avg 203 ms；
+- max 205 ms。
+
+T4 单动态 source 约 1 Hz：
+
+- 4 次 false window；
+- avg 203 ms；
+- max 207 ms。
+
+### Q3：错开的多个 1 Hz GeoJSON 会导致 global loaded 几乎无法稳定为 true 吗？
+
+**NO / 本次观测不支持。**
+
+T2 约 60 s 中总 false 时间约 2.03 s，约 3.4%；绝大多数时间 global loaded=true。它确实产生 readiness thrash，但不是“几乎永远 false”。
+
+### Q4：GeoJSON tile mutation 会推进 global retainedUnderlayContentRevision 并影响 retained cache 吗？
+
+**YES / CONFIRMED。**
+
+T4 global contentRevision 1760 → 2540。仅依赖静态 source 的 R0 也从 build 1 → 121、invalidation 20 → 200。
+
+### Q5：不引用 GeoJSON 的 retained segment 仍会受它的 loaded/fading/tile mutation 影响吗？
+
+**YES。**
+
+运行证据：
+
+- T4 diagnostics 正确报告动态 source `affected=[2]`；
+- 但 R0 `deps=[step099-static]` 仍随动态 source mutation 重建/失效。
+
+源码证据：
+
+- `retainedRangeIsStable(begin,end)` 虽为 range API，但最后遍历 **全部 `renderSources`**，任一 source `hasFadingTiles()` 都让任意 retained range unstable。
+
+本次 T4 稳态 `fade=false`，因此 R0 的实际反复失效主要直接证明 global content revision/tile mutation；GLOBAL_FADE 属源码确认、未在本轮场景主动触发的全局 gate。
+
+### Q6：`tryRenderParticleFastFrame` 仍有哪些 global gate 会阻挡未来 localized cache CPU fast path？
+
+**确认仍存在：**
+
+1. **GLOBAL_UPDATE_SIGNATURE**
+   - `particleFastPathNonCameraInputsMatch` 全局比较：
+   - styleLoaded / spriteLoaded
+   - light
+   - images
+   - **sources**
+   - **layers**
+   - fontFaces / fileSource / glyphURL
+   - transition / placement / tile LOD 等全局输入。
+
+2. **GLOBAL_CONTENT_REVISION**
+   - `particlePreparedContentRevision == orchestrator.getRetainedUnderlayContentRevision()`。
+
+3. **GLOBAL_FADE**
+   - `particleFastPathDynamicState` 遍历全部 renderSources 汇总 fading；
+   - `retainedRangeIsStable` 也遍历全部 renderSources。
+
+4. **GLOBAL_PENDING / TRANSITION / REPAINT**
+   - pendingChanges
+   - renderLight transition
+   - 任意 layer transition
+   - 任意非粒子 layer repaint
+   - placement transition。
+
+5. **GLOBAL_ANNOTATION_MUTATION**
+   - AnnotationManager `hasPendingChanges()`。
+
+6. **RETAINED REVISION / CACHE / TOPOLOGY / BOUNDARY**
+   - retained cache validity/static revision
+   - global retained revision tracker
+   - topology revision
+   - boundary/config revision。
+
+7. **singleContinuousSegment**
+   - 仍要求 plan 恰好能由一个 Continuous segment 表达；
+   - multi-continuous 继续 fail closed，本 Step 未修改。
+
+因此即使未来 cache invalidation 变成 source/segment-local，fast path 仍有多组 global gate 需要后续 Step 单独设计，不能在 STEP-099 顺手放宽。
+
+### Q7：blocker 分类
+
+**运行态 CONFIRMED：**
+
+- `PERMANENT_SOURCE_UNLOADED`
+- `DYNAMIC_SOURCE_READINESS_THRASH`
+- `GLOBAL_CONTENT_REVISION`
+
+**源码 CONFIRMED，本轮未主动触发独立运行场景：**
+
+- `GLOBAL_FADE`
+- `GLOBAL_UPDATE_SIGNATURE`
+
+**OTHER：**
+
+- global pendingChanges
+- placement/light/non-particle transition/repaint
+- annotation mutation
+- topology/boundary/revision/cache validity
+- singleContinuous fail-closed
+
+## 9. 任务边界审计
+
+确认未改：
+
+- retained cache 核心算法；
+- fast path gate 逻辑；
+- `singleContinuousSegment`；
+- multi-continuous 策略；
+- segment-local invalidation 正式语义；
+- RenderSegment execution；
+- NavSea；
+- private NavSea Native API；
+- RN 业务 API；
+- Source `isLoaded()` 定义。
+
+新增 dependency / affectedSegmentIndices 只是观察信息；它没有参与正式 invalidation。
+
+## 10. 证据文件
+
+忽略目录：
+
+`artifacts/maplibre-particle/android-validation/`
+
+主要文件：
+
+- `build-info.txt`
+- `build.log`
+- `MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`
+- `step099-logcat.txt`
+- `step099-device-info.txt`
+- `step099-metal-gtest.log`
+- `step099-cmake-metal.log`
+
+APK SHA-256：
+
+`5de73f0358b835a78d3ae7e2ac22f4efdb2a66775b8c63654a8bb7313957d90a`
+
+STEP-099 log SHA-256：
+
+`0f15d75dde77e7dd2f4d98c46a4c1501a628205e8aae62130b0cb96db6b8482f`
+
+## 11. 下一阶段建议
+
+STEP-099 只负责定位，不在本 Step 修复。
+
+下一阶段应基于本轮证据拆开处理：
+
+1. 先决定 global source readiness 是否要引入“影响当前 style/render segment 的 readiness 范围”，解决 permanently unready / transient unrelated source 对全局 loaded 的影响；
+2. 再设计 source/segment-local content revision 与 invalidation，避免 R1 GeoJSON mutation 重建 R0；
+3. 最后单独审查 fast-path global signature/fade/pending/placement 等 gate，不能把 cache locality 与 fast-path locality 混成一个修改；
+4. 保持 Style Z-order 唯一事实来源和当前通用 Render Segment 模型。
+
+## 12. 最终状态
+
+**STEP-099 CLOSED / PASS。**
+
+Pass 含义仅为：
+
+- diagnostics 能回答任务问题；
+- Native 定向测试已有 PASS 证据；
+- 最终 Android x86_64 OpenGL APK BUILD SUCCESS；
+- FZG1-2 T1～T4 实跑完成；
+- Q1～Q7 有源码/运行证据；
+- 未改变正式渲染语义。
+
+不代表：
+
+- Vulkan host 已通过；
+- iOS runtime 已测试；
+- 下一阶段 localized readiness/invalidation 已实现；
+- fast path global gates 已优化。