docs: close STEP-067 scalar GPU renderer

docs/40_任务/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex任务_v1.md

@@ -0,0 +1,169 @@
+# STEP-067 MapLibreParticleLab V3-03 Scalar GPU + Generic Field Renderer — Codex任务 v1
+
+## 0. 任务定位
+
+本任务承接已关闭的 STEP-066，只实施 **GPU field bundle / WeatherColor generic value source**。
+
+目标：让 V3 scalar snapshot 首次可由 WeatherColorLayer 真正渲染，并保留 vector magnitude 色场；不实现 DIRECTION 粒子推进，不做 JNI/RN v2 ingress，不做 Android 编译。
+
+## 1. 当前基线
+
+仓库：`/mnt/sda1/MapLibreParticleLab`
+
+分支：`particle/main`
+
+任务书创建时：
+
+`HEAD == origin/particle/main == 9dabb95e4425ffbcb863c520923f5d4b537a3feb`
+
+执行时重新确认 HEAD、origin、`git status --short`，不得 reset/clean/stash。
+
+STEP-062 用户修改、历史 untracked、build/cache/tgz 均视为无关内容，禁止 `git add .` / `git add -A`。
+## 2. 开工前必须完整阅读
+
+- `AGENTS.md`
+- `PARTICLE_BASELINE.md`
+- `docs/00_项目规范/`
+- `docs/20_调查/STEP-065_MapLibreParticleLab_V3通用ScalarVectorField现状调查_v1.md`
+- `docs/30_设计/MapLibreParticleLab_V3通用ScalarVectorField运行时架构设计_v1.md`
+- `docs/50_Step记录/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_v1.md`
+- `docs/报告/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_Codex完成报告_v1.md`
+- 当前 `field_data_adapter.*`
+- 当前 `render_weather_color_layer.*`
+- 当前 `render_particle_validation_layer.*` 中 field texture / upload / reuse 路径
+- `weather_color_layer.*`、`weather_color_stop.hpp`、相关 shader/UBO/generator 与 tests
+
+不得按任务书猜源码；先以当前 HEAD 为准。
+
+## 3. 冻结语义
+
+1. `FieldValueSource = SCALAR | VECTOR_MAGNITUDE`，必须显式选择，不能根据 channel presence 猜。
+2. `SCALAR` 要求 scalar present；`VECTOR_MAGNITUDE` 要求 vector present；不满足则 WeatherColor renderer fail-closed/unavailable。
+3. Wind/Tide 使用 `VECTOR_MAGNITUDE`；Rain/Wave color 使用 `SCALAR`。
+4. Particle renderer 本任务仍只接受 `VectorSemantics::Velocity`；DIRECTION 留 V3-04。
+5. T0/T1/MIX、Pause、Timeline ownership、OLD_T1→NEW_T0 reuse、only NEW_T1 upload 的架构不变。
+6. WeatherColorLayer 与 RasterParticleLayer 继续分离，但消费同一 Source-owned snapshots。
+7. `FieldColorStop.value` 是 generic 值。C++ 内部 `speedMps` 命名必须在本 Step 收敛为 generic `value`/`fieldValue`；Android/JNI/RN 旧 ABI 本 Step 不修改。
+## 4. 必做实现
+
+### A. Generic FieldValueSource
+
+在 C++ style/render 层新增最小 enum/config，推荐：`enum class FieldValueSource { Scalar, VectorMagnitude };`。
+
+放在与 WeatherColorLayer 最贴近且不引入业务域的位置。WeatherColorLayer 必须持有明确 value source；默认值必须保持现有 Wind 行为，即 `VECTOR_MAGNITUDE`，保证旧路径兼容。
+
+### B. WeatherColor scalar/vector GPU 输入
+
+扩展现有 WeatherColor field texture 生成/上传，使：
+
+- `VECTOR_MAGNITUDE`：继续从 vector U/V 得到 magnitude 语义；不得改变现有 Wind 可视结果。
+- `SCALAR`：真正上传/编码 scalar 值，shader 根据 T0/T1 MIX 对 scalar 做时间插值后进入相同 generic color ramp。
+- shared validity 必须进入 alpha/有效性判断；T0/T1 任一无效时按现有 fail-closed 策略不可显示错误值。
+- 不允许 scalar 伪装成 U/V。
+
+可继续复用现有 texture/UBO/shader 基础设施，但要让 field texture 的数据语义显式，不要复制第二套 WeatherColor renderer。
+
+### C. Generic color ramp 命名
+
+把 C++ Core/style/render/shader 中与 WeatherColor 色阶相关的 `speedMps` / 固定 speed 语义改成 generic value。至少：
+
+- `WeatherColorStop.speedMps` → generic `value`
+- 校验逻辑变成 finite、严格递增 generic value
+- shader/UBO 注释和日志不再声称单位固定 m/s
+- 删除/替换 `scale=0..30mps` 这类 Wind-only 日志
+
+不得改变 RN `.2` 公共 API，也不得修改 Android/JNI/Kotlin/TS。
+### D. Particle renderer 保护
+
+本任务不得实现 DIRECTION advection。现有 RasterParticleLayer 必须显式要求：
+
+- vector present
+- `VectorSemantics::Velocity`
+
+scalar-only 或 DIRECTION vector 必须 fail-closed，不创建/继续使用错误粒子资源。
+
+### E. GPU reuse/content identity
+
+复核 WeatherColor 的 T0/T1 resource reuse：
+
+- normal boundary OLD_T1→NEW_T0 可复用相同 decoded plane bundle
+- 新 T1 只上传新需要的 texture
+- scalar/vector/validity 变化必须触发正确 content change
+- 正常 playback 不允许因为 generic value source 改造而重建 Particle simulation 或 clear trail
+
+如果当前 `sameFieldGpuContent()` 已满足，无需再改 Core Contract。
+
+## 5. Shader 约束
+
+允许修改 WeatherColor 实际使用的 shader/UBO/generator，只限完成 generic field value。必须保持：
+
+- T0/T1 GPU 时间插值
+- spatial sampling/bounds
+- current vector particle shader physics 不变
+- 不把 provider、WeatherV2、Rain/Wave/Tide 业务名写进 shader
+- 不增加第二套专用 rain/wave shader
+
+如果同一 shader 当前同时承载 particle/weather pass，可做最小 pass/value-source 分支，但不能借此重构整个粒子 shader 架构。
+## 6. 最小验证
+
+不加入 Jest。使用现有 C++/OpenGL 测试体系，至少覆盖：
+
+- WeatherColor default `VECTOR_MAGNITUDE` 保持旧 Wind 行为
+- scalar-only + `SCALAR` 可建立 field texture/render resources
+- vector-only + `VECTOR_MAGNITUDE` 可建立资源
+- scalar+vector 可由 value source 明确选择对应 channel
+- scalar-only + `VECTOR_MAGNITUDE` fail-closed
+- vector-only + `SCALAR` fail-closed
+- T0/T1 channel/valueSource compatibility 错误不被渲染
+- scalar T0/T1 MIX 数值路径正确
+- vector magnitude T0/T1 MIX 不回归
+- validity mask 对 scalar/vector 都生效
+- DIRECTION vector 在 Particle renderer fail-closed
+- existing v1 Wind fixture/source tests 回归通过
+- `git diff --check` PASS
+
+执行规定的 Linux OpenGL 精确编译/测试，遵循全局 `$build-output-throttle`。
+
+不得执行 Android Gradle、AAR、APK、ADB。
+
+## 7. 硬边界
+
+本任务禁止修改 Android/JNI/Java/Kotlin、RN package/API/version、Test Host JS/TS、WeatherV2、NavSea；禁止实现 DIRECTION particle movement / wave physics；禁止解析 NSFT/PMTiles；禁止新增 provider/network/cache；禁止重构 Timeline/Playback/Runtime Window；禁止新建 RainRenderer/WaveRenderer/TideRenderer；禁止 Jest 与 Android build/install/ADB。
+## 8. 文档输出
+
+必须新增/更新：
+
+- `docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md`
+- `docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md`
+- 追加 `粒子开发记录.md`
+
+所有文档中文。报告逐项列出生产代码修改文件、Renderer/shader 语义变化、精确编译/测试结果、未执行 Android/Jest、未触碰无关工作区。
+
+## 9. 必做清单
+
+- [ ] 复读规范、STEP-065/066 与当前源码
+- [ ] 引入显式 `FieldValueSource::Scalar / VectorMagnitude`
+- [ ] 默认保持 VectorMagnitude 旧 Wind 行为
+- [ ] WeatherColor scalar GPU path 可用
+- [ ] WeatherColor vector magnitude path 回归
+- [ ] shared validity 同时保护 scalar/vector
+- [ ] C++ WeatherColor `speedMps` 语义改为 generic value
+- [ ] Particle renderer 拒绝 scalar-only 和 DIRECTION
+- [ ] T0/T1/MIX 与 resource reuse 不回归
+- [ ] 最小精确 Linux/OpenGL tests PASS
+- [ ] `git diff --check` PASS
+- [ ] Step/报告/开发记录完成
+- [ ] scoped Git commit + push `origin/particle/main`
+## 10. Git 收尾
+
+完成后只显式 `git add` 本任务文件与实际修改文件，严禁把 STEP-062 用户修改、历史 untracked、build/cache/tgz 带入提交。
+
+创建合理 scoped commit；更新完成报告记录全部 commit hash/message、push 结果与最终远端分支。
+
+必须 push 到 `origin/particle/main`，最终复核：
+
+`HEAD == origin/particle/main`
+
+push 失败不得声称完成。
+
+完成后直接按必做清单报告“已完成 / 未完成 / 无法验证”，不要输出实施计划。

