docs: record STEP-066 core contract

docs/50_Step记录/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_v1.md

@@ -0,0 +1,35 @@
+# STEP-066 MapLibreParticleLab V3-02 Core Contract 与 Scalar Snapshot Adapter
+
+状态：完成
+
+## 目标与基线
+
+在 `particle/main` 的 STEP-065 冻结设计上，仅实现 Core Contract、Snapshot、Adapter 与最小 Core 测试。开工时 `HEAD == origin/particle/main == d23ae2079dcfef3ce48517f734fe487207e28d23`；工作区已有 STEP-062 两处用户修改及历史 untracked/build 内容，均未纳入本 Step。
+
+## 完成内容
+
+- [x] 阅读规范、STEP-065、任务书与当前实际源码。
+- [x] 定义通用 `ParticleFieldPayloadBundle`、v2 plane descriptor 与 `VectorSemantics::Velocity|Direction`。
+- [x] Snapshot 升级为 optional scalar、optional interleaved U/V vector、shared `valid`；移除 Core 对 `WIND/GLOBAL` 的 capability hardcode。
+- [x] 实现 v2 vector-only、scalar-only、scalar+vector；neither、plane presence/长度/encoding、validity、semantics 与 finite/noData 错误 fail-closed。
+- [x] 保留 v1 单 payload parser；在 ingress 派生 shared validity，并归一为 vector-only + `VELOCITY`。
+- [x] 收紧 T0/T1 compatibility 至 grid/bounds、scalar/vector presence 与 vector semantics；不改变 Source-owned Timeline、T0/T1/MIX、pause 或 rollover ownership。
+- [x] `sameFieldGpuContent()` 逐值比较 decoded scalar/vector/validity plane，不依赖 fieldId/dataVersion/legacy hash 猜测内容。
+- [x] 最小 renderer 适配：速度纹理读取改为 generic vector 成员；scalar-only 输入清空/不创建 drawables，V3-03 前 fail-closed；未改 shader、纹理编码、GPU 计算或粒子运动语义。
+- [x] `source.test.cpp` 覆盖 v1 normalize、三种 v2 合法组合、neither、三种长度错误、missing semantics、DIRECTION without vector、NaN/Inf、invalid finite placeholder、compatibility 与三 plane identity。
+
+## 验证
+
+- `ninja -C build-linux-opengl -j3 mbgl-test`：PASS。
+- `ninja -C build-linux-opengl -j3 test/CMakeFiles/mbgl-test.dir/style/source.test.cpp.o`：PASS。
+- `ninja -C build-linux-opengl -j3 mbgl-test-runner`：PASS。
+- `build-linux-opengl/mbgl-test-runner --gtest_filter=Source.ParticleFieldV3*`：PASS（退出码 0）。
+- `git diff --check`：PASS。
+
+全部 build/test 输出经 `build-output-throttle` 限流。未执行 Android Gradle、AAR/APK、ADB 或 Jest。
+
+## 范围确认、阻塞与下一步
+
+没有 Android/JNI/RN、WeatherV2、NavSea、shader 或 Test Host JS/TS 修改；STEP-062 用户修改和历史 untracked 内容未暂存。Scalar GPU texture、generic `FieldValueSource`、DIRECTION advection、v2 JNI/RN ingress 均未实现，按冻结路线留给 V3-03/V3-04/V3-05；scalar snapshot 在现有 renderer 为 unavailable/fail-closed。
+
+下一步：STEP-067（V3-03 Scalar GPU Texture + Generic Field Renderer）。

docs/报告/STEP-066_MapLibreParticleLab_V3-02_CoreContract与ScalarSnapshotAdapter_Codex完成报告_v1.md

