# STEP-057 Android Host 天气运行时接口基础

状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`。

Starting HEAD：`faf7548220e9a1282275711c236987f7faedfa03`，分支 `particle/main`。

已实现：Android `WeatherRuntime` typed facade；canonical byte[] submit result enum；clear fields；timestamp seek；play/pause/0.5/1/2x；独立 visibility；OFF unload；WeatherColor 8-stop dynamic ramp；独立 particle/trail RGBA；Android→JNI→C++ 接线；REAL WEATHER Test App submit/playback 改走 facade。

Core 保持 canonical U/V、Timeline、Runtime Field Window、T0/T1 interpolation 和 Renderer 架构边界。正常窗口边界的 GPU content reuse 路径未改变；normal seek 不改变 window revision，跨窗口仍由既有 revision 驱动 reuse。

OFF 会停止 Timeline、clear Host ownership，并在 Render 线程的空 Source path 清理 layer drawables、particle State/Trail/draw targets、field textures 和 WeatherColor resources。结构化日志包括 `TIMELINE_STOP`、`FIELD_WINDOW_CLEAR`、`SNAPSHOT_CLEAR`、`PARTICLE_RESOURCE_RELEASE`、`TRAIL_RESOURCE_RELEASE`、`WEATHER_COLOR_RESOURCE_RELEASE`。

本地验证：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 未运行。

## STEP-057B 状态语义修正（2026-09-07）

状态：`IMPLEMENTED / WAITING_CODE_REVIEW`。

基于 `dad6876c72f29e2d5671677ee15e13cd25e653a1`，本轮只修改 `WeatherRuntime` 与状态测试/记录：普通 `REJECTED_ADAPTER`、`REJECTED_INCOMPATIBLE`、`REJECTED_NON_MONOTONIC`、`REJECTED_CAPACITY` 和空 metadata/payload 保持当前 state；`REJECTED_SOURCE_MODE`、`UNKNOWN` 才进入 ERROR。pending T0、initial window、next snapshot、duplicate 的成功/保持语义不变。

`READY + enable(true)`、`WAITING_FOR_FIELDS + enable(true)` 为幂等 no-op；`DISABLED + enable(true)` 成功恢复到 WAITING；ERROR enable 明确返回 REJECTED 并保持 ERROR。clear/disable 成功与失败转换保持原有契约，DISABLED 重复 disable 仍为成功 no-op。

`WeatherRuntimeStateTest` 已覆盖普通 rejection 保持 READY/WAITING、真正错误、所有 enable 分支、clear/disable，以及 public flow 的 invalid submit 和 ERROR enable。public flow 测试源码已加入现有 Mockito/JUnit 体系，但本轮未运行 Android Gradle；因此仍需代码审计后统一 Android 验收。