docs/50_Step记录/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_v1.md

@@ -1,6 +1,6 @@
 # STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer
 
-状态：完成（Linux 全量重链受执行环境时限限制，见验证）
+状态：完成（CLOSED / PASS）
 
 ## 目标与基线
 
@@ -29,8 +29,9 @@ WeatherColor style/render、Particle renderer guard、实际 GLSL/生成的 Open
 - 精确受影响对象：`render_weather_color_layer.cpp.o`、`render_particle_validation_layer.cpp.o`、`style_layer.test.cpp.o`：PASS（经 build-output-throttle；ccache 临时目录使用 `/tmp/maplibre-particle-ccache-tmp`）。
 - `build-linux-opengl/mbgl-test-runner --gtest_filter='Source.ParticleFieldV3*:Layer.WeatherColorUsesIndependentFixedOpacity'`：PASS，退出码 0。
 - `git diff --check`：PASS。
-- 尝试 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`：未在单次受限终端时限内完成全量 shader 依赖重链；首轮唯一错误为 sandbox 的 `/root/.cache/ccache/tmp` 只读，改用 `/tmp` 后受影响对象均已通过。不得将此记为全量链接 PASS。
+- 用户于当前 `HEAD`（`06fcbef9ccb820e595f06acbd356950de7e3a73f`）手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`，输出为 `ninja: no work to do.`。确认 `mbgl-test` 与 `mbgl-test-runner` 两个完整目标及其依赖均已是最新，没有待处理的构建或重链接工作。
+- 上述结果仅确认目标构建/重链接状态；本次没有重新执行全量测试用例，不能将其表述为全量测试用例重跑 PASS。
 
 ## 阻塞与下一步
 
