# STEP-109 V23 CPU FieldSnapshot 深比较快路 — RDC 阶段报告 v1

日期：2026-10-10（JST）
结论：**PARTIAL / 开发态**。已针对 V23 源码热点实施局部修正；尚无 V23 真机 CPU 改善证据。

## 1. 基线
- 仓库：Mac /Users/tei/dev/MapLibreParticleLab，particle/main。
- 起点：5b8bdfbfbb4263fe12a060e77bc310cf77f27d61，起点工作区干净。
- 正式已发布 V23：13.6.1-particle.23（Android/RN）、6.29.0-particle.23（iOS）；发行 Tag、Source Lock、制品均未变更。
- NavSea Mac V23 集成 checkout 为 /Users/tei/dev/NavSea-Build；Windows D:\React\NavSea 当前仍引用 13.4.1-particle.21，且有多项其他工作区修改。本轮未改 NavSea。

## 2. V23 实际源码发现
- render_particle_validation_layer.cpp 每帧调用 sameFieldGpuEndpoint() 校验既有 T0/T1，内部逐项比较 vector 和 valid。
- render_weather_color_layer.cpp 每帧调用 sameFieldGpuContent()，内部比较 scalar/vector/valid。
- 两条判断在 immutable T0/T1 未改变时仍可执行 O(N) 深比较。
- STEP-090 Fast Path 存在；STEP-102/106 RenderSegment Placement 局部修复已有 FZG 定向证据，因此不能直接照搬 V21 cache-invalid 诊断。
- V21 93.8% CPU 与 simpleperf 浮点数组采样仅为历史方向提示，不能归因于此次代码或称为 V23 基线。

## 3. 已实施代码
- src/mln/renderer/layers/render_particle_validation_layer.cpp：资源绑定持有 T0/T1 不可变快照 shared_ptr；当前资源已验证同一快照时 O(1) 判等，新对象仍严格核对内容。
- src/mln/renderer/layers/render_weather_color_layer.cpp：WeatherColor 纹理同样记录 Source 快照身份；相同内容的新对象仍使用原严格比较及资源复用。
- 全部身份绑定只在纹理准备成功或内容等价验证后建立；资源销毁、重新创建与 context loss 均自然清除。
- 未改 RN 对外 API、风场 canonical contract、T0/T1 mix、Runtime Field Window、粒子数量、GPU 纹理算法及 RenderSegment 安全回退。

## 4. 验证与限制
- scoped git diff --check：**PASS**。
- Mac Metal Core：**INTERRUPTED / NOT COMPLETED / NOT PASS**。执行 `bazel build -c opt --//:renderer=metal //:mbgl-core` 触发 649 actions 的通用 Native 重编译；基于本轮仅两文件微调、尚未安排设备验收，主动中止以控制开发成本。原远程 session 8049 和 Bazel PID 8350 均已停止；未取得构建最终通过或编译错误结论。日志：`/tmp/maplibre_step109_cpu_field_identity_bazel_20261010.log`。
- Android 用户手工编译/安装、OpenGL 实机、iOS 实机、性能同屏 A/B、全量定向测试：**NOT RUN**。
- 没有测得实际 CPU 下降百分比；本次不生成正式发行版，不覆盖 V23 Tag 或 Source Lock。

## 5. 后续验收门槛
1. Native 编译通过并定向执行现有 Field GPU / Timeline / Source 测试。
2. Android FZG1-2 以相同天气输入和粒子设置、相同 Layer stack、同一 BuildType 做 V23 原版与修正版 A/B，采样进程、RenderThread、JS，并检查 FieldTextureUpload/SimulationReset。
3. 时间切换、T0/T1 重叠窗口、clear/reload/context loss、切层、地图平移与关闭天气后恢复，在 Android/iOS 分别核对画面正确、无旧场、无多余纹理重建。
4. 用户验收后，再新建发行版本，按 GSRL 发布不可变制品与 SOURCE_LOCK.json。

## 6. Git
本次开发提交与远端回读事实见下一节。提交只意味着代码可追溯，不意味着已编译、通过真机或正式发行。

## 7. Git 开发提交与远端回读（2026-10-10）
- 本次仅提交两份 Renderer C++ 源码、STEP-109、RDC 阶段报告、粒子开发记录共五个相关文件，未执行 `git add -A` 或触碰正式发行文件。
- 首个开发提交：`2aae38f4023f2ef682c9039c93dfa1e96b0e6e1b`；`perf(particle): skip repeated field snapshot deep comparisons`。
- `git push origin HEAD:refs/heads/particle/main`：**PASS**，fast-forward；远端 `git ls-remote` 回读同一 SHA：**PASS**。
- 本次只是开发态代码与记录推送；Mac Metal build 中断、Android/iOS 真实 CPU A/B NOT RUN，STEP-109 保持 **PARTIAL**。正式 V23 GSRL Tag 和制品仍完全不变。