# 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、未提交。