MapLibreParticleLab/docs/报告/STEP-089_静态渲染Revision与Invalidation基础层_Codex完成报告_v1.md

STEP-089 静态渲染 Revision 与 Invalidation 基础层 Codex 完成报告 v1

最终状态

CLOSED / PASS

完成项

• 已完成 static revision / buildRevision 门控。
• 已完成 topology snapshot / topologyRevision。
• 已覆盖 camera、viewport、pixel ratio、style、layer、source、tile、image、glyph、placement/fade、context、debug、3D/custom fail-closed。
• 已移除 transient drawable churn 对 static revision 的误触发。
• 已修复 equivalent stencil tile set 因 shared_ptr identity 导致的误失效。
• 已保留真正 LayerGroup topology 变化的失效能力。
• 已保持 STEP-088 Cache ON/OFF 运行时能力。
• 未实现 STEP-090 fast path。

实机回归中发现并修复的问题

1. 首版把 LayerGroup drawable maintenance 当成 semantic mutation，导致 staticRevision 每帧递增。
2. stencil tile shared_ptr identity 在正常帧中变化，导致 false positive。
3. LayerGroup transient churn 继续导致 topology false positive。
4. 最终改为 semantic content revision + stable topology snapshot，稳态复用恢复。

验证

• OpenGL：PASS。
• Retained directed tests：12/12 PASS。
• Metal/iOS mbgl-core：BUILD SUCCEEDED。
• Android APK：BUILD SUCCESSFUL。
• Android 稳态：
  • build 固定；
  • reuse 持续增长；
  • staticRevision == buildRevision 且保持稳定。
• Camera 变化：
  • revision 前进；
  • cache rebuild 一次；
  • 随后恢复稳定 reuse。
• git diff --check：PASS。

Android 代表日志

frame=480  build=2 reuse=302 staticRevision=21 buildRevision=21
frame=600  build=2 reuse=422 staticRevision=21 buildRevision=21
frame=720  build=2 reuse=542 staticRevision=21 buildRevision=21

相机变化后：

build=19 reuse=3519 staticRevision=44 buildRevision=44
build=19 reuse=3639 staticRevision=44 buildRevision=44
build=19 reuse=3759 staticRevision=44 buildRevision=44
build=19 reuse=3879 staticRevision=44 buildRevision=44

Git

• Code commit: bcec6ce5e0f4d1cfc35fd0b4dddadfaf6e37e0fb
• Code commit message: feat: add retained underlay revision invalidation
• Remote branch: origin/particle/main
• Push result / Final HEAD：见最终收尾提交。