# STEP-097 A2 阶段验证记录 v2

**状态：PARTIAL / 独立扩展回归发现既有断言与既有函数语义冲突。** 本报告接续 v1，不覆盖其原始验证事实；A2 生产代码仍为未提交的工作树改动，不可据此进入 B/C。

## 1. 本次实际动作

- 2026-09-26（JST），在 Mac `/Users/tei/dev/MapLibreParticleLab`，`particle/main` 当前远端与本地同为 `bd1cfe95b7595a95314b9083754823ae170c5c8e`；Integration `main` 已核对 `318f8ccf911ac3136c3086a1d14e61f83e2d4bce`。
- 现有 A2 工作树修改仍保留，未修改生产文件、未提交 A2 源码；用户的未跟踪 STEP-098 任务 MD 原样保留。本次只扩大原生回归并核对失败的旧源码/测试。
- v1 已记录：OpenGL 和 Metal host 原生测试程序各自编译 exit 0；A2 聚焦 16/16 PASS，两次 Shader 生成一致；Metal 仅主机源码/原生测试，不是 iOS 实机测试。

## 2. 扩大回归

使用 OpenGL `build-step088-opengl/mbgl-test-runner`，运行：

```sh
--gtest_filter='ParticleFieldRuntime.*:ParticleFieldProfileValidator.*:ParticleGpuField.*:ParticleFieldBinding.*:Source.RasterArray*:Source.HostField*:Source.ParticleField*:Source.CanonicalField*'
```

结果 **58 项中 57 PASS、1 FAIL，退出码 1**。失败项 `Source.RasterArrayGpuContentIdentityExcludesRuntimeGeneration` 位于 `test/style/source.test.cpp:288`，预期 `sameFieldGpuContent(east, changed)` 为 false，实测 true。

核查本次未修改的 HEAD 定义：`sameFieldGpuContent()` 明确只比较兼容性、解码 scalar/vector/valid，不比较 `generation`、`dataVersion` 等生产者身份；旧测试却在仅增加 `dataVersion` 时要求 false。两者存在**原有测试期望与既有函数契约不一致**。本轮未另建旧 HEAD 二进制作基线重演，因此只称静态可证的原有矛盾，不声称已做旧版运行复现。

A2 新增 `sameFieldGpuEndpoint()` 负责严格 GPU 端点身份，明确比较 generation/dataVersion/validTime、U/V、validity、grid、encoding 等；对应新 `ParticleGpuField.*` 四项已通过。旧内容等价与新端点等价不应被混为一谈。

排除上述旧测试后，同一组其余 **57/57 PASS，退出码 0**；这只是隔离验证，不是宣布全部回归 PASS。

## 3. 后续修复门槛

- Codex 恢复 GPT-6-Sol medium 后，先复核旧内容比较与新端点比较各自用途；修正旧测试断言，使其与实际函数语义一致，或发现更深的契约问题时写阻塞报告。禁止仅为让旧断言通过而更改新端点身份约束或放宽安全机制。
- 修改后重新编译原生 runner，原 58 项完整回归必须退出 0，并复跑 A2 聚焦用例。随后核对 Android 端 A2 APK 与当前最终代码一致。
- **Android Gradle 编译由用户手工执行。** 标准 Mac 仓库命令为 `cd /Users/tei/dev/MapLibreParticleLab && ./tools/particle_android_validation/build_validation_apk.sh`。在 A2 代码完成前执行只能算中途 smoke，不是最终 Android 验收。用户提供编译结果后，再通过 RDC 对 FZG1-2 `192.168.200.139:5555` 安装、Logcat、截图验证。
- iOS runtime 按用户明确决定豁免，记 `USER_ACCEPTED_WITHOUT_IOS_RUNTIME_TEST`；不虚报 iOS 实测。
- 未进入 B/C，未运行 STEP-098，未改冻结的 `.13` 正式发布。

## 4. 原始证据

Mac 忽略目录 `artifacts/maplibre-particle/step097-a2-rdc/`：

- `a2-broader-core.log`：58 项、1 FAIL 原始记录；
- `a2-broader-excluding-legacy-test.log`：其余 57/57 PASS；
- `a2-broader-run-metadata.txt` / `a2-broader-exclude-metadata.txt`：过滤器；
- v1 中已有 `build-opengl.log`、`build-metal-host.log`、`a2-focused-tests.log`、`a2-metalhost-core-tests.log`、Shader 生成日志。

本报告不覆盖测试失败，也不将尚未提交的代码描述为正式完成。