-无功能阻塞。需要具备持续 Linux 构建会话的环境在同一 commit 补跑全量 `mbgl-test` / `mbgl-test-runner` 链接；Android 验收按 V3-08 的单独周期执行。
+无功能阻塞。本 Step 的 Linux 全量目标重链收尾已确认；Android 验收按 V3-08 的单独周期执行，且不属于本 Step 的关闭条件。

docs/报告/STEP-067_MapLibreParticleLab_V3-03_ScalarGPU与GenericFieldRenderer_Codex完成报告_v1.md

@@ -1,6 +1,6 @@
 # STEP-067 MapLibreParticleLab V3-03 Scalar GPU 与 Generic Field Renderer Codex 完成报告
 
-状态：IMPLEMENTED / Linux 全量重链待持续构建环境复验
+状态：CLOSED / PASS
 
 ## 生产代码修改
 
@@ -11,10 +11,12 @@
 
 ## 验证结果
 
-shader generator、三个受影响 C++ 编译对象、`Source.ParticleFieldV3*` 与 WeatherColor layer 过滤测试、`git diff --check` 均 PASS，命令输出均经 build-output-throttle 限流。全量 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner` 因受限终端的 30 秒上限未完成；初始 ccache 临时目录只读已通过 `/tmp` 规避，不能据此虚报全量链接 PASS。
+shader generator、三个受影响 C++ 编译对象、`Source.ParticleFieldV3*` 与 WeatherColor layer 过滤测试、`git diff --check` 均 PASS，命令输出均经 build-output-throttle 限流。此前受限终端未完成的全量重链，已由用户在当前 `HEAD`（`06fcbef9ccb820e595f06acbd356950de7e3a73f`）手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner` 收尾，输出为 `ninja: no work to do.`；因此确认 `mbgl-test`、`mbgl-test-runner` 的完整目标和依赖已最新，没有待处理的构建或重链接工作。
+
+该手工 Ninja 结果不等于重新执行全量测试用例：本次未重跑完整测试套件，只确认构建/重链接目标无待处理工作。
 
 未执行 Android Gradle、AAR、APK、ADB 或 Jest；未触碰 STEP-062 用户修改、历史 untracked、build/cache/tgz。
 
 ## Git 收尾
 
