# STEP-070 MapLibreParticleLab V3-06 四类场 Fixture 与 RN 通用回归

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

## 目标与边界

在 `particle/main` `3b012759` 上增加离线 V3 fixture、转换/校验工具、RN Test Host `.3` 公共 API 接线和最小 Core contract test。不修改 Timeline/Playback/T0/T1/MIX/rollover、schema、shader、WeatherV2、NavSea 或 STEP-062 两份用户 dirty 文档；不运行 Android Gradle/AAR/APK/ADB/Jest。

## 完成内容

- [x] `tools/particle_v3_fixture` 生成并校验 v2 metadata、shared validity、可选 scalar/vector、长度与 SHA-256。validator 对每一个 validity=1 的 cell 检查所有存在 plane：finite 且不等于 noData。
- [x] `wind-real` 从本地 canonical v1 `field.f32` 重新封装；shared validity 严格派生为 `finite(U) && finite(V) && U != -9999 && V != -9999`。
- [x] `wave-real` 由 WeatherV2 `ecmwf-wam/waves/2026090912/wave_bin` 的正式 `2026090918/2026090919` BIN 和 header sidecar 解码：scalar=`height_m`，vector=规范化 `unit_to_u/unit_to_v`，语义 `DIRECTION`；`period_s` 和原始 degree 不进入 canonical。
- [x] `tide-real` 由 WeatherV2 `cmems/tide/2026090900/current_bin` 的正式 `2026090901/2026090902` BIN 和 header sidecar 解码为 vector-only `VELOCITY`。
- [x] Wave/Tide 每帧 summary 记录正式源 BIN 与 sidecar SHA-256、target_time、referenceTime、bounds、grid、projection、included/excluded channels 和 validity 派生规则；两者 generation 为小且严格递增的 `1/2`。
- [x] Rain 保持 `rain-decoder-fixture`，manifest/provenance 明确为非真实 field values，因为本 Step 未实现 PMTiles reader；fallback generation 为严格递增的 `1/2`。
- [x] Test Host 的 `fieldDatasets` 已指向 `wave-real` 和 `tide-real`，继续仅经 package `FieldRuntime` 公共 API 提交 local file refs。
- [x] 保留并验证 Wave synthetic scalar/vector independence；新增 C++ provider-neutral 四类 shape contract test。

## 验证

- [x] `python3 tools/particle_v3_fixture/generate_fixtures.py --write-reference-fixtures --validate`：PASS。
- [x] package `.3` `tsc --noEmit`：PASS。
- [x] RN Test Host `npm run typecheck`：PASS（不含 Jest）。
- [x] RN TurboModule `combine-js-to-schema-cli.js`：PASS。
- [x] 使用 `CCACHE_DIR=/tmp/step070-ccache`，重新编译 `source.test.cpp.o`：PASS。
- [x] `mbgl-test` / `mbgl-test-runner` 完整 Linux OpenGL 重编译/重链：459/459 完成；`Source.ParticleFieldV3*` 过滤测试 6/6 PASS；验证链退出码 0。
- [x] `git diff --check`：PASS（提交前复核）。
- [ ] Android Gradle/AAR/APK/ADB/Jest：按任务范围未运行。

## 当前结果、阻塞与下一步

fixture 数据契约、TypeScript/codegen、Linux 完整重链与 V3 Source 过滤测试均已完成。Android/JNI 真实编译和设备视觉验收仍由后续统一周期完成。Rain 要升级为真实数值场，需要另行实现只读 PMTiles reader；不得把现有 fallback 改称 real。

## Git 收尾

- implementation：`8588e6fcb4f3f5d874159c2e42619c5227cb7921`（`feat: add V3 field fixtures and RN regression host`），已 push 至 `origin/particle/main`。
- docs-only Git handoff 在 `git add` 创建 `.git/index.lock` 时因只读文件系统被阻断，未提交、未推送；STEP-062 两份用户 dirty 文档与历史 untracked/build/cache/tgz 均未暂存。