MapLibreParticleLab/docs/50_Step记录/STEP-101_RenderOrchestrator销毁生命周期修复_v1.md

STEP-101 RenderOrchestrator 销毁生命周期修复记录 v1

状态：CLOSED / PASS（Native + Android runtime） 日期：2026-10-07

目标与基线

• 工作区：/Users/tei/dev/MapLibreParticleLab-step101
• 分支：step101-render-orchestrator-teardown
• start HEAD：d29e84c1a90daeea104b389d28b000c4f017d08d
• implementation commit：64cf8f44350eb8ec4b45360db4d3f9505ac4ac0b（fix: make render orchestrator teardown safe），已 push 到 origin/particle/main 并回读一致。
• 工作合同：docs/40_任务/STEP-101_RenderOrchestrator销毁生命周期修复_Codex任务_v2.md，第 13 节优先于前文冲突项。
• V18 为不可变已发布版本；本阶段未创建、发布或标记 V19。
• 目标：修复 RenderSource/Tile 销毁时 observer 可能回调已析构的 RenderOrchestrator readiness mutex/state 的生命周期漏洞。

V18 成员声明使 readiness mutex/state 早于 renderSources 自动析构。Tile 销毁时同步发出 Cancelled 回调的路径可达，且与现场 Android destroyed mutex SIGABRT 高度吻合；没有完整符号化栈与修复后等价实机结果，暂不把它写成唯一确认的现场根因。

必做项进度

• RenderSource::setObserver(nullptr) 恢复 NullObserver，保留正常 observer 转发。
• Orchestrator 析构：保留 contextLost layer handling；第一次 tagged drain；detach RenderSource、GlyphManager、ImageManager observer；在 readiness state 存活时清理 sources；第二次 tagged drain。
• 静态审计独立 render-job 队列：waitForEmpty() 不排空该队列；OpenGL context 析构的 runRenderJobs(true) 属于后续 backend 清理，测试中也单独调用 runRenderJobs()。不能以双 drain 代替 render-job 验收。
• 新增非 Jest C++ 测试源码：默认/真实/detach observer、三种 tile callback、Cancelled、source 清理后第二次 drain、render-job 单独处理和重复 teardown。helper 像生产代码一样注册 Orchestrator observer，并断言 source 销毁前旧 observer 已被替换。
• Android Validation 增加 T1 RESET_ONCE、T2 RESET_LOOP_20、T3 RESET_WITH_DYNAMIC_GEOJSON、T4 RESET_WITH_DIAGNOSTICS；通过 Activity recreate 触发 MapView 销毁/新建，并输出 SurfaceView detach、nativeReset、resetRenderer、style ready 与 diagnostics 日志供逐次配对。
• 只读审计正常 renderSources.erase() / clearData()：两者在 Orchestrator 存活期间执行；TileCache 析构等待其延迟释放任务结束。本阶段没有扩大其行为修改，运行态异步边界仍待 RDC 验证。
• 静态核对 STEP-100 locality、Fast Path、singleContinuousSegment、Source::isLoaded() 等代码未被本次 diff 修改。
• Native：Android full native build PASS；focused Android C++ TestRunner 6/6 PASS。Mac host 因 libuv 环境阻塞，未虚报。
• Android Validation APK build PASS；T1～T4 实机 PASS；T2 完整 20 次真实 reset/recreate，crash buffer 为空。
• STEP-100 T4 R-C-R locality 回归 PASS：R0 buildDelta=0、invalidationDelta=0、reuseDelta=+3878。
• V19 candidate、NavSea 五次冷启动与正式 V19 发布：属于后续发行 Gate，尚未执行。

允许与禁止范围

实际变更限于 Orchestrator/RenderSource 生命周期、对应 C++ 测试、Android Validation 场景及 Java/JNI reset 观测日志。未修改 NavSea、provider/network、STEP-100 locality 实现、发布坐标或 V18 产物。未运行 Jest。

检查与当前结果

本次验证仅包含源码 diff 静态审计与 git diff --check。构建、链接、GTest、Gradle/APK、ADB、设备、NavSea、发布均 NOT RUN；源码交付不能记为运行态 PASS。完成报告：docs/报告/STEP-101_RenderOrchestrator销毁生命周期修复_Codex完成报告_v1.md。

阻塞与下一步

当前没有已观测编译失败；实际编译与场景行为仍未知。由 RDC 按完成报告的命令独立编译、运行 Native 测试、Android T1～T4、STEP-100 locality，并核对每次 RESET_REQUEST 对应 SurfaceView detach、nativeReset、resetRenderer 和新 renderer ready。随后才进入 V19 candidate 与 NavSea 等价验收；全部门槛满足后才可考虑正式发布。

RDC 最终证据

• Android Validation APK：61,957,678 bytes；libmaplibre.so 39,637,512 bytes；SHA-256 14cbd35ed0bc1366389ddea69925901013e3b209ed3575462421a7920c73c721。
• T1～T4 teardown：全部 PASS；T2 20 次 reset；动态 GeoJSON / diagnostics 条件均无 crash。
• STEP-100 locality：global revision 62→894；R0 build 1→1、invalidation 19→19、reuse 12→3890；PASS。
• Android C++ focused TestRunner：4 个 RenderSegmentLocality + 2 个 RenderOrchestratorTeardown 全部 PASS；status=0。
• Mac host GTest：ENV BLOCKED（本机缺可用 libuv pkg-config），不影响 Android full native/device 闭环结论。
• Jest：NOT RUN。

STEP-101 CLOSED / PASS。 下一阶段进入 V19 candidate → NavSea 等价冷启动 Gate → 不可变公开发行。