-本报告随 scoped 文档提交交付；实现提交 hash、文档提交 hash、push 输出与 `HEAD == origin/particle/main` 的最终复核会在本次 Git 收尾后记录于终端回执。仅显式暂存本 Step 的生产代码、测试与文档文件。
+实现基线提交为 `06fcbef9ccb820e595f06acbd356950de7e3a73f`（`docs: record STEP-067 scalar GPU renderer`）。本次关闭仅提交 STEP-067 任务归档、Step 记录、完成报告和开发记录；不会暂存 STEP-062 用户修改、历史未跟踪文件、build/cache 或 tgz。关闭提交 hash、push 结果与最终 `HEAD == origin/particle/main` 复核见本次交付终端回执。

粒子开发记录.md

@@ -641,3 +641,8 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 `
 - `WeatherColorStop` 的 C++ 字段从 `speedMps` 收敛为 generic `value`；shader/UBO/log 不再声称固定 m/s。切换 value source 会重新编码资源，正常 OLD_T1→NEW_T0 rollover 仍复用同一 decoded bundle。
 - RasterParticleLayer 继续只接受 `Velocity` U/V；scalar-only 或 `Direction` 立即不可绘制并释放粒子资源，未实现 DIRECTION advection。
 - shader generator、受影响 C++ 对象和 Core/layer 过滤测试均通过；全量 OpenGL `mbgl-test` 链接受当前单次终端时限限制未完成，未虚报 PASS。未运行 Gradle/AAR/APK/ADB/Jest，未触碰 STEP-062 或历史未跟踪内容。
+
+## 2026-09-11 — STEP-067 Linux 全量目标验证收尾
+
+- 用户在当前 `HEAD` `06fcbef9ccb820e595f06acbd356950de7e3a73f` 手工执行 `ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner`，Ninja 返回 `no work to do.`；确认 `mbgl-test` 与 `mbgl-test-runner` 完整目标及其依赖已经最新，没有待处理构建或重链接工作。
+- 此结果只关闭此前 Linux 全量目标重链复验，不代表重新执行全量测试用例；本轮未执行 Android Gradle/AAR/APK/ADB/Jest，未修改生产代码、STEP-062 用户修改或其他历史未跟踪内容。STEP-067 正式 `CLOSED / PASS`。