MapLibreParticleLab/docs/报告/STEP-058A_SharedCadence与WeatherRuntime生命周期修正_Codex完成报告_v1.md

STEP-058A Shared Cadence 与 WeatherRuntime 生命周期修正 — Codex 完成报告

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

实际修正

• shared cadence advance 收敛至 RasterArrayTimelineRuntime::advanceIfDue(now)：同一 mutex 内完成 due 判断、cadence revision、真实 monotonic elapsed 的 Timeline 推进和 frame 返回。
• Particle 与 WeatherColor 都可消费 shared advance。WeatherColor-only + PLAY 首先到达 deadline 时可独立推进 MIX；Particle 在同一 cadence window 后到只读取已推进 revision，不会双 tick。
• WeatherColor-only + PAUSE 的 needsRepaint() 不再主动持续刷新；Particle visible + PAUSE 仍以自身 simulation cadence 运作；两层 hidden 时 facade 不调度 wake-up。
• 新增幂等 WeatherRuntime.dispose()。它取消 pending Handler callback；旧 Runnable 即使执行也不会 triggerRepaint() 或再次 schedule；dispose 后 Command API 拒绝、submit/playback/seek fail-fast。
• Test App 在 style reload、离开 REAL WEATHER、Activity destroy 之前显式 dispose 旧 Runtime。

修改文件

• include/mbgl/style/sources/raster_array_source.hpp
• src/mbgl/style/sources/raster_array_source.cpp
• src/mbgl/renderer/layers/render_particle_validation_layer.cpp
• src/mbgl/renderer/layers/render_raster_particle_layer.hpp
• src/mbgl/renderer/layers/render_weather_color_layer.cpp
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java
• platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java
• platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt
• test/style/source.test.cpp
• STEP-058 设计/Step 记录、粒子开发记录.md 与本报告。

验证

• throttle 下 Linux/OpenGL ninja -C build-linux-opengl mbgl-test-runner mbgl-render-test-runner：PASS。
• throttle 下 mbgl-test-runner --gtest_filter='Source.RasterArray*'：PASS，包含 shared cadence deterministic deadline、单 consumer advance、PAUSE、target switch 与 missed deadline no-busy-loop 覆盖。
• git diff --check：PASS。
• 未执行 Android Gradle、APK、ADB、设备/虚拟机测试或 Jest。

风险与人工验收

Android JNI/Java 编译、Handler callback 与真机 30/60 FPS、Particle OFF/WeatherColor ON PLAY/PAUSE、两层 OFF、style reload/remount 下旧 Runtime wake 停止仍需后续人工验收。Core 的 T0/T1/MIX、field reuse、normal boundary simulationRebuild=false/trailCleared=false 未重写。

Git

• Starting HEAD：8d12a4b361fe0b59a03327ea4ee782f01c554533
• 功能 commit：ab86eb8f6780f2a77c3772e695650f46fc0b6608
• 功能 commit message：fix: share weather cadence across renderers
• 文档 commit：7188040e8790a8a462ac28ce93c9c995f759a84a
• Push：成功，8d12a4b36..c95d404c1 particle/main -> particle/main
• Remote branch：origin/particle/main
• 功能/文档主体 Final HEAD：7188040e8790a8a462ac28ce93c9c995f759a84a

本报告元数据收尾后的 Final HEAD 为 c95d404c17f4bc56924cef8f1734492cd4c42e41；交付消息列出最终文档收尾 commit，且不改变功能代码。