feat: add retained underlay revision invalidation

2026-09-22 21:01:01 +09:00
parent 07a17b4c70
commit bcec6ce5e0
11 changed files with 817 additions and 24 deletions
--- a/docs/40_任务/STEP-089_静态渲染Revision与Invalidation基础层_Codex任务_v1.md
+++ b/docs/40_任务/STEP-089_静态渲染Revision与Invalidation基础层_Codex任务_v1.md
@@ -0,0 +1,144 @@
+# STEP-089 静态渲染 Revision 与 Invalidation 基础层 Codex 任务 v1
+
+## 目标
+
+为 STEP-090 Static CPU Fast Path 建立可靠、可验证的静态状态失效判据。
+
+STEP-089 不负责跳过 static source/tile/render-tree/prepare，也不负责降低 CPU；只建立“静态前缀当前是否仍可安全复用”的 revision / invalidation 基础，确保后续 fast path 不会复用过期静态状态。
+
+当前基线：
+
+- branch: `particle/main`
+- baseline HEAD: `07a17b4c701cd22c8e8b516ad84f4044f291f9fa`
+- STEP-088 retained underlay 已完成：
+  - GPU static draw cache
+  - map-scoped runtime Cache ON/OFF
+  - Release 最小 diagnostics
+  - Android/iOS/RN runtime API
+  - Android NavSea 真实 PBF 性能场景
+- 实测证明主要剩余成本是 Particle continuous repaint 下 PBF/vector/static renderer pipeline 被重复 processing。
+- STEP-090 才负责 CPU fast path。
+
+## 必做项
+
+- [ ] 引入单调递增的 static/retained revision 机制，能表达“静态前缀相关输入已变化”。
+- [ ] retained cache build 时记录所依据的 revision。
+- [ ] reuse 前必须确认当前 revision 与 build revision 一致。
+- [ ] 下列变化必须使 revision 前进或明确 invalidate：
+  - [ ] camera / transform
+  - [ ] viewport / size / pixel ratio
+  - [ ] style reload / style mutation
+  - [ ] layer add/remove/reorder/property mutation
+  - [ ] source add/remove/change
+  - [ ] tile / drawable 内容更新
+  - [ ] image / sprite / glyph 变化
+  - [ ] placement / symbol fade 状态变化
+  - [ ] render context / surface / backend resource reset
+  - [ ] debug render options
+  - [ ] terrain / 3D / custom layer 等当前不能安全证明静态的场景
+- [ ] symbol fade / placement transition 活跃时不得复用 stale static cache。
+- [ ] unsupported / uncertain 情况继续 fail closed 到 full renderer。
+- [ ] Cache OFF/ON runtime 行为保持不变。
+- [ ] Release diagnostics 保持低成本；允许新增只读 revision 字段，但禁止 per-frame Release 日志。
+- [ ] Debug 日志可增加 revision / invalidation reason，便于 RDC 验证。
+- [ ] 原有 LayerGroup ordinal、dynamic boundary、transparent underlay、legacy ordering 语义不得回退。
+- [ ] 不实现 STEP-090 的 static CPU processing skip。
+- [ ] 不新增 React 管理的 renderer cache。
+- [ ] 不把 provider/network/NavSea Store 逻辑引入 MapLibre Core。
+- [ ] 不使用 Jest。
+
+## Revision 设计约束
+
+优先采用单调 `uint64_t` revision / generation：
+
+- revision 只增不减；
+- 不依赖 wall clock；
+- 不要求每种事件都维护独立缓存副本；
+- 可以保留 reason/category 作为诊断，但 correctness 依赖 revision，而不是字符串 reason；
+- revision wraparound 可按现实上不可达处理，但类型必须明确。
+
+建议最少区分：
+
+- 当前 static revision；
+- retained underlay build revision；
+
+如现有 Renderer/RenderOrchestrator 的生命周期更适合其他命名，可调整，但不要把模型复杂化。
+
+## Invalidation 范围原则
+
+STEP-089 首选“安全偏保守”。
+
+如果某类状态变化是否会影响 static prefix 无法可靠判断：
+
+- 直接 bump revision / invalidate；
+- 不做复杂局部 dependency graph；
+- 不为了提高 hit rate 提前实现 STEP-090 级别的细粒度 source/layer dependency tracking。
+
+目标是让 STEP-090 有一个可信的 fast-path gate，而不是在 089 追求最高 cache reuse。
+
+## Placement / Symbol 特别规则
+
+已有 Android 真机证据：
+
+- Particle 放到全部 63 层上方时，symbol-heavy prefix 会出现持续 `static-placement` / `static-transition`。
+- BEFORE_SYMBOL_CLUSTER（fill/line 在下，symbol cluster 在上）是目前最稳定边界。
+
+因此：
+
+- placement/fade active 必须阻止旧 static state 被错误复用；
+- fade/placement 稳定后允许重新 build 并记录新 revision；
+- 不得简单忽略 symbol placement 来提高 TOP 场景 reuse。
+
+## Runtime API / Diagnostics
+
+保持现有：
+
+- `setRetainedUnderlayEnabled`
+- `getRetainedUnderlayDiagnostics`
+
+允许在 diagnostics 增加：
+
+- `staticRevision`
+- `buildRevision`
+
+如增加，Android/iOS/RN 三端需一致；如果为了控制 STEP-089 范围决定暂不公开，也至少在 Debug Native 日志中可观察。
+
+不要新增第二套 runtime module / map registry。
+
+## 测试要求
+
+新增/扩展 Native directed tests，至少覆盖：
+
+1. revision 单调递增；
+2. build revision 与 current revision 相等时允许 reuse；
+3. camera/viewport/style/source 变化后 revision 改变并禁止旧 cache reuse；
+4. placement/fade active 时不 reuse stale cache；
+5. Cache OFF -> invalidate；重新 ON -> 下一次重新 build；
+6. unsupported / resource failure 保持安全 fallback；
+7. 原有 RetainedDynamicBoundary / LayerGroupRange / RetainedUnderlayCache 测试继续通过。
+
+不要求 Jest。
+
+## Codex 执行规则
+
+- 先完整阅读本任务、AGENTS.md、STEP-088 v3 Step/报告，以及 retained underlay 当前实现。
+- 不需要提交实施计划。
+- 直接实现。
+- 不运行 Gradle / Android build / ADB / Xcode。
+- 不运行大型 noisy build/test；编译和最终验证由 RDC 负责。
+- 可以做必要的静态代码检查，但不要替代 RDC 编译。
+- 不 commit/push，等 RDC 验证后统一收尾。
+- 不触碰用户既有无关 dirty/untracked。
+- 不使用 worktree。
+- 无法完成的项明确说明，不得静默跳过。
+
+## 完成时必须报告
+
+逐项按“已完成 / 未完成 / 无法验证”报告上述必做项，并列出：
+
+- 修改文件；
+- revision 的实际所有者与生命周期；
+- 每类 invalidation 在哪里触发；
+- 新增测试名；
+- RDC 应执行的精确 OpenGL / Metal / Android Validation 命令；
+- 明确说明没有实现 STEP-090 fast path。
--- a/docs/50_Step记录/STEP-089_静态渲染Revision与Invalidation基础层_v1.md
+++ b/docs/50_Step记录/STEP-089_静态渲染Revision与Invalidation基础层_v1.md
@@ -0,0 +1,117 @@
+# STEP-089 静态渲染 Revision 与 Invalidation 基础层 v1
+
+## 状态
+
+**CLOSED / PASS**
+
+STEP-089 已完成 retained underlay 的静态状态 revision / invalidation 基础层，为 STEP-090 Static CPU Fast Path 提供可靠的安全门控。
+
+## 核心实现
+
+- 新增单调递增的静态 revision / generation。
+- retained cache build 时记录 buildRevision。
+- reuse 前要求 buildRevision 与当前 staticRevision 一致。
+- 新增稳定 topology snapshot：
+  - dynamic boundary；
+  - static prefix 中每个 LayerGroup 的 layerIndex；
+  - groupName；
+  - groupType。
+- 真正的 LayerGroup 增删、排序、index 变化会推进 topologyRevision。
+- Renderer 内部 transient drawable churn 不再直接推进 static revision。
+- 等价的 stencil tile set 不因 shared_ptr identity 变化而误失效。
+- 支持并记录以下语义失效来源：
+  - camera / viewport / pixel ratio；
+  - style / layer / source mutation；
+  - tile content change；
+  - image / sprite / glyph；
+  - placement / fade；
+  - context reset；
+  - debug options；
+  - 3D / unsupported custom/static layer。
+- unsupported / uncertain 场景继续 fail-closed。
+- STEP-088 runtime Cache ON/OFF 行为保持不变。
+- 未实现 STEP-090 CPU fast path。
+
+## Android 实机关键验证
+
+测试场景：
+- Android 13 / x86_64；
+- NavSea 正式 63 层 PBF Style；
+- Particle = AFTER_CLIP；
+- 固定 Camera：Karatsu；
+- Cache ON。
+
+### 稳态
+
+修复前曾出现：
+- drawable-mutation 每帧失效；
+- layer-group-mutation 每帧失效；
+- staticRevision 每帧递增；
+- build 每帧递增；
+- reuse=0。
+
+最终版本：
+
+```text
+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
+```
+
+确认：
+- staticRevision 稳定；
+- buildRevision == staticRevision；
+- build 不再增长；
+- reuse 持续增长。
+
+### Camera 变化
+
+相机变化后：
+- staticRevision: 41 -> 44；
+- build: 18 -> 19；
+- buildRevision = 44；
+
+随后稳定：
+
+```text
+build=19
+reuse=3519 -> 3639 -> 3759 -> 3879
+staticRevision=44
+buildRevision=44
+```
+
+确认真实变化会使 revision 前进并重建一次，稳定后恢复 reuse。
+
+## Native 测试
+
+Retained directed tests：12/12 PASS。
+
+覆盖：
+- dynamic boundary；
+- layer group range；
+- cache build/reuse/invalidation；
+- runtime Cache ON/OFF；
+- revision 单调；
+- 无语义变化时 revision 不前进；
+- 等价 intra-frame remove/add 不推进 topology；
+- 持久 topology 变化只推进一次；
+- ordering/index 变化推进 topology；
+- buildRevision 匹配才允许 reuse；
+- placement/fade 活跃时拒绝 stale cache。
+
+## 构建验证
+
+- Mac OpenGL mbgl-test-runner：PASS。
+- Metal/iOS mbgl-core：BUILD SUCCEEDED。
+- Android x86_64 stripped Debug Validation APK：BUILD SUCCESSFUL，约 57 MB。
+- Android 实机稳态 reuse：PASS。
+- Android Camera invalidation -> rebuild -> reuse：PASS。
+- git diff --check：PASS。
+
+## 结论
+
+STEP-089 已建立可信的 static revision gate。后续 STEP-090 可以在该 gate 为稳定状态时尝试跳过静态 PBF/vector CPU processing；089 本身不做 CPU fast path。
+
+## 下一步
+
+进入 STEP-090：Static CPU Fast Path。
--- a/docs/报告/STEP-089_静态渲染Revision与Invalidation基础层_Codex完成报告_v1.md
+++ b/docs/报告/STEP-089_静态渲染Revision与Invalidation基础层_Codex完成报告_v1.md
@@ -0,0 +1,60 @@
+# 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 代表日志
+
+```text
+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
+```
+
+相机变化后：
+
+```text
+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
+
+将在 scoped commit/push 后补充最终 commit hash。