feat: add provider-neutral particle field adapter contract

docs/50_Step记录/STEP-049_Provider-neutral_Field_Data_Adapter与Runtime输入契约_v1.md

@@ -0,0 +1,40 @@
+# STEP-049 Provider-neutral Field Data Adapter 与 Runtime 输入契约
+
+- 状态：进行中（等待 Android 综合验收）
+- 目标：建立不包含 provider/network/vendor 语义的 C++ Field descriptor、payload adapter 与 immutable Snapshot 输入边界，并复用既有 Runtime Field Window。
+- 基线：`f0954476783b60c6ad4fdde7229657abed2e70f6`，`particle/main`，与 `origin/particle/main` 一致。
+
+## 实际实现结构
+
+新增 `ParticleFieldDescriptor`、`ParticleFieldSnapshot`、`ParticleFieldDataAdapter` 与 `ParticleFieldAdapterResult`，位于 `include/mbgl/particle/field/field_data_adapter.hpp` / `src/mbgl/particle/field/field_data_adapter.cpp`。descriptor 仅描述 field identity、类型/域、有效时间、网格 bounds、U/V canonical layout、format、stride/byte length、no-data、版本和可选 checksum；不包含 URL、token、provider 或网络对象。
+
+`ParticleFieldDataAdapter::decode()` 校验 descriptor、`interleaved-uv` + `float32-le`、尺寸/stride、payload 长度和 finite data，生成拥有自有 `std::vector` 的 Snapshot。`OfflineFixtureParticleAdapter` 仍保留 `fixture-v1` schema、fixture whitelist、metadata 与 checksum 校验，但最终通过正式 adapter 输出 Snapshot；因此 fixture 不是 production adapter 的限制。
+
+## 错误与接线
+
+结构化错误包括 `InvalidDescriptor`、`UnsupportedFormat`、`DimensionMismatch`、`PayloadSizeMismatch`、`InvalidTimestampOrIdentity`、`NonFiniteData` 和 `DecodeValidationFailure`，错误码与 message 分离。`RasterArraySource` 继续只调用 `updateRuntimeFieldWindow()`；没有第二套 T0/T1 状态机，`OLD_T1 → NEW_T0`、正常只上传 NEW_T1、Duplicate NOOP、MIX property-only 和 fail-closed 语义未改。
+
+Renderer 仅将日志字段从 fixture identity 改为 neutral `fieldID`，未引入 provider/network/vendor、decode、Timeline 或缓存业务。Timeline、Playback、WeatherColorLayer、Android JNI 和 GPU simulation 未改。
+
+## 验证与待验收
+
+- Linux OpenGL `mbgl-test-runner` 构建：PASS。
+- 定向测试：`Source.ParticleFieldDataAdapter*`、`Source.RasterArray*` 共 11 项，PASS。
+- `git diff --check`：PASS。
+- Android Gradle/APK/ADB/设备测试：按任务要求未执行，等待用户一次综合验收，覆盖 EAST/NORTH/VORTEX、Playback、neutral valid/invalid、payload mismatch、reuse、MIX、no black screen。
+- Jest：未新增、未执行。
+
+## 必做项
+
+- [x] neutral descriptor + immutable Snapshot
+- [x] C++ Data Adapter 与 structured error
+- [x] fixture wrapper 复用正式 adapter
+- [x] RasterArraySource 继续复用 Runtime Field Window
+- [x] 未新增 Provider Framework / network / vendor 逻辑
+- [x] Linux 定向构建与测试
+- [x] Step、开发记录与完成报告
+- [ ] Android 综合验收与 `CLOSED / PASS`
+
+## 阻塞与下一步
+
+当前无代码阻塞；正式关闭依赖用户执行任务书规定的一次 Android 综合验收。Codex 不执行 Android build/install/ADB。

docs/报告/STEP-048_下一阶段规划调查_Codex完成报告_v1.md