@@ -0,0 +1,36 @@
+# STEP-066 MapLibreParticleLab V3-02 Core Contract 与 Scalar Snapshot Adapter Codex 完成报告
+
+状态：CLOSED / PASS
+
+## 结果
+
+V3 Core 已从 Wind-only U/V payload 统一为 generic snapshot：0/1 scalar、0/1 vector、1 shared validity。v1 仍可读取，并在 adapter ingress 转为 `VELOCITY` vector snapshot；v2 vector-only、scalar-only、scalar+vector 均由 Core 通过。无 channel、尺寸、validity、semantic、finite 或 valid-cell noData 错误均拒绝。
+
+`fieldType` 与 `displayDomain` 保留为可选 legacy metadata，但不再决定 Core capability、validity 或 T0/T1 compatibility。content identity 直接比较 decoded scalar/vector/validity plane，任一 plane 改变不会误判 same-content。
+
+## 逐项状态
+
+|任务项|结果|
+|---|---|
+|规范、STEP-065、实际源码与工作区核对|已完成|
+|V3 generic snapshot/descriptor/payload bundle|已完成|
+|WIND/GLOBAL validity hardcode 移除|已完成|
+|v2 vector-only/scalar-only/scalar+vector|已完成|
+|shared validity、VectorSemantics、v1 thin normalize|已完成|
+|interpolation compatibility/content identity|已完成|
+|Timeline/Runtime Window ownership 保护|已完成|
+|最小 Core fixtures/tests|已完成（内存 plane fixture）|
+|精确 Linux/Core 编译和过滤测试|已完成|
+|Android/JNI/RN/WeatherV2/NavSea 不修改|已确认|
+|Step、报告、开发记录|已完成|
+
+## 验证与未完成项
+
+Linux OpenGL `mbgl-test`、受影响 `source.test.cpp.o`、`mbgl-test-runner` 均已通过；`Source.ParticleFieldV3*` 过滤测试退出码为 0；`git diff --check` 通过。首次受限沙箱编译因 ccache 临时目录只读失败，获准使用现有构建缓存后完成，非源码错误。
+
+未完成且不属于本 Step：V3-03 scalar GPU texture/`FieldValueSource`、V3-04 DIRECTION normalizing/advection、V3-05 v2 JNI/RN 三 plane ingress、真实业务 fixture/Android 验收。既有 renderer 对无 vector snapshot 明确 fail-closed，未伪造 scalar 为 U/V。
+
+## Git 收尾
+
+- Source/function commits：`379c9ed0e`（`core: add scalar vector field snapshots`）与 `6d1f3e051`（`core: preserve fixture times in generic snapshots`）。
+- Docs handoff commit、push 结果、最终 HEAD / `origin/particle/main`：在 docs handoff 提交后回填。

粒子开发记录.md

@@ -627,3 +627,10 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 `
 - Renderer policy 与数据分离：Field 明确选择 `SCALAR` 或 `VECTOR_MAGNITUDE`，Particle 明确选择 `VELOCITY` 或 `DIRECTION`；Wave direction 是归一化方向，插值近零/反向时 fail-closed，推进 scale 独立于业务数据。
 - 保留 v1 作为最薄 ingress normalize，运行时只保留一套 V3 Timeline/GPU bundle；保护 T0/T1/MIX、pause、OLD_T1→NEW_T0 bundle reuse、only NEW_T1 upload、normal rollover 不重建 simulation/clear trail。
 - 下一步为 V3-02 Core Contract + Scalar Snapshot/Adapter；先完成 Linux/Core fixture 与 compatibility，再统一进入 GPU、Android/JNI/RN 与一次 Android 综合验收。
+
+# 2026-09-10 — STEP-066 V3-02 Core Contract 与 Scalar Snapshot Adapter
+
+- Core snapshot 现为 optional scalar、optional interleaved U/V vector 与 shared validity；v2 vector-only、scalar-only、scalar+vector 均由独立 plane bundle 解码，neither 和尺寸/semantic/finite/validity 错误 fail-closed。
+- 旧 v1 单 payload 未扩展：adapter 从 U/V noData 派生 shared validity，并归一为 `VELOCITY` vector snapshot；Core 不再以 `WIND/GLOBAL` 判断 capability 或 compatibility。
+- Timeline T0/T1/MIX/pause/rollover ownership 未改；compatibility 收紧为 grid/bounds、channel presence 与 vector semantics；content identity 覆盖 scalar/vector/validity 的逐值变化。
+- 既有 GPU renderer 尚不消费 scalar：本轮只让 scalar-only 不可用，未改 shader 或渲染计算。Linux OpenGL Core/source test 精确编译和 `Source.ParticleFieldV3*` 过滤测试通过；未运行 Gradle/AAR/APK/ADB/Jest。