MapLibreParticleLab/docs/报告/STEP-049_Timeline回归修复_Codex完成报告_v1.md

STEP-049 Timeline 回归修复 — Codex 完成报告

状态

IMPLEMENTED / WAITING_ANDROID_REVALIDATION。本报告不宣称 CLOSED / PASS。

基线与根因

• Starting HEAD：dcedbe7394e74b80d91f00315a9956dfaea35229
• 实际远端 origin/particle/main 起始 HEAD：dcedbe7394e74b80d91f00315a9956dfaea35229
• 根因：tryLoadRuntimeField() 以 generation 0 调用正式 adapter；adapter 合法拒绝，Timeline candidate 在更晚的 tryInitializeTimeline() 才分配 generation。Runtime Window 使用已分配 generation，故出现 Timeline 失败而 Window 正常。
• 原 STEP-049 11/11 未捕获：测试覆盖了直接 adapter、手工 Timeline 和 Runtime Window，但没有覆盖真实 Source 异步 candidate preload → adapter → Timeline READY 顺序。

实际修改

• src/mbgl/style/sources/raster_array_source.cpp：candidate decode 前分配全局 generation，移除 Timeline 阶段重复赋值；增强低频 adapter rejection 日志。
• src/mbgl/particle/field/field_data_adapter.cpp、.hpp 与 fixture wrapper：保留正式 contract 和 generation 非零校验，提供 error code 名称用于日志。
• test/style/source.test.cpp：新增真实 candidate → adapter → Timeline READY 回归测试。
• platform/android/MapLibreAndroidTestApp/.../ParticleCoreLayerValidationActivity.kt：仅整理 Window/Timeline 状态可见性。
• docs/50_Step记录/STEP-049..._v2.md、本报告、粒子开发记录.md。

未修改 Runtime Field Window、Duplicate、Renderer simulation、Timeline Core 状态机或 Android per-frame JNI；未新增兼容层。

验证

• C++/Core/OpenGL：cmake --build build-linux-opengl --target mbgl-test-runner -j3，PASS。
• 定向测试：Source.RasterArrayTimelineCandidatesReachReadyThroughFieldAdapter:Source.ParticleFieldDataAdapter*:Source.RasterArray*，12/12 PASS。
• 合法 candidate 通过正式 adapter 并进入 Timeline READY：PASS。
• generation=0 / invalid descriptor 结构化拒绝：PASS。
• git diff --check：PASS。
• Android Gradle/APK/copy/install/ADB/设备：未执行。
• Jest：未新增、未执行。

Android 待复验

需验证 ParticleTimeline: event=READY、PLAY 不再 TIMELINE_NOT_READY、MIX/cursor 推进、跨至少两个 Window boundary、Pause/Resume、GAP WAIT、INVALID NEXT、fail-closed、Renderer 持续和 simulationRebuild=false/trailCleared=false。

Git 收尾

• commit hash：a418e50a0105a23e70112eb77cd813485eae6855
• commit message：fix: restore particle timeline readiness after field adapter
• push result：SUCCESS
• remote branch：origin/particle/main
• Final HEAD（修复提交推送时）：a418e50a0105a23e70112eb77cd813485eae6855
• 无关 untracked 文件：保留，未修改、未 stage、未提交。