From eae86524866eff19ce01f97f4cb8992c2ac9eb44 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Thu, 3 Sep 2026 19:23:38 +0800 Subject: [PATCH] docs: close runtime particle field validation --- .../STEP-045_Runtime_Field动态更新接口_v2.md | 51 ++++++++++++++++++ ...untime_Field动态更新接口_Codex完成报告_v2.md | 52 +++++++++++++++++++ 粒子开发记录.md | 8 +++ 3 files changed, 111 insertions(+) create mode 100644 docs/50_Step记录/STEP-045_Runtime_Field动态更新接口_v2.md create mode 100644 docs/报告/40-04_Runtime_Field动态更新接口_Codex完成报告_v2.md diff --git a/docs/50_Step记录/STEP-045_Runtime_Field动态更新接口_v2.md b/docs/50_Step记录/STEP-045_Runtime_Field动态更新接口_v2.md new file mode 100644 index 000000000..786fb4d04 --- /dev/null +++ b/docs/50_Step记录/STEP-045_Runtime_Field动态更新接口_v2.md @@ -0,0 +1,51 @@ +# STEP-045 Runtime Field 动态更新接口 + +- 状态：`CLOSED / PASS` +- 最终 Android 验证日期：2026-09-03 +- 当前最终功能基线：`4e31163516ad77473df672e162f554223cd2f09e` + +## 目标与冻结接口 + +40-04 使正式 `RasterParticleLayer` 数据链在运行中接收新的内存 Field 时间片，不依赖 Style reload、Source/Layer recreate 或 simulation restart。 + +- 正式更新接口：`RasterArraySource::updateRuntimeFieldWindow(ParticleFieldSnapshot)`。 +- Duplicate 验证接口：`RasterArraySource::repeatRuntimeFieldWindow()`；它重新提交 Source 当前 T1，并经正式 update API 返回 `Noop`。 +- `RasterArraySource::Impl::field/nextField` 是正式 T0/T1 的唯一权威状态；JNI 只是薄桥，Android Validation 只触发测试动作，Kotlin 不持有正式 T0/T1。 +- Renderer 负责 GPU Field resource reuse/upload；`RasterParticleLayer` 继续负责既有 simulation、Trail 与 Composite。 + +## Android OpenGL 最终验收：PASS + +| 验收项 | 结果 | 最终证据 | +|---|---|---| +| T-RUNTIME-01 | PASS | 初始 T0=uniform-east、T1=uniform-north；MIX 0/50/100 正常，`TIME_MIX_UPDATE` 期间 Field upload/reset 不增加。 | +| T-RUNTIME-02 | PASS | A/B→B/C（east/north→north/vortex）：`FIELD_REUSE from=OLD_T1 to=NEW_T0`，仅上传 vortex，`simulationRebuild=false`、`trailCleared=false`。 | +| T-RUNTIME-03 | PASS | B/C→C/D（north/vortex→vortex/nodata）：再次复用 OLD_T1，仅上传 nodata，证明连续推进未写死一次。 | +| T-RUNTIME-04 | PASS | C/D 下 MIX 50/100/0：`fieldUploadCount=5`、`resetCount=0` 始终不变，MIX 保持 property-only。 | +| T-RUNTIME-05 | PASS | C/D 下连续 `DUPLICATE T1`：每次 `FIELD_WINDOW_UPDATE_APPLIED result=NOOP` 与 duplicate bridge `result=NOOP`；无 upload/reset/style load，T0/T1 不变。 | +| T-RUNTIME-06 | PASS | candidate 耗尽返回 `FIELD_WINDOW_UPDATE_REJECTED reason=NO_PRELOADED_FIELD`；随后 MIX 仍显示 C/D，`fieldUploadCount=5`、`resetCount=0`，fail-closed 成立。 | + +## 最终运行时契约 + +```text +Runtime / Validation Host + -> RasterArraySource::updateRuntimeFieldWindow(...) + -> Source-owned T0/T1 + -> A/B -> B/C -> C/D + -> OLD_T1 -> NEW_T0 GPU reuse + -> upload only new T1 + -> ongoing RasterParticleLayer simulation / Trail / Composite +``` + +- 正常推进不重载 Style、不重建 Layer/Source、不 reset simulation、不 clear Trail；日志确认 `simulationRebuild=false`、`trailCleared=false`。 +- 初始 `STYLE_LOAD reason=TIME_WINDOW` 是用户建立 A/B Validation window 的允许初始化行为。之后 A/B→B/C、B/C→C/D、Duplicate 和 candidate 耗尽 reject 全程 `styleEpoch=2` 不变。 +- MIX property 更新产生的 `LAYER_CHANGED` 是正常 RenderLayer change 通知，不是 Layer recreate；最终 `renderLayerInstanceId=1` 保持稳定。 + +## 未改变的冻结能力与范围外内容 + +40-04 未改变 `U=east-positive`、`V=north-positive`、Mercator shader 边界 `dy=-v`、T0/T1 GPU interpolation、MIX property-only，或 40-03 的 full particle draw（N State texels→N simulated particles→N actual particle draw）与已验证 capacity ≥ 1,048,576。 + +本 Step 未实现真实天气 HTTP、GRIB、Server、forecast cache、vendor/provider 协议、NavSea/React Native 正式接入、粒子形状/旋转/箭头、颜色系统、WeatherColorLayer、Vulkan、iOS/Metal、生产 Land/Ocean Mask 或 APK packaging/ZIP 技术债。 + +## 收尾边界 + +本收尾只更新文档和开发记录；未修改功能代码，未运行新的 Linux/OpenGL 编译、Android Gradle、ADB、实机测试或 Jest。 diff --git a/docs/报告/40-04_Runtime_Field动态更新接口_Codex完成报告_v2.md b/docs/报告/40-04_Runtime_Field动态更新接口_Codex完成报告_v2.md new file mode 100644 index 000000000..bf290e86f --- /dev/null +++ b/docs/报告/40-04_Runtime_Field动态更新接口_Codex完成报告_v2.md @@ -0,0 +1,52 @@ +# 40-04 Runtime Field 动态更新接口 Codex 最终完成报告 + +## 状态 + +`40-04：CLOSED / PASS` + +Android OpenGL 最终统一验证日期：2026-09-03。最终功能基线为 `4e31163516ad77473df672e162f554223cd2f09e`。 + +## 最终验收结论 + +- T-RUNTIME-01：PASS +- T-RUNTIME-02：PASS +- T-RUNTIME-03：PASS +- T-RUNTIME-04：PASS +- T-RUNTIME-05：PASS +- T-RUNTIME-06：PASS + +| 问题 | 结论 | +|---|---| +| A/B→B/C 是否通过 | 是 | +| B/C→C/D 是否通过 | 是 | +| OLD_T1→NEW_T0 是否连续复用 | 是 | +| 正常推进是否只上传新 T1 | 是 | +| 正常推进是否 reset simulation / clear trail | 否 / 否 | +| 正常推进是否 Style reload / Layer recreate | 否 / 否 | +| MIX 是否 property-only | 是 | +| Duplicate 是否返回 NOOP、重复 upload 或 reset | 是 / 否 / 否 | +| Fail-closed 是否通过且 reject 后窗口可用 | 是 | +| Android 最终验证是否通过 | 是 | + +## 实机证据 + +初始窗口为 uniform-east/uniform-north。MIX 0/50/100 仅记录 `TIME_MIX_UPDATE`，不增加 Field upload/reset。两次运行时推进依次得到 north/vortex、vortex/nodata；均记录 `FIELD_WINDOW_UPDATE_REQUEST`、`FIELD_WINDOW_UPDATE_APPLIED result=APPLIED`、`FIELD_REUSE from=OLD_T1 to=NEW_T0` 与单个 `FIELD_UPLOAD reason=NEW_CONTENT`，并确认 `simulationRebuild=false`、`trailCleared=false`。 + +在 vortex/nodata，MIX 50/100/0 后 `fieldUploadCount=5`、`resetCount=0` 保持。连续 Duplicate 记录 `FIELD_WINDOW_UPDATE_DUPLICATE_REQUEST`、`FIELD_WINDOW_UPDATE_APPLIED result=NOOP`、T0=vortex/T1=nodata 和 duplicate bridge `result=NOOP`，没有 `FIELD_UPLOAD`、`SIMULATION_RESET` 或 `STYLE_LOAD`。候选耗尽返回 `NO_PRELOADED_FIELD`；之后 MIX 50 仍维持 C/D 与相同计数，证明 fail-closed 不污染当前窗口。 + +用户主动建立时间窗的 `STYLE_LOAD reason=TIME_WINDOW` 是允许初始化；后续所有 Runtime 操作的 `styleEpoch=2` 未变化。MIX 的 `LAYER_CHANGED` 是 property change 通知，非 Layer recreate；`renderLayerInstanceId=1` 稳定。 + +## 接口与责任边界 + +`RasterArraySource::updateRuntimeFieldWindow(...)` 是正式 Runtime API；`repeatRuntimeFieldWindow()` 仅为 Duplicate Validation 重提当前 T1 并复用同一 API 的 NOOP 分支。Source 持有正式 T0/T1；JNI 为薄桥；Android Validation 触发动作；Renderer 负责 GPU reuse/upload；RasterParticleLayer 持续 simulation/render。Kotlin 不持有 T0/T1 权威状态。 + +40-04 未改变 U/V、`dy=-v`、GPU interpolation/MIX property-only 或 40-03 full particle draw 和 capacity ≥ 1,048,576。真实天气网络、GRIB、provider、NavSea/React Native、粒子视觉阶段、WeatherColorLayer、Vulkan、iOS/Metal、生产 mask 与 APK 技术债均未实现。 + +## 收尾检查与 Git + +- 本收尾修改功能代码：否。 +- 新的 Android Gradle / ADB / Jest：均未运行。 +- `git diff --check`：通过。 +- 收尾 commit：待本次文档提交后记录于 Git 交付。 +- 建议 message：`docs: close runtime particle field validation`。 +- remote branch：`origin/particle/main`。 diff --git a/粒子开发记录.md b/粒子开发记录.md index 943901a29..7c3ac8093 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -298,3 +298,11 @@ - 已有 Runtime API 的 `sameFieldGpuContent(currentT1, newT1)` NOOP 分支正确，但 Android 只有 ADVANCE（候选耗尽后为 T-RUNTIME-06 reject），无法真实重提当前 T1。 - 新增 Source-owned `repeatRuntimeFieldWindow()` 和最小 Android/JNI 薄桥；`DUPLICATE T1` 只把当前 `Impl::nextField` 重交正式 update API，在 vortex/nodata 窗口返回 NOOP，不推进 candidate queue，不改变 Source window，也不触发 `onSourceChanged()`。 - C++ Source test 在 C/D 后断言 Noop、T0/T1 不变及 source changed count 不增；Linux/OpenGL 精确 Core/test object 编译、format/diff check 通过。Android Gradle、ADB、设备和 Jest 未执行；状态继续 `IMPLEMENTED / WAITING FOR ANDROID VALIDATION`。 + +## 2026-09-03 — 40-04 / STEP-045 Runtime Field 动态更新最终关闭 + +- 40-04 / STEP-045 正式 `CLOSED / PASS`。Android OpenGL 最终统一验证 T-RUNTIME-01～06 全部 PASS。 +- 正式 Runtime Field 接口已证明支持 A/B→B/C→C/D 连续时间窗推进：OLD_T1 复用为 NEW_T0，只上传真正的新 T1，正常推进不重载 Style、不重建 Layer、不重启 simulation、不清 Trail。 +- MIX 保持 property-only；Duplicate 重提当前 T1 返回 NOOP，不产生 Field upload/reset/style reload；候选耗尽 fail-closed，当前 vortex/nodata 窗口继续可用。 +- `STYLE_LOAD reason=TIME_WINDOW` 仅是用户建立初始窗口的允许初始化；真正 Runtime 操作期间 styleEpoch 稳定。MIX 的 `LAYER_CHANGED` 不是 Layer recreate，最终 renderLayerInstanceId 保持 1。 +- 40-04 未改变 U/V、`dy=-v`、GPU interpolation、40-03 full particle draw 或已验证 capacity ≥ 1,048,576；真实网络/GRIB/provider、视觉阶段、WeatherColorLayer、Vulkan、iOS/Metal、生产 mask、APK 技术债仍属范围外，未进入下一阶段。