MapLibreParticleLab/docs/报告/STEP-097_A2_阶段验证记录_v2.md

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，运行：

--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 生成日志。

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