@@ -22,3 +22,11 @@ Gitea API 与 Git remote 均确认调查基线为 `46dceb5cb6110c94393b7413465f8
 ## 输出与收尾
 
 生成：本调查报告及本完成报告。未修改功能代码、测试、Android、Renderer 或 build 文件；未执行 Android Gradle、ADB、Jest。`git diff --check` 通过后仅提交两份调查文档并 push `origin/particle/main`。
+
+## Git 收尾补充
+
+- commit hash：`f0954476783b60c6ad4fdde7229657abed2e70f6`
+- commit message：`docs: investigate next particle runtime stage`
+- push result：`SUCCESS`
+- remote branch：`origin/particle/main`
+- Final HEAD：`f0954476783b60c6ad4fdde7229657abed2e70f6`

docs/报告/STEP-049_Provider-neutral_Field_Data_Adapter与Runtime输入契约_Codex完成报告_v1.md

@@ -0,0 +1,41 @@
+# STEP-049 Provider-neutral Field Data Adapter 与 Runtime 输入契约 — Codex 完成报告
+
+## 结果
+
+已完成 C++ provider-neutral Field descriptor、payload adapter、structured error 和 immutable Snapshot 接线。状态：`IMPLEMENTED / WAITING FOR ANDROID VALIDATION`；不能在用户 Android 验收前宣称 `CLOSED / PASS`。
+
+## Git 基线与修改
+
+- 起始 HEAD：`f0954476783b60c6ad4fdde7229657abed2e70f6`
+- branch：`particle/main`
+- origin 起始 HEAD：`f0954476783b60c6ad4fdde7229657abed2e70f6`
+- 实际修改：`CMakeLists.txt`、Field adapter 新增头/源文件、fixture adapter、`RasterArraySource`、validation renderer 日志、`test/style/source.test.cpp`、STEP-048 报告、STEP-049 Step 记录、粒子开发记录。
+- 未修改/未 stage：工作区已有的无关 untracked 任务文件与 `STEP-046-e48fa087-review.diff`。
+
+## 设计结论
+
+`ParticleFieldDescriptor` 是最小 canonical 输入契约，包含 field identity、类型/显示域、valid time、网格 bounds、dimensions、layout/encoding、stride、byte length、no-data、data version 和可选 checksum。`ParticleFieldDataAdapter::decode()` 只接收 descriptor、bytes、runtime generation，校验后生成自持有 vectors 的 Snapshot；不持有 Android、Renderer、Timeline、provider 或 network 对象。
+
+`OfflineFixtureParticleAdapter` 继续负责 fixture-v1 metadata/whitelist/checksum，并调用正式 adapter。`RasterArraySource` 仍复用唯一的 `updateRuntimeFieldWindow()`；没有改变 T0/T1、Timeline、Playback、MIX、GPU reuse 或 Renderer 业务边界。
+
+## 验证
+
+- C++ / Core / OpenGL：`cmake --build build-linux-opengl --target mbgl-test-runner -j3`，PASS。
+- 定向已有测试：`./mbgl-test-runner --gtest_filter='Source.ParticleFieldDataAdapter*:Source.RasterArray*'`，11/11 PASS。
+- `git diff --check`：PASS。
+- Android Gradle、APK copy/install、ADB、设备：未执行（任务明确由用户承担）。
+- Jest：未新增、未执行。
+
+## Git 收尾
+
+- commit hash：`3c9c58b57`
+- commit message：`feat: add provider-neutral particle field adapter contract`
+- push result：待执行
+- remote branch：`origin/particle/main`
+- Final HEAD：`3c9c58b57`（push 前）
+
+## 未完成项与风险
+
+- 用户尚未执行 Android 一次综合验收，因此 EAST/NORTH/VORTEX、Playback、neutral valid/invalid、fail-closed、reuse、MIX 与 no-black-screen 的设备结果待补。
+- 当前 adapter canonical format 仍只支持 `interleaved-uv` + `float32-le`，这是本阶段现有 Runtime 的明确边界，不是 provider schema。
+- `ParticleFieldSnapshot::isValid()` 继续按当前 Wind/Global renderer 语义校验；Wave/Tide/Current 的 Ocean-only 语义不在本阶段实现。