fix: audit STEP-057 weather runtime facade

docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md

@@ -14,8 +14,8 @@
 - `setWeatherColorVisible` / `setParticleVisible`：仅 visibility，`hide != unload`。
 - `setForecastTime(timestampMs)`：Core 按 timestamp 选相邻 T0/T1 并计算 MIX。恰好命中末快照为 MIX=1；中间线性插值；超范围、未 READY、Gap/Invalid 返回 `REJECTED`，不会沿用错误旧时间。正常 seek 不 submit field、不 reset particle、不 clear trail；仅跨窗口时沿用既有 OLD_T1→NEW_T0 reuse。
 - `setPlaybackState(PLAY/PAUSE)`、`setPlaybackSpeed(HALF/NORMAL/DOUBLE)`：复用 Source Timeline，不创建 Android Timer。
-- `setWeatherColorOpacity`、`setParticleVisual`：低频 visual 更新。
-- `setWeatherColorStops(List<ColorStop>)`：2 至 8 个 stop，speed finite 严格递增，RGBA 均为有限 [0,1]。低于/高于边界分别钳到首/末颜色，中间线性插值。无效输入 reject，并保留上一套有效 ramp。
+- `setWeatherColorOpacity`、`setParticleCount`、`setParticleLineWidth`、`setParticleLength`、`setParticleOpacity`、`setTrailOpacity`、`setTrailFade`、`setParticleSpeedColorEnabled`：明确 typed 的低频 visual 更新；正式 Host API 不接收 property string。
+- `setWeatherColorStops(List<ColorStop>)`：2 至 Core `MaxWeatherColorStops` 个 stop（v1 为 8，Java 经 JNI `getWeatherColorStopCapacity()` 获取），speed finite 严格递增，RGBA 均为有限 [0,1]。低于/高于边界分别钳到首/末颜色，中间线性插值。无效输入 reject，并保留上一套有效 ramp。
 - `setParticleColors(...)`：独立 particle/trail RGBA；不依赖 WeatherColor ramp。legacy `speed-color-enabled=true` 时仅当前 segment 可使用旧 speed 色，不改变 WeatherColor stops。
 
 状态为 `DISABLED`、`WAITING_FOR_FIELDS`、`READY`、`ERROR`，仅由低频命令和 submit result 更新。v1 提供同步 typed result/state query；没有 listener，未来 RN 薄层可在这些调用完成后读取结果。

docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md

@@ -13,3 +13,15 @@ OFF 会停止 Timeline、clear Host ownership，并在 Render 线程的空 Sourc
 本地验证：shader generator、Linux OpenGL `mbgl-core`、`style_layer.test.cpp` 与 `source.test.cpp` 精确编译；`git diff --check`。Android Gradle/APK/ADB/设备测试和 Jest 未运行。
 
 未完成：Android 手工 T1–T13 验收，特别是 OFF resource log、ON 后重新 T0/T1、dynamic ramp/colour 无 field upload/particle reset、timestamp mid-point 和窗口边界回归。
+
+## STEP-057A 审计修正（2026-09-07）
+
+状态保持 `IMPLEMENTED / WAITING_ANDROID_VALIDATION`。基于已推送 `efaa3e61c` 审计修正，不进入 STEP-058。
+
+- 删除正式 `WeatherRuntime.setParticleVisual(String, float)`；改为 particle count、line width、length、particle/trail opacity、trail fade、speed-color enabled 的明确 typed 方法。Test App 的 fixture-only generic property 调试仍只留在低层路径。
+- 修正 facade 状态：READY 重复 enable 幂等；DISABLED enable 进入 WAITING；ERROR 收到 pending T0 恢复 WAITING；initial window ready 进入 READY；clear/disable 只在对应 Core 成功时转入 WAITING/DISABLED。新增 Android 既有 JUnit state transition 定向测试源码，未按本轮限制执行 Gradle。
+- `RenderOrchestrator` 不再对所有 hidden RasterArray layer 执行额外 prepare/update。`RenderLayer` 默认无 cleanup；仅仍持有资源、Host-field Source 已空的 RasterParticle/WeatherColor renderer 显式 opt-in，完成一次空场 GPU cleanup。普通 hidden layer 语义不变。
+- Host stop capacity 改为由 JNI 读取 Core `MaxWeatherColorStops`；Host API 继续接受 `ColorStop` list，未暴露 UBO。严格验证与 particle/trail 独立性保持。
+- timestamp 测试改为 epoch milliseconds（2024-01-01 UTC 起的 64-bit ms），覆盖 exact T0、midpoint、exact T1、上下界 out-of-range 与 clear 后 fail-closed。
+
+验证：output-throttle 下 shader generator、Linux OpenGL `mbgl-core`、`mbgl-render`、`mbgl-test-runner`、相关精确 Source/Style compile 和定向非 Jest tests 均 PASS；`git diff --check` PASS。Android Gradle/APK/ADB/设备/Jest 未运行。

docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md

@@ -0,0 +1,34 @@
+# STEP-057A Android Host 天气运行时接口审计修正 — Codex 完成报告
+
+状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`。本轮仅修正 STEP-057，不进入 STEP-058、React Native bridge 或性能任务。
+
+## 实际修正
+
+1. `WeatherRuntime` 删除公开 `setParticleVisual(String, float)`。正式 API 改为 `setParticleCount`、`setParticleLineWidth`、`setParticleLength`、`setParticleOpacity`、`setTrailOpacity`、`setTrailFade`、`setParticleSpeedColorEnabled`；Core property 语义未改。Test App 的未映射 fixture diagnostic 才可使用低层 generic setter。
+2. 状态转换被收敛为可单测函数：READY enable 幂等；DISABLED 成功 enable → WAITING；ERROR 成功 pending field → WAITING；initial window ready/next snapshot → READY；成功 clear → WAITING；成功 disable → DISABLED。新增 `WeatherRuntimeStateTest`，使用现有 Android JUnit 体系；遵从任务限制未运行 Gradle。
+3. 取消 `RenderOrchestrator` 的所有 hidden RasterArray 层全局 prepare/update。新增默认关闭的 `RenderLayer::needsHiddenLayerSourceCleanup`；只有持有 GPU resource 且 Host-field source 已清空的 RasterParticle/WeatherColor layers opt-in，才在 hidden 时接收一轮 cleanup。普通 hidden MapLibre layer 生命周期不变。
+4. stop 上限继续由 C++ `MaxWeatherColorStops=8` 定义。Java 经 JNI 获取 capacity，facade 以 `ColorStop` list 验证，不暴露 UBO 数组。严格 speed/RGBA 校验和独立 particle/trail color 保持。
+5. Source timestamp tests 现在使用 epoch milliseconds：T0=`1704067200000`、T1=`1704070800000`，验证 exact T0、midpoint、exact T1、lower/upper out-of-range 与 clear 后 fail-closed。
+
+既有 clear/unload、JNI、Core-owned T0/T1/MIX、dynamic ramp、独立颜色、field/window reuse、无 style reload 均保留。正常 window boundary 的 OLD_T1→NEW_T0 / only NEW_T1 upload 路径未改；本轮没有触及 simulation/trail reset 条件。
+
+## 验证
+
+所有编译、codegen 和测试均经 `build-output-throttle` wrapper，日志仅存 `/tmp/step057a-logs/`，未提交。
+
+- shader generator：PASS。
+- Linux OpenGL `mbgl-core`：PASS。
+- Linux OpenGL `mbgl-render`：PASS。
+- Linux OpenGL `mbgl-test-runner`：PASS。
+- `style_layer.test.cpp` / `source.test.cpp` 精确编译：PASS。
+- 定向非 Jest tests（timestamp seek、clear、WeatherColor stop validation、particle/trail properties）：PASS。
+- `git diff --check`：PASS。
+
+未执行：Android Gradle、APK build、ADB、Android device validation、Jest。
+
+## Git
+
+- 审计起点：`efaa3e61c94e056bf06a955eb250cdfdc1633ecd`
+- 功能提交、文档提交、push 和 Final HEAD：在完成提交后以最终交付结果为准。
+
+Android 后续人工验收仍需重点检查 OFF hidden cleanup logs、READY 重复 ON、ERROR→pending→WAITING、dynamic stop/colour 无 field upload/reset、epoch-ms seek 与正常 window boundary `simulationRebuild=false` / `trailCleared=false`。