MapLibreParticleLab/docs/报告/40_01_RasterArrayFieldIdentity修复_Codex完成报告_v1.md

40-01 RasterArray Field Identity 修复 Codex 完成报告 v1

1. 结论

已修复 Android Style/source recreation 后 uniform-north 错误复用 uniform-east GPU field 的 identity collision。40-01 继续为 WAITING_MANUAL_VALIDATION；未运行 Android Gradle、ADB 或真机。

2. 根因

RasterArraySource::tryLoad() 将 ParticleFieldSnapshot::generation 由 source 实例成员递增。相同 source ID 的 Style 重建会新建实例，east 首次 load 与 north 首次 load 都可能得到 generation 1。RenderRasterParticleLayer 正式 sourceChanged 只比较 generation，故将不同 fixture 错认为同一 field，复用了旧 east GPU texture。

3. 新 contract

• ParticleFieldSnapshot::generation 是 process-wide、单调递增的运行时 snapshot revision；由 raster_array_source.cpp 的 atomic 分配。它不表示 metadata dataVersion，不使用时间戳或随机数。
• renderer 的 fieldIdentityChanged(current, next) 同时比较 generation、fixtureID、dataVersion。任一变化均触发既有 field upload、resetSequence()、State re-seed 与 Trail clear；三者都相同则不重复上传。
• 未修改 shader U/V、State/Trail/Composite slot wiring、ACTIVE/STATIC lifecycle、Rotation bootstrap、mask、world wrap、antimeridian、RenderTarget 或 Android UI。

4. 诊断与测试

• source load 日志：ParticleField: source loaded fixtureId=... generation=... dataVersion=...。
• renderer switch 日志：ParticleRender: fixture switched from=... to=... oldGeneration=... newGeneration=... gpuFieldGeneration=... trail=cleared stateSeed=INITIALIZE。
• 定向 C++ 测试覆盖两个独立 east/north RasterArraySource 实例 generation 不同；generation 相同、fixture 不同仍为 changed；同 fixture/generation/dataVersion 为 unchanged，dataVersion 改变为 changed。
• Linux OpenGL 精确编译：raster_array_source.cpp.o、render_particle_validation_layer.cpp.o、source.test.cpp.o，PASS。
• clang-format --dry-run --Werror 与 git diff --check：PASS。

5. Git 收尾

最终代码修复 commit：1cd3e771095922863b3717689c690fc8ab0ed8c6（fix: distinguish raster array field snapshots）。push 成功后 remote branch 与 origin/particle/main HEAD 在交付结果